@genkit-ai/a2ui 0.5.0-rc.0

package/lib/middleware.mjs

@@ -0,0 +1,240 @@
+import { generateMiddleware, z } from "genkit";
+import {
+  DEFAULT_CATALOG_ID,
+  renderCatalogInstructions
+} from "./catalog.mjs";
+import { resolveCatalog } from "./loader.mjs";
+import { A2uiStreamParser } from "./parser.mjs";
+import { a2uiPart, isA2uiPart } from "./part.mjs";
+import {
+  A2UI_VERSION,
+  SUPPORTED_VERSIONS
+} from "./types.mjs";
+const A2uiOptionsSchema = z.object({
+  /**
+   * The id of the catalog describing what the agent may render. Defaults to
+   * `'basic'` (the bundled basic catalog). Register additional catalogs with
+   * `loadCatalog(ai, { id, catalog | file })` and reference them by id here.
+   */
+  catalog: z.string().optional(),
+  /**
+   * Where to inject the catalog's capabilities. `'system'` (default) appends
+   * A2UI instructions to the system prompt; `'none'` injects nothing (useful if
+   * you supply your own instructions).
+   */
+  instructions: z.enum(["system", "none"]).optional(),
+  /**
+   * Validate emitted envelopes against the catalog. `'warn'` (default) logs a
+   * warning and drops the offending block/envelope, keeping the rest of the
+   * turn alive; `'strict'` throws on malformed JSON or unknown components (best
+   * for development); `'off'` passes them through unchecked.
+   *
+   * IMPORTANT: this validates envelope structure and component *type names*
+   * against the catalog only. It does NOT validate component props or
+   * data-model values. Model-controlled values such as `Image.url` and `Text`
+   * (inline Markdown, which the renderer may turn into HTML) pass through
+   * untouched even under `'strict'`. `'strict'` is a well-formedness check, not
+   * a security boundary — see the "Security / trust boundary" section of the
+   * README. Prop sanitization is the renderer/catalog's responsibility, and
+   * hosts should CSP-restrict image and other remote sources.
+   */
+  validate: z.enum(["strict", "warn", "off"]).optional(),
+  /**
+   * Surface id policy. Provide a fixed id to reuse for every surface. Defaults
+   * to a fresh UUID per surface.
+   */
+  surfaceId: z.string().optional(),
+  /**
+   * Protocol version stamped on emitted envelopes. Defaults to `'v0.9'`.
+   * Constrained to the versions the renderer understands so a typo can't emit
+   * envelopes that fail at runtime.
+   */
+  version: z.enum(SUPPORTED_VERSIONS).optional()
+});
+function isTextPart(part) {
+  return !!part && typeof part === "object" && typeof part.text === "string";
+}
+function surfaceIdFactory(policy) {
+  if (typeof policy === "string") return () => policy;
+  return () => globalThis.crypto.randomUUID();
+}
+function replayableSurfaceIds(base) {
+  const generated = [];
+  let cursor = 0;
+  const next = () => {
+    const id = base();
+    generated.push(id);
+    return id;
+  };
+  const replayNext = () => cursor < generated.length ? generated[cursor++] : next();
+  const reset = () => {
+    cursor = 0;
+  };
+  return { next, replayNext, reset };
+}
+function partsFromParse(result) {
+  const out = [];
+  for (const seg of result.segments) {
+    if ("prose" in seg) {
+      if (seg.prose) out.push({ text: seg.prose });
+    } else {
+      out.push(a2uiPart(seg.envelopes));
+    }
+  }
+  return out;
+}
+const a2ui = generateMiddleware(
+  {
+    name: "a2ui",
+    description: "Adds A2UI (Agent-to-UI) streaming UI support: injects catalog capabilities into the prompt and rewrites emitted UI blocks into a2ui data parts.",
+    configSchema: A2uiOptionsSchema
+  },
+  (options) => {
+    const { ai, config } = options;
+    const {
+      catalog: catalogId = DEFAULT_CATALOG_ID,
+      instructions = "system",
+      validate = "warn",
+      version = A2UI_VERSION
+    } = config ?? {};
+    const nextSurfaceId = surfaceIdFactory(config?.surfaceId);
+    return {
+      model: async (req, ctx, next) => {
+        const catalog = await resolveCatalog(ai, catalogId);
+        const surfaceIds = replayableSurfaceIds(nextSurfaceId);
+        const sanitized = sanitizeInboundA2ui(req);
+        const request = instructions === "none" ? sanitized : injectInstructions(sanitized, catalog);
+        const streamParser = new A2uiStreamParser({
+          catalog,
+          validate,
+          version,
+          surfaceId: surfaceIds.next
+        });
+        const originalOnChunk = ctx?.onChunk;
+        const wrappedCtx = originalOnChunk ? {
+          ...ctx,
+          onChunk: (chunk) => {
+            const transformed = transformChunk(chunk, streamParser);
+            if (transformed) originalOnChunk(transformed);
+          }
+        } : ctx;
+        const response = await next(request, wrappedCtx);
+        if (originalOnChunk) {
+          const tail = partsFromParse(streamParser.flush());
+          if (tail.length > 0) originalOnChunk({ content: tail });
+        }
+        surfaceIds.reset();
+        return transformResponse(response, {
+          catalog,
+          validate,
+          version,
+          surfaceId: surfaceIds.replayNext
+        });
+      }
+    };
+  }
+);
+function injectInstructions(req, catalog) {
+  const text = renderCatalogInstructions(catalog);
+  const messages = [...req.messages];
+  const sysIdx = messages.findIndex((m) => m.role === "system");
+  if (sysIdx >= 0) {
+    const sys = messages[sysIdx];
+    messages[sysIdx] = {
+      ...sys,
+      content: [...sys.content, { text: "\n\n" + text }]
+    };
+  } else {
+    messages.unshift({ role: "system", content: [{ text }] });
+  }
+  return { ...req, messages };
+}
+function transformChunk(chunk, parser) {
+  if (!chunk?.content || chunk.content.length === 0) return chunk;
+  const newContent = [];
+  for (const part of chunk.content) {
+    if (isTextPart(part) && part.text !== "") {
+      newContent.push(...partsFromParse(parser.push(part.text)));
+    } else {
+      newContent.push(part);
+    }
+  }
+  if (newContent.length === 0) return null;
+  return { ...chunk, content: newContent };
+}
+function transformResponse(response, opts) {
+  const message = response.message;
+  if (!message?.content) return response;
+  const parser = new A2uiStreamParser(opts);
+  const newContent = [];
+  for (const part of message.content) {
+    if (isTextPart(part)) {
+      const pushed = parser.push(part.text);
+      const flushed = parser.flush();
+      const segments = [...pushed.segments, ...flushed.segments];
+      newContent.push(...partsFromParse({ segments }));
+    } else {
+      newContent.push(part);
+    }
+  }
+  return {
+    ...response,
+    message: { ...message, content: newContent }
+  };
+}
+function sanitizeInboundA2ui(req) {
+  let changed = false;
+  const messages = [];
+  for (const message of req.messages) {
+    if (!Array.isArray(message.content)) {
+      messages.push(message);
+      continue;
+    }
+    let msgChanged = false;
+    const content = [];
+    for (const part of message.content) {
+      if (isA2uiPart(part)) {
+        msgChanged = true;
+        const text = summarizeA2uiPart(part.data.envelopes);
+        if (text) content.push({ text });
+      } else {
+        content.push(part);
+      }
+    }
+    if (!msgChanged) {
+      messages.push(message);
+      continue;
+    }
+    changed = true;
+    if (content.length === 0) continue;
+    messages.push({ ...message, content });
+  }
+  return changed ? { ...req, messages } : req;
+}
+function summarizeA2uiPart(envelopes) {
+  const out = [];
+  let pendingSurface = [];
+  const flushSurface = () => {
+    if (pendingSurface.length === 0) return;
+    out.push("```a2ui\n" + JSON.stringify(pendingSurface) + "\n```");
+    pendingSurface = [];
+  };
+  for (const env of envelopes) {
+    if (!env || typeof env !== "object") continue;
+    if ("action" in env && env.action) {
+      flushSurface();
+      const a = env.action;
+      const ctx = a.context && Object.keys(a.context).length ? ` context=${JSON.stringify(a.context)}` : "";
+      out.push(`[UI action "${a.name}" on surface ${a.surfaceId}${ctx}]`);
+    } else if ("createSurface" in env && env.createSurface || "updateComponents" in env && env.updateComponents || "updateDataModel" in env && env.updateDataModel || "deleteSurface" in env && env.deleteSurface) {
+      pendingSurface.push(env);
+    }
+  }
+  flushSurface();
+  return out.join("\n");
+}
+export {
+  A2uiOptionsSchema,
+  a2ui
+};
+//# sourceMappingURL=middleware.mjs.map

