@genkit-ai/a2ui 0.5.0-rc.0

package/lib/catalog.js

@@ -0,0 +1,285 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var catalog_exports = {};
+__export(catalog_exports, {
+  A2UI_CATALOG_VALUE_TYPE: () => A2UI_CATALOG_VALUE_TYPE,
+  BASIC_ICON_NAMES: () => BASIC_ICON_NAMES,
+  DEFAULT_CATALOG_ID: () => DEFAULT_CATALOG_ID,
+  SURFACE_ID_PLACEHOLDER: () => SURFACE_ID_PLACEHOLDER,
+  basicCatalog: () => basicCatalog,
+  renderCatalogInstructions: () => renderCatalogInstructions
+});
+module.exports = __toCommonJS(catalog_exports);
+var import_types = require("./types.js");
+const A2UI_CATALOG_VALUE_TYPE = "a2ui-catalog";
+const DEFAULT_CATALOG_ID = "basic";
+const BASIC_ICON_NAMES = [
+  "accountCircle",
+  "add",
+  "arrowBack",
+  "arrowForward",
+  "attachFile",
+  "calendarToday",
+  "call",
+  "camera",
+  "check",
+  "close",
+  "delete",
+  "download",
+  "edit",
+  "event",
+  "error",
+  "fastForward",
+  "favorite",
+  "favoriteOff",
+  "folder",
+  "help",
+  "home",
+  "info",
+  "locationOn",
+  "lock",
+  "lockOpen",
+  "mail",
+  "menu",
+  "moreVert",
+  "moreHoriz",
+  "notificationsOff",
+  "notifications",
+  "pause",
+  "payment",
+  "person",
+  "phone",
+  "photo",
+  "play",
+  "print",
+  "refresh",
+  "rewind",
+  "search",
+  "send",
+  "settings",
+  "share",
+  "shoppingCart",
+  "skipNext",
+  "skipPrevious",
+  "star",
+  "starHalf",
+  "starOff",
+  "stop",
+  "upload",
+  "visibility",
+  "visibilityOff",
+  "volumeDown",
+  "volumeMute",
+  "volumeOff",
+  "volumeUp",
+  "warning"
+];
+const basicCatalog = {
+  id: import_types.BASIC_CATALOG_ID,
+  components: [
+    {
+      name: "Text",
+      description: "Displays a run of text. For headings/titles set the `variant` prop (h1..h5) rather than embedding Markdown; the text itself may use inline Markdown.",
+      props: "text: string (required); variant?: one of h1|h2|h3|h4|h5|caption|body."
+    },
+    {
+      name: "Image",
+      description: "Displays an image from a URL.",
+      props: "url: string (required); description?: string; fit?: contain|cover|fill|none|scaleDown; variant?: icon|avatar|smallFeature|mediumFeature|largeFeature|header."
+    },
+    {
+      name: "Icon",
+      description: 'Displays a named material icon. `name` MUST be one of the exact names listed below \u2014 do NOT invent names (e.g. there is no "cloud", "air", or "thermostat"). If none fits, omit the Icon rather than guessing.',
+      props: `name: one of ${BASIC_ICON_NAMES.join(", ")} (required, exact).`
+    },
+    {
+      name: "Row",
+      description: "Lays out children horizontally.",
+      props: "children: string[] of component ids (required); justify?: start|center|end|spaceAround|spaceBetween|spaceEvenly|stretch; align?: start|center|end|stretch."
+    },
+    {
+      name: "Column",
+      description: "Lays out children vertically.",
+      props: "children: string[] of component ids (required); justify?: start|center|end|spaceBetween|spaceAround|spaceEvenly|stretch; align?: start|center|end|stretch."
+    },
+    {
+      name: "List",
+      description: "A list of children.",
+      props: "children: string[] of component ids (required); direction?: vertical|horizontal; listStyle?: ordered|unordered|none."
+    },
+    {
+      name: "Card",
+      description: "A visually-contained card wrapping a single child.",
+      props: "child: string id of a single child component (required; wrap multiple in a Column/Row)."
+    },
+    {
+      name: "Divider",
+      description: "A horizontal or vertical separator line.",
+      props: "axis?: horizontal|vertical."
+    },
+    {
+      name: "Button",
+      description: "A clickable button that fires an action back to the agent.",
+      props: "child: string id of a child (usually a Text) (required); variant?: default|primary|borderless; action: { event: { name: string, context?: object } } (required \u2014 the event name is sent back to the agent when clicked)."
+    },
+    {
+      name: "TextField",
+      description: "A single- or multi-line text input.",
+      props: "label: string (required); value?: string or { path } binding; variant?: shortText|longText|number|obscured."
+    },
+    {
+      name: "CheckBox",
+      description: "A labeled checkbox.",
+      props: "label: string (required); value: boolean or { path } binding (required)."
+    },
+    {
+      name: "Slider",
+      description: "A numeric slider.",
+      props: "max: number (required); value: number or { path } binding (required); label?: string; min?: number; step?: number."
+    }
+  ]
+};
+function renderStyleTips(has) {
+  const tips = [];
+  const containers = ["Card", "Column", "Row"].filter((c) => has.has(c));
+  if (containers.length) {
+    tips.push(
+      `- Group related content with layout components (${containers.join(
+        "/"
+      )}) and give it a clear hierarchy.`
+    );
+  }
+  if (has.has("Text")) {
+    tips.push(
+      '- Give titles a heading `variant` (e.g. h2/h3) and secondary text the `caption` variant instead of embedding "#"/"##" heading markers in the text.'
+    );
+  }
+  const accents = ["Icon", "Divider", "Image"].filter((c) => has.has(c));
+  if (accents.length) {
+    tips.push(
+      `- Use ${accents.join(
+        "/"
+      )} to add visual meaning and separate sections where it helps.`
+    );
+  }
+  if (has.has("Button")) {
+    tips.push('- Give primary buttons `variant: "primary"`.');
+  }
+  return tips.length ? `
+
+Make it look good, not bland:
+${tips.join("\n")}` : "";
+}
+function renderExample(catalog, has) {
+  if (has.has("Card") && has.has("Column") && has.has("Text")) {
+    return `
+
+Example (a small weather card):
+\`\`\`a2ui
+[
+  { "createSurface": { "surfaceId": "SURFACE_ID", "catalogId": "${catalog.id}" } },
+  { "updateComponents": { "surfaceId": "SURFACE_ID", "components": [
+    { "id": "root", "component": "Card", "child": "body" },
+    { "id": "body", "component": "Column", "children": ["title", "temp"] },
+    { "id": "title", "component": "Text", "text": "Weather in Tokyo", "variant": "h3" },
+    { "id": "temp", "component": "Text", "text": { "path": "/temp" } }
+  ] } },
+  { "updateDataModel": { "surfaceId": "SURFACE_ID", "path": "/temp", "value": "18\xB0C" } }
+]
+\`\`\``;
+  }
+  const rootComponent = catalog.components[0]?.name ?? "Text";
+  return `
+
+Example (a minimal surface):
+\`\`\`a2ui
+[
+  { "createSurface": { "surfaceId": "SURFACE_ID", "catalogId": "${catalog.id}" } },
+  { "updateComponents": { "surfaceId": "SURFACE_ID", "components": [
+    { "id": "root", "component": "${rootComponent}" }
+  ] } }
+]
+\`\`\``;
+}
+function renderCatalogInstructions(catalog) {
+  const componentDocs = catalog.components.map((c) => `- ${c.name}: ${c.description} Props: ${c.props}`).join("\n");
+  const has = new Set(catalog.components.map((c) => c.name));
+  const styleSection = renderStyleTips(has);
+  const exampleSection = renderExample(catalog, has);
+  const inputs = ["TextField", "CheckBox", "Slider"].filter((c) => has.has(c));
+  const inputList = inputs.join(", ");
+  const formsSection = inputs.length ? `
+- Forms: input components (${inputList}) do NOT send their values automatically.
+  To capture what the user entered you MUST do BOTH of these:
+  1. Bind each input's \`value\` to a data-model path, e.g.
+     \`{ "component": "TextField", "label": "Email", "value": { "path": "/email" } }\`.
+     Typing updates the data model at that path.
+  2. On the submit \`Button\`, echo those same paths in
+     \`action.event.context\` so their current values are sent back to you, e.g.
+     \`"context": { "email": { "path": "/email" }, "name": { "path": "/name" } }\`.
+  Without the \`{ path }\` bindings and the button \`context\`, the action arrives
+  with an empty \`context\` and the entered values are lost.` : "";
+  return `# Rendering UI with A2UI
+
+You can render rich, interactive UI (not just text) by emitting an A2UI surface.
+When a result is better *shown* than *told* (weather, lists, forms, comparisons,
+confirmations, anything visual or interactive), render a UI surface.
+
+To render UI, output a single fenced code block tagged \`a2ui\` containing a JSON
+array of A2UI envelope messages. You may still write normal prose before it.
+
+Rules:
+- The UI is an ADJACENCY LIST: a flat array of components. Build the tree using
+  string \`id\` references, NOT nested objects. Exactly one component MUST have
+  \`id: "root"\`.
+- Every component has a \`component\` (type name) and an \`id\`. Container
+  components reference their children by id via a \`children\` array; single-child
+  wrappers reference one \`child\` id.
+- Values can be literals, or a data-model binding \`{ "path": "/somePath" }\`.
+- Use \`createSurface\` first (with \`catalogId\`), then \`updateComponents\` to add
+  the component list, then optionally \`updateDataModel\` to set data. You may
+  combine them in one array, in order.
+- Interactive components fire an \`action\` with an event \`name\`; that name is
+  sent back to you when the user interacts, so choose meaningful names.${formsSection}
+- When a user interacts with a surface (e.g. presses a button) and you respond
+  with updated UI, RE-RENDER THE WHOLE SURFACE: start again with
+  \`createSurface\` followed by \`updateComponents\`. Do not emit a bare
+  \`updateDataModel\`/\`updateComponents\` expecting a previous surface to still
+  exist.${styleSection}
+
+The catalogId to use is:
+"${catalog.id}"
+
+Available components:
+${componentDocs}${exampleSection}
+
+Do not explain the JSON; just render the block. Use "SURFACE_ID" literally as a
+placeholder for the surface id \u2014 the system replaces it with a real id.`;
+}
+const SURFACE_ID_PLACEHOLDER = "SURFACE_ID";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  A2UI_CATALOG_VALUE_TYPE,
+  BASIC_ICON_NAMES,
+  DEFAULT_CATALOG_ID,
+  SURFACE_ID_PLACEHOLDER,
+  basicCatalog,
+  renderCatalogInstructions
+});
+//# sourceMappingURL=catalog.js.map

