@genkit-ai/a2ui 0.5.0-rc.0

package/lib/part.d.mts

@@ -0,0 +1,56 @@
+import { Part } from 'genkit';
+import { A2uiEnvelope, A2uiPart } from './types.mjs';
+
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Helpers for working with the canonical "a2ui part" — a Genkit `data` part
+ * whose `data` is an object `{ envelopes }` wrapping an array of A2UI envelopes,
+ * tagged with {@link A2UI_MIME_TYPE}.
+ *
+ * These helpers operate on plain part-shaped objects (no Genkit runtime import),
+ * so they are safe to use on both the server and the browser. To pull envelopes
+ * off an agent stream, pass the chunk's parts:
+ * `a2uiEnvelopesFromParts(chunk.raw.modelChunk?.content)`.
+ *
+ * @module
+ */
+
+/** Builds an a2ui data part wrapping the given envelopes. */
+declare function a2uiPart(envelopes: A2uiEnvelope[]): A2uiPart;
+/** Type guard: is this part an a2ui data part? */
+declare function isA2uiPart(part: unknown): part is A2uiPart;
+/**
+ * Extracts all A2UI envelopes carried by the given `parts`.
+ *
+ * This is the single entry point for reading envelopes off any part-carrying
+ * value: pass a message's, chunk's, or response's `content`. For example, to
+ * consume an agent stream:
+ *
+ * ```ts
+ * for await (const chunk of turn.stream) {
+ *   const envelopes = a2uiEnvelopesFromParts(chunk.raw.modelChunk?.content);
+ * }
+ * ```
+ *
+ * `parts` is nullable purely for call-site convenience (a chunk's content can
+ * be `undefined`); a nullish list is treated as empty.
+ *
+ * Returns `[]` for content that carries no a2ui parts (e.g. plain prose).
+ */
+declare function a2uiEnvelopesFromParts(parts: readonly Part[] | null | undefined): A2uiEnvelope[];
+
+export { a2uiEnvelopesFromParts, a2uiPart, isA2uiPart };

package/lib/part.d.ts

@@ -0,0 +1,56 @@
+import { Part } from 'genkit';
+import { A2uiEnvelope, A2uiPart } from './types.js';
+
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Helpers for working with the canonical "a2ui part" — a Genkit `data` part
+ * whose `data` is an object `{ envelopes }` wrapping an array of A2UI envelopes,
+ * tagged with {@link A2UI_MIME_TYPE}.
+ *
+ * These helpers operate on plain part-shaped objects (no Genkit runtime import),
+ * so they are safe to use on both the server and the browser. To pull envelopes
+ * off an agent stream, pass the chunk's parts:
+ * `a2uiEnvelopesFromParts(chunk.raw.modelChunk?.content)`.
+ *
+ * @module
+ */
+
+/** Builds an a2ui data part wrapping the given envelopes. */
+declare function a2uiPart(envelopes: A2uiEnvelope[]): A2uiPart;
+/** Type guard: is this part an a2ui data part? */
+declare function isA2uiPart(part: unknown): part is A2uiPart;
+/**
+ * Extracts all A2UI envelopes carried by the given `parts`.
+ *
+ * This is the single entry point for reading envelopes off any part-carrying
+ * value: pass a message's, chunk's, or response's `content`. For example, to
+ * consume an agent stream:
+ *
+ * ```ts
+ * for await (const chunk of turn.stream) {
+ *   const envelopes = a2uiEnvelopesFromParts(chunk.raw.modelChunk?.content);
+ * }
+ * ```
+ *
+ * `parts` is nullable purely for call-site convenience (a chunk's content can
+ * be `undefined`); a nullish list is treated as empty.
+ *
+ * Returns `[]` for content that carries no a2ui parts (e.g. plain prose).
+ */
+declare function a2uiEnvelopesFromParts(parts: readonly Part[] | null | undefined): A2uiEnvelope[];
+
+export { a2uiEnvelopesFromParts, a2uiPart, isA2uiPart };

package/lib/part.js

@@ -0,0 +1,52 @@
+"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 part_exports = {};
+__export(part_exports, {
+  a2uiEnvelopesFromParts: () => a2uiEnvelopesFromParts,
+  a2uiPart: () => a2uiPart,
+  isA2uiPart: () => isA2uiPart
+});
+module.exports = __toCommonJS(part_exports);
+var import_types = require("./types.js");
+function a2uiPart(envelopes) {
+  return {
+    data: { envelopes },
+    metadata: { mimeType: import_types.A2UI_MIME_TYPE }
+  };
+}
+function isA2uiPart(part) {
+  const p = part;
+  const data = p?.data;
+  return !!p && typeof p === "object" && !!data && typeof data === "object" && Array.isArray(data.envelopes) && p.metadata?.mimeType === import_types.A2UI_MIME_TYPE;
+}
+function a2uiEnvelopesFromParts(parts) {
+  if (!Array.isArray(parts)) return [];
+  const out = [];
+  for (const part of parts) {
+    if (isA2uiPart(part)) out.push(...part.data.envelopes);
+  }
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  a2uiEnvelopesFromParts,
+  a2uiPart,
+  isA2uiPart
+});
+//# sourceMappingURL=part.js.map