package/lib/middleware.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/middleware.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 * The `a2ui()` generate middleware — the whole server-side integration.\n *\n * Add it to `defineAgent({ use: [...] })` or `ai.generate({ use: [...] })` and\n * the agent gains the ability to render A2UI surfaces. The middleware:\n *\n * 1. Injects the catalog's capabilities into the system prompt so the model\n *    knows what UI it may render.\n * 2. Intercepts the model's output (both the streamed chunks and the final\n *    message), extracts any `a2ui` fenced blocks, validates them against the\n *    catalog, and rewrites them into the canonical a2ui data part.\n *\n * Downstream (client transport, `@a2ui/web_core`) only ever sees a2ui parts —\n * \"pure vs mixed\" turns are a prompting choice, not a separate code path.\n *\n * Implemented with `generateMiddleware` and the `model` hook, so it wraps each\n * raw model call in the agent's tool loop.\n *\n * @module\n */\n\nimport { generateMiddleware, z, type GenerateMiddleware } from 'genkit';\nimport type {\n  GenerateRequest,\n  GenerateResponseChunkData,\n  GenerateResponseData,\n  MessageData,\n  Part,\n  TextPart,\n} from 'genkit/model';\nimport {\n  DEFAULT_CATALOG_ID,\n  renderCatalogInstructions,\n  type A2uiCatalog,\n} from './catalog.mjs';\nimport { resolveCatalog } from './loader.mjs';\nimport { A2uiStreamParser, type ParseResult } from './parser.mjs';\nimport { a2uiPart, isA2uiPart } from './part.mjs';\nimport {\n  A2UI_VERSION,\n  SUPPORTED_VERSIONS,\n  type A2uiEnvelope,\n} from './types.mjs';\n\n/** Zod schema for the {@link a2ui} middleware configuration. */\nexport const A2uiOptionsSchema = z.object({\n  /**\n   * The id of the catalog describing what the agent may render. Defaults to\n   * `'basic'` (the bundled basic catalog). Register additional catalogs with\n   * `loadCatalog(ai, { id, catalog | file })` and reference them by id here.\n   */\n  catalog: z.string().optional(),\n\n  /**\n   * Where to inject the catalog's capabilities. `'system'` (default) appends\n   * A2UI instructions to the system prompt; `'none'` injects nothing (useful if\n   * you supply your own instructions).\n   */\n  instructions: z.enum(['system', 'none']).optional(),\n\n  /**\n   * Validate emitted envelopes against the catalog. `'warn'` (default) logs a\n   * warning and drops the offending block/envelope, keeping the rest of the\n   * turn alive; `'strict'` throws on malformed JSON or unknown components (best\n   * for development); `'off'` passes them through unchecked.\n   *\n   * IMPORTANT: this validates envelope structure and component *type names*\n   * against the catalog only. It does NOT validate component props or\n   * data-model values. Model-controlled values such as `Image.url` and `Text`\n   * (inline Markdown, which the renderer may turn into HTML) pass through\n   * untouched even under `'strict'`. `'strict'` is a well-formedness check, not\n   * a security boundary — see the \"Security / trust boundary\" section of the\n   * README. Prop sanitization is the renderer/catalog's responsibility, and\n   * hosts should CSP-restrict image and other remote sources.\n   */\n  validate: z.enum(['strict', 'warn', 'off']).optional(),\n\n  /**\n   * Surface id policy. Provide a fixed id to reuse for every surface. Defaults\n   * to a fresh UUID per surface.\n   */\n  surfaceId: z.string().optional(),\n\n  /**\n   * Protocol version stamped on emitted envelopes. Defaults to `'v0.9'`.\n   * Constrained to the versions the renderer understands so a typo can't emit\n   * envelopes that fail at runtime.\n   */\n  version: z\n    .enum(SUPPORTED_VERSIONS as unknown as [string, ...string[]])\n    .optional(),\n});\n\n/** Configuration for the {@link a2ui} middleware. */\nexport type A2uiOptions = z.infer<typeof A2uiOptionsSchema>;\n\n/** Type guard: is this part a text part? */\nfunction isTextPart(part: Part): part is TextPart {\n  return (\n    !!part &&\n    typeof part === 'object' &&\n    typeof (part as { text?: unknown }).text === 'string'\n  );\n}\n\n/** Resolves the configured surface-id policy into a factory. */\nfunction surfaceIdFactory(policy: A2uiOptions['surfaceId']): () => string {\n  if (typeof policy === 'string') return () => policy;\n  // Use the Web Crypto API (available on Node >=16 and all supported \"exotic\"\n  // runtimes, e.g. Cloudflare Workers) rather than a hard `node:crypto` import,\n  // keeping the middleware portable.\n  return () => globalThis.crypto.randomUUID();\n}\n\n/**\n * Wraps a surface-id factory so a single model turn's streamed parse and its\n * final-message parse mint the *same* surface ids.\n *\n * A turn is parsed twice: once incrementally over the streamed chunks, and once\n * over the aggregated final message (so consumers that read `response.message`\n * see a2ui parts too). Each parse pulls surface ids from the factory. With the\n * default `randomUUID` policy those two parses would otherwise produce different\n * ids for the same surface. So while streaming we generate and record ids in\n * order (`next`); before re-parsing the final message we `reset`, then\n * `replayNext` hands back the recorded ids in the same order (only generating a\n * fresh id if the final parse yields more blocks than the stream did).\n */\nfunction replayableSurfaceIds(base: () => string): {\n  next: () => string;\n  replayNext: () => string;\n  reset: () => void;\n} {\n  const generated: string[] = [];\n  let cursor = 0;\n  const next = () => {\n    const id = base();\n    generated.push(id);\n    return id;\n  };\n  const replayNext = () =>\n    cursor < generated.length ? generated[cursor++] : next();\n  const reset = () => {\n    cursor = 0;\n  };\n  return { next, replayNext, reset };\n}\n\n/**\n * Turns a parse result into ordered prose + a2ui parts, preserving the exact\n * source order (so prose after a block stays after it). Returns the new parts\n * to substitute for the original text part.\n */\nfunction partsFromParse(result: ParseResult): Part[] {\n  const out: Part[] = [];\n  for (const seg of result.segments) {\n    if ('prose' in seg) {\n      if (seg.prose) out.push({ text: seg.prose });\n    } else {\n      out.push(a2uiPart(seg.envelopes));\n    }\n  }\n  return out;\n}\n\n/**\n * The A2UI generate middleware.\n *\n * @example\n * ```ts\n * import { a2ui } from '@genkit-ai/a2ui';\n *\n * export const uiAgent = ai.defineAgent({\n *   name: 'uiAgent',\n *   model: 'googleai/gemini-flash-latest',\n *   system: 'You help users. Render UI when it is clearer than prose.',\n *   use: [a2ui()], // defaults to the bundled 'basic' catalog\n * });\n * ```\n */\nexport const a2ui: GenerateMiddleware<typeof A2uiOptionsSchema> =\n  generateMiddleware(\n    {\n      name: 'a2ui',\n      description:\n        'Adds A2UI (Agent-to-UI) streaming UI support: injects catalog ' +\n        'capabilities into the prompt and rewrites emitted UI blocks into a2ui ' +\n        'data parts.',\n      configSchema: A2uiOptionsSchema,\n    },\n    (options) => {\n      const { ai, config } = options;\n      const {\n        catalog: catalogId = DEFAULT_CATALOG_ID,\n        instructions = 'system',\n        validate = 'warn',\n        version = A2UI_VERSION,\n      } = config ?? {};\n      const nextSurfaceId = surfaceIdFactory(config?.surfaceId);\n\n      return {\n        model: async (req, ctx, next) => {\n          // Resolve the catalog by id from the registry (falls back to the\n          // bundled basic catalog for the default id).\n          const catalog = await resolveCatalog(ai, catalogId);\n\n          // Share surface ids between the streamed parse and the final-message\n          // parse of this single turn, so the same surface gets the same id in\n          // both (see replayableSurfaceIds).\n          const surfaceIds = replayableSurfaceIds(nextSurfaceId);\n\n          // 0) Sanitize any inbound a2ui data parts (e.g. a surface action sent\n          //    back as the next turn, or replayed history) into model-readable\n          //    text, so the underlying model's converter never sees the a2ui\n          //    mime type.\n          const sanitized = sanitizeInboundA2ui(req);\n\n          // 1) Inject catalog instructions into the system prompt.\n          const request =\n            instructions === 'none'\n              ? sanitized\n              : injectInstructions(sanitized, catalog);\n\n          // 2) Wrap the streaming callback so streamed text is split into prose\n          //    deltas + whole a2ui parts as blocks complete.\n          const streamParser = new A2uiStreamParser({\n            catalog,\n            validate,\n            version,\n            surfaceId: surfaceIds.next,\n          });\n\n          const originalOnChunk = ctx?.onChunk;\n          const wrappedCtx = originalOnChunk\n            ? {\n                ...ctx,\n                onChunk: (chunk: GenerateResponseChunkData) => {\n                  const transformed = transformChunk(chunk, streamParser);\n                  if (transformed) originalOnChunk(transformed);\n                },\n              }\n            : ctx;\n\n          // 3) Run downstream model, then flush the stream parser so the last\n          //    withheld prose tail (the parser holds back up to a partial\n          //    opening fence) and any unterminated trailing block still reach\n          //    the streaming consumer. Without this, clients that render purely\n          //    from stream deltas would show truncated prose / miss a final\n          //    block (the aggregated message recovers it, but the stream would\n          //    not).\n          const response = await next(request, wrappedCtx);\n          if (originalOnChunk) {\n            const tail = partsFromParse(streamParser.flush());\n            if (tail.length > 0) originalOnChunk({ content: tail });\n          }\n\n          // 4) Transform the final message. The final parse replays the same\n          //    surface ids the stream minted.\n          surfaceIds.reset();\n          return transformResponse(response, {\n            catalog,\n            validate,\n            version,\n            surfaceId: surfaceIds.replayNext,\n          });\n        },\n      };\n    }\n  );\n\n/** Appends A2UI instructions to (or creates) the system message. */\nfunction injectInstructions(\n  req: GenerateRequest,\n  catalog: A2uiCatalog\n): GenerateRequest {\n  const text = renderCatalogInstructions(catalog);\n  const messages: MessageData[] = [...req.messages];\n  const sysIdx = messages.findIndex((m) => m.role === 'system');\n  if (sysIdx >= 0) {\n    const sys = messages[sysIdx];\n    messages[sysIdx] = {\n      ...sys,\n      content: [...sys.content, { text: '\\n\\n' + text }],\n    };\n  } else {\n    messages.unshift({ role: 'system', content: [{ text }] });\n  }\n  return { ...req, messages };\n}\n\n/** Transforms a single streamed chunk; returns null if nothing to emit. */\nfunction transformChunk(\n  chunk: GenerateResponseChunkData,\n  parser: A2uiStreamParser\n): GenerateResponseChunkData | null {\n  if (!chunk?.content || chunk.content.length === 0) return chunk;\n  const newContent: Part[] = [];\n  for (const part of chunk.content) {\n    if (isTextPart(part) && part.text !== '') {\n      newContent.push(...partsFromParse(parser.push(part.text)));\n    } else {\n      newContent.push(part);\n    }\n  }\n  if (newContent.length === 0) return null;\n  return { ...chunk, content: newContent };\n}\n\n/** Transforms the final response message: prose text + a2ui parts. */\nfunction transformResponse(\n  response: GenerateResponseData,\n  opts: {\n    catalog: A2uiCatalog;\n    validate: 'strict' | 'warn' | 'off';\n    version: string;\n    surfaceId: () => string;\n  }\n): GenerateResponseData {\n  const message = response.message;\n  if (!message?.content) return response;\n\n  const parser = new A2uiStreamParser(opts);\n  const newContent: Part[] = [];\n  for (const part of message.content) {\n    if (isTextPart(part)) {\n      // Combine the streamed-push and final-flush segments so ordering (prose\n      // before/after a block) is preserved in the aggregated message too.\n      const pushed = parser.push(part.text);\n      const flushed = parser.flush();\n      const segments = [...pushed.segments, ...flushed.segments];\n      newContent.push(...partsFromParse({ segments } as ParseResult));\n    } else {\n      newContent.push(part);\n    }\n  }\n  return {\n    ...response,\n    message: { ...message, content: newContent },\n  };\n}\n\n/**\n * Converts inbound a2ui data parts in the request into model-readable text.\n *\n * The a2ui data part (mime `application/a2ui+json`) is meaningful to the client\n * renderer, but the underlying model's message converter (e.g. Gemini) does not\n * understand it. When a rendered surface's action is sent back as the next\n * turn's input — or when prior assistant turns containing surfaces are replayed\n * as history — we replace those parts with a compact text summary so the model\n * can reason about them.\n */\nfunction sanitizeInboundA2ui(req: GenerateRequest): GenerateRequest {\n  let changed = false;\n  const messages: MessageData[] = [];\n  for (const message of req.messages) {\n    if (!Array.isArray(message.content)) {\n      messages.push(message);\n      continue;\n    }\n    let msgChanged = false;\n    const content: Part[] = [];\n    for (const part of message.content) {\n      if (isA2uiPart(part)) {\n        msgChanged = true;\n        const text = summarizeA2uiPart(part.data.envelopes);\n        if (text) content.push({ text });\n      } else {\n        content.push(part as Part);\n      }\n    }\n    if (!msgChanged) {\n      messages.push(message);\n      continue;\n    }\n    changed = true;\n    // Drop a message that sanitizing emptied out. This happens when its only\n    // content was an a2ui part whose envelopes all summarized to nothing (e.g.\n    // an empty or all-unrecognized envelope array). Sending `content: []`\n    // downstream would make providers like Gemini and Vertex reject the\n    // request, so skip the message entirely instead.\n    if (content.length === 0) continue;\n    messages.push({ ...message, content });\n  }\n  return changed ? { ...req, messages } : req;\n}\n\n/**\n * Converts an array of a2ui envelopes from an inbound message part back into\n * model-readable text — the inverse of the outbound block-to-part transform.\n *\n * The two envelope kinds are handled differently on purpose:\n *\n * - Assistant-authored surface envelopes (`createSurface`, `updateComponents`,\n *   `updateDataModel`, `deleteSurface`) are reconstructed as the canonical\n *   `a2ui` fenced block the model originally emitted. Replaying a prior turn's\n *   surface as history therefore shows the model its own UI output in the exact\n *   format it is asked to produce, reinforcing correct behavior. (Summarizing it\n *   to a sentinel like `[rendered UI surface]` instead taught the model to emit\n *   that literal string in place of a real block.)\n * - Client-synthesized `action` envelopes never had a block form, so they\n *   become a short text summary the model can reason about.\n *\n * Consecutive surface envelopes are grouped into a single block (one surface is\n * usually several envelopes: create + update(s)). Unknown envelope shapes are\n * dropped, so an all-unrecognized (or empty) envelope array summarizes to an\n * empty string; {@link sanitizeInboundA2ui} then drops the emptied message\n * rather than sending empty content downstream.\n */\nfunction summarizeA2uiPart(envelopes: A2uiEnvelope[]): string {\n  const out: string[] = [];\n  let pendingSurface: A2uiEnvelope[] = [];\n\n  const flushSurface = () => {\n    if (pendingSurface.length === 0) return;\n    // Keep the real surface ids verbatim. The model may not reuse them for a\n    // NEW surface: the parser forces a fresh id onto every `createSurface`\n    // block (see `finalizeBlock`), so a copied id can't overwrite a prior\n    // surface. Keeping the real ids lets the model correlate a replayed action\n    // (`[UI action ... on surface <id>]`) with the surface it targeted — which\n    // matters when several surfaces are on screen at once.\n    //\n    // Encode compactly (not pretty-printed): fewer tokens, and it collapses the\n    // payload to a single line so the block is exactly three lines (open fence,\n    // JSON, close fence). Because JSON escapes any newline inside a string as\n    // `\\n`, an A2UI `Text` value containing a fenced code sample can't put a\n    // literal ``` at the start of a line, so it can never prematurely close this\n    // block (the parser's close fence is line-anchored). The block text can\n    // still contain ``` characters mid-line; a fully robust emitter would use a\n    // variable-length fence, but that also requires the parser's fixed\n    // three-backtick open fence to become count-aware, so it is deferred.\n    out.push('```a2ui\\n' + JSON.stringify(pendingSurface) + '\\n```');\n    pendingSurface = [];\n  };\n\n  for (const env of envelopes) {\n    if (!env || typeof env !== 'object') continue;\n    if ('action' in env && env.action) {\n      // Emit any buffered surface block before the action, preserving order.\n      flushSurface();\n      const a = env.action;\n      const ctx =\n        a.context && Object.keys(a.context).length\n          ? ` context=${JSON.stringify(a.context)}`\n          : '';\n      out.push(`[UI action \"${a.name}\" on surface ${a.surfaceId}${ctx}]`);\n    } else if (\n      ('createSurface' in env && env.createSurface) ||\n      ('updateComponents' in env && env.updateComponents) ||\n      ('updateDataModel' in env && env.updateDataModel) ||\n      ('deleteSurface' in env && env.deleteSurface)\n    ) {\n      pendingSurface.push(env);\n    }\n  }\n  flushSurface();\n  return out.join('\\n');\n}\n"],"mappings":"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","names":[]}