package/lib/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/catalog.ts"],"sourcesContent":["/**\n * Copyright 2026 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A2UI catalog description used by the {@link a2ui} middleware.\n *\n * A catalog pins the set of components a surface may render. The middleware uses\n * it for two things: (1) telling the model what it may render (prompt\n * injection), and (2) validating emitted envelopes only reference known\n * components. The renderer on the client registers a matching `@a2ui/*` catalog\n * under the same `id`.\n *\n * @module\n */\n\nimport { BASIC_CATALOG_ID } from './types.js';\n\n/**\n * The registry value type under which A2UI catalogs are stored, so the\n * {@link a2ui} middleware can look them up by id (and, in the future, tooling\n * can list them). Register with `ai.registry.registerValue(...)` via\n * {@link loadCatalog}.\n */\nexport const A2UI_CATALOG_VALUE_TYPE = 'a2ui-catalog';\n\n/**\n * The default catalog id used by the {@link a2ui} middleware when none is\n * given. Resolves to the bundled {@link basicCatalog}.\n */\nexport const DEFAULT_CATALOG_ID = 'basic';\n\n/** A component the model may use, plus a short description of its props. */\nexport interface A2uiCatalogComponent {\n  /** The component type name, e.g. `Text`. */\n  name: string;\n  /** One-line description of what the component renders. */\n  description: string;\n  /**\n   * A short, model-facing description of the component's props. Kept as plain\n   * text (rather than a JSON Schema) to keep the injected prompt compact.\n   */\n  props: string;\n}\n\n/** A parsed catalog: an id plus the components it exposes. */\nexport interface A2uiCatalog {\n  /** Globally-unique catalog id (also used as `catalogId` on `createSurface`). */\n  id: string;\n  /** The components available in this catalog. */\n  components: A2uiCatalogComponent[];\n}\n\n/**\n * The set of icon names the basic catalog's `Icon` component supports. Names\n * outside this list render as literal text (the renderer degrades gracefully),\n * so the prompt lists them to steer the model toward valid names. Note the\n * middleware validates component *types* against the catalog but does not\n * validate individual `Icon` name values.\n */\nexport const BASIC_ICON_NAMES = [\n  'accountCircle',\n  'add',\n  'arrowBack',\n  'arrowForward',\n  'attachFile',\n  'calendarToday',\n  'call',\n  'camera',\n  'check',\n  'close',\n  'delete',\n  'download',\n  'edit',\n  'event',\n  'error',\n  'fastForward',\n  'favorite',\n  'favoriteOff',\n  'folder',\n  'help',\n  'home',\n  'info',\n  'locationOn',\n  'lock',\n  'lockOpen',\n  'mail',\n  'menu',\n  'moreVert',\n  'moreHoriz',\n  'notificationsOff',\n  'notifications',\n  'pause',\n  'payment',\n  'person',\n  'phone',\n  'photo',\n  'play',\n  'print',\n  'refresh',\n  'rewind',\n  'search',\n  'send',\n  'settings',\n  'share',\n  'shoppingCart',\n  'skipNext',\n  'skipPrevious',\n  'star',\n  'starHalf',\n  'starOff',\n  'stop',\n  'upload',\n  'visibility',\n  'visibilityOff',\n  'volumeDown',\n  'volumeMute',\n  'volumeOff',\n  'volumeUp',\n  'warning',\n] as const;\n\n/**\n * The A2UI \"Basic Catalog\" (v0.9), mirroring the components published by\n * `@a2ui/web_core`'s basic catalog. Use this to render standard UI without\n * defining your own design system.\n */\nexport const basicCatalog: A2uiCatalog = {\n  id: BASIC_CATALOG_ID,\n  components: [\n    {\n      name: 'Text',\n      description:\n        'Displays a run of text. For headings/titles set the `variant` prop ' +\n        '(h1..h5) rather than embedding Markdown; the text itself may use ' +\n        'inline Markdown.',\n      props:\n        'text: string (required); variant?: one of h1|h2|h3|h4|h5|caption|body.',\n    },\n    {\n      name: 'Image',\n      description: 'Displays an image from a URL.',\n      props:\n        'url: string (required); description?: string; fit?: contain|cover|fill|none|scaleDown; variant?: icon|avatar|smallFeature|mediumFeature|largeFeature|header.',\n    },\n    {\n      name: 'Icon',\n      description:\n        'Displays a named material icon. `name` MUST be one of the exact names ' +\n        'listed below — do NOT invent names (e.g. there is no \"cloud\", \"air\", ' +\n        'or \"thermostat\"). If none fits, omit the Icon rather than guessing.',\n      props: `name: one of ${BASIC_ICON_NAMES.join(', ')} (required, exact).`,\n    },\n    {\n      name: 'Row',\n      description: 'Lays out children horizontally.',\n      props:\n        'children: string[] of component ids (required); justify?: start|center|end|spaceAround|spaceBetween|spaceEvenly|stretch; align?: start|center|end|stretch.',\n    },\n    {\n      name: 'Column',\n      description: 'Lays out children vertically.',\n      props:\n        'children: string[] of component ids (required); justify?: start|center|end|spaceBetween|spaceAround|spaceEvenly|stretch; align?: start|center|end|stretch.',\n    },\n    {\n      name: 'List',\n      description: 'A list of children.',\n      props:\n        'children: string[] of component ids (required); direction?: vertical|horizontal; listStyle?: ordered|unordered|none.',\n    },\n    {\n      name: 'Card',\n      description: 'A visually-contained card wrapping a single child.',\n      props:\n        'child: string id of a single child component (required; wrap multiple in a Column/Row).',\n    },\n    {\n      name: 'Divider',\n      description: 'A horizontal or vertical separator line.',\n      props: 'axis?: horizontal|vertical.',\n    },\n    {\n      name: 'Button',\n      description: 'A clickable button that fires an action back to the agent.',\n      props:\n        'child: string id of a child (usually a Text) (required); variant?: default|primary|borderless; action: { event: { name: string, context?: object } } (required — the event name is sent back to the agent when clicked).',\n    },\n    {\n      name: 'TextField',\n      description: 'A single- or multi-line text input.',\n      props:\n        'label: string (required); value?: string or { path } binding; variant?: shortText|longText|number|obscured.',\n    },\n    {\n      name: 'CheckBox',\n      description: 'A labeled checkbox.',\n      props:\n        'label: string (required); value: boolean or { path } binding (required).',\n    },\n    {\n      name: 'Slider',\n      description: 'A numeric slider.',\n      props:\n        'max: number (required); value: number or { path } binding (required); label?: string; min?: number; step?: number.',\n    },\n  ],\n};\n\n/**\n * Builds the \"make it look good\" styling tips, scoped to the components the\n * catalog actually provides so a custom catalog is never told to emit\n * components it lacks (which would then fail `validate: 'strict'`).\n */\nfunction renderStyleTips(has: Set<string>): string {\n  const tips: string[] = [];\n  const containers = ['Card', 'Column', 'Row'].filter((c) => has.has(c));\n  if (containers.length) {\n    tips.push(\n      `- Group related content with layout components (${containers.join(\n        '/'\n      )}) and give it a clear hierarchy.`\n    );\n  }\n  if (has.has('Text')) {\n    tips.push(\n      '- Give titles a heading `variant` (e.g. h2/h3) and secondary text the ' +\n        '`caption` variant instead of embedding \"#\"/\"##\" heading markers in ' +\n        'the text.'\n    );\n  }\n  const accents = ['Icon', 'Divider', 'Image'].filter((c) => has.has(c));\n  if (accents.length) {\n    tips.push(\n      `- Use ${accents.join(\n        '/'\n      )} to add visual meaning and separate sections where it helps.`\n    );\n  }\n  if (has.has('Button')) {\n    tips.push('- Give primary buttons `variant: \"primary\"`.');\n  }\n  return tips.length\n    ? `\\n\\nMake it look good, not bland:\\n${tips.join('\\n')}`\n    : '';\n}\n\n/**\n * Builds a worked example. Uses a rich Card/Column/Text layout when the catalog\n * supports it (the common case, e.g. the basic catalog); otherwise falls back\n * to a minimal example built only from components the catalog provides, so the\n * example never references unknown components.\n */\nfunction renderExample(catalog: A2uiCatalog, has: Set<string>): string {\n  if (has.has('Card') && has.has('Column') && has.has('Text')) {\n    return `\n\nExample (a small weather card):\n\\`\\`\\`a2ui\n[\n  { \"createSurface\": { \"surfaceId\": \"SURFACE_ID\", \"catalogId\": \"${catalog.id}\" } },\n  { \"updateComponents\": { \"surfaceId\": \"SURFACE_ID\", \"components\": [\n    { \"id\": \"root\", \"component\": \"Card\", \"child\": \"body\" },\n    { \"id\": \"body\", \"component\": \"Column\", \"children\": [\"title\", \"temp\"] },\n    { \"id\": \"title\", \"component\": \"Text\", \"text\": \"Weather in Tokyo\", \"variant\": \"h3\" },\n    { \"id\": \"temp\", \"component\": \"Text\", \"text\": { \"path\": \"/temp\" } }\n  ] } },\n  { \"updateDataModel\": { \"surfaceId\": \"SURFACE_ID\", \"path\": \"/temp\", \"value\": \"18°C\" } }\n]\n\\`\\`\\``;\n  }\n  // Minimal fallback: root uses whatever the catalog's first component is.\n  const rootComponent = catalog.components[0]?.name ?? 'Text';\n  return `\n\nExample (a minimal surface):\n\\`\\`\\`a2ui\n[\n  { \"createSurface\": { \"surfaceId\": \"SURFACE_ID\", \"catalogId\": \"${catalog.id}\" } },\n  { \"updateComponents\": { \"surfaceId\": \"SURFACE_ID\", \"components\": [\n    { \"id\": \"root\", \"component\": \"${rootComponent}\" }\n  ] } }\n]\n\\`\\`\\``;\n}\n\n/**\n * Renders a catalog into model-facing instructions describing the A2UI protocol\n * and the available components. Injected into the system prompt by the\n * middleware when `instructions !== 'none'`.\n */\nexport function renderCatalogInstructions(catalog: A2uiCatalog): string {\n  const componentDocs = catalog.components\n    .map((c) => `- ${c.name}: ${c.description} Props: ${c.props}`)\n    .join('\\n');\n\n  const has = new Set(catalog.components.map((c) => c.name));\n  const styleSection = renderStyleTips(has);\n  const exampleSection = renderExample(catalog, has);\n\n  // Forms guidance only applies if the catalog has input components.\n  const inputs = ['TextField', 'CheckBox', 'Slider'].filter((c) => has.has(c));\n  const inputList = inputs.join(', ');\n  const formsSection = inputs.length\n    ? `\n- Forms: input components (${inputList}) do NOT send their values automatically.\n  To capture what the user entered you MUST do BOTH of these:\n  1. Bind each input's \\`value\\` to a data-model path, e.g.\n     \\`{ \"component\": \"TextField\", \"label\": \"Email\", \"value\": { \"path\": \"/email\" } }\\`.\n     Typing updates the data model at that path.\n  2. On the submit \\`Button\\`, echo those same paths in\n     \\`action.event.context\\` so their current values are sent back to you, e.g.\n     \\`\"context\": { \"email\": { \"path\": \"/email\" }, \"name\": { \"path\": \"/name\" } }\\`.\n  Without the \\`{ path }\\` bindings and the button \\`context\\`, the action arrives\n  with an empty \\`context\\` and the entered values are lost.`\n    : '';\n\n  return `# Rendering UI with A2UI\n\nYou can render rich, interactive UI (not just text) by emitting an A2UI surface.\nWhen a result is better *shown* than *told* (weather, lists, forms, comparisons,\nconfirmations, anything visual or interactive), render a UI surface.\n\nTo render UI, output a single fenced code block tagged \\`a2ui\\` containing a JSON\narray of A2UI envelope messages. You may still write normal prose before it.\n\nRules:\n- The UI is an ADJACENCY LIST: a flat array of components. Build the tree using\n  string \\`id\\` references, NOT nested objects. Exactly one component MUST have\n  \\`id: \"root\"\\`.\n- Every component has a \\`component\\` (type name) and an \\`id\\`. Container\n  components reference their children by id via a \\`children\\` array; single-child\n  wrappers reference one \\`child\\` id.\n- Values can be literals, or a data-model binding \\`{ \"path\": \"/somePath\" }\\`.\n- Use \\`createSurface\\` first (with \\`catalogId\\`), then \\`updateComponents\\` to add\n  the component list, then optionally \\`updateDataModel\\` to set data. You may\n  combine them in one array, in order.\n- Interactive components fire an \\`action\\` with an event \\`name\\`; that name is\n  sent back to you when the user interacts, so choose meaningful names.${formsSection}\n- When a user interacts with a surface (e.g. presses a button) and you respond\n  with updated UI, RE-RENDER THE WHOLE SURFACE: start again with\n  \\`createSurface\\` followed by \\`updateComponents\\`. Do not emit a bare\n  \\`updateDataModel\\`/\\`updateComponents\\` expecting a previous surface to still\n  exist.${styleSection}\n\nThe catalogId to use is:\n\"${catalog.id}\"\n\nAvailable components:\n${componentDocs}${exampleSection}\n\nDo not explain the JSON; just render the block. Use \"SURFACE_ID\" literally as a\nplaceholder for the surface id — the system replaces it with a real id.`;\n}\n\n/** The literal placeholder the model is told to use for surface ids. */\nexport const SURFACE_ID_PLACEHOLDER = 'SURFACE_ID';\n"],"mappings":"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","names":[]}

package/lib/catalog.mjs

@@ -0,0 +1,256 @@
+import { BASIC_CATALOG_ID } from "./types.mjs";
+const A2UI_CATALOG_VALUE_TYPE = "a2ui-catalog";
+const DEFAULT_CATALOG_ID = "basic";
+const BASIC_ICON_NAMES = [
+  "accountCircle",
+  "add",
+  "arrowBack",
+  "arrowForward",
+  "attachFile",
+  "calendarToday",
+  "call",
+  "camera",
+  "check",
+  "close",
+  "delete",
+  "download",
+  "edit",
+  "event",
+  "error",
+  "fastForward",
+  "favorite",
+  "favoriteOff",
+  "folder",
+  "help",
+  "home",
+  "info",
+  "locationOn",
+  "lock",
+  "lockOpen",
+  "mail",
+  "menu",
+  "moreVert",
+  "moreHoriz",
+  "notificationsOff",
+  "notifications",
+  "pause",
+  "payment",
+  "person",
+  "phone",
+  "photo",
+  "play",
+  "print",
+  "refresh",
+  "rewind",
+  "search",
+  "send",
+  "settings",
+  "share",
+  "shoppingCart",
+  "skipNext",
+  "skipPrevious",
+  "star",
+  "starHalf",
+  "starOff",
+  "stop",
+  "upload",
+  "visibility",
+  "visibilityOff",
+  "volumeDown",
+  "volumeMute",
+  "volumeOff",
+  "volumeUp",
+  "warning"
+];
+const basicCatalog = {
+  id: BASIC_CATALOG_ID,
+  components: [
+    {
+      name: "Text",
+      description: "Displays a run of text. For headings/titles set the `variant` prop (h1..h5) rather than embedding Markdown; the text itself may use inline Markdown.",
+      props: "text: string (required); variant?: one of h1|h2|h3|h4|h5|caption|body."
+    },
+    {
+      name: "Image",
+      description: "Displays an image from a URL.",
+      props: "url: string (required); description?: string; fit?: contain|cover|fill|none|scaleDown; variant?: icon|avatar|smallFeature|mediumFeature|largeFeature|header."
+    },
+    {
+      name: "Icon",
+      description: 'Displays a named material icon. `name` MUST be one of the exact names listed below \u2014 do NOT invent names (e.g. there is no "cloud", "air", or "thermostat"). If none fits, omit the Icon rather than guessing.',
+      props: `name: one of ${BASIC_ICON_NAMES.join(", ")} (required, exact).`
+    },
+    {
+      name: "Row",
+      description: "Lays out children horizontally.",
+      props: "children: string[] of component ids (required); justify?: start|center|end|spaceAround|spaceBetween|spaceEvenly|stretch; align?: start|center|end|stretch."
+    },
+    {
+      name: "Column",
+      description: "Lays out children vertically.",
+      props: "children: string[] of component ids (required); justify?: start|center|end|spaceBetween|spaceAround|spaceEvenly|stretch; align?: start|center|end|stretch."
+    },
+    {
+      name: "List",
+      description: "A list of children.",
+      props: "children: string[] of component ids (required); direction?: vertical|horizontal; listStyle?: ordered|unordered|none."
+    },
+    {
+      name: "Card",
+      description: "A visually-contained card wrapping a single child.",
+      props: "child: string id of a single child component (required; wrap multiple in a Column/Row)."
+    },
+    {
+      name: "Divider",
+      description: "A horizontal or vertical separator line.",
+      props: "axis?: horizontal|vertical."
+    },
+    {
+      name: "Button",
+      description: "A clickable button that fires an action back to the agent.",
+      props: "child: string id of a child (usually a Text) (required); variant?: default|primary|borderless; action: { event: { name: string, context?: object } } (required \u2014 the event name is sent back to the agent when clicked)."
+    },
+    {
+      name: "TextField",
+      description: "A single- or multi-line text input.",
+      props: "label: string (required); value?: string or { path } binding; variant?: shortText|longText|number|obscured."
+    },
+    {
+      name: "CheckBox",
+      description: "A labeled checkbox.",
+      props: "label: string (required); value: boolean or { path } binding (required)."
+    },
+    {
+      name: "Slider",
+      description: "A numeric slider.",
+      props: "max: number (required); value: number or { path } binding (required); label?: string; min?: number; step?: number."
+    }
+  ]
+};
+function renderStyleTips(has) {
+  const tips = [];
+  const containers = ["Card", "Column", "Row"].filter((c) => has.has(c));
+  if (containers.length) {
+    tips.push(
+      `- Group related content with layout components (${containers.join(
+        "/"
+      )}) and give it a clear hierarchy.`
+    );
+  }
+  if (has.has("Text")) {
+    tips.push(
+      '- Give titles a heading `variant` (e.g. h2/h3) and secondary text the `caption` variant instead of embedding "#"/"##" heading markers in the text.'
+    );
+  }
+  const accents = ["Icon", "Divider", "Image"].filter((c) => has.has(c));
+  if (accents.length) {
+    tips.push(
+      `- Use ${accents.join(
+        "/"
+      )} to add visual meaning and separate sections where it helps.`
+    );
+  }
+  if (has.has("Button")) {
+    tips.push('- Give primary buttons `variant: "primary"`.');
+  }
+  return tips.length ? `
+
+Make it look good, not bland:
+${tips.join("\n")}` : "";
+}
+function renderExample(catalog, has) {
+  if (has.has("Card") && has.has("Column") && has.has("Text")) {
+    return `
+
+Example (a small weather card):
+\`\`\`a2ui
+[
+  { "createSurface": { "surfaceId": "SURFACE_ID", "catalogId": "${catalog.id}" } },
+  { "updateComponents": { "surfaceId": "SURFACE_ID", "components": [
+    { "id": "root", "component": "Card", "child": "body" },
+    { "id": "body", "component": "Column", "children": ["title", "temp"] },
+    { "id": "title", "component": "Text", "text": "Weather in Tokyo", "variant": "h3" },
+    { "id": "temp", "component": "Text", "text": { "path": "/temp" } }
+  ] } },
+  { "updateDataModel": { "surfaceId": "SURFACE_ID", "path": "/temp", "value": "18\xB0C" } }
+]
+\`\`\``;
+  }
+  const rootComponent = catalog.components[0]?.name ?? "Text";
+  return `
+
+Example (a minimal surface):
+\`\`\`a2ui
+[
+  { "createSurface": { "surfaceId": "SURFACE_ID", "catalogId": "${catalog.id}" } },
+  { "updateComponents": { "surfaceId": "SURFACE_ID", "components": [
+    { "id": "root", "component": "${rootComponent}" }
+  ] } }
+]
+\`\`\``;
+}
+function renderCatalogInstructions(catalog) {
+  const componentDocs = catalog.components.map((c) => `- ${c.name}: ${c.description} Props: ${c.props}`).join("\n");
+  const has = new Set(catalog.components.map((c) => c.name));
+  const styleSection = renderStyleTips(has);
+  const exampleSection = renderExample(catalog, has);
+  const inputs = ["TextField", "CheckBox", "Slider"].filter((c) => has.has(c));
+  const inputList = inputs.join(", ");
+  const formsSection = inputs.length ? `
+- Forms: input components (${inputList}) do NOT send their values automatically.
+  To capture what the user entered you MUST do BOTH of these:
+  1. Bind each input's \`value\` to a data-model path, e.g.
+     \`{ "component": "TextField", "label": "Email", "value": { "path": "/email" } }\`.
+     Typing updates the data model at that path.
+  2. On the submit \`Button\`, echo those same paths in
+     \`action.event.context\` so their current values are sent back to you, e.g.
+     \`"context": { "email": { "path": "/email" }, "name": { "path": "/name" } }\`.
+  Without the \`{ path }\` bindings and the button \`context\`, the action arrives
+  with an empty \`context\` and the entered values are lost.` : "";
+  return `# Rendering UI with A2UI
+
+You can render rich, interactive UI (not just text) by emitting an A2UI surface.
+When a result is better *shown* than *told* (weather, lists, forms, comparisons,
+confirmations, anything visual or interactive), render a UI surface.
+
+To render UI, output a single fenced code block tagged \`a2ui\` containing a JSON
+array of A2UI envelope messages. You may still write normal prose before it.
+
+Rules:
+- The UI is an ADJACENCY LIST: a flat array of components. Build the tree using
+  string \`id\` references, NOT nested objects. Exactly one component MUST have
+  \`id: "root"\`.
+- Every component has a \`component\` (type name) and an \`id\`. Container
+  components reference their children by id via a \`children\` array; single-child
+  wrappers reference one \`child\` id.
+- Values can be literals, or a data-model binding \`{ "path": "/somePath" }\`.
+- Use \`createSurface\` first (with \`catalogId\`), then \`updateComponents\` to add
+  the component list, then optionally \`updateDataModel\` to set data. You may
+  combine them in one array, in order.
+- Interactive components fire an \`action\` with an event \`name\`; that name is
+  sent back to you when the user interacts, so choose meaningful names.${formsSection}
+- When a user interacts with a surface (e.g. presses a button) and you respond
+  with updated UI, RE-RENDER THE WHOLE SURFACE: start again with
+  \`createSurface\` followed by \`updateComponents\`. Do not emit a bare
+  \`updateDataModel\`/\`updateComponents\` expecting a previous surface to still
+  exist.${styleSection}
+
+The catalogId to use is:
+"${catalog.id}"
+
+Available components:
+${componentDocs}${exampleSection}
+
+Do not explain the JSON; just render the block. Use "SURFACE_ID" literally as a
+placeholder for the surface id \u2014 the system replaces it with a real id.`;
+}
+const SURFACE_ID_PLACEHOLDER = "SURFACE_ID";
+export {
+  A2UI_CATALOG_VALUE_TYPE,
+  BASIC_ICON_NAMES,
+  DEFAULT_CATALOG_ID,
+  SURFACE_ID_PLACEHOLDER,
+  basicCatalog,
+  renderCatalogInstructions
+};
+//# sourceMappingURL=catalog.mjs.map

package/lib/catalog.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/catalog.ts"],"sourcesContent":["/**\n * Copyright 2026 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A2UI catalog description used by the {@link a2ui} middleware.\n *\n * A catalog pins the set of components a surface may render. The middleware uses\n * it for two things: (1) telling the model what it may render (prompt\n * injection), and (2) validating emitted envelopes only reference known\n * components. The renderer on the client registers a matching `@a2ui/*` catalog\n * under the same `id`.\n *\n * @module\n */\n\nimport { BASIC_CATALOG_ID } from './types.mjs';\n\n/**\n * The registry value type under which A2UI catalogs are stored, so the\n * {@link a2ui} middleware can look them up by id (and, in the future, tooling\n * can list them). Register with `ai.registry.registerValue(...)` via\n * {@link loadCatalog}.\n */\nexport const A2UI_CATALOG_VALUE_TYPE = 'a2ui-catalog';\n\n/**\n * The default catalog id used by the {@link a2ui} middleware when none is\n * given. Resolves to the bundled {@link basicCatalog}.\n */\nexport const DEFAULT_CATALOG_ID = 'basic';\n\n/** A component the model may use, plus a short description of its props. */\nexport interface A2uiCatalogComponent {\n  /** The component type name, e.g. `Text`. */\n  name: string;\n  /** One-line description of what the component renders. */\n  description: string;\n  /**\n   * A short, model-facing description of the component's props. Kept as plain\n   * text (rather than a JSON Schema) to keep the injected prompt compact.\n   */\n  props: string;\n}\n\n/** A parsed catalog: an id plus the components it exposes. */\nexport interface A2uiCatalog {\n  /** Globally-unique catalog id (also used as `catalogId` on `createSurface`). */\n  id: string;\n  /** The components available in this catalog. */\n  components: A2uiCatalogComponent[];\n}\n\n/**\n * The set of icon names the basic catalog's `Icon` component supports. Names\n * outside this list render as literal text (the renderer degrades gracefully),\n * so the prompt lists them to steer the model toward valid names. Note the\n * middleware validates component *types* against the catalog but does not\n * validate individual `Icon` name values.\n */\nexport const BASIC_ICON_NAMES = [\n  'accountCircle',\n  'add',\n  'arrowBack',\n  'arrowForward',\n  'attachFile',\n  'calendarToday',\n  'call',\n  'camera',\n  'check',\n  'close',\n  'delete',\n  'download',\n  'edit',\n  'event',\n  'error',\n  'fastForward',\n  'favorite',\n  'favoriteOff',\n  'folder',\n  'help',\n  'home',\n  'info',\n  'locationOn',\n  'lock',\n  'lockOpen',\n  'mail',\n  'menu',\n  'moreVert',\n  'moreHoriz',\n  'notificationsOff',\n  'notifications',\n  'pause',\n  'payment',\n  'person',\n  'phone',\n  'photo',\n  'play',\n  'print',\n  'refresh',\n  'rewind',\n  'search',\n  'send',\n  'settings',\n  'share',\n  'shoppingCart',\n  'skipNext',\n  'skipPrevious',\n  'star',\n  'starHalf',\n  'starOff',\n  'stop',\n  'upload',\n  'visibility',\n  'visibilityOff',\n  'volumeDown',\n  'volumeMute',\n  'volumeOff',\n  'volumeUp',\n  'warning',\n] as const;\n\n/**\n * The A2UI \"Basic Catalog\" (v0.9), mirroring the components published by\n * `@a2ui/web_core`'s basic catalog. Use this to render standard UI without\n * defining your own design system.\n */\nexport const basicCatalog: A2uiCatalog = {\n  id: BASIC_CATALOG_ID,\n  components: [\n    {\n      name: 'Text',\n      description:\n        'Displays a run of text. For headings/titles set the `variant` prop ' +\n        '(h1..h5) rather than embedding Markdown; the text itself may use ' +\n        'inline Markdown.',\n      props:\n        'text: string (required); variant?: one of h1|h2|h3|h4|h5|caption|body.',\n    },\n    {\n      name: 'Image',\n      description: 'Displays an image from a URL.',\n      props:\n        'url: string (required); description?: string; fit?: contain|cover|fill|none|scaleDown; variant?: icon|avatar|smallFeature|mediumFeature|largeFeature|header.',\n    },\n    {\n      name: 'Icon',\n      description:\n        'Displays a named material icon. `name` MUST be one of the exact names ' +\n        'listed below — do NOT invent names (e.g. there is no \"cloud\", \"air\", ' +\n        'or \"thermostat\"). If none fits, omit the Icon rather than guessing.',\n      props: `name: one of ${BASIC_ICON_NAMES.join(', ')} (required, exact).`,\n    },\n    {\n      name: 'Row',\n      description: 'Lays out children horizontally.',\n      props:\n        'children: string[] of component ids (required); justify?: start|center|end|spaceAround|spaceBetween|spaceEvenly|stretch; align?: start|center|end|stretch.',\n    },\n    {\n      name: 'Column',\n      description: 'Lays out children vertically.',\n      props:\n        'children: string[] of component ids (required); justify?: start|center|end|spaceBetween|spaceAround|spaceEvenly|stretch; align?: start|center|end|stretch.',\n    },\n    {\n      name: 'List',\n      description: 'A list of children.',\n      props:\n        'children: string[] of component ids (required); direction?: vertical|horizontal; listStyle?: ordered|unordered|none.',\n    },\n    {\n      name: 'Card',\n      description: 'A visually-contained card wrapping a single child.',\n      props:\n        'child: string id of a single child component (required; wrap multiple in a Column/Row).',\n    },\n    {\n      name: 'Divider',\n      description: 'A horizontal or vertical separator line.',\n      props: 'axis?: horizontal|vertical.',\n    },\n    {\n      name: 'Button',\n      description: 'A clickable button that fires an action back to the agent.',\n      props:\n        'child: string id of a child (usually a Text) (required); variant?: default|primary|borderless; action: { event: { name: string, context?: object } } (required — the event name is sent back to the agent when clicked).',\n    },\n    {\n      name: 'TextField',\n      description: 'A single- or multi-line text input.',\n      props:\n        'label: string (required); value?: string or { path } binding; variant?: shortText|longText|number|obscured.',\n    },\n    {\n      name: 'CheckBox',\n      description: 'A labeled checkbox.',\n      props:\n        'label: string (required); value: boolean or { path } binding (required).',\n    },\n    {\n      name: 'Slider',\n      description: 'A numeric slider.',\n      props:\n        'max: number (required); value: number or { path } binding (required); label?: string; min?: number; step?: number.',\n    },\n  ],\n};\n\n/**\n * Builds the \"make it look good\" styling tips, scoped to the components the\n * catalog actually provides so a custom catalog is never told to emit\n * components it lacks (which would then fail `validate: 'strict'`).\n */\nfunction renderStyleTips(has: Set<string>): string {\n  const tips: string[] = [];\n  const containers = ['Card', 'Column', 'Row'].filter((c) => has.has(c));\n  if (containers.length) {\n    tips.push(\n      `- Group related content with layout components (${containers.join(\n        '/'\n      )}) and give it a clear hierarchy.`\n    );\n  }\n  if (has.has('Text')) {\n    tips.push(\n      '- Give titles a heading `variant` (e.g. h2/h3) and secondary text the ' +\n        '`caption` variant instead of embedding \"#\"/\"##\" heading markers in ' +\n        'the text.'\n    );\n  }\n  const accents = ['Icon', 'Divider', 'Image'].filter((c) => has.has(c));\n  if (accents.length) {\n    tips.push(\n      `- Use ${accents.join(\n        '/'\n      )} to add visual meaning and separate sections where it helps.`\n    );\n  }\n  if (has.has('Button')) {\n    tips.push('- Give primary buttons `variant: \"primary\"`.');\n  }\n  return tips.length\n    ? `\\n\\nMake it look good, not bland:\\n${tips.join('\\n')}`\n    : '';\n}\n\n/**\n * Builds a worked example. Uses a rich Card/Column/Text layout when the catalog\n * supports it (the common case, e.g. the basic catalog); otherwise falls back\n * to a minimal example built only from components the catalog provides, so the\n * example never references unknown components.\n */\nfunction renderExample(catalog: A2uiCatalog, has: Set<string>): string {\n  if (has.has('Card') && has.has('Column') && has.has('Text')) {\n    return `\n\nExample (a small weather card):\n\\`\\`\\`a2ui\n[\n  { \"createSurface\": { \"surfaceId\": \"SURFACE_ID\", \"catalogId\": \"${catalog.id}\" } },\n  { \"updateComponents\": { \"surfaceId\": \"SURFACE_ID\", \"components\": [\n    { \"id\": \"root\", \"component\": \"Card\", \"child\": \"body\" },\n    { \"id\": \"body\", \"component\": \"Column\", \"children\": [\"title\", \"temp\"] },\n    { \"id\": \"title\", \"component\": \"Text\", \"text\": \"Weather in Tokyo\", \"variant\": \"h3\" },\n    { \"id\": \"temp\", \"component\": \"Text\", \"text\": { \"path\": \"/temp\" } }\n  ] } },\n  { \"updateDataModel\": { \"surfaceId\": \"SURFACE_ID\", \"path\": \"/temp\", \"value\": \"18°C\" } }\n]\n\\`\\`\\``;\n  }\n  // Minimal fallback: root uses whatever the catalog's first component is.\n  const rootComponent = catalog.components[0]?.name ?? 'Text';\n  return `\n\nExample (a minimal surface):\n\\`\\`\\`a2ui\n[\n  { \"createSurface\": { \"surfaceId\": \"SURFACE_ID\", \"catalogId\": \"${catalog.id}\" } },\n  { \"updateComponents\": { \"surfaceId\": \"SURFACE_ID\", \"components\": [\n    { \"id\": \"root\", \"component\": \"${rootComponent}\" }\n  ] } }\n]\n\\`\\`\\``;\n}\n\n/**\n * Renders a catalog into model-facing instructions describing the A2UI protocol\n * and the available components. Injected into the system prompt by the\n * middleware when `instructions !== 'none'`.\n */\nexport function renderCatalogInstructions(catalog: A2uiCatalog): string {\n  const componentDocs = catalog.components\n    .map((c) => `- ${c.name}: ${c.description} Props: ${c.props}`)\n    .join('\\n');\n\n  const has = new Set(catalog.components.map((c) => c.name));\n  const styleSection = renderStyleTips(has);\n  const exampleSection = renderExample(catalog, has);\n\n  // Forms guidance only applies if the catalog has input components.\n  const inputs = ['TextField', 'CheckBox', 'Slider'].filter((c) => has.has(c));\n  const inputList = inputs.join(', ');\n  const formsSection = inputs.length\n    ? `\n- Forms: input components (${inputList}) do NOT send their values automatically.\n  To capture what the user entered you MUST do BOTH of these:\n  1. Bind each input's \\`value\\` to a data-model path, e.g.\n     \\`{ \"component\": \"TextField\", \"label\": \"Email\", \"value\": { \"path\": \"/email\" } }\\`.\n     Typing updates the data model at that path.\n  2. On the submit \\`Button\\`, echo those same paths in\n     \\`action.event.context\\` so their current values are sent back to you, e.g.\n     \\`\"context\": { \"email\": { \"path\": \"/email\" }, \"name\": { \"path\": \"/name\" } }\\`.\n  Without the \\`{ path }\\` bindings and the button \\`context\\`, the action arrives\n  with an empty \\`context\\` and the entered values are lost.`\n    : '';\n\n  return `# Rendering UI with A2UI\n\nYou can render rich, interactive UI (not just text) by emitting an A2UI surface.\nWhen a result is better *shown* than *told* (weather, lists, forms, comparisons,\nconfirmations, anything visual or interactive), render a UI surface.\n\nTo render UI, output a single fenced code block tagged \\`a2ui\\` containing a JSON\narray of A2UI envelope messages. You may still write normal prose before it.\n\nRules:\n- The UI is an ADJACENCY LIST: a flat array of components. Build the tree using\n  string \\`id\\` references, NOT nested objects. Exactly one component MUST have\n  \\`id: \"root\"\\`.\n- Every component has a \\`component\\` (type name) and an \\`id\\`. Container\n  components reference their children by id via a \\`children\\` array; single-child\n  wrappers reference one \\`child\\` id.\n- Values can be literals, or a data-model binding \\`{ \"path\": \"/somePath\" }\\`.\n- Use \\`createSurface\\` first (with \\`catalogId\\`), then \\`updateComponents\\` to add\n  the component list, then optionally \\`updateDataModel\\` to set data. You may\n  combine them in one array, in order.\n- Interactive components fire an \\`action\\` with an event \\`name\\`; that name is\n  sent back to you when the user interacts, so choose meaningful names.${formsSection}\n- When a user interacts with a surface (e.g. presses a button) and you respond\n  with updated UI, RE-RENDER THE WHOLE SURFACE: start again with\n  \\`createSurface\\` followed by \\`updateComponents\\`. Do not emit a bare\n  \\`updateDataModel\\`/\\`updateComponents\\` expecting a previous surface to still\n  exist.${styleSection}\n\nThe catalogId to use is:\n\"${catalog.id}\"\n\nAvailable components:\n${componentDocs}${exampleSection}\n\nDo not explain the JSON; just render the block. Use \"SURFACE_ID\" literally as a\nplaceholder for the surface id — the system replaces it with a real id.`;\n}\n\n/** The literal placeholder the model is told to use for surface ids. */\nexport const SURFACE_ID_PLACEHOLDER = 'SURFACE_ID';\n"],"mappings":"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","names":[]}