package/lib/part.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/part.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 * Helpers for working with the canonical \"a2ui part\" — a Genkit `data` part\n * whose `data` is an object `{ envelopes }` wrapping an array of A2UI envelopes,\n * tagged with {@link A2UI_MIME_TYPE}.\n *\n * These helpers operate on plain part-shaped objects (no Genkit runtime import),\n * so they are safe to use on both the server and the browser. To pull envelopes\n * off an agent stream, pass the chunk's parts:\n * `a2uiEnvelopesFromParts(chunk.raw.modelChunk?.content)`.\n *\n * @module\n */\n\nimport { type Part } from 'genkit';\nimport { A2UI_MIME_TYPE, type A2uiEnvelope, type A2uiPart } from './types.js';\n\n/** A minimal structural view of a Genkit part for these helpers. */\ninterface PartLike {\n  data?: unknown;\n  metadata?: Record<string, unknown> | null;\n  [key: string]: unknown;\n}\n\n/** Builds an a2ui data part wrapping the given envelopes. */\nexport function a2uiPart(envelopes: A2uiEnvelope[]): A2uiPart {\n  return {\n    data: { envelopes },\n    metadata: { mimeType: A2UI_MIME_TYPE },\n  };\n}\n\n/** Type guard: is this part an a2ui data part? */\nexport function isA2uiPart(part: unknown): part is A2uiPart {\n  const p = part as PartLike | null | undefined;\n  const data = p?.data as { envelopes?: unknown } | undefined;\n  return (\n    !!p &&\n    typeof p === 'object' &&\n    !!data &&\n    typeof data === 'object' &&\n    Array.isArray(data.envelopes) &&\n    (p as PartLike).metadata?.mimeType === A2UI_MIME_TYPE\n  );\n}\n\n/**\n * Extracts all A2UI envelopes carried by the given `parts`.\n *\n * This is the single entry point for reading envelopes off any part-carrying\n * value: pass a message's, chunk's, or response's `content`. For example, to\n * consume an agent stream:\n *\n * ```ts\n * for await (const chunk of turn.stream) {\n *   const envelopes = a2uiEnvelopesFromParts(chunk.raw.modelChunk?.content);\n * }\n * ```\n *\n * `parts` is nullable purely for call-site convenience (a chunk's content can\n * be `undefined`); a nullish list is treated as empty.\n *\n * Returns `[]` for content that carries no a2ui parts (e.g. plain prose).\n */\nexport function a2uiEnvelopesFromParts(\n  parts: readonly Part[] | null | undefined\n): A2uiEnvelope[] {\n  if (!Array.isArray(parts)) return [];\n  const out: A2uiEnvelope[] = [];\n  for (const part of parts) {\n    if (isA2uiPart(part)) out.push(...part.data.envelopes);\n  }\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8BA,mBAAiE;AAU1D,SAAS,SAAS,WAAqC;AAC5D,SAAO;AAAA,IACL,MAAM,EAAE,UAAU;AAAA,IAClB,UAAU,EAAE,UAAU,4BAAe;AAAA,EACvC;AACF;AAGO,SAAS,WAAW,MAAiC;AAC1D,QAAM,IAAI;AACV,QAAM,OAAO,GAAG;AAChB,SACE,CAAC,CAAC,KACF,OAAO,MAAM,YACb,CAAC,CAAC,QACF,OAAO,SAAS,YAChB,MAAM,QAAQ,KAAK,SAAS,KAC3B,EAAe,UAAU,aAAa;AAE3C;AAoBO,SAAS,uBACd,OACgB;AAChB,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO,CAAC;AACnC,QAAM,MAAsB,CAAC;AAC7B,aAAW,QAAQ,OAAO;AACxB,QAAI,WAAW,IAAI,EAAG,KAAI,KAAK,GAAG,KAAK,KAAK,SAAS;AAAA,EACvD;AACA,SAAO;AACT;","names":[]}

package/lib/part.mjs

@@ -0,0 +1,26 @@
+import { A2UI_MIME_TYPE } from "./types.mjs";
+function a2uiPart(envelopes) {
+  return {
+    data: { envelopes },
+    metadata: { mimeType: A2UI_MIME_TYPE }
+  };
+}
+function isA2uiPart(part) {
+  const p = part;
+  const data = p?.data;
+  return !!p && typeof p === "object" && !!data && typeof data === "object" && Array.isArray(data.envelopes) && p.metadata?.mimeType === A2UI_MIME_TYPE;
+}
+function a2uiEnvelopesFromParts(parts) {
+  if (!Array.isArray(parts)) return [];
+  const out = [];
+  for (const part of parts) {
+    if (isA2uiPart(part)) out.push(...part.data.envelopes);
+  }
+  return out;
+}
+export {
+  a2uiEnvelopesFromParts,
+  a2uiPart,
+  isA2uiPart
+};
+//# sourceMappingURL=part.mjs.map