package/lib/parser.d.mts

@@ -0,0 +1,132 @@
+import { A2uiCatalog } from './catalog.mjs';
+import { A2uiEnvelope } 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.
+ */
+/**
+ * Streaming parser that extracts A2UI envelopes from model output.
+ *
+ * The model emits A2UI as a fenced code block tagged `a2ui` containing a JSON
+ * array of envelopes (see {@link renderCatalogInstructions}). This parser scans
+ * a text stream incrementally, separating ordinary prose (which streams through
+ * as deltas) from complete A2UI blocks (which are buffered until the closing
+ * fence, then parsed into whole, validated envelopes — the protocol requires
+ * ordered, complete messages, so we never emit half-parsed JSON).
+ *
+ * This module is Node-free so it can be unit-tested and reused anywhere.
+ *
+ * @module
+ */
+
+/**
+ * A single ordered piece of parsed output: either a run of prose or one
+ * completed A2UI envelope batch. Segments preserve the exact source order, so
+ * prose that appears *after* a block is not reordered ahead of it.
+ */
+type ParseSegment = {
+    prose: string;
+} | {
+    envelopes: A2uiEnvelope[];
+};
+/** Result of feeding text to {@link A2uiStreamParser.push}. */
+interface ParseResult {
+    /**
+     * Ordered prose/envelope segments exactly as they appear in the source text.
+     * Prefer this over {@link ParseResult.prose}/{@link ParseResult.envelopeBatches}
+     * when order between prose and blocks matters.
+     */
+    segments: ParseSegment[];
+    /**
+     * Convenience: all prose runs concatenated (never contains A2UI blocks). Loses
+     * the relative order of prose vs. blocks — use {@link ParseResult.segments}
+     * when that matters.
+     */
+    prose: string;
+    /** Convenience: the fully-parsed A2UI envelope batches, in order. */
+    envelopeBatches: A2uiEnvelope[][];
+}
+/** Options controlling how the parser finalizes envelopes. */
+interface A2uiParserOptions {
+    /** Catalog used to validate component references. */
+    catalog?: A2uiCatalog;
+    /**
+     * `'strict'` throws on unknown components / bad JSON; `'warn'` logs a warning
+     * and drops the offending block/envelope; `'off'` skips validation entirely.
+     */
+    validate?: 'strict' | 'warn' | 'off';
+    /** Protocol version stamped onto envelopes lacking one. */
+    version?: string;
+    /** Produces the surface id substituted for the model's placeholder. */
+    surfaceId: () => string;
+}
+/**
+ * Incremental A2UI extractor. Create one per model turn, `push()` text deltas as
+ * they arrive, and `flush()` at the end to drain any trailing block.
+ */
+declare class A2uiStreamParser {
+    private readonly options;
+    private buffer;
+    private inBlock;
+    /** Stable surface id for the current block (placeholders map to this). */
+    private currentSurfaceId;
+    constructor(options: A2uiParserOptions);
+    /** Feeds a chunk of model text, returning prose + any completed blocks. */
+    push(text: string): ParseResult;
+    /** Drains any remaining buffered content at end of stream. */
+    flush(): ParseResult;
+    private drain;
+    /**
+     * Handles a validation failure according to the configured `validate` mode:
+     * throws in `'strict'`, logs a warning in `'warn'` (the middleware default),
+     * and is silent in `'off'`. Always returns `null` so callers can
+     * `return this.reject(...)`.
+     */
+    private reject;
+    /** Parses, validates, and normalizes one block's JSON into envelopes. */
+    private finalizeBlock;
+    /**
+     * Validates a single envelope, substitutes the real surface id for the
+     * placeholder, and stamps the protocol version.
+     */
+    private normalizeEnvelope;
+    /**
+     * Ensures every component references a known catalog component. Returns an
+     * error message describing the first problem found, or `null` if valid.
+     *
+     * This checks component *type names* against the catalog only. It intentionally
+     * does NOT enforce the "must contain a root" protocol rule — that applies only
+     * to full-surface renders and is enforced at the batch level in
+     * {@link finalizeBlock} (an incremental update to an existing surface may
+     * legitimately patch a subtree without re-declaring `root`).
+     */
+    private validateComponents;
+    /**
+     * Enforces the "RE-RENDER THE WHOLE SURFACE" protocol rule for full-surface
+     * renders. The v0.9 spec requires that "one of the components in one of the
+     * component lists MUST have an id of `root`" — a batch-level rule, not a
+     * per-message one. A split render is therefore legal: the root (and layout)
+     * may live in one `updateComponents` while its leaf components arrive in a
+     * later one within the same batch. So this checks that *at least one*
+     * `updateComponents` in the batch declares a `root`, not that every one does.
+     *
+     * Returns an error message, or `null` if valid. Unlike
+     * {@link validateComponents} this is a protocol check, not a catalog check, so
+     * it runs regardless of whether a catalog is configured.
+     */
+    private validateRoot;
+}
+
+export { type A2uiParserOptions, A2uiStreamParser, type ParseResult, type ParseSegment };