package/lib/part.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/part.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 * Helpers for working with the canonical \"a2ui part\" — a Genkit `data` part\n * whose `data` is an object `{ envelopes }` wrapping an array of A2UI envelopes,\n * tagged with {@link A2UI_MIME_TYPE}.\n *\n * These helpers operate on plain part-shaped objects (no Genkit runtime import),\n * so they are safe to use on both the server and the browser. To pull envelopes\n * off an agent stream, pass the chunk's parts:\n * `a2uiEnvelopesFromParts(chunk.raw.modelChunk?.content)`.\n *\n * @module\n */\n\nimport { type Part } from 'genkit';\nimport { A2UI_MIME_TYPE, type A2uiEnvelope, type A2uiPart } from './types.mjs';\n\n/** A minimal structural view of a Genkit part for these helpers. */\ninterface PartLike {\n  data?: unknown;\n  metadata?: Record<string, unknown> | null;\n  [key: string]: unknown;\n}\n\n/** Builds an a2ui data part wrapping the given envelopes. */\nexport function a2uiPart(envelopes: A2uiEnvelope[]): A2uiPart {\n  return {\n    data: { envelopes },\n    metadata: { mimeType: A2UI_MIME_TYPE },\n  };\n}\n\n/** Type guard: is this part an a2ui data part? */\nexport function isA2uiPart(part: unknown): part is A2uiPart {\n  const p = part as PartLike | null | undefined;\n  const data = p?.data as { envelopes?: unknown } | undefined;\n  return (\n    !!p &&\n    typeof p === 'object' &&\n    !!data &&\n    typeof data === 'object' &&\n    Array.isArray(data.envelopes) &&\n    (p as PartLike).metadata?.mimeType === A2UI_MIME_TYPE\n  );\n}\n\n/**\n * Extracts all A2UI envelopes carried by the given `parts`.\n *\n * This is the single entry point for reading envelopes off any part-carrying\n * value: pass a message's, chunk's, or response's `content`. For example, to\n * consume an agent stream:\n *\n * ```ts\n * for await (const chunk of turn.stream) {\n *   const envelopes = a2uiEnvelopesFromParts(chunk.raw.modelChunk?.content);\n * }\n * ```\n *\n * `parts` is nullable purely for call-site convenience (a chunk's content can\n * be `undefined`); a nullish list is treated as empty.\n *\n * Returns `[]` for content that carries no a2ui parts (e.g. plain prose).\n */\nexport function a2uiEnvelopesFromParts(\n  parts: readonly Part[] | null | undefined\n): A2uiEnvelope[] {\n  if (!Array.isArray(parts)) return [];\n  const out: A2uiEnvelope[] = [];\n  for (const part of parts) {\n    if (isA2uiPart(part)) out.push(...part.data.envelopes);\n  }\n  return out;\n}\n"],"mappings":"AA8BA,SAAS,sBAAwD;AAU1D,SAAS,SAAS,WAAqC;AAC5D,SAAO;AAAA,IACL,MAAM,EAAE,UAAU;AAAA,IAClB,UAAU,EAAE,UAAU,eAAe;AAAA,EACvC;AACF;AAGO,SAAS,WAAW,MAAiC;AAC1D,QAAM,IAAI;AACV,QAAM,OAAO,GAAG;AAChB,SACE,CAAC,CAAC,KACF,OAAO,MAAM,YACb,CAAC,CAAC,QACF,OAAO,SAAS,YAChB,MAAM,QAAQ,KAAK,SAAS,KAC3B,EAAe,UAAU,aAAa;AAE3C;AAoBO,SAAS,uBACd,OACgB;AAChB,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO,CAAC;AACnC,QAAM,MAAsB,CAAC;AAC7B,aAAW,QAAQ,OAAO;AACxB,QAAI,WAAW,IAAI,EAAG,KAAI,KAAK,GAAG,KAAK,KAAK,SAAS;AAAA,EACvD;AACA,SAAO;AACT;","names":[]}

package/lib/types.d.mts

@@ -0,0 +1,153 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Shared A2UI protocol types and constants.
+ *
+ * This module is intentionally free of any Node-only dependencies so it can be
+ * imported both on the server (the {@link a2ui} middleware) and in the browser
+ * (the client transport helpers). It mirrors the wire shapes of the A2UI v0.9
+ * specification without depending on `@a2ui/web_core` (the renderer packages are
+ * only needed on the client).
+ *
+ * @module
+ */
+/**
+ * The MIME type that identifies an A2UI payload. This is stamped onto the
+ * `metadata.mimeType` of the Genkit `data` part that carries A2UI envelopes,
+ * matching the A2A binding of the A2UI spec exactly.
+ */
+declare const A2UI_MIME_TYPE = "application/a2ui+json";
+/** The default A2UI protocol version stamped on emitted envelopes. */
+declare const A2UI_VERSION = "v0.9";
+/**
+ * The catalog id of the A2UI "Basic Catalog" (v0.9). Surfaces created with the
+ * basic catalog reference this id, and the client renderer registers a catalog
+ * under the same id.
+ */
+declare const BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json";
+/**
+ * The protocol versions this plugin knows how to emit. This is the single
+ * source of truth: {@link SupportedVersion} is derived from it, and the
+ * middleware's `version` config validates against it (so a typo like `'v0.10'`
+ * is rejected at config time rather than producing envelopes the renderer
+ * rejects at runtime).
+ */
+declare const SUPPORTED_VERSIONS: readonly ["v0.9", "v0.9.1"];
+type SupportedVersion = (typeof SUPPORTED_VERSIONS)[number];
+/**
+ * A single component entry in an A2UI adjacency list. UI is expressed as a flat
+ * list of components; the tree is reconstructed via `id` references. Exactly one
+ * component has `id: "root"`.
+ *
+ * Beyond `component`/`id`/`weight`, every component carries catalog-specific
+ * props (e.g. `text`, `children`, `child`, `action`), so this is intentionally
+ * open-ended.
+ */
+interface A2uiComponent {
+    /** The catalog component type name, e.g. `Text`, `Column`, `Button`. */
+    component: string;
+    /** The unique id of this component. Exactly one component must be `"root"`. */
+    id?: string;
+    /** Relative flex weight when nested directly in a Row/Column. */
+    weight?: number;
+    /** Catalog-specific component props. */
+    [prop: string]: unknown;
+}
+/** Creates (or re-initializes) a UI surface. */
+interface CreateSurfaceEnvelope {
+    version: SupportedVersion;
+    createSurface: {
+        surfaceId: string;
+        catalogId: string;
+        theme?: unknown;
+        sendDataModel?: boolean;
+    };
+}
+/** Adds or replaces components on an existing surface. */
+interface UpdateComponentsEnvelope {
+    version: SupportedVersion;
+    updateComponents: {
+        surfaceId: string;
+        components: A2uiComponent[];
+    };
+}
+/** Mutates a value in a surface's per-surface data model. */
+interface UpdateDataModelEnvelope {
+    version: SupportedVersion;
+    updateDataModel: {
+        surfaceId: string;
+        /** JSON-Pointer path. When omitted, `value` replaces the whole model. */
+        path?: string;
+        value?: unknown;
+    };
+}
+/** Removes a surface. */
+interface DeleteSurfaceEnvelope {
+    version: SupportedVersion;
+    deleteSurface: {
+        surfaceId: string;
+    };
+}
+/**
+ * A user action reported by a rendered surface (client → server), wrapped as an
+ * envelope so it rides the same a2ui part channel as server → client envelopes.
+ * This is the typed shape {@link actionToMessage} produces and
+ * {@link A2uiEnvelope} recognizes on the way back in.
+ */
+interface ActionEnvelope {
+    action: A2uiClientAction;
+}
+/**
+ * A single A2UI envelope message.
+ *
+ * Most variants flow server → client (surfaces the agent renders); the
+ * {@link ActionEnvelope} variant flows client → server (a user interaction sent
+ * back as the next turn). Keeping both directions in one union lets
+ * {@link a2uiPart} be the single constructor for every a2ui part.
+ */
+type A2uiEnvelope = CreateSurfaceEnvelope | UpdateComponentsEnvelope | UpdateDataModelEnvelope | DeleteSurfaceEnvelope | ActionEnvelope;
+/**
+ * The canonical "a2ui part": a Genkit `data` part whose `data` is an object
+ * `{ envelopes }` wrapping the array of A2UI envelopes, and whose
+ * `metadata.mimeType` is {@link A2UI_MIME_TYPE}.
+ *
+ * The array is wrapped in an object (rather than being the `data` value
+ * directly) so the payload is a `Map<String, dynamic>`-shaped object on every
+ * runtime — some (e.g. Dart) expect a data part's `data` to be an object, not a
+ * bare array.
+ */
+interface A2uiPart {
+    data: {
+        envelopes: A2uiEnvelope[];
+    };
+    metadata: {
+        mimeType: typeof A2UI_MIME_TYPE;
+        [key: string]: unknown;
+    };
+}
+/**
+ * A client → server user action reported by a rendered surface (e.g. a button
+ * press). Sent back to the agent as the next turn's input.
+ */
+interface A2uiClientAction {
+    name: string;
+    surfaceId: string;
+    sourceComponentId: string;
+    timestamp: string;
+    context: Record<string, unknown>;
+}
+
+export { A2UI_MIME_TYPE, A2UI_VERSION, type A2uiClientAction, type A2uiComponent, type A2uiEnvelope, type A2uiPart, type ActionEnvelope, BASIC_CATALOG_ID, type CreateSurfaceEnvelope, type DeleteSurfaceEnvelope, SUPPORTED_VERSIONS, type SupportedVersion, type UpdateComponentsEnvelope, type UpdateDataModelEnvelope };