package/lib/parser.d.ts

@@ -0,0 +1,132 @@
+import { A2uiCatalog } from './catalog.js';
+import { A2uiEnvelope } 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.
+ */
+/**
+ * Streaming parser that extracts A2UI envelopes from model output.
+ *
+ * The model emits A2UI as a fenced code block tagged `a2ui` containing a JSON
+ * array of envelopes (see {@link renderCatalogInstructions}). This parser scans
+ * a text stream incrementally, separating ordinary prose (which streams through
+ * as deltas) from complete A2UI blocks (which are buffered until the closing
+ * fence, then parsed into whole, validated envelopes — the protocol requires
+ * ordered, complete messages, so we never emit half-parsed JSON).
+ *
+ * This module is Node-free so it can be unit-tested and reused anywhere.
+ *
+ * @module
+ */
+
+/**
+ * A single ordered piece of parsed output: either a run of prose or one
+ * completed A2UI envelope batch. Segments preserve the exact source order, so
+ * prose that appears *after* a block is not reordered ahead of it.
+ */
+type ParseSegment = {
+    prose: string;
+} | {
+    envelopes: A2uiEnvelope[];
+};
+/** Result of feeding text to {@link A2uiStreamParser.push}. */
+interface ParseResult {
+    /**
+     * Ordered prose/envelope segments exactly as they appear in the source text.
+     * Prefer this over {@link ParseResult.prose}/{@link ParseResult.envelopeBatches}
+     * when order between prose and blocks matters.
+     */
+    segments: ParseSegment[];
+    /**
+     * Convenience: all prose runs concatenated (never contains A2UI blocks). Loses
+     * the relative order of prose vs. blocks — use {@link ParseResult.segments}
+     * when that matters.
+     */
+    prose: string;
+    /** Convenience: the fully-parsed A2UI envelope batches, in order. */
+    envelopeBatches: A2uiEnvelope[][];
+}
+/** Options controlling how the parser finalizes envelopes. */
+interface A2uiParserOptions {
+    /** Catalog used to validate component references. */
+    catalog?: A2uiCatalog;
+    /**
+     * `'strict'` throws on unknown components / bad JSON; `'warn'` logs a warning
+     * and drops the offending block/envelope; `'off'` skips validation entirely.
+     */
+    validate?: 'strict' | 'warn' | 'off';
+    /** Protocol version stamped onto envelopes lacking one. */
+    version?: string;
+    /** Produces the surface id substituted for the model's placeholder. */
+    surfaceId: () => string;
+}
+/**
+ * Incremental A2UI extractor. Create one per model turn, `push()` text deltas as
+ * they arrive, and `flush()` at the end to drain any trailing block.
+ */
+declare class A2uiStreamParser {
+    private readonly options;
+    private buffer;
+    private inBlock;
+    /** Stable surface id for the current block (placeholders map to this). */
+    private currentSurfaceId;
+    constructor(options: A2uiParserOptions);
+    /** Feeds a chunk of model text, returning prose + any completed blocks. */
+    push(text: string): ParseResult;
+    /** Drains any remaining buffered content at end of stream. */
+    flush(): ParseResult;
+    private drain;
+    /**
+     * Handles a validation failure according to the configured `validate` mode:
+     * throws in `'strict'`, logs a warning in `'warn'` (the middleware default),
+     * and is silent in `'off'`. Always returns `null` so callers can
+     * `return this.reject(...)`.
+     */
+    private reject;
+    /** Parses, validates, and normalizes one block's JSON into envelopes. */
+    private finalizeBlock;
+    /**
+     * Validates a single envelope, substitutes the real surface id for the
+     * placeholder, and stamps the protocol version.
+     */
+    private normalizeEnvelope;
+    /**
+     * Ensures every component references a known catalog component. Returns an
+     * error message describing the first problem found, or `null` if valid.
+     *
+     * This checks component *type names* against the catalog only. It intentionally
+     * does NOT enforce the "must contain a root" protocol rule — that applies only
+     * to full-surface renders and is enforced at the batch level in
+     * {@link finalizeBlock} (an incremental update to an existing surface may
+     * legitimately patch a subtree without re-declaring `root`).
+     */
+    private validateComponents;
+    /**
+     * Enforces the "RE-RENDER THE WHOLE SURFACE" protocol rule for full-surface
+     * renders. The v0.9 spec requires that "one of the components in one of the
+     * component lists MUST have an id of `root`" — a batch-level rule, not a
+     * per-message one. A split render is therefore legal: the root (and layout)
+     * may live in one `updateComponents` while its leaf components arrive in a
+     * later one within the same batch. So this checks that *at least one*
+     * `updateComponents` in the batch declares a `root`, not that every one does.
+     *
+     * Returns an error message, or `null` if valid. Unlike
+     * {@link validateComponents} this is a protocol check, not a catalog check, so
+     * it runs regardless of whether a catalog is configured.
+     */
+    private validateRoot;
+}
+
+export { type A2uiParserOptions, A2uiStreamParser, type ParseResult, type ParseSegment };