package/lib/types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Shared A2UI protocol types and constants.
+ *
+ * This module is intentionally free of any Node-only dependencies so it can be
+ * imported both on the server (the {@link a2ui} middleware) and in the browser
+ * (the client transport helpers). It mirrors the wire shapes of the A2UI v0.9
+ * specification without depending on `@a2ui/web_core` (the renderer packages are
+ * only needed on the client).
+ *
+ * @module
+ */
+/**
+ * The MIME type that identifies an A2UI payload. This is stamped onto the
+ * `metadata.mimeType` of the Genkit `data` part that carries A2UI envelopes,
+ * matching the A2A binding of the A2UI spec exactly.
+ */
+declare const A2UI_MIME_TYPE = "application/a2ui+json";
+/** The default A2UI protocol version stamped on emitted envelopes. */
+declare const A2UI_VERSION = "v0.9";
+/**
+ * The catalog id of the A2UI "Basic Catalog" (v0.9). Surfaces created with the
+ * basic catalog reference this id, and the client renderer registers a catalog
+ * under the same id.
+ */
+declare const BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json";
+/**
+ * The protocol versions this plugin knows how to emit. This is the single
+ * source of truth: {@link SupportedVersion} is derived from it, and the
+ * middleware's `version` config validates against it (so a typo like `'v0.10'`
+ * is rejected at config time rather than producing envelopes the renderer
+ * rejects at runtime).
+ */
+declare const SUPPORTED_VERSIONS: readonly ["v0.9", "v0.9.1"];
+type SupportedVersion = (typeof SUPPORTED_VERSIONS)[number];
+/**
+ * A single component entry in an A2UI adjacency list. UI is expressed as a flat
+ * list of components; the tree is reconstructed via `id` references. Exactly one
+ * component has `id: "root"`.
+ *
+ * Beyond `component`/`id`/`weight`, every component carries catalog-specific
+ * props (e.g. `text`, `children`, `child`, `action`), so this is intentionally
+ * open-ended.
+ */
+interface A2uiComponent {
+    /** The catalog component type name, e.g. `Text`, `Column`, `Button`. */
+    component: string;
+    /** The unique id of this component. Exactly one component must be `"root"`. */
+    id?: string;
+    /** Relative flex weight when nested directly in a Row/Column. */
+    weight?: number;
+    /** Catalog-specific component props. */
+    [prop: string]: unknown;
+}
+/** Creates (or re-initializes) a UI surface. */
+interface CreateSurfaceEnvelope {
+    version: SupportedVersion;
+    createSurface: {
+        surfaceId: string;
+        catalogId: string;
+        theme?: unknown;
+        sendDataModel?: boolean;
+    };
+}
+/** Adds or replaces components on an existing surface. */
+interface UpdateComponentsEnvelope {
+    version: SupportedVersion;
+    updateComponents: {
+        surfaceId: string;
+        components: A2uiComponent[];
+    };
+}
+/** Mutates a value in a surface's per-surface data model. */
+interface UpdateDataModelEnvelope {
+    version: SupportedVersion;
+    updateDataModel: {
+        surfaceId: string;
+        /** JSON-Pointer path. When omitted, `value` replaces the whole model. */
+        path?: string;
+        value?: unknown;
+    };
+}
+/** Removes a surface. */
+interface DeleteSurfaceEnvelope {
+    version: SupportedVersion;
+    deleteSurface: {
+        surfaceId: string;
+    };
+}
+/**
+ * A user action reported by a rendered surface (client → server), wrapped as an
+ * envelope so it rides the same a2ui part channel as server → client envelopes.
+ * This is the typed shape {@link actionToMessage} produces and
+ * {@link A2uiEnvelope} recognizes on the way back in.
+ */
+interface ActionEnvelope {
+    action: A2uiClientAction;
+}
+/**
+ * A single A2UI envelope message.
+ *
+ * Most variants flow server → client (surfaces the agent renders); the
+ * {@link ActionEnvelope} variant flows client → server (a user interaction sent
+ * back as the next turn). Keeping both directions in one union lets
+ * {@link a2uiPart} be the single constructor for every a2ui part.
+ */
+type A2uiEnvelope = CreateSurfaceEnvelope | UpdateComponentsEnvelope | UpdateDataModelEnvelope | DeleteSurfaceEnvelope | ActionEnvelope;
+/**
+ * The canonical "a2ui part": a Genkit `data` part whose `data` is an object
+ * `{ envelopes }` wrapping the array of A2UI envelopes, and whose
+ * `metadata.mimeType` is {@link A2UI_MIME_TYPE}.
+ *
+ * The array is wrapped in an object (rather than being the `data` value
+ * directly) so the payload is a `Map<String, dynamic>`-shaped object on every
+ * runtime — some (e.g. Dart) expect a data part's `data` to be an object, not a
+ * bare array.
+ */
+interface A2uiPart {
+    data: {
+        envelopes: A2uiEnvelope[];
+    };
+    metadata: {
+        mimeType: typeof A2UI_MIME_TYPE;
+        [key: string]: unknown;
+    };
+}
+/**
+ * A client → server user action reported by a rendered surface (e.g. a button
+ * press). Sent back to the agent as the next turn's input.
+ */
+interface A2uiClientAction {
+    name: string;
+    surfaceId: string;
+    sourceComponentId: string;
+    timestamp: string;
+    context: Record<string, unknown>;
+}
+
+export { A2UI_MIME_TYPE, A2UI_VERSION, type A2uiClientAction, type A2uiComponent, type A2uiEnvelope, type A2uiPart, type ActionEnvelope, BASIC_CATALOG_ID, type CreateSurfaceEnvelope, type DeleteSurfaceEnvelope, SUPPORTED_VERSIONS, type SupportedVersion, type UpdateComponentsEnvelope, type UpdateDataModelEnvelope };

package/lib/types.js

@@ -0,0 +1,38 @@
+"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 types_exports = {};
+__export(types_exports, {
+  A2UI_MIME_TYPE: () => A2UI_MIME_TYPE,
+  A2UI_VERSION: () => A2UI_VERSION,
+  BASIC_CATALOG_ID: () => BASIC_CATALOG_ID,
+  SUPPORTED_VERSIONS: () => SUPPORTED_VERSIONS
+});
+module.exports = __toCommonJS(types_exports);
+const A2UI_MIME_TYPE = "application/a2ui+json";
+const A2UI_VERSION = "v0.9";
+const BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json";
+const SUPPORTED_VERSIONS = ["v0.9", "v0.9.1"];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  A2UI_MIME_TYPE,
+  A2UI_VERSION,
+  BASIC_CATALOG_ID,
+  SUPPORTED_VERSIONS
+});
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.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 * Shared A2UI protocol types and constants.\n *\n * This module is intentionally free of any Node-only dependencies so it can be\n * imported both on the server (the {@link a2ui} middleware) and in the browser\n * (the client transport helpers). It mirrors the wire shapes of the A2UI v0.9\n * specification without depending on `@a2ui/web_core` (the renderer packages are\n * only needed on the client).\n *\n * @module\n */\n\n/**\n * The MIME type that identifies an A2UI payload. This is stamped onto the\n * `metadata.mimeType` of the Genkit `data` part that carries A2UI envelopes,\n * matching the A2A binding of the A2UI spec exactly.\n */\nexport const A2UI_MIME_TYPE = 'application/a2ui+json';\n\n/** The default A2UI protocol version stamped on emitted envelopes. */\nexport const A2UI_VERSION = 'v0.9';\n\n/**\n * The catalog id of the A2UI \"Basic Catalog\" (v0.9). Surfaces created with the\n * basic catalog reference this id, and the client renderer registers a catalog\n * under the same id.\n */\nexport const BASIC_CATALOG_ID =\n  'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json';\n\n/**\n * The protocol versions this plugin knows how to emit. This is the single\n * source of truth: {@link SupportedVersion} is derived from it, and the\n * middleware's `version` config validates against it (so a typo like `'v0.10'`\n * is rejected at config time rather than producing envelopes the renderer\n * rejects at runtime).\n */\nexport const SUPPORTED_VERSIONS = ['v0.9', 'v0.9.1'] as const;\n\nexport type SupportedVersion = (typeof SUPPORTED_VERSIONS)[number];\n\n/**\n * A single component entry in an A2UI adjacency list. UI is expressed as a flat\n * list of components; the tree is reconstructed via `id` references. Exactly one\n * component has `id: \"root\"`.\n *\n * Beyond `component`/`id`/`weight`, every component carries catalog-specific\n * props (e.g. `text`, `children`, `child`, `action`), so this is intentionally\n * open-ended.\n */\nexport interface A2uiComponent {\n  /** The catalog component type name, e.g. `Text`, `Column`, `Button`. */\n  component: string;\n  /** The unique id of this component. Exactly one component must be `\"root\"`. */\n  id?: string;\n  /** Relative flex weight when nested directly in a Row/Column. */\n  weight?: number;\n  /** Catalog-specific component props. */\n  [prop: string]: unknown;\n}\n\n/** Creates (or re-initializes) a UI surface. */\nexport interface CreateSurfaceEnvelope {\n  version: SupportedVersion;\n  createSurface: {\n    surfaceId: string;\n    catalogId: string;\n    theme?: unknown;\n    sendDataModel?: boolean;\n  };\n}\n\n/** Adds or replaces components on an existing surface. */\nexport interface UpdateComponentsEnvelope {\n  version: SupportedVersion;\n  updateComponents: {\n    surfaceId: string;\n    components: A2uiComponent[];\n  };\n}\n\n/** Mutates a value in a surface's per-surface data model. */\nexport interface UpdateDataModelEnvelope {\n  version: SupportedVersion;\n  updateDataModel: {\n    surfaceId: string;\n    /** JSON-Pointer path. When omitted, `value` replaces the whole model. */\n    path?: string;\n    value?: unknown;\n  };\n}\n\n/** Removes a surface. */\nexport interface DeleteSurfaceEnvelope {\n  version: SupportedVersion;\n  deleteSurface: {\n    surfaceId: string;\n  };\n}\n\n/**\n * A user action reported by a rendered surface (client → server), wrapped as an\n * envelope so it rides the same a2ui part channel as server → client envelopes.\n * This is the typed shape {@link actionToMessage} produces and\n * {@link A2uiEnvelope} recognizes on the way back in.\n */\nexport interface ActionEnvelope {\n  action: A2uiClientAction;\n}\n\n/**\n * A single A2UI envelope message.\n *\n * Most variants flow server → client (surfaces the agent renders); the\n * {@link ActionEnvelope} variant flows client → server (a user interaction sent\n * back as the next turn). Keeping both directions in one union lets\n * {@link a2uiPart} be the single constructor for every a2ui part.\n */\nexport type A2uiEnvelope =\n  | CreateSurfaceEnvelope\n  | UpdateComponentsEnvelope\n  | UpdateDataModelEnvelope\n  | DeleteSurfaceEnvelope\n  | ActionEnvelope;\n\n/**\n * The canonical \"a2ui part\": a Genkit `data` part whose `data` is an object\n * `{ envelopes }` wrapping the array of A2UI envelopes, and whose\n * `metadata.mimeType` is {@link A2UI_MIME_TYPE}.\n *\n * The array is wrapped in an object (rather than being the `data` value\n * directly) so the payload is a `Map<String, dynamic>`-shaped object on every\n * runtime — some (e.g. Dart) expect a data part's `data` to be an object, not a\n * bare array.\n */\nexport interface A2uiPart {\n  data: { envelopes: A2uiEnvelope[] };\n  metadata: {\n    mimeType: typeof A2UI_MIME_TYPE;\n    [key: string]: unknown;\n  };\n}\n\n/**\n * A client → server user action reported by a rendered surface (e.g. a button\n * press). Sent back to the agent as the next turn's input.\n */\nexport interface A2uiClientAction {\n  name: string;\n  surfaceId: string;\n  sourceComponentId: string;\n  timestamp: string;\n  context: Record<string, unknown>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiCO,MAAM,iBAAiB;AAGvB,MAAM,eAAe;AAOrB,MAAM,mBACX;AASK,MAAM,qBAAqB,CAAC,QAAQ,QAAQ;","names":[]}

package/lib/types.mjs

@@ -0,0 +1,11 @@
+const A2UI_MIME_TYPE = "application/a2ui+json";
+const A2UI_VERSION = "v0.9";
+const BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json";
+const SUPPORTED_VERSIONS = ["v0.9", "v0.9.1"];
+export {
+  A2UI_MIME_TYPE,
+  A2UI_VERSION,
+  BASIC_CATALOG_ID,
+  SUPPORTED_VERSIONS
+};
+//# sourceMappingURL=types.mjs.map

package/lib/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.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 * Shared A2UI protocol types and constants.\n *\n * This module is intentionally free of any Node-only dependencies so it can be\n * imported both on the server (the {@link a2ui} middleware) and in the browser\n * (the client transport helpers). It mirrors the wire shapes of the A2UI v0.9\n * specification without depending on `@a2ui/web_core` (the renderer packages are\n * only needed on the client).\n *\n * @module\n */\n\n/**\n * The MIME type that identifies an A2UI payload. This is stamped onto the\n * `metadata.mimeType` of the Genkit `data` part that carries A2UI envelopes,\n * matching the A2A binding of the A2UI spec exactly.\n */\nexport const A2UI_MIME_TYPE = 'application/a2ui+json';\n\n/** The default A2UI protocol version stamped on emitted envelopes. */\nexport const A2UI_VERSION = 'v0.9';\n\n/**\n * The catalog id of the A2UI \"Basic Catalog\" (v0.9). Surfaces created with the\n * basic catalog reference this id, and the client renderer registers a catalog\n * under the same id.\n */\nexport const BASIC_CATALOG_ID =\n  'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json';\n\n/**\n * The protocol versions this plugin knows how to emit. This is the single\n * source of truth: {@link SupportedVersion} is derived from it, and the\n * middleware's `version` config validates against it (so a typo like `'v0.10'`\n * is rejected at config time rather than producing envelopes the renderer\n * rejects at runtime).\n */\nexport const SUPPORTED_VERSIONS = ['v0.9', 'v0.9.1'] as const;\n\nexport type SupportedVersion = (typeof SUPPORTED_VERSIONS)[number];\n\n/**\n * A single component entry in an A2UI adjacency list. UI is expressed as a flat\n * list of components; the tree is reconstructed via `id` references. Exactly one\n * component has `id: \"root\"`.\n *\n * Beyond `component`/`id`/`weight`, every component carries catalog-specific\n * props (e.g. `text`, `children`, `child`, `action`), so this is intentionally\n * open-ended.\n */\nexport interface A2uiComponent {\n  /** The catalog component type name, e.g. `Text`, `Column`, `Button`. */\n  component: string;\n  /** The unique id of this component. Exactly one component must be `\"root\"`. */\n  id?: string;\n  /** Relative flex weight when nested directly in a Row/Column. */\n  weight?: number;\n  /** Catalog-specific component props. */\n  [prop: string]: unknown;\n}\n\n/** Creates (or re-initializes) a UI surface. */\nexport interface CreateSurfaceEnvelope {\n  version: SupportedVersion;\n  createSurface: {\n    surfaceId: string;\n    catalogId: string;\n    theme?: unknown;\n    sendDataModel?: boolean;\n  };\n}\n\n/** Adds or replaces components on an existing surface. */\nexport interface UpdateComponentsEnvelope {\n  version: SupportedVersion;\n  updateComponents: {\n    surfaceId: string;\n    components: A2uiComponent[];\n  };\n}\n\n/** Mutates a value in a surface's per-surface data model. */\nexport interface UpdateDataModelEnvelope {\n  version: SupportedVersion;\n  updateDataModel: {\n    surfaceId: string;\n    /** JSON-Pointer path. When omitted, `value` replaces the whole model. */\n    path?: string;\n    value?: unknown;\n  };\n}\n\n/** Removes a surface. */\nexport interface DeleteSurfaceEnvelope {\n  version: SupportedVersion;\n  deleteSurface: {\n    surfaceId: string;\n  };\n}\n\n/**\n * A user action reported by a rendered surface (client → server), wrapped as an\n * envelope so it rides the same a2ui part channel as server → client envelopes.\n * This is the typed shape {@link actionToMessage} produces and\n * {@link A2uiEnvelope} recognizes on the way back in.\n */\nexport interface ActionEnvelope {\n  action: A2uiClientAction;\n}\n\n/**\n * A single A2UI envelope message.\n *\n * Most variants flow server → client (surfaces the agent renders); the\n * {@link ActionEnvelope} variant flows client → server (a user interaction sent\n * back as the next turn). Keeping both directions in one union lets\n * {@link a2uiPart} be the single constructor for every a2ui part.\n */\nexport type A2uiEnvelope =\n  | CreateSurfaceEnvelope\n  | UpdateComponentsEnvelope\n  | UpdateDataModelEnvelope\n  | DeleteSurfaceEnvelope\n  | ActionEnvelope;\n\n/**\n * The canonical \"a2ui part\": a Genkit `data` part whose `data` is an object\n * `{ envelopes }` wrapping the array of A2UI envelopes, and whose\n * `metadata.mimeType` is {@link A2UI_MIME_TYPE}.\n *\n * The array is wrapped in an object (rather than being the `data` value\n * directly) so the payload is a `Map<String, dynamic>`-shaped object on every\n * runtime — some (e.g. Dart) expect a data part's `data` to be an object, not a\n * bare array.\n */\nexport interface A2uiPart {\n  data: { envelopes: A2uiEnvelope[] };\n  metadata: {\n    mimeType: typeof A2UI_MIME_TYPE;\n    [key: string]: unknown;\n  };\n}\n\n/**\n * A client → server user action reported by a rendered surface (e.g. a button\n * press). Sent back to the agent as the next turn's input.\n */\nexport interface A2uiClientAction {\n  name: string;\n  surfaceId: string;\n  sourceComponentId: string;\n  timestamp: string;\n  context: Record<string, unknown>;\n}\n"],"mappings":"AAiCO,MAAM,iBAAiB;AAGvB,MAAM,eAAe;AAOrB,MAAM,mBACX;AASK,MAAM,qBAAqB,CAAC,QAAQ,QAAQ;","names":[]}