From 5149865c387ab252f76be5784cbb99a4af0cb361 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Tue, 12 May 2026 02:06:10 -0400
Subject: [PATCH 01/25] add a2ui message rendering

---
 apps/tlon-web/cosmos.config.json              |   3 +-
 apps/tlon-web/vite.cosmos.config.mts          |  87 +++
 packages/api/src/__tests__/a2ui.test.ts       | 100 +++
 .../src/__tests__/postContent.a2ui.test.ts    |  39 ++
 packages/api/src/client/a2ui.ts               | 340 ++++++++++
 packages/api/src/client/content-helpers.ts    |   4 +
 packages/api/src/client/index.ts              |   1 +
 packages/api/src/client/postContent.ts        |  15 +
 packages/app/fixtures/A2UI.fixture.tsx        | 626 ++++++++++++++++++
 .../ChatMessage/StaticChatMessage.tsx         |  31 +
 .../ui/components/PostContent/A2UIBlock.tsx   | 280 ++++++++
 .../components/PostContent/BlockRenderer.tsx  |   3 +
 .../PostContent/ContentRenderer.tsx           |   2 +
 .../components/PostContent/contentUtils.tsx   |   7 +
 14 files changed, 1536 insertions(+), 2 deletions(-)
 create mode 100644 apps/tlon-web/vite.cosmos.config.mts
 create mode 100644 packages/api/src/__tests__/a2ui.test.ts
 create mode 100644 packages/api/src/__tests__/postContent.a2ui.test.ts
 create mode 100644 packages/api/src/client/a2ui.ts
 create mode 100644 packages/app/fixtures/A2UI.fixture.tsx
 create mode 100644 packages/app/ui/components/PostContent/A2UIBlock.tsx

diff --git a/apps/tlon-web/cosmos.config.json b/apps/tlon-web/cosmos.config.json
index b0e1a3281c..5b43149a2e 100644
--- a/apps/tlon-web/cosmos.config.json
+++ b/apps/tlon-web/cosmos.config.json
@@ -3,12 +3,11 @@
   "hostname": "localhost",
   "port": 5555,
   "vite": {
-    "configPath": "./vite.config.mts"
+    "configPath": "./vite.cosmos.config.mts"
   },
   "dom": {
     "containerQuerySelector": "#app"
   },
   "fixturesLocation": "../../packages/app/fixtures",
-  "rendererUrl": "http://localhost:5050/apps/groups/",
   "plugins": ["react-cosmos-plugin-vite"]
 }
diff --git a/apps/tlon-web/vite.cosmos.config.mts b/apps/tlon-web/vite.cosmos.config.mts
new file mode 100644
index 0000000000..09eed7b58a
--- /dev/null
+++ b/apps/tlon-web/vite.cosmos.config.mts
@@ -0,0 +1,87 @@
+/// <reference types="vitest" />
+import { tamaguiPlugin } from '@tamagui/vite-plugin';
+import react from '@vitejs/plugin-react';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { Plugin, PluginOption, defineConfig, loadEnv } from 'vite';
+import svgr from 'vite-plugin-svgr';
+
+import expo52PatchPlugin from './expo52PatchPlugin';
+import packageJson from './package.json';
+import reactNativeWeb from './reactNativeWebPlugin';
+
+// Dedicated Vite config for React Cosmos.
+//
+// react-cosmos-plugin-vite 7.2.0 misbehaves when the host config sets `base`:
+// the renderer swap can miss, causing the real app to boot inside the renderer.
+// Keep Cosmos on a minimal config without `base`, Urbit proxy, PWA, or Sentry.
+export default defineConfig(({ mode }) => {
+  process.env.VITE_STORAGE_VERSION = packageJson.version;
+  Object.assign(process.env, loadEnv(mode, process.cwd()));
+
+  return {
+    envPrefix: ['VITE_', 'TAMAGUI_'],
+    plugins: [
+      cosmosIndexHtmlPlugin(),
+      exportingRawText(/\.sql$/),
+      expo52PatchPlugin(),
+      react({
+        babel: {
+          plugins: [
+            '@babel/plugin-proposal-export-namespace-from',
+            'react-native-worklets/plugin',
+          ],
+        },
+        jsxImportSource: '@welldone-software/why-did-you-render',
+      }) as PluginOption[],
+      svgr({ include: '**/*.svg' }) as Plugin,
+      reactNativeWeb(),
+      tamaguiPlugin({
+        config: './tamagui.config.ts',
+        platform: 'web',
+      }) as Plugin,
+    ],
+    resolve: {
+      conditions: ['tlon-source'],
+      dedupe: ['@tanstack/react-query'],
+      alias: {
+        '@': fileURLToPath(new URL('./src', import.meta.url)),
+        'virtual:pwa-register/react': fileURLToPath(
+          new URL('./src/logic/useAppUpdatesStub.ts', import.meta.url)
+        ),
+        'react-native-reanimated': fileURLToPath(
+          new URL('../../node_modules/react-native-reanimated', import.meta.url)
+        ),
+      },
+    },
+    optimizeDeps: {
+      exclude: ['sqlocal', 'virtual:pwa-register/react'],
+    },
+  };
+});
+
+function cosmosIndexHtmlPlugin(): Plugin {
+  return {
+    name: 'cosmos index html',
+    enforce: 'pre',
+    transformIndexHtml(html) {
+      return html.replace(
+        /\s*<script type="module" src="\/src\/storage-wipe\.ts"><\/script>/,
+        ''
+      );
+    },
+  };
+}
+
+function exportingRawText(matchId: RegExp): Plugin {
+  return {
+    name: 'inline sql',
+    enforce: 'pre',
+    transform(_code, id) {
+      if (matchId.test(id)) {
+        const sql = fs.readFileSync(id, 'utf-8');
+        return `export default ${JSON.stringify(sql)}`;
+      }
+    },
+  };
+}
diff --git a/packages/api/src/__tests__/a2ui.test.ts b/packages/api/src/__tests__/a2ui.test.ts
new file mode 100644
index 0000000000..1ca843acd5
--- /dev/null
+++ b/packages/api/src/__tests__/a2ui.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, test } from 'vitest';
+
+import type { PostBlobDataEntryA2UI } from '../client/a2ui';
+import { validateA2UIBlobEntry } from '../client/a2ui';
+import { appendToPostBlob, parsePostBlob } from '../client/content-helpers';
+
+const a2uiBlobEntry: PostBlobDataEntryA2UI = {
+  type: 'a2ui',
+  version: 1,
+  messages: [
+    {
+      version: 'v0.9',
+      createSurface: {
+        surfaceId: 'weather-card',
+        catalogId: 'tlon.a2ui.basic.v1',
+      },
+    },
+    {
+      version: 'v0.9',
+      updateComponents: {
+        surfaceId: 'weather-card',
+        root: 'root',
+        components: [
+          { id: 'root', component: 'Card', child: 'body' },
+          {
+            id: 'body',
+            component: 'Column',
+            children: ['title', 'summary', 'refreshButton'],
+          },
+          { id: 'title', component: 'Text', text: 'Weather' },
+          { id: 'summary', component: 'Text', text: '72F and clear' },
+          {
+            id: 'refreshButton',
+            component: 'Button',
+            child: 'refreshLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'refresh weather' },
+              },
+            },
+          },
+          { id: 'refreshLabel', component: 'Text', text: 'Refresh' },
+        ],
+      },
+    },
+  ],
+};
+
+describe('a2ui blob entries', () => {
+  test('validates supported a2ui payloads', () => {
+    expect(validateA2UIBlobEntry(a2uiBlobEntry)).toBe(true);
+  });
+
+  test('parsePostBlob parses supported a2ui entries', () => {
+    const blob = appendToPostBlob(undefined, a2uiBlobEntry);
+
+    expect(parsePostBlob(blob)).toEqual([a2uiBlobEntry]);
+  });
+
+  test('rejects unsupported a2ui components and actions', () => {
+    expect(
+      parsePostBlob(
+        JSON.stringify([
+          {
+            ...a2uiBlobEntry,
+            messages: [
+              a2uiBlobEntry.messages[0],
+              {
+                version: 'v0.9',
+                updateComponents: {
+                  surfaceId: 'weather-card',
+                  components: [
+                    { id: 'root', component: 'Badge', text: 'unsupported' },
+                  ],
+                },
+              },
+            ],
+          },
+          {
+            ...a2uiBlobEntry,
+            messages: [
+              a2uiBlobEntry.messages[0],
+              {
+                version: 'v0.9',
+                updateComponents: {
+                  surfaceId: 'weather-card',
+                  components: [
+                    { id: 'root', component: 'Button', child: 'label' },
+                    { id: 'label', component: 'Text', text: 'Call function' },
+                  ],
+                },
+              },
+            ],
+          },
+        ])
+      )
+    ).toEqual([{ type: 'unknown' }, { type: 'unknown' }]);
+  });
+});
diff --git a/packages/api/src/__tests__/postContent.a2ui.test.ts b/packages/api/src/__tests__/postContent.a2ui.test.ts
new file mode 100644
index 0000000000..6b03720d96
--- /dev/null
+++ b/packages/api/src/__tests__/postContent.a2ui.test.ts
@@ -0,0 +1,39 @@
+import { expect, test } from 'vitest';
+
+import { convertContent } from '../client/postContent';
+
+test('convertContent renders supported a2ui blob entries before story content', () => {
+  const a2ui = {
+    type: 'a2ui',
+    version: 1,
+    messages: [
+      {
+        version: 'v0.9',
+        createSurface: {
+          surfaceId: 'approval-card',
+          catalogId: 'tlon.a2ui.basic.v1',
+        },
+      },
+      {
+        version: 'v0.9',
+        updateComponents: {
+          surfaceId: 'approval-card',
+          root: 'root',
+          components: [
+            { id: 'root', component: 'Card', child: 'body' },
+            { id: 'body', component: 'Column', children: ['title'] },
+            { id: 'title', component: 'Text', text: 'Approve DM?' },
+          ],
+        },
+      },
+    ],
+  };
+
+  const content = convertContent(
+    [{ inline: ['Fallback text'] }],
+    JSON.stringify([a2ui])
+  );
+
+  expect(content[0]).toEqual({ type: 'a2ui', a2ui });
+  expect(content[1]).toMatchObject({ type: 'paragraph' });
+});
diff --git a/packages/api/src/client/a2ui.ts b/packages/api/src/client/a2ui.ts
new file mode 100644
index 0000000000..633e23e2d7
--- /dev/null
+++ b/packages/api/src/client/a2ui.ts
@@ -0,0 +1,340 @@
+import { z } from 'zod';
+
+export const TLON_A2UI_ACTION_SEND_MESSAGE = 'tlon.sendMessage';
+
+type A2UIComponentBase = {
+  id: string;
+  weight?: number;
+};
+
+export type A2UITextComponent = A2UIComponentBase & {
+  component: 'Text';
+  text: string;
+  variant?: 'body' | 'caption' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5';
+};
+
+export type A2UIContainerComponent = A2UIComponentBase & {
+  component: 'Row' | 'Column';
+  children: string[];
+  justify?: 'start' | 'center' | 'end' | 'spaceBetween' | 'spaceAround';
+  align?: 'start' | 'center' | 'end' | 'stretch';
+};
+
+export type A2UICardComponent = A2UIComponentBase & {
+  component: 'Card';
+  child: string;
+};
+
+export type A2UIDividerComponent = A2UIComponentBase & {
+  component: 'Divider';
+};
+
+export type A2UIButtonComponent = A2UIComponentBase & {
+  component: 'Button';
+  child: string;
+  disabled?: boolean;
+  variant?: 'default' | 'primary' | 'secondary' | 'borderless';
+  action: {
+    event: {
+      name: typeof TLON_A2UI_ACTION_SEND_MESSAGE;
+      context?: {
+        text?: string;
+      };
+    };
+  };
+};
+
+export type A2UIComponent =
+  | A2UITextComponent
+  | A2UIContainerComponent
+  | A2UICardComponent
+  | A2UIDividerComponent
+  | A2UIButtonComponent;
+
+export type A2UICreateSurfaceMessage = {
+  version: 'v0.9';
+  createSurface: {
+    surfaceId: string;
+    catalogId: string;
+  };
+};
+
+export type A2UIUpdateComponentsMessage = {
+  version: 'v0.9';
+  updateComponents: {
+    surfaceId: string;
+    components: A2UIComponent[];
+    root?: string;
+  };
+};
+
+export type A2UIMessage =
+  | A2UICreateSurfaceMessage
+  | A2UIUpdateComponentsMessage;
+
+export type PostBlobDataEntryA2UI = {
+  type: 'a2ui';
+  version: 1;
+  messages: A2UIMessage[];
+  recipe?: unknown;
+};
+
+const A2UI_LIMITS = {
+  maxBytes: 32 * 1024,
+  maxComponents: 50,
+  maxDepth: 8,
+  maxChildren: 12,
+  maxButtons: 8,
+  maxTextNodeLength: 1000,
+  maxButtonMessageLength: 1000,
+  maxTotalTextLength: 8000,
+} as const;
+
+const A2UI_CONTAINER_JUSTIFY_VALUES = [
+  'start',
+  'center',
+  'end',
+  'spaceBetween',
+  'spaceAround',
+] as const;
+
+const A2UI_CONTAINER_ALIGN_VALUES = [
+  'start',
+  'center',
+  'end',
+  'stretch',
+] as const;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isValidWeight(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (typeof value === 'number' &&
+      Number.isFinite(value) &&
+      value >= 0 &&
+      value <= 12)
+  );
+}
+
+function isValidContainerJustify(value: unknown): boolean {
+  return (
+    value === undefined ||
+    A2UI_CONTAINER_JUSTIFY_VALUES.includes(
+      value as (typeof A2UI_CONTAINER_JUSTIFY_VALUES)[number]
+    )
+  );
+}
+
+function isValidContainerAlign(value: unknown): boolean {
+  return (
+    value === undefined ||
+    A2UI_CONTAINER_ALIGN_VALUES.includes(
+      value as (typeof A2UI_CONTAINER_ALIGN_VALUES)[number]
+    )
+  );
+}
+
+function validateA2UIComponent(component: unknown): component is A2UIComponent {
+  if (!isPlainObject(component) || !isNonEmptyString(component.id)) {
+    return false;
+  }
+  if (!isValidWeight(component.weight)) {
+    return false;
+  }
+
+  switch (component.component) {
+    case 'Text':
+      return (
+        typeof component.text === 'string' &&
+        component.text.length <= A2UI_LIMITS.maxTextNodeLength
+      );
+    case 'Row':
+    case 'Column':
+      return (
+        Array.isArray(component.children) &&
+        component.children.length <= A2UI_LIMITS.maxChildren &&
+        component.children.every((child) => isNonEmptyString(child)) &&
+        isValidContainerJustify(component.justify) &&
+        isValidContainerAlign(component.align)
+      );
+    case 'Card':
+      return isNonEmptyString(component.child);
+    case 'Divider':
+      return true;
+    case 'Button': {
+      const action = component.action;
+      const event = isPlainObject(action) ? action.event : null;
+      const context = isPlainObject(event) ? event.context : undefined;
+      return (
+        isNonEmptyString(component.child) &&
+        isPlainObject(action) &&
+        isPlainObject(event) &&
+        event.name === TLON_A2UI_ACTION_SEND_MESSAGE &&
+        (context === undefined || isPlainObject(context)) &&
+        (context === undefined ||
+          context.text === undefined ||
+          (typeof context.text === 'string' &&
+            context.text.length <= A2UI_LIMITS.maxButtonMessageLength))
+      );
+    }
+    default:
+      return false;
+  }
+}
+
+export function getA2UIUpdateMessage(
+  entry: PostBlobDataEntryA2UI
+): A2UIUpdateComponentsMessage | null {
+  return (
+    entry.messages.find(
+      (message): message is A2UIUpdateComponentsMessage =>
+        'updateComponents' in message
+    ) ?? null
+  );
+}
+
+export function getA2UIRootComponentId(
+  entry: PostBlobDataEntryA2UI
+): string | null {
+  const update = getA2UIUpdateMessage(entry);
+  if (!update) {
+    return null;
+  }
+  return (
+    update.updateComponents.root ??
+    update.updateComponents.components[0]?.id ??
+    null
+  );
+}
+
+export function validateA2UIBlobEntry(
+  entry: unknown
+): entry is PostBlobDataEntryA2UI {
+  if (!isPlainObject(entry) || entry.type !== 'a2ui' || entry.version !== 1) {
+    return false;
+  }
+
+  if (JSON.stringify(entry).length > A2UI_LIMITS.maxBytes) {
+    return false;
+  }
+
+  if (!Array.isArray(entry.messages)) {
+    return false;
+  }
+
+  const createMessage = entry.messages.find(
+    (message): message is A2UICreateSurfaceMessage =>
+      isPlainObject(message) && 'createSurface' in message
+  );
+  const updateMessage = entry.messages.find(
+    (message): message is A2UIUpdateComponentsMessage =>
+      isPlainObject(message) && 'updateComponents' in message
+  );
+
+  if (
+    !createMessage ||
+    !updateMessage ||
+    createMessage.version !== 'v0.9' ||
+    updateMessage.version !== 'v0.9' ||
+    !isPlainObject(createMessage.createSurface) ||
+    !isPlainObject(updateMessage.updateComponents)
+  ) {
+    return false;
+  }
+
+  const surfaceId = createMessage.createSurface.surfaceId;
+  const updateSurfaceId = updateMessage.updateComponents.surfaceId;
+  const catalogId = createMessage.createSurface.catalogId;
+  const components = updateMessage.updateComponents.components;
+
+  if (
+    !isNonEmptyString(surfaceId) ||
+    surfaceId !== updateSurfaceId ||
+    !isNonEmptyString(catalogId) ||
+    !Array.isArray(components) ||
+    components.length === 0 ||
+    components.length > A2UI_LIMITS.maxComponents
+  ) {
+    return false;
+  }
+
+  if (!components.every(validateA2UIComponent)) {
+    return false;
+  }
+
+  const byId = new Map<string, A2UIComponent>();
+  let buttonCount = 0;
+  let totalTextLength = 0;
+
+  for (const component of components) {
+    if (byId.has(component.id)) {
+      return false;
+    }
+    byId.set(component.id, component);
+    if (component.component === 'Button') {
+      buttonCount += 1;
+      totalTextLength += component.action.event.context?.text?.length ?? 0;
+    } else if (component.component === 'Text') {
+      totalTextLength += component.text.length;
+    }
+  }
+
+  if (
+    buttonCount > A2UI_LIMITS.maxButtons ||
+    totalTextLength > A2UI_LIMITS.maxTotalTextLength
+  ) {
+    return false;
+  }
+
+  const root = updateMessage.updateComponents.root ?? components[0]?.id;
+  if (!isNonEmptyString(root) || !byId.has(root)) {
+    return false;
+  }
+
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+
+  function visit(id: string, depth: number): boolean {
+    if (depth > A2UI_LIMITS.maxDepth || visiting.has(id)) {
+      return false;
+    }
+    if (visited.has(id)) {
+      return true;
+    }
+    const component = byId.get(id);
+    if (!component) {
+      return false;
+    }
+    visiting.add(id);
+    const children =
+      component.component === 'Row' || component.component === 'Column'
+        ? component.children
+        : component.component === 'Card' || component.component === 'Button'
+          ? [component.child]
+          : [];
+    if (children.length > A2UI_LIMITS.maxChildren) {
+      return false;
+    }
+    for (const child of children) {
+      if (!visit(child, depth + 1)) {
+        return false;
+      }
+    }
+    visiting.delete(id);
+    visited.add(id);
+    return true;
+  }
+
+  return visit(root, 1);
+}
+
+export const PostBlobDataEntryA2UISchema = z.custom<PostBlobDataEntryA2UI>(
+  validateA2UIBlobEntry
+);
diff --git a/packages/api/src/client/content-helpers.ts b/packages/api/src/client/content-helpers.ts
index 1931f5b7e0..9411362f6d 100644
--- a/packages/api/src/client/content-helpers.ts
+++ b/packages/api/src/client/content-helpers.ts
@@ -20,6 +20,9 @@ import {
   constructStory,
   pathToCite,
 } from '../urbit';
+import { PostBlobDataEntryA2UISchema } from './a2ui';
+
+export * from './a2ui';
 
 const logger = createDevLogger('content-helpers', false);
 
@@ -679,6 +682,7 @@ const postBlobDataEntryDefinitions = [
   PostBlobDataEntryFileSchema,
   PostBlobDataEntryVoiceMemoSchema,
   PostBlobDataEntryVideoSchema,
+  PostBlobDataEntryA2UISchema,
 ] as const;
 
 export const PostBlobDataEntrySchema = z.union(postBlobDataEntryDefinitions);
diff --git a/packages/api/src/client/index.ts b/packages/api/src/client/index.ts
index dd349cf14a..2cb0b759d4 100644
--- a/packages/api/src/client/index.ts
+++ b/packages/api/src/client/index.ts
@@ -1,4 +1,5 @@
 export { udToDate } from './apiUtils';
+export * from './a2ui';
 export * from './channelContentConfig';
 export * from './channelsApi';
 export * from './chatApi';
diff --git a/packages/api/src/client/postContent.ts b/packages/api/src/client/postContent.ts
index dfa5319a50..26ea18124e 100644
--- a/packages/api/src/client/postContent.ts
+++ b/packages/api/src/client/postContent.ts
@@ -1,3 +1,4 @@
+import type { PostBlobDataEntryA2UI } from '../client/a2ui';
 import { formatUd } from '../client/apiUtils';
 import {
   PostBlobDataEntryFile,
@@ -116,6 +117,11 @@ export type VoiceMemoBlockData = {
   voiceMemo: PostBlobDataEntryVoiceMemo;
 };
 
+export type A2UIBlockData = {
+  type: 'a2ui';
+  a2ui: PostBlobDataEntryA2UI;
+};
+
 export type LinkBlockData = {
   type: 'link';
   url: string;
@@ -161,6 +167,7 @@ export type BlockData =
   | BlockquoteBlockData
   | ParagraphBlockData
   | ImageBlockData
+  | A2UIBlockData
   | VideoBlockData
   | FileUploadBlockData
   | VoiceMemoBlockData
@@ -397,6 +404,14 @@ export function convertContent(
           break;
         }
 
+        case 'a2ui': {
+          out.push({
+            type: 'a2ui',
+            a2ui: entry,
+          });
+          break;
+        }
+
         case 'unknown': {
           out.push({
             type: 'blockquote',
diff --git a/packages/app/fixtures/A2UI.fixture.tsx b/packages/app/fixtures/A2UI.fixture.tsx
new file mode 100644
index 0000000000..2860691a6b
--- /dev/null
+++ b/packages/app/fixtures/A2UI.fixture.tsx
@@ -0,0 +1,626 @@
+// tamagui-ignore
+import type { JSONContent } from '@tloncorp/api/urbit';
+import type { JSONValue } from '@tloncorp/shared';
+import type { PostBlobDataEntryA2UI } from '@tloncorp/shared/logic';
+import { appendToPostBlob } from '@tloncorp/shared/logic';
+import React, { PropsWithChildren, useMemo, useState } from 'react';
+
+import { ChatMessage, ScrollView, View } from '../ui';
+import {
+  DraftInputContext,
+  DraftInputContextProvider,
+} from '../ui/components/draftInputs/shared';
+import { ChannelProvider } from '../ui/contexts/channel';
+import { FixtureWrapper } from './FixtureWrapper';
+import { exampleContacts, makePost, verse } from './contentHelpers';
+import { group, tlonLocalIntros } from './fakeData';
+
+const weatherA2UI: PostBlobDataEntryA2UI = {
+  type: 'a2ui',
+  version: 1,
+  messages: [
+    {
+      version: 'v0.9',
+      createSurface: {
+        surfaceId: 'weather-brooklyn',
+        catalogId: 'tlon.a2ui.basic.v1',
+      },
+    },
+    {
+      version: 'v0.9',
+      updateComponents: {
+        surfaceId: 'weather-brooklyn',
+        root: 'root',
+        components: [
+          { id: 'root', component: 'Card', child: 'main-column' },
+          {
+            id: 'main-column',
+            component: 'Column',
+            align: 'center',
+            children: [
+              'temp-row',
+              'location',
+              'description',
+              'forecastDivider',
+              'forecast-row',
+            ],
+          },
+          {
+            id: 'temp-row',
+            component: 'Row',
+            align: 'start',
+            children: ['temp-high', 'temp-low'],
+          },
+          {
+            id: 'temp-high',
+            component: 'Text',
+            variant: 'h1',
+            text: '63°',
+          },
+          {
+            id: 'temp-low',
+            component: 'Text',
+            variant: 'h2',
+            text: '48°',
+          },
+          {
+            id: 'location',
+            component: 'Text',
+            variant: 'h3',
+            text: '22903 (Charlottesville, VA)',
+          },
+          {
+            id: 'description',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Partly cloudy · Humidity 76%, Wind 3 mph',
+          },
+          { id: 'forecastDivider', component: 'Divider' },
+          {
+            id: 'forecast-row',
+            component: 'Row',
+            align: 'center',
+            justify: 'spaceAround',
+            children: ['today', 'tomorrow', 'next'],
+          },
+          {
+            id: 'today',
+            component: 'Column',
+            align: 'center',
+            weight: 1,
+            children: ['todayLabel', 'todayIcon', 'todayTemp'],
+          },
+          {
+            id: 'todayLabel',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Today',
+          },
+          { id: 'todayIcon', component: 'Text', variant: 'h2', text: '🌧️' },
+          {
+            id: 'todayTemp',
+            component: 'Text',
+            variant: 'caption',
+            text: '63°',
+          },
+          {
+            id: 'tomorrow',
+            component: 'Column',
+            align: 'center',
+            weight: 1,
+            children: ['tomorrowLabel', 'tomorrowIcon', 'tomorrowTemp'],
+          },
+          {
+            id: 'tomorrowLabel',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Wed',
+          },
+          { id: 'tomorrowIcon', component: 'Text', variant: 'h2', text: '☁️' },
+          {
+            id: 'tomorrowTemp',
+            component: 'Text',
+            variant: 'caption',
+            text: '74°',
+          },
+          {
+            id: 'next',
+            component: 'Column',
+            align: 'center',
+            weight: 1,
+            children: ['nextLabel', 'nextIcon', 'nextTemp'],
+          },
+          {
+            id: 'nextLabel',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Thu',
+          },
+          { id: 'nextIcon', component: 'Text', variant: 'h2', text: '🌧️' },
+          {
+            id: 'nextTemp',
+            component: 'Text',
+            variant: 'caption',
+            text: '75°',
+          },
+        ],
+      },
+    },
+  ],
+};
+
+const confirmationA2UI: PostBlobDataEntryA2UI = {
+  type: 'a2ui',
+  version: 1,
+  messages: [
+    {
+      version: 'v0.9',
+      createSurface: {
+        surfaceId: 'confirm-dm-zod',
+        catalogId: 'tlon.a2ui.basic.v1',
+      },
+    },
+    {
+      version: 'v0.9',
+      updateComponents: {
+        surfaceId: 'confirm-dm-zod',
+        root: 'root',
+        components: [
+          { id: 'root', component: 'Card', child: 'body' },
+          {
+            id: 'body',
+            component: 'Column',
+            children: [
+              'eyebrow',
+              'title',
+              'copy',
+              'divider',
+              'details',
+              'actions',
+            ],
+          },
+          {
+            id: 'eyebrow',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Approval needed',
+          },
+          {
+            id: 'title',
+            component: 'Text',
+            variant: 'h3',
+            text: 'Allow DM from ~zod?',
+          },
+          {
+            id: 'copy',
+            component: 'Text',
+            text: 'This ship wants to start a direct message.',
+          },
+          { id: 'divider', component: 'Divider' },
+          {
+            id: 'details',
+            component: 'Column',
+            children: ['requester', 'note'],
+          },
+          {
+            id: 'requester',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Requester: ~zod',
+          },
+          {
+            id: 'note',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Approve to open a DM, or decline to ignore the request.',
+          },
+          {
+            id: 'actions',
+            component: 'Row',
+            children: ['approve', 'decline', 'block'],
+          },
+          {
+            id: 'approve',
+            component: 'Button',
+            variant: 'primary',
+            child: 'approveLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'approve dm ~zod' },
+              },
+            },
+          },
+          { id: 'approveLabel', component: 'Text', text: 'Approve' },
+          {
+            id: 'decline',
+            component: 'Button',
+            child: 'declineLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'decline dm ~zod' },
+              },
+            },
+          },
+          { id: 'declineLabel', component: 'Text', text: 'Decline' },
+          {
+            id: 'block',
+            component: 'Button',
+            variant: 'borderless',
+            child: 'blockLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'block dm ~zod' },
+              },
+            },
+          },
+          { id: 'blockLabel', component: 'Text', text: 'Block' },
+        ],
+      },
+    },
+  ],
+};
+
+const buildStatusA2UI: PostBlobDataEntryA2UI = {
+  type: 'a2ui',
+  version: 1,
+  messages: [
+    {
+      version: 'v0.9',
+      createSurface: {
+        surfaceId: 'build-status',
+        catalogId: 'tlon.a2ui.basic.v1',
+      },
+    },
+    {
+      version: 'v0.9',
+      updateComponents: {
+        surfaceId: 'build-status',
+        root: 'root',
+        components: [
+          { id: 'root', component: 'Card', child: 'body' },
+          {
+            id: 'body',
+            component: 'Column',
+            children: ['eyebrow', 'title', 'copy', 'divider', 'meta', 'action'],
+          },
+          {
+            id: 'eyebrow',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Deploy preview',
+          },
+          {
+            id: 'title',
+            component: 'Text',
+            variant: 'h3',
+            text: 'Ready for review',
+          },
+          {
+            id: 'copy',
+            component: 'Text',
+            text: 'The latest web build passed checks and is available to inspect.',
+          },
+          { id: 'divider', component: 'Divider' },
+          {
+            id: 'meta',
+            component: 'Column',
+            children: ['branch', 'runtime'],
+          },
+          {
+            id: 'branch',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Branch: db/a2ui-v1',
+          },
+          {
+            id: 'runtime',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Runtime: web · light theme',
+          },
+          {
+            id: 'action',
+            component: 'Button',
+            variant: 'primary',
+            child: 'actionLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'open deploy preview' },
+              },
+            },
+          },
+          { id: 'actionLabel', component: 'Text', text: 'Open preview' },
+        ],
+      },
+    },
+  ],
+};
+
+const meetingA2UI: PostBlobDataEntryA2UI = {
+  type: 'a2ui',
+  version: 1,
+  messages: [
+    {
+      version: 'v0.9',
+      createSurface: {
+        surfaceId: 'meeting-summary',
+        catalogId: 'tlon.a2ui.basic.v1',
+      },
+    },
+    {
+      version: 'v0.9',
+      updateComponents: {
+        surfaceId: 'meeting-summary',
+        root: 'root',
+        components: [
+          { id: 'root', component: 'Card', child: 'body' },
+          {
+            id: 'body',
+            component: 'Column',
+            children: ['title', 'copy', 'divider', 'notes', 'actions'],
+          },
+          {
+            id: 'title',
+            component: 'Text',
+            variant: 'h3',
+            text: 'Design sync',
+          },
+          {
+            id: 'copy',
+            component: 'Text',
+            text: 'Three notes were captured from the A2UI discussion.',
+          },
+          { id: 'divider', component: 'Divider' },
+          {
+            id: 'notes',
+            component: 'Column',
+            children: ['noteOne', 'noteTwo', 'noteThree'],
+          },
+          {
+            id: 'noteOne',
+            component: 'Text',
+            variant: 'caption',
+            text: '1. Start with presentation-only rendering.',
+          },
+          {
+            id: 'noteTwo',
+            component: 'Text',
+            variant: 'caption',
+            text: '2. Use event actions for buttons.',
+          },
+          {
+            id: 'noteThree',
+            component: 'Text',
+            variant: 'caption',
+            text: '3. Keep server expansion as a later phase.',
+          },
+          {
+            id: 'actions',
+            component: 'Row',
+            children: ['save', 'dismiss'],
+          },
+          {
+            id: 'save',
+            component: 'Button',
+            variant: 'primary',
+            child: 'saveLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'save design sync notes' },
+              },
+            },
+          },
+          { id: 'saveLabel', component: 'Text', text: 'Save' },
+          {
+            id: 'dismiss',
+            component: 'Button',
+            variant: 'borderless',
+            child: 'dismissLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'dismiss design sync notes' },
+              },
+            },
+          },
+          { id: 'dismissLabel', component: 'Text', text: 'Dismiss' },
+        ],
+      },
+    },
+  ],
+};
+
+const scoreA2UI: PostBlobDataEntryA2UI = {
+  type: 'a2ui',
+  version: 1,
+  messages: [
+    {
+      version: 'v0.9',
+      createSurface: {
+        surfaceId: 'score-summary',
+        catalogId: 'tlon.a2ui.basic.v1',
+      },
+    },
+    {
+      version: 'v0.9',
+      updateComponents: {
+        surfaceId: 'score-summary',
+        root: 'root',
+        components: [
+          { id: 'root', component: 'Card', child: 'body' },
+          {
+            id: 'body',
+            component: 'Column',
+            align: 'center',
+            children: ['eyebrow', 'scoreRow', 'divider', 'summary'],
+          },
+          {
+            id: 'eyebrow',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Final',
+          },
+          {
+            id: 'scoreRow',
+            component: 'Row',
+            align: 'center',
+            justify: 'center',
+            children: ['home', 'dash', 'away'],
+          },
+          {
+            id: 'home',
+            component: 'Text',
+            variant: 'h2',
+            text: 'Tlon 4',
+          },
+          { id: 'dash', component: 'Text', variant: 'caption', text: 'vs' },
+          {
+            id: 'away',
+            component: 'Text',
+            variant: 'h2',
+            text: 'Mars 2',
+          },
+          { id: 'divider', component: 'Divider' },
+          {
+            id: 'summary',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Two goals in the final minute sealed it.',
+          },
+        ],
+      },
+    },
+  ],
+};
+
+const weatherPost = makePost(
+  exampleContacts.mark,
+  [verse.inline('Weather: 22903 is 57F and partly cloudy.')],
+  { blob: appendToPostBlob(undefined, weatherA2UI), replyCount: 0 }
+);
+
+const confirmationPost = makePost(
+  exampleContacts.groupAdmin,
+  [verse.inline('Allow DM from ~zod?')],
+  { blob: appendToPostBlob(undefined, confirmationA2UI), replyCount: 0 }
+);
+
+const buildStatusPost = makePost(
+  exampleContacts.mark,
+  [verse.inline('Deploy preview is ready.')],
+  { blob: appendToPostBlob(undefined, buildStatusA2UI), replyCount: 0 }
+);
+
+const meetingPost = makePost(
+  exampleContacts.groupAdmin,
+  [verse.inline('Design sync notes captured.')],
+  { blob: appendToPostBlob(undefined, meetingA2UI), replyCount: 0 }
+);
+
+const scorePost = makePost(
+  exampleContacts.mark,
+  [verse.inline('Final score: Tlon 4, Mars 2.')],
+  { blob: appendToPostBlob(undefined, scoreA2UI), replyCount: 0 }
+);
+
+const examplePosts = [
+  weatherPost,
+  confirmationPost,
+  buildStatusPost,
+  meetingPost,
+  scorePost,
+];
+
+function A2UIDraftProvider({ children }: PropsWithChildren) {
+  const [shouldBlur, setShouldBlur] = useState(false);
+  const draftContext = useMemo<DraftInputContext>(
+    () => ({
+      canStartDraft: true,
+      channel: tlonLocalIntros,
+      clearDraft: async () => {},
+      configuration: {} as Record<string, JSONValue>,
+      getDraft: async () => null,
+      group,
+      sendPostFromDraft: async (draft) => {
+        alert(
+          draft.content
+            .map((item) => (typeof item === 'string' ? item : ''))
+            .join('')
+        );
+      },
+      setShouldBlur,
+      shouldBlur,
+      startDraft: () => {},
+      storeDraft: async (_content: JSONContent) => {},
+    }),
+    [shouldBlur]
+  );
+
+  return (
+    <DraftInputContextProvider value={draftContext}>
+      {children}
+    </DraftInputContextProvider>
+  );
+}
+
+function A2UIFixture({ post }: { post: typeof weatherPost }) {
+  return (
+    <FixtureWrapper fillWidth fillHeight>
+      <ChannelProvider value={{ channel: tlonLocalIntros }}>
+        <A2UIDraftProvider>
+          <ScrollView
+            flex={1}
+            contentContainerStyle={{
+              paddingHorizontal: '$m',
+              paddingVertical: '$2xl',
+            }}
+          >
+            <View maxWidth={520} width="100%">
+              <ChatMessage post={post} showAuthor={true} showReplies={true} />
+            </View>
+          </ScrollView>
+        </A2UIDraftProvider>
+      </ChannelProvider>
+    </FixtureWrapper>
+  );
+}
+
+function A2UIExamplesFixture() {
+  return (
+    <FixtureWrapper fillWidth fillHeight>
+      <ChannelProvider value={{ channel: tlonLocalIntros }}>
+        <A2UIDraftProvider>
+          <ScrollView
+            horizontal
+            flex={1}
+            contentContainerStyle={{
+              paddingHorizontal: '$m',
+              paddingVertical: '$2xl',
+            }}
+          >
+            {examplePosts.map((post, index) => (
+              <View
+                key={post.id}
+                width={280}
+                marginRight={index === examplePosts.length - 1 ? '$m' : '$l'}
+              >
+                <ChatMessage post={post} showAuthor={true} showReplies={true} />
+              </View>
+            ))}
+          </ScrollView>
+        </A2UIDraftProvider>
+      </ChannelProvider>
+    </FixtureWrapper>
+  );
+}
+
+export default {
+  Weather: () => <A2UIFixture post={weatherPost} />,
+  ConfirmationDialog: () => <A2UIFixture post={confirmationPost} />,
+  Examples: () => <A2UIExamplesFixture />,
+};
diff --git a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
index f4a85aa4eb..6d6b1a7b40 100644
--- a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
+++ b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
@@ -12,7 +12,9 @@ import {
   usePostContent,
   usePostLastEditContent,
 } from '../PostContent/contentUtils';
+import type { A2UIEvent } from '../PostContent/contentUtils';
 import { SentTimeText } from '../SentTimeText';
+import { useDraftInputContext } from '../draftInputs/shared';
 import { ChatMessageDeliveryStatus } from './ChatMessageDeliveryStatus';
 import { ChatMessageHighlight } from './ChatMessageHighlight';
 import { ChatMessageReplySummary } from './ChatMessageReplySummary';
@@ -55,6 +57,7 @@ export function StaticChatMessage({
   showReplies?: boolean;
 }) {
   const isNotice = post.type === 'notice';
+  const draftInputContext = useDraftInputContext();
 
   if (isNotice) {
     showAuthor = false;
@@ -88,6 +91,29 @@ export function StaticChatMessage({
     }
   }, [onPressRetry, post]);
 
+  const handleA2UIEvent = useCallback(
+    async (event: A2UIEvent) => {
+      if (!draftInputContext || draftInputContext.canStartDraft === false) {
+        return;
+      }
+
+      const text = event.text.trim();
+      if (!text) {
+        return;
+      }
+
+      await draftInputContext.sendPostFromDraft({
+        channelId: draftInputContext.channel.id,
+        content: [text],
+        attachments: [],
+        channelType: draftInputContext.channel.type,
+        replyToPostId: null,
+        isEdit: false,
+      });
+    },
+    [draftInputContext]
+  );
+
   const content = usePostContent(post);
   const lastEditContent = usePostLastEditContent(post);
 
@@ -162,6 +188,11 @@ export function StaticChatMessage({
             onPressImage={handleImagePressed}
             getImageViewerId={(src) => getPostImageViewerId(post.id, src)}
             onLongPress={handleLongPress}
+            onA2UIEvent={
+              draftInputContext && draftInputContext.canStartDraft !== false
+                ? handleA2UIEvent
+                : undefined
+            }
             searchQuery={searchQuery}
           />
         )}
diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
new file mode 100644
index 0000000000..54c2ee5baa
--- /dev/null
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -0,0 +1,280 @@
+import * as cn from '@tloncorp/shared/logic';
+import { Button, Text } from '@tloncorp/ui';
+import React, { ComponentProps, useCallback, useMemo } from 'react';
+import { View, XStack, YStack } from 'tamagui';
+
+import { useContentContext } from './contentUtils';
+
+type RenderOptions = {
+  cardDepth?: number;
+  parentAlign?: cn.A2UIContainerComponent['align'];
+};
+
+function getTextSize(component: cn.A2UITextComponent) {
+  switch (component.variant) {
+    case 'h1':
+      return '$title/l';
+    case 'h2':
+      return '$label/2xl';
+    case 'h3':
+      return '$label/xl';
+    case 'caption':
+      return '$label/m';
+    default:
+      return '$body';
+  }
+}
+
+function getTextColor(component: cn.A2UITextComponent) {
+  return component.variant === 'caption' ? '$secondaryText' : '$primaryText';
+}
+
+function getButtonTreatment(component: cn.A2UIButtonComponent) {
+  switch (component.variant) {
+    case 'primary':
+      return { fill: 'solid', intent: 'primary' } as const;
+    case 'secondary':
+      return { fill: 'outline', intent: 'secondary' } as const;
+    case 'borderless':
+      return { fill: 'ghost', intent: 'secondary' } as const;
+    default:
+      return { fill: 'outline', intent: 'secondary' } as const;
+  }
+}
+
+function getJustifyContent(justify?: cn.A2UIContainerComponent['justify']) {
+  switch (justify) {
+    case 'center':
+      return 'center';
+    case 'end':
+      return 'flex-end';
+    case 'spaceBetween':
+      return 'space-between';
+    case 'spaceAround':
+      return 'space-around';
+    default:
+      return 'flex-start';
+  }
+}
+
+function getAlignItems(
+  align?: cn.A2UIContainerComponent['align'],
+  fallback: 'center' | 'stretch' = 'center'
+) {
+  switch (align) {
+    case 'start':
+      return 'flex-start';
+    case 'end':
+      return 'flex-end';
+    case 'stretch':
+      return 'stretch';
+    default:
+      return fallback;
+  }
+}
+
+function getComponentFlex(component: cn.A2UIComponent) {
+  return component.weight === undefined ? undefined : component.weight;
+}
+
+function getTextAlign(align?: cn.A2UIContainerComponent['align']) {
+  return align === 'center' ? 'center' : undefined;
+}
+
+function getA2UIComponentText(
+  component: cn.A2UIComponent | undefined,
+  components: Map<string, cn.A2UIComponent>
+): string {
+  if (!component) {
+    return '';
+  }
+  switch (component.component) {
+    case 'Text':
+      return component.text;
+    case 'Button':
+    case 'Card':
+      return getA2UIComponentText(components.get(component.child), components);
+    case 'Row':
+    case 'Column':
+      return component.children
+        .map((child) => getA2UIComponentText(components.get(child), components))
+        .filter(Boolean)
+        .join(' ');
+    case 'Divider':
+      return '';
+  }
+}
+
+export function A2UIBlock({
+  block,
+  ...props
+}: { block: cn.A2UIBlockData } & ComponentProps<typeof YStack>) {
+  const context = useContentContext();
+  const update = cn.getA2UIUpdateMessage(block.a2ui);
+  const root = cn.getA2UIRootComponentId(block.a2ui);
+  const components = useMemo(() => {
+    return new Map(
+      update?.updateComponents.components.map((component) => [
+        component.id,
+        component,
+      ]) ?? []
+    );
+  }, [update]);
+
+  const handleButtonPress = useCallback(
+    (component: cn.A2UIButtonComponent) => {
+      const text =
+        component.action.event.context?.text ??
+        getA2UIComponentText(components.get(component.child), components);
+
+      if (!text.trim()) {
+        return;
+      }
+
+      context.onA2UIEvent?.({
+        name: component.action.event.name,
+        text,
+        sourceComponentId: component.id,
+      });
+    },
+    [components, context]
+  );
+
+  const renderComponent = useCallback(
+    (id: string, options: RenderOptions = {}): React.ReactNode => {
+      const component = components.get(id);
+      if (!component) {
+        return null;
+      }
+
+      switch (component.component) {
+        case 'Text': {
+          return (
+            <Text
+              key={component.id}
+              size={getTextSize(component)}
+              color={getTextColor(component)}
+              lineHeight={component.variant === 'h1' ? 44 : undefined}
+              textAlign={getTextAlign(options.parentAlign)}
+              flex={getComponentFlex(component)}
+            >
+              {component.text}
+            </Text>
+          );
+        }
+        case 'Row':
+          return (
+            <XStack
+              key={component.id}
+              gap="$m"
+              alignItems={getAlignItems(component.align)}
+              justifyContent={getJustifyContent(component.justify)}
+              flexWrap="wrap"
+              width="100%"
+              flex={getComponentFlex(component)}
+            >
+              {component.children.map((child) =>
+                renderComponent(child, { parentAlign: component.align })
+              )}
+            </XStack>
+          );
+        case 'Column':
+          const isTextOnlyColumn = component.children.every(
+            (child) => components.get(child)?.component === 'Text'
+          );
+          return (
+            <YStack
+              key={component.id}
+              gap={isTextOnlyColumn ? '$xs' : '$l'}
+              alignItems={getAlignItems(component.align, 'stretch')}
+              justifyContent={getJustifyContent(component.justify)}
+              flex={getComponentFlex(component)}
+            >
+              {component.children.map((child) =>
+                renderComponent(child, { parentAlign: component.align })
+              )}
+            </YStack>
+          );
+        case 'Card': {
+          const isNestedCard = Boolean(options.cardDepth);
+          return (
+            <YStack
+              key={component.id}
+              borderWidth={1}
+              borderColor="$border"
+              borderRadius="$m"
+              backgroundColor={
+                isNestedCard ? '$background' : '$secondaryBackground'
+              }
+              padding={isNestedCard ? '$2xl' : '$m'}
+              gap={isNestedCard ? '$l' : '$m'}
+              shadowColor="$shadow"
+              shadowOffset={{ width: 0, height: 8 }}
+              shadowOpacity={isNestedCard ? 0.04 : 0.08}
+              shadowRadius={isNestedCard ? 12 : 20}
+              flex={getComponentFlex(component)}
+              width={isNestedCard ? '100%' : undefined}
+              alignSelf={isNestedCard ? 'stretch' : 'flex-start'}
+              overflow="hidden"
+            >
+              {renderComponent(component.child, {
+                cardDepth: (options.cardDepth ?? 0) + 1,
+              })}
+            </YStack>
+          );
+        }
+        case 'Divider':
+          return (
+            <View
+              key={component.id}
+              height={1}
+              backgroundColor="$secondaryBackground"
+              marginVertical="$xs"
+              width="100%"
+              flex={getComponentFlex(component)}
+            />
+          );
+        case 'Button': {
+          const disabled = component.disabled || !context.onA2UIEvent;
+          const label = getA2UIComponentText(
+            components.get(component.child),
+            components
+          );
+          const treatment = getButtonTreatment(component);
+          return (
+            <Button.Frame
+              key={component.id}
+              size="medium"
+              fill={treatment.fill}
+              intent={treatment.intent}
+              alignSelf={
+                options.parentAlign === 'center' ? 'center' : 'flex-start'
+              }
+              height={44}
+              paddingHorizontal="$xl"
+              flex={getComponentFlex(component)}
+              disabled={disabled}
+              dimmed={disabled}
+              onPress={
+                disabled ? undefined : () => handleButtonPress(component)
+              }
+            >
+              <Button.Text size="medium">{label}</Button.Text>
+            </Button.Frame>
+          );
+        }
+      }
+    },
+    [components, context.onA2UIEvent, handleButtonPress]
+  );
+
+  if (!root) {
+    return null;
+  }
+
+  return (
+    <YStack gap="$s" maxWidth={560} {...props}>
+      {renderComponent(root)}
+    </YStack>
+  );
+}
diff --git a/packages/app/ui/components/PostContent/BlockRenderer.tsx b/packages/app/ui/components/PostContent/BlockRenderer.tsx
index 6793ae7a72..353c509660 100644
--- a/packages/app/ui/components/PostContent/BlockRenderer.tsx
+++ b/packages/app/ui/components/PostContent/BlockRenderer.tsx
@@ -35,6 +35,7 @@ import {
 import { VideoEmbed } from '../Embed';
 import { FileUploadPreview } from '../FileUploadPreview';
 import { HighlightedCode } from '../HighlightedCode';
+import { A2UIBlock } from './A2UIBlock';
 import { BlockquoteSideBorder } from './BlockquoteSideBorder';
 import { InlineRenderer } from './InlineRenderer';
 import { ContentContext, useContentContext } from './contentUtils';
@@ -698,6 +699,7 @@ export const defaultBlockRenderers: BlockRendererConfig = {
   lineText: LineText,
   blockquote: BlockquoteBlock,
   paragraph: ParagraphBlock,
+  a2ui: A2UIBlock,
   link: LinkBlock,
   image: ImageBlock,
   video: VideoBlock,
@@ -720,6 +722,7 @@ export type DefaultRendererProps = {
   lineText: Partial<ComponentProps<typeof LineText>>;
   blockquote: BlockSettings<typeof BlockquoteBlock>;
   paragraph: BlockSettings<typeof ParagraphBlock>;
+  a2ui: BlockSettings<typeof A2UIBlock>;
   link: BlockSettings<typeof LinkBlock>;
   image: BlockSettings<typeof ImageBlock>;
   video: BlockSettings<typeof VideoBlock>;
diff --git a/packages/app/ui/components/PostContent/ContentRenderer.tsx b/packages/app/ui/components/PostContent/ContentRenderer.tsx
index 53c8fc7091..0b9f8df369 100644
--- a/packages/app/ui/components/PostContent/ContentRenderer.tsx
+++ b/packages/app/ui/components/PostContent/ContentRenderer.tsx
@@ -56,6 +56,7 @@ function ContentRenderer({
   onPressImage,
   getImageViewerId,
   onLongPress,
+  onA2UIEvent,
   isNotice,
   searchQuery,
   ...rest
@@ -67,6 +68,7 @@ function ContentRenderer({
       onPressImage={onPressImage}
       getImageViewerId={getImageViewerId}
       onLongPress={onLongPress}
+      onA2UIEvent={onA2UIEvent}
       isNotice={isNotice}
       searchQuery={searchQuery}
     >
diff --git a/packages/app/ui/components/PostContent/contentUtils.tsx b/packages/app/ui/components/PostContent/contentUtils.tsx
index 86d2baaac8..9fa713e2d1 100644
--- a/packages/app/ui/components/PostContent/contentUtils.tsx
+++ b/packages/app/ui/components/PostContent/contentUtils.tsx
@@ -30,9 +30,16 @@ export interface ContentContextProps {
   onPressImage?: (src: string) => void;
   getImageViewerId?: (src: string) => string | undefined;
   onLongPress?: () => void;
+  onA2UIEvent?: (event: A2UIEvent) => void | Promise<void>;
   searchQuery?: string;
 }
 
+export type A2UIEvent = {
+  name: 'tlon.sendMessage';
+  text: string;
+  sourceComponentId: string;
+};
+
 export const ContentContext = createStyledContext<ContentContextProps>();
 
 export const useContentContext = () => useContext(ContentContext);

From 950f7bdde67a4ee46b6e993b1296c4d94e33c8b8 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Tue, 12 May 2026 19:40:06 -0400
Subject: [PATCH 02/25] add a2ui fixture examples

---
 packages/app/fixtures/A2UI.fixture.tsx        | 652 +++++++++++++++---
 .../ui/components/PostContent/A2UIBlock.tsx   |  54 +-
 2 files changed, 581 insertions(+), 125 deletions(-)

diff --git a/packages/app/fixtures/A2UI.fixture.tsx b/packages/app/fixtures/A2UI.fixture.tsx
index 2860691a6b..1567ab9282 100644
--- a/packages/app/fixtures/A2UI.fixture.tsx
+++ b/packages/app/fixtures/A2UI.fixture.tsx
@@ -39,6 +39,7 @@ const weatherA2UI: PostBlobDataEntryA2UI = {
             align: 'center',
             children: [
               'temp-row',
+              'tempDivider',
               'location',
               'description',
               'forecastDivider',
@@ -48,8 +49,21 @@ const weatherA2UI: PostBlobDataEntryA2UI = {
           {
             id: 'temp-row',
             component: 'Row',
-            align: 'start',
-            children: ['temp-high', 'temp-low'],
+            align: 'center',
+            justify: 'center',
+            children: ['temp-high-column', 'temp-low-column'],
+          },
+          {
+            id: 'temp-high-column',
+            component: 'Column',
+            align: 'center',
+            children: ['temp-high-label', 'temp-high'],
+          },
+          {
+            id: 'temp-high-label',
+            component: 'Text',
+            variant: 'caption',
+            text: 'High',
           },
           {
             id: 'temp-high',
@@ -57,12 +71,25 @@ const weatherA2UI: PostBlobDataEntryA2UI = {
             variant: 'h1',
             text: '63°',
           },
+          {
+            id: 'temp-low-column',
+            component: 'Column',
+            align: 'center',
+            children: ['temp-low-label', 'temp-low'],
+          },
+          {
+            id: 'temp-low-label',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Low',
+          },
           {
             id: 'temp-low',
             component: 'Text',
-            variant: 'h2',
+            variant: 'h1',
             text: '48°',
           },
+          { id: 'tempDivider', component: 'Divider' },
           {
             id: 'location',
             component: 'Text',
@@ -149,119 +176,165 @@ const weatherA2UI: PostBlobDataEntryA2UI = {
   ],
 };
 
-const confirmationA2UI: PostBlobDataEntryA2UI = {
-  type: 'a2ui',
-  version: 1,
-  messages: [
-    {
-      version: 'v0.9',
-      createSurface: {
-        surfaceId: 'confirm-dm-zod',
-        catalogId: 'tlon.a2ui.basic.v1',
+function makeApprovalA2UI({
+  surfaceId,
+  title,
+  copy,
+  allowNote,
+  requestId,
+}: {
+  surfaceId: string;
+  title: string;
+  copy?: string;
+  allowNote: string;
+  requestId: string;
+}): PostBlobDataEntryA2UI {
+  const bodyChildren = copy
+    ? ['eyebrow', 'title', 'copy', 'divider', 'details', 'actions']
+    : ['eyebrow', 'title', 'divider', 'details', 'actions'];
+
+  return {
+    type: 'a2ui',
+    version: 1,
+    messages: [
+      {
+        version: 'v0.9',
+        createSurface: {
+          surfaceId,
+          catalogId: 'tlon.a2ui.basic.v1',
+        },
       },
-    },
-    {
-      version: 'v0.9',
-      updateComponents: {
-        surfaceId: 'confirm-dm-zod',
-        root: 'root',
-        components: [
-          { id: 'root', component: 'Card', child: 'body' },
-          {
-            id: 'body',
-            component: 'Column',
-            children: [
-              'eyebrow',
-              'title',
-              'copy',
-              'divider',
-              'details',
-              'actions',
-            ],
-          },
-          {
-            id: 'eyebrow',
-            component: 'Text',
-            variant: 'caption',
-            text: 'Approval needed',
-          },
-          {
-            id: 'title',
-            component: 'Text',
-            variant: 'h3',
-            text: 'Allow DM from ~zod?',
-          },
-          {
-            id: 'copy',
-            component: 'Text',
-            text: 'This ship wants to start a direct message.',
-          },
-          { id: 'divider', component: 'Divider' },
-          {
-            id: 'details',
-            component: 'Column',
-            children: ['requester', 'note'],
-          },
-          {
-            id: 'requester',
-            component: 'Text',
-            variant: 'caption',
-            text: 'Requester: ~zod',
-          },
-          {
-            id: 'note',
-            component: 'Text',
-            variant: 'caption',
-            text: 'Approve to open a DM, or decline to ignore the request.',
-          },
-          {
-            id: 'actions',
-            component: 'Row',
-            children: ['approve', 'decline', 'block'],
-          },
-          {
-            id: 'approve',
-            component: 'Button',
-            variant: 'primary',
-            child: 'approveLabel',
-            action: {
-              event: {
-                name: 'tlon.sendMessage',
-                context: { text: 'approve dm ~zod' },
+      {
+        version: 'v0.9',
+        updateComponents: {
+          surfaceId,
+          root: 'root',
+          components: [
+            { id: 'root', component: 'Card', child: 'body' },
+            {
+              id: 'body',
+              component: 'Column',
+              children: bodyChildren,
+            },
+            {
+              id: 'eyebrow',
+              component: 'Text',
+              variant: 'caption',
+              text: 'Approval request',
+            },
+            {
+              id: 'title',
+              component: 'Text',
+              variant: 'h3',
+              text: title,
+            },
+            ...(copy
+              ? [
+                  {
+                    id: 'copy',
+                    component: 'Text',
+                    variant: 'caption',
+                    text: copy,
+                  } as const,
+                ]
+              : []),
+            { id: 'divider', component: 'Divider' },
+            {
+              id: 'details',
+              component: 'Column',
+              children: ['allowNote', 'rejectNote', 'banNote'],
+            },
+            {
+              id: 'allowNote',
+              component: 'Text',
+              variant: 'caption',
+              text: allowNote,
+            },
+            {
+              id: 'rejectNote',
+              component: 'Text',
+              variant: 'caption',
+              text: 'Reject declines this request. They can try again later.',
+            },
+            {
+              id: 'banNote',
+              component: 'Text',
+              variant: 'caption',
+              text: 'Ban blocks this ship from contacting the bot.',
+            },
+            {
+              id: 'actions',
+              component: 'Row',
+              children: ['allow', 'reject', 'ban'],
+            },
+            {
+              id: 'allow',
+              component: 'Button',
+              variant: 'primary',
+              child: 'allowLabel',
+              action: {
+                event: {
+                  name: 'tlon.sendMessage',
+                  context: { text: `/allow ${requestId}` },
+                },
               },
             },
-          },
-          { id: 'approveLabel', component: 'Text', text: 'Approve' },
-          {
-            id: 'decline',
-            component: 'Button',
-            child: 'declineLabel',
-            action: {
-              event: {
-                name: 'tlon.sendMessage',
-                context: { text: 'decline dm ~zod' },
+            { id: 'allowLabel', component: 'Text', text: 'Allow' },
+            {
+              id: 'reject',
+              component: 'Button',
+              child: 'rejectLabel',
+              action: {
+                event: {
+                  name: 'tlon.sendMessage',
+                  context: { text: `/reject ${requestId}` },
+                },
               },
             },
-          },
-          { id: 'declineLabel', component: 'Text', text: 'Decline' },
-          {
-            id: 'block',
-            component: 'Button',
-            variant: 'borderless',
-            child: 'blockLabel',
-            action: {
-              event: {
-                name: 'tlon.sendMessage',
-                context: { text: 'block dm ~zod' },
+            { id: 'rejectLabel', component: 'Text', text: 'Reject' },
+            {
+              id: 'ban',
+              component: 'Button',
+              variant: 'borderless',
+              child: 'banLabel',
+              action: {
+                event: {
+                  name: 'tlon.sendMessage',
+                  context: { text: `/ban ${requestId}` },
+                },
               },
             },
-          },
-          { id: 'blockLabel', component: 'Text', text: 'Block' },
-        ],
+            { id: 'banLabel', component: 'Text', text: 'Ban' },
+          ],
+        },
       },
-    },
-  ],
-};
+    ],
+  };
+}
+
+const confirmationA2UI = makeApprovalA2UI({
+  surfaceId: 'confirm-dm-sampel',
+  title: 'DM request from ~sampel-palnet',
+  copy: 'Message: "Hello, I would like to chat with your bot..."',
+  allowNote: 'Allow lets the bot process and respond to DMs from this user.',
+  requestId: 'da1b2',
+});
+
+const channelApprovalA2UI = makeApprovalA2UI({
+  surfaceId: 'confirm-channel-littel',
+  title: '~littel-wolfur mentioned the bot in Design',
+  copy: 'Message: "@bearclawd can you review this build before I merge?"',
+  allowNote: 'Allow lets the bot process and respond to this ship in this channel.',
+  requestId: 'c3d4e',
+});
+
+const groupApprovalA2UI = makeApprovalA2UI({
+  surfaceId: 'confirm-group-robin',
+  title: 'Group invite from ~robin-dasler',
+  copy: 'Garden Club (~robin-dasler/garden-club)',
+  allowNote: 'Allow joins this group so the bot can participate there.',
+  requestId: 'g5f6a',
+});
 
 const buildStatusA2UI: PostBlobDataEntryA2UI = {
   type: 'a2ui',
@@ -284,7 +357,14 @@ const buildStatusA2UI: PostBlobDataEntryA2UI = {
           {
             id: 'body',
             component: 'Column',
-            children: ['eyebrow', 'title', 'copy', 'divider', 'meta', 'action'],
+            children: [
+              'eyebrow',
+              'title',
+              'copy',
+              'divider',
+              'meta',
+              'actions',
+            ],
           },
           {
             id: 'eyebrow',
@@ -321,6 +401,11 @@ const buildStatusA2UI: PostBlobDataEntryA2UI = {
             variant: 'caption',
             text: 'Runtime: web · light theme',
           },
+          {
+            id: 'actions',
+            component: 'Row',
+            children: ['action'],
+          },
           {
             id: 'action',
             component: 'Button',
@@ -498,6 +583,315 @@ const scoreA2UI: PostBlobDataEntryA2UI = {
   ],
 };
 
+const basicComponentsA2UI: PostBlobDataEntryA2UI = {
+  type: 'a2ui',
+  version: 1,
+  messages: [
+    {
+      version: 'v0.9',
+      createSurface: {
+        surfaceId: 'basic-components',
+        catalogId: 'tlon.a2ui.basic.v1',
+      },
+    },
+    {
+      version: 'v0.9',
+      updateComponents: {
+        surfaceId: 'basic-components',
+        root: 'root',
+        components: [
+          { id: 'root', component: 'Card', child: 'body' },
+          {
+            id: 'body',
+            component: 'Column',
+            children: [
+              'title',
+              'intro',
+              'textDivider',
+              'textVariants',
+              'layoutDivider',
+              'layoutCard',
+              'buttonDivider',
+              'buttonRows',
+            ],
+          },
+          {
+            id: 'title',
+            component: 'Text',
+            variant: 'h3',
+            text: 'Basic A2UI components',
+          },
+          {
+            id: 'intro',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Supported presentation components in the initial Tlon renderer.',
+          },
+          { id: 'textDivider', component: 'Divider' },
+          {
+            id: 'textVariants',
+            component: 'Column',
+            children: [
+              'textH1',
+              'textH2',
+              'textH3',
+              'textH4',
+              'textH5',
+              'textBody',
+              'textCaption',
+            ],
+          },
+          { id: 'textH1', component: 'Text', variant: 'h1', text: 'Heading 1' },
+          { id: 'textH2', component: 'Text', variant: 'h2', text: 'Heading 2' },
+          { id: 'textH3', component: 'Text', variant: 'h3', text: 'Heading 3' },
+          { id: 'textH4', component: 'Text', variant: 'h4', text: 'Heading 4' },
+          { id: 'textH5', component: 'Text', variant: 'h5', text: 'Heading 5' },
+          { id: 'textBody', component: 'Text', text: 'Body text' },
+          {
+            id: 'textCaption',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Caption text',
+          },
+          { id: 'layoutDivider', component: 'Divider' },
+          { id: 'layoutCard', component: 'Card', child: 'layoutBody' },
+          {
+            id: 'layoutBody',
+            component: 'Column',
+            children: ['layoutTitle', 'rowStart', 'rowCenter', 'rowEnd'],
+          },
+          {
+            id: 'layoutTitle',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Rows, columns, and nested cards',
+          },
+          {
+            id: 'rowStart',
+            component: 'Row',
+            justify: 'spaceBetween',
+            children: ['startLabel', 'startValue'],
+          },
+          { id: 'startLabel', component: 'Text', text: 'spaceBetween' },
+          {
+            id: 'startValue',
+            component: 'Text',
+            variant: 'caption',
+            text: 'right edge',
+          },
+          {
+            id: 'rowCenter',
+            component: 'Row',
+            align: 'center',
+            justify: 'center',
+            children: ['centerA', 'centerB'],
+          },
+          { id: 'centerA', component: 'Text', variant: 'caption', text: 'center' },
+          { id: 'centerB', component: 'Text', text: 'aligned row' },
+          {
+            id: 'rowEnd',
+            component: 'Row',
+            justify: 'end',
+            children: ['endLabel', 'endValue'],
+          },
+          { id: 'endLabel', component: 'Text', variant: 'caption', text: 'end' },
+          { id: 'endValue', component: 'Text', text: 'aligned row' },
+          { id: 'buttonDivider', component: 'Divider' },
+          {
+            id: 'buttonRows',
+            component: 'Column',
+            children: ['buttonRowOne', 'buttonRowTwo'],
+          },
+          {
+            id: 'buttonRowOne',
+            component: 'Row',
+            children: ['primaryButton', 'secondaryButton', 'defaultButton'],
+          },
+          {
+            id: 'primaryButton',
+            component: 'Button',
+            variant: 'primary',
+            child: 'primaryLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'primary action' },
+              },
+            },
+          },
+          { id: 'primaryLabel', component: 'Text', text: 'Primary' },
+          {
+            id: 'secondaryButton',
+            component: 'Button',
+            variant: 'secondary',
+            child: 'secondaryLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'secondary action' },
+              },
+            },
+          },
+          { id: 'secondaryLabel', component: 'Text', text: 'Secondary' },
+          {
+            id: 'defaultButton',
+            component: 'Button',
+            variant: 'default',
+            child: 'defaultLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'default action' },
+              },
+            },
+          },
+          { id: 'defaultLabel', component: 'Text', text: 'Default' },
+          {
+            id: 'buttonRowTwo',
+            component: 'Row',
+            children: ['borderlessButton', 'disabledButton'],
+          },
+          {
+            id: 'borderlessButton',
+            component: 'Button',
+            variant: 'borderless',
+            child: 'borderlessLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'borderless action' },
+              },
+            },
+          },
+          { id: 'borderlessLabel', component: 'Text', text: 'Borderless' },
+          {
+            id: 'disabledButton',
+            component: 'Button',
+            disabled: true,
+            child: 'disabledLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'disabled action' },
+              },
+            },
+          },
+          { id: 'disabledLabel', component: 'Text', text: 'Disabled' },
+        ],
+      },
+    },
+  ],
+};
+
+const nestedCardA2UI: PostBlobDataEntryA2UI = {
+  type: 'a2ui',
+  version: 1,
+  messages: [
+    {
+      version: 'v0.9',
+      createSurface: {
+        surfaceId: 'nested-card',
+        catalogId: 'tlon.a2ui.basic.v1',
+      },
+    },
+    {
+      version: 'v0.9',
+      updateComponents: {
+        surfaceId: 'nested-card',
+        root: 'root',
+        components: [
+          { id: 'root', component: 'Card', child: 'body' },
+          {
+            id: 'body',
+            component: 'Column',
+            children: ['eyebrow', 'title', 'copy', 'summaryCard', 'actions'],
+          },
+          {
+            id: 'eyebrow',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Nested card',
+          },
+          {
+            id: 'title',
+            component: 'Text',
+            variant: 'h3',
+            text: 'Release summary',
+          },
+          {
+            id: 'copy',
+            component: 'Text',
+            text: 'A sub-card can group related details inside a larger message.',
+          },
+          { id: 'summaryCard', component: 'Card', child: 'summaryBody' },
+          {
+            id: 'summaryBody',
+            component: 'Column',
+            children: ['summaryTitle', 'summaryDivider', 'summaryRows'],
+          },
+          {
+            id: 'summaryTitle',
+            component: 'Text',
+            variant: 'caption',
+            text: 'Changes included',
+          },
+          { id: 'summaryDivider', component: 'Divider' },
+          {
+            id: 'summaryRows',
+            component: 'Column',
+            children: ['summaryOne', 'summaryTwo', 'summaryThree'],
+          },
+          {
+            id: 'summaryOne',
+            component: 'Text',
+            text: 'Weather card refresh',
+          },
+          {
+            id: 'summaryTwo',
+            component: 'Text',
+            text: 'DM approval prompt',
+          },
+          {
+            id: 'summaryThree',
+            component: 'Text',
+            text: 'Basic component catalog',
+          },
+          {
+            id: 'actions',
+            component: 'Row',
+            children: ['acknowledge', 'details'],
+          },
+          {
+            id: 'acknowledge',
+            component: 'Button',
+            variant: 'primary',
+            child: 'acknowledgeLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'acknowledge release summary' },
+              },
+            },
+          },
+          { id: 'acknowledgeLabel', component: 'Text', text: 'Acknowledge' },
+          {
+            id: 'details',
+            component: 'Button',
+            child: 'detailsLabel',
+            action: {
+              event: {
+                name: 'tlon.sendMessage',
+                context: { text: 'show release details' },
+              },
+            },
+          },
+          { id: 'detailsLabel', component: 'Text', text: 'Details' },
+        ],
+      },
+    },
+  ],
+};
+
 const weatherPost = makePost(
   exampleContacts.mark,
   [verse.inline('Weather: 22903 is 57F and partly cloudy.')],
@@ -506,10 +900,22 @@ const weatherPost = makePost(
 
 const confirmationPost = makePost(
   exampleContacts.groupAdmin,
-  [verse.inline('Allow DM from ~zod?')],
+  [verse.inline('DM request from ~sampel-palnet')],
   { blob: appendToPostBlob(undefined, confirmationA2UI), replyCount: 0 }
 );
 
+const channelApprovalPost = makePost(
+  exampleContacts.mark,
+  [verse.inline('Channel mention request from ~littel-wolfur')],
+  { blob: appendToPostBlob(undefined, channelApprovalA2UI), replyCount: 0 }
+);
+
+const groupApprovalPost = makePost(
+  exampleContacts.groupAdmin,
+  [verse.inline('Group invite request from ~robin-dasler')],
+  { blob: appendToPostBlob(undefined, groupApprovalA2UI), replyCount: 0 }
+);
+
 const buildStatusPost = makePost(
   exampleContacts.mark,
   [verse.inline('Deploy preview is ready.')],
@@ -528,11 +934,26 @@ const scorePost = makePost(
   { blob: appendToPostBlob(undefined, scoreA2UI), replyCount: 0 }
 );
 
+const basicComponentsPost = makePost(
+  exampleContacts.mark,
+  [verse.inline('Basic A2UI component catalog.')],
+  { blob: appendToPostBlob(undefined, basicComponentsA2UI), replyCount: 0 }
+);
+
+const nestedCardPost = makePost(
+  exampleContacts.groupAdmin,
+  [verse.inline('Release summary with nested card.')],
+  { blob: appendToPostBlob(undefined, nestedCardA2UI), replyCount: 0 }
+);
+
 const examplePosts = [
   weatherPost,
   confirmationPost,
+  channelApprovalPost,
+  groupApprovalPost,
   buildStatusPost,
   meetingPost,
+  nestedCardPost,
   scorePost,
 ];
 
@@ -576,6 +997,8 @@ function A2UIFixture({ post }: { post: typeof weatherPost }) {
           <ScrollView
             flex={1}
             contentContainerStyle={{
+              alignItems: 'flex-start',
+              flexDirection: 'column',
               paddingHorizontal: '$m',
               paddingVertical: '$2xl',
             }}
@@ -596,9 +1019,10 @@ function A2UIExamplesFixture() {
       <ChannelProvider value={{ channel: tlonLocalIntros }}>
         <A2UIDraftProvider>
           <ScrollView
-            horizontal
             flex={1}
             contentContainerStyle={{
+              alignItems: 'flex-start',
+              flexDirection: 'column',
               paddingHorizontal: '$m',
               paddingVertical: '$2xl',
             }}
@@ -606,8 +1030,9 @@ function A2UIExamplesFixture() {
             {examplePosts.map((post, index) => (
               <View
                 key={post.id}
-                width={280}
-                marginRight={index === examplePosts.length - 1 ? '$m' : '$l'}
+                maxWidth={520}
+                width="100%"
+                marginBottom={index === examplePosts.length - 1 ? 0 : '$l'}
               >
                 <ChatMessage post={post} showAuthor={true} showReplies={true} />
               </View>
@@ -620,6 +1045,7 @@ function A2UIExamplesFixture() {
 }
 
 export default {
+  BasicComponents: () => <A2UIFixture post={basicComponentsPost} />,
   Weather: () => <A2UIFixture post={weatherPost} />,
   ConfirmationDialog: () => <A2UIFixture post={confirmationPost} />,
   Examples: () => <A2UIExamplesFixture />,
diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index 54c2ee5baa..c65312e838 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -15,7 +15,7 @@ function getTextSize(component: cn.A2UITextComponent) {
     case 'h1':
       return '$title/l';
     case 'h2':
-      return '$label/2xl';
+      return '$label/xl';
     case 'h3':
       return '$label/xl';
     case 'caption':
@@ -29,16 +29,45 @@ function getTextColor(component: cn.A2UITextComponent) {
   return component.variant === 'caption' ? '$secondaryText' : '$primaryText';
 }
 
+function getComponentGap(
+  component: cn.A2UIContainerComponent,
+  components: Map<string, cn.A2UIComponent>
+) {
+  const hasButton = component.children.some(
+    (child) => components.get(child)?.component === 'Button'
+  );
+  const isTextOnly = component.children.every(
+    (child) => components.get(child)?.component === 'Text'
+  );
+
+  if (hasButton) {
+    return '$m';
+  }
+
+  if (isTextOnly) {
+    return component.component === 'Row' ? '$s' : '$xs';
+  }
+
+  return '$m';
+}
+
+function hasButtonChild(
+  component: cn.A2UIContainerComponent,
+  components: Map<string, cn.A2UIComponent>
+) {
+  return component.children.some(
+    (child) => components.get(child)?.component === 'Button'
+  );
+}
+
 function getButtonTreatment(component: cn.A2UIButtonComponent) {
   switch (component.variant) {
     case 'primary':
       return { fill: 'solid', intent: 'primary' } as const;
     case 'secondary':
-      return { fill: 'outline', intent: 'secondary' } as const;
     case 'borderless':
-      return { fill: 'ghost', intent: 'secondary' } as const;
     default:
-      return { fill: 'outline', intent: 'secondary' } as const;
+      return { fill: 'ghost', intent: 'secondary' } as const;
   }
 }
 
@@ -166,7 +195,10 @@ export function A2UIBlock({
           return (
             <XStack
               key={component.id}
-              gap="$m"
+              gap={getComponentGap(component, components)}
+              marginTop={
+                hasButtonChild(component, components) ? '$l' : undefined
+              }
               alignItems={getAlignItems(component.align)}
               justifyContent={getJustifyContent(component.justify)}
               flexWrap="wrap"
@@ -178,14 +210,11 @@ export function A2UIBlock({
               )}
             </XStack>
           );
-        case 'Column':
-          const isTextOnlyColumn = component.children.every(
-            (child) => components.get(child)?.component === 'Text'
-          );
+        case 'Column': {
           return (
             <YStack
               key={component.id}
-              gap={isTextOnlyColumn ? '$xs' : '$l'}
+              gap={getComponentGap(component, components)}
               alignItems={getAlignItems(component.align, 'stretch')}
               justifyContent={getJustifyContent(component.justify)}
               flex={getComponentFlex(component)}
@@ -195,6 +224,7 @@ export function A2UIBlock({
               )}
             </YStack>
           );
+        }
         case 'Card': {
           const isNestedCard = Boolean(options.cardDepth);
           return (
@@ -206,7 +236,7 @@ export function A2UIBlock({
               backgroundColor={
                 isNestedCard ? '$background' : '$secondaryBackground'
               }
-              padding={isNestedCard ? '$2xl' : '$m'}
+              padding={isNestedCard ? '$2xl' : '$l'}
               gap={isNestedCard ? '$l' : '$m'}
               shadowColor="$shadow"
               shadowOffset={{ width: 0, height: 8 }}
@@ -228,7 +258,7 @@ export function A2UIBlock({
             <View
               key={component.id}
               height={1}
-              backgroundColor="$secondaryBackground"
+              backgroundColor="$border"
               marginVertical="$xs"
               width="100%"
               flex={getComponentFlex(component)}

From 036b5d81a295319c0fbd472463cc7f1c4ef92586 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Tue, 12 May 2026 20:05:48 -0400
Subject: [PATCH 03/25] simplify a2ui app changes

---
 apps/tlon-web/cosmos.config.json              |   3 +-
 apps/tlon-web/vite.cosmos.config.mts          |  87 ----
 packages/app/fixtures/A2UI.fixture.tsx        | 385 +-----------------
 .../ChatMessage/StaticChatMessage.tsx         |  11 +-
 .../ui/components/PostContent/A2UIBlock.tsx   |  10 +-
 .../PostContent/ContentRenderer.tsx           |   4 +-
 .../components/PostContent/contentUtils.tsx   |   8 +-
 7 files changed, 14 insertions(+), 494 deletions(-)
 delete mode 100644 apps/tlon-web/vite.cosmos.config.mts

diff --git a/apps/tlon-web/cosmos.config.json b/apps/tlon-web/cosmos.config.json
index 5b43149a2e..b0e1a3281c 100644
--- a/apps/tlon-web/cosmos.config.json
+++ b/apps/tlon-web/cosmos.config.json
@@ -3,11 +3,12 @@
   "hostname": "localhost",
   "port": 5555,
   "vite": {
-    "configPath": "./vite.cosmos.config.mts"
+    "configPath": "./vite.config.mts"
   },
   "dom": {
     "containerQuerySelector": "#app"
   },
   "fixturesLocation": "../../packages/app/fixtures",
+  "rendererUrl": "http://localhost:5050/apps/groups/",
   "plugins": ["react-cosmos-plugin-vite"]
 }
diff --git a/apps/tlon-web/vite.cosmos.config.mts b/apps/tlon-web/vite.cosmos.config.mts
deleted file mode 100644
index 09eed7b58a..0000000000
--- a/apps/tlon-web/vite.cosmos.config.mts
+++ /dev/null
@@ -1,87 +0,0 @@
-/// <reference types="vitest" />
-import { tamaguiPlugin } from '@tamagui/vite-plugin';
-import react from '@vitejs/plugin-react';
-import fs from 'fs';
-import { fileURLToPath } from 'url';
-import { Plugin, PluginOption, defineConfig, loadEnv } from 'vite';
-import svgr from 'vite-plugin-svgr';
-
-import expo52PatchPlugin from './expo52PatchPlugin';
-import packageJson from './package.json';
-import reactNativeWeb from './reactNativeWebPlugin';
-
-// Dedicated Vite config for React Cosmos.
-//
-// react-cosmos-plugin-vite 7.2.0 misbehaves when the host config sets `base`:
-// the renderer swap can miss, causing the real app to boot inside the renderer.
-// Keep Cosmos on a minimal config without `base`, Urbit proxy, PWA, or Sentry.
-export default defineConfig(({ mode }) => {
-  process.env.VITE_STORAGE_VERSION = packageJson.version;
-  Object.assign(process.env, loadEnv(mode, process.cwd()));
-
-  return {
-    envPrefix: ['VITE_', 'TAMAGUI_'],
-    plugins: [
-      cosmosIndexHtmlPlugin(),
-      exportingRawText(/\.sql$/),
-      expo52PatchPlugin(),
-      react({
-        babel: {
-          plugins: [
-            '@babel/plugin-proposal-export-namespace-from',
-            'react-native-worklets/plugin',
-          ],
-        },
-        jsxImportSource: '@welldone-software/why-did-you-render',
-      }) as PluginOption[],
-      svgr({ include: '**/*.svg' }) as Plugin,
-      reactNativeWeb(),
-      tamaguiPlugin({
-        config: './tamagui.config.ts',
-        platform: 'web',
-      }) as Plugin,
-    ],
-    resolve: {
-      conditions: ['tlon-source'],
-      dedupe: ['@tanstack/react-query'],
-      alias: {
-        '@': fileURLToPath(new URL('./src', import.meta.url)),
-        'virtual:pwa-register/react': fileURLToPath(
-          new URL('./src/logic/useAppUpdatesStub.ts', import.meta.url)
-        ),
-        'react-native-reanimated': fileURLToPath(
-          new URL('../../node_modules/react-native-reanimated', import.meta.url)
-        ),
-      },
-    },
-    optimizeDeps: {
-      exclude: ['sqlocal', 'virtual:pwa-register/react'],
-    },
-  };
-});
-
-function cosmosIndexHtmlPlugin(): Plugin {
-  return {
-    name: 'cosmos index html',
-    enforce: 'pre',
-    transformIndexHtml(html) {
-      return html.replace(
-        /\s*<script type="module" src="\/src\/storage-wipe\.ts"><\/script>/,
-        ''
-      );
-    },
-  };
-}
-
-function exportingRawText(matchId: RegExp): Plugin {
-  return {
-    name: 'inline sql',
-    enforce: 'pre',
-    transform(_code, id) {
-      if (matchId.test(id)) {
-        const sql = fs.readFileSync(id, 'utf-8');
-        return `export default ${JSON.stringify(sql)}`;
-      }
-    },
-  };
-}
diff --git a/packages/app/fixtures/A2UI.fixture.tsx b/packages/app/fixtures/A2UI.fixture.tsx
index 1567ab9282..e14a2fa10a 100644
--- a/packages/app/fixtures/A2UI.fixture.tsx
+++ b/packages/app/fixtures/A2UI.fixture.tsx
@@ -336,253 +336,6 @@ const groupApprovalA2UI = makeApprovalA2UI({
   requestId: 'g5f6a',
 });
 
-const buildStatusA2UI: PostBlobDataEntryA2UI = {
-  type: 'a2ui',
-  version: 1,
-  messages: [
-    {
-      version: 'v0.9',
-      createSurface: {
-        surfaceId: 'build-status',
-        catalogId: 'tlon.a2ui.basic.v1',
-      },
-    },
-    {
-      version: 'v0.9',
-      updateComponents: {
-        surfaceId: 'build-status',
-        root: 'root',
-        components: [
-          { id: 'root', component: 'Card', child: 'body' },
-          {
-            id: 'body',
-            component: 'Column',
-            children: [
-              'eyebrow',
-              'title',
-              'copy',
-              'divider',
-              'meta',
-              'actions',
-            ],
-          },
-          {
-            id: 'eyebrow',
-            component: 'Text',
-            variant: 'caption',
-            text: 'Deploy preview',
-          },
-          {
-            id: 'title',
-            component: 'Text',
-            variant: 'h3',
-            text: 'Ready for review',
-          },
-          {
-            id: 'copy',
-            component: 'Text',
-            text: 'The latest web build passed checks and is available to inspect.',
-          },
-          { id: 'divider', component: 'Divider' },
-          {
-            id: 'meta',
-            component: 'Column',
-            children: ['branch', 'runtime'],
-          },
-          {
-            id: 'branch',
-            component: 'Text',
-            variant: 'caption',
-            text: 'Branch: db/a2ui-v1',
-          },
-          {
-            id: 'runtime',
-            component: 'Text',
-            variant: 'caption',
-            text: 'Runtime: web · light theme',
-          },
-          {
-            id: 'actions',
-            component: 'Row',
-            children: ['action'],
-          },
-          {
-            id: 'action',
-            component: 'Button',
-            variant: 'primary',
-            child: 'actionLabel',
-            action: {
-              event: {
-                name: 'tlon.sendMessage',
-                context: { text: 'open deploy preview' },
-              },
-            },
-          },
-          { id: 'actionLabel', component: 'Text', text: 'Open preview' },
-        ],
-      },
-    },
-  ],
-};
-
-const meetingA2UI: PostBlobDataEntryA2UI = {
-  type: 'a2ui',
-  version: 1,
-  messages: [
-    {
-      version: 'v0.9',
-      createSurface: {
-        surfaceId: 'meeting-summary',
-        catalogId: 'tlon.a2ui.basic.v1',
-      },
-    },
-    {
-      version: 'v0.9',
-      updateComponents: {
-        surfaceId: 'meeting-summary',
-        root: 'root',
-        components: [
-          { id: 'root', component: 'Card', child: 'body' },
-          {
-            id: 'body',
-            component: 'Column',
-            children: ['title', 'copy', 'divider', 'notes', 'actions'],
-          },
-          {
-            id: 'title',
-            component: 'Text',
-            variant: 'h3',
-            text: 'Design sync',
-          },
-          {
-            id: 'copy',
-            component: 'Text',
-            text: 'Three notes were captured from the A2UI discussion.',
-          },
-          { id: 'divider', component: 'Divider' },
-          {
-            id: 'notes',
-            component: 'Column',
-            children: ['noteOne', 'noteTwo', 'noteThree'],
-          },
-          {
-            id: 'noteOne',
-            component: 'Text',
-            variant: 'caption',
-            text: '1. Start with presentation-only rendering.',
-          },
-          {
-            id: 'noteTwo',
-            component: 'Text',
-            variant: 'caption',
-            text: '2. Use event actions for buttons.',
-          },
-          {
-            id: 'noteThree',
-            component: 'Text',
-            variant: 'caption',
-            text: '3. Keep server expansion as a later phase.',
-          },
-          {
-            id: 'actions',
-            component: 'Row',
-            children: ['save', 'dismiss'],
-          },
-          {
-            id: 'save',
-            component: 'Button',
-            variant: 'primary',
-            child: 'saveLabel',
-            action: {
-              event: {
-                name: 'tlon.sendMessage',
-                context: { text: 'save design sync notes' },
-              },
-            },
-          },
-          { id: 'saveLabel', component: 'Text', text: 'Save' },
-          {
-            id: 'dismiss',
-            component: 'Button',
-            variant: 'borderless',
-            child: 'dismissLabel',
-            action: {
-              event: {
-                name: 'tlon.sendMessage',
-                context: { text: 'dismiss design sync notes' },
-              },
-            },
-          },
-          { id: 'dismissLabel', component: 'Text', text: 'Dismiss' },
-        ],
-      },
-    },
-  ],
-};
-
-const scoreA2UI: PostBlobDataEntryA2UI = {
-  type: 'a2ui',
-  version: 1,
-  messages: [
-    {
-      version: 'v0.9',
-      createSurface: {
-        surfaceId: 'score-summary',
-        catalogId: 'tlon.a2ui.basic.v1',
-      },
-    },
-    {
-      version: 'v0.9',
-      updateComponents: {
-        surfaceId: 'score-summary',
-        root: 'root',
-        components: [
-          { id: 'root', component: 'Card', child: 'body' },
-          {
-            id: 'body',
-            component: 'Column',
-            align: 'center',
-            children: ['eyebrow', 'scoreRow', 'divider', 'summary'],
-          },
-          {
-            id: 'eyebrow',
-            component: 'Text',
-            variant: 'caption',
-            text: 'Final',
-          },
-          {
-            id: 'scoreRow',
-            component: 'Row',
-            align: 'center',
-            justify: 'center',
-            children: ['home', 'dash', 'away'],
-          },
-          {
-            id: 'home',
-            component: 'Text',
-            variant: 'h2',
-            text: 'Tlon 4',
-          },
-          { id: 'dash', component: 'Text', variant: 'caption', text: 'vs' },
-          {
-            id: 'away',
-            component: 'Text',
-            variant: 'h2',
-            text: 'Mars 2',
-          },
-          { id: 'divider', component: 'Divider' },
-          {
-            id: 'summary',
-            component: 'Text',
-            variant: 'caption',
-            text: 'Two goals in the final minute sealed it.',
-          },
-        ],
-      },
-    },
-  ],
-};
-
 const basicComponentsA2UI: PostBlobDataEntryA2UI = {
   type: 'a2ui',
   version: 1,
@@ -783,115 +536,6 @@ const basicComponentsA2UI: PostBlobDataEntryA2UI = {
   ],
 };
 
-const nestedCardA2UI: PostBlobDataEntryA2UI = {
-  type: 'a2ui',
-  version: 1,
-  messages: [
-    {
-      version: 'v0.9',
-      createSurface: {
-        surfaceId: 'nested-card',
-        catalogId: 'tlon.a2ui.basic.v1',
-      },
-    },
-    {
-      version: 'v0.9',
-      updateComponents: {
-        surfaceId: 'nested-card',
-        root: 'root',
-        components: [
-          { id: 'root', component: 'Card', child: 'body' },
-          {
-            id: 'body',
-            component: 'Column',
-            children: ['eyebrow', 'title', 'copy', 'summaryCard', 'actions'],
-          },
-          {
-            id: 'eyebrow',
-            component: 'Text',
-            variant: 'caption',
-            text: 'Nested card',
-          },
-          {
-            id: 'title',
-            component: 'Text',
-            variant: 'h3',
-            text: 'Release summary',
-          },
-          {
-            id: 'copy',
-            component: 'Text',
-            text: 'A sub-card can group related details inside a larger message.',
-          },
-          { id: 'summaryCard', component: 'Card', child: 'summaryBody' },
-          {
-            id: 'summaryBody',
-            component: 'Column',
-            children: ['summaryTitle', 'summaryDivider', 'summaryRows'],
-          },
-          {
-            id: 'summaryTitle',
-            component: 'Text',
-            variant: 'caption',
-            text: 'Changes included',
-          },
-          { id: 'summaryDivider', component: 'Divider' },
-          {
-            id: 'summaryRows',
-            component: 'Column',
-            children: ['summaryOne', 'summaryTwo', 'summaryThree'],
-          },
-          {
-            id: 'summaryOne',
-            component: 'Text',
-            text: 'Weather card refresh',
-          },
-          {
-            id: 'summaryTwo',
-            component: 'Text',
-            text: 'DM approval prompt',
-          },
-          {
-            id: 'summaryThree',
-            component: 'Text',
-            text: 'Basic component catalog',
-          },
-          {
-            id: 'actions',
-            component: 'Row',
-            children: ['acknowledge', 'details'],
-          },
-          {
-            id: 'acknowledge',
-            component: 'Button',
-            variant: 'primary',
-            child: 'acknowledgeLabel',
-            action: {
-              event: {
-                name: 'tlon.sendMessage',
-                context: { text: 'acknowledge release summary' },
-              },
-            },
-          },
-          { id: 'acknowledgeLabel', component: 'Text', text: 'Acknowledge' },
-          {
-            id: 'details',
-            component: 'Button',
-            child: 'detailsLabel',
-            action: {
-              event: {
-                name: 'tlon.sendMessage',
-                context: { text: 'show release details' },
-              },
-            },
-          },
-          { id: 'detailsLabel', component: 'Text', text: 'Details' },
-        ],
-      },
-    },
-  ],
-};
-
 const weatherPost = makePost(
   exampleContacts.mark,
   [verse.inline('Weather: 22903 is 57F and partly cloudy.')],
@@ -916,45 +560,18 @@ const groupApprovalPost = makePost(
   { blob: appendToPostBlob(undefined, groupApprovalA2UI), replyCount: 0 }
 );
 
-const buildStatusPost = makePost(
-  exampleContacts.mark,
-  [verse.inline('Deploy preview is ready.')],
-  { blob: appendToPostBlob(undefined, buildStatusA2UI), replyCount: 0 }
-);
-
-const meetingPost = makePost(
-  exampleContacts.groupAdmin,
-  [verse.inline('Design sync notes captured.')],
-  { blob: appendToPostBlob(undefined, meetingA2UI), replyCount: 0 }
-);
-
-const scorePost = makePost(
-  exampleContacts.mark,
-  [verse.inline('Final score: Tlon 4, Mars 2.')],
-  { blob: appendToPostBlob(undefined, scoreA2UI), replyCount: 0 }
-);
-
 const basicComponentsPost = makePost(
   exampleContacts.mark,
   [verse.inline('Basic A2UI component catalog.')],
   { blob: appendToPostBlob(undefined, basicComponentsA2UI), replyCount: 0 }
 );
 
-const nestedCardPost = makePost(
-  exampleContacts.groupAdmin,
-  [verse.inline('Release summary with nested card.')],
-  { blob: appendToPostBlob(undefined, nestedCardA2UI), replyCount: 0 }
-);
-
 const examplePosts = [
   weatherPost,
   confirmationPost,
   channelApprovalPost,
   groupApprovalPost,
-  buildStatusPost,
-  meetingPost,
-  nestedCardPost,
-  scorePost,
+  basicComponentsPost,
 ];
 
 function A2UIDraftProvider({ children }: PropsWithChildren) {
diff --git a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
index 6d6b1a7b40..00d43c925b 100644
--- a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
+++ b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
@@ -12,7 +12,6 @@ import {
   usePostContent,
   usePostLastEditContent,
 } from '../PostContent/contentUtils';
-import type { A2UIEvent } from '../PostContent/contentUtils';
 import { SentTimeText } from '../SentTimeText';
 import { useDraftInputContext } from '../draftInputs/shared';
 import { ChatMessageDeliveryStatus } from './ChatMessageDeliveryStatus';
@@ -91,13 +90,13 @@ export function StaticChatMessage({
     }
   }, [onPressRetry, post]);
 
-  const handleA2UIEvent = useCallback(
-    async (event: A2UIEvent) => {
+  const handleA2UISendMessage = useCallback(
+    async (message: string) => {
       if (!draftInputContext || draftInputContext.canStartDraft === false) {
         return;
       }
 
-      const text = event.text.trim();
+      const text = message.trim();
       if (!text) {
         return;
       }
@@ -188,9 +187,9 @@ export function StaticChatMessage({
             onPressImage={handleImagePressed}
             getImageViewerId={(src) => getPostImageViewerId(post.id, src)}
             onLongPress={handleLongPress}
-            onA2UIEvent={
+            onA2UISendMessage={
               draftInputContext && draftInputContext.canStartDraft !== false
-                ? handleA2UIEvent
+                ? handleA2UISendMessage
                 : undefined
             }
             searchQuery={searchQuery}
diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index c65312e838..578d72c591 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -160,11 +160,7 @@ export function A2UIBlock({
         return;
       }
 
-      context.onA2UIEvent?.({
-        name: component.action.event.name,
-        text,
-        sourceComponentId: component.id,
-      });
+      context.onA2UISendMessage?.(text);
     },
     [components, context]
   );
@@ -265,7 +261,7 @@ export function A2UIBlock({
             />
           );
         case 'Button': {
-          const disabled = component.disabled || !context.onA2UIEvent;
+          const disabled = component.disabled || !context.onA2UISendMessage;
           const label = getA2UIComponentText(
             components.get(component.child),
             components
@@ -295,7 +291,7 @@ export function A2UIBlock({
         }
       }
     },
-    [components, context.onA2UIEvent, handleButtonPress]
+    [components, context.onA2UISendMessage, handleButtonPress]
   );
 
   if (!root) {
diff --git a/packages/app/ui/components/PostContent/ContentRenderer.tsx b/packages/app/ui/components/PostContent/ContentRenderer.tsx
index 0b9f8df369..252e06476e 100644
--- a/packages/app/ui/components/PostContent/ContentRenderer.tsx
+++ b/packages/app/ui/components/PostContent/ContentRenderer.tsx
@@ -56,7 +56,7 @@ function ContentRenderer({
   onPressImage,
   getImageViewerId,
   onLongPress,
-  onA2UIEvent,
+  onA2UISendMessage,
   isNotice,
   searchQuery,
   ...rest
@@ -68,7 +68,7 @@ function ContentRenderer({
       onPressImage={onPressImage}
       getImageViewerId={getImageViewerId}
       onLongPress={onLongPress}
-      onA2UIEvent={onA2UIEvent}
+      onA2UISendMessage={onA2UISendMessage}
       isNotice={isNotice}
       searchQuery={searchQuery}
     >
diff --git a/packages/app/ui/components/PostContent/contentUtils.tsx b/packages/app/ui/components/PostContent/contentUtils.tsx
index 9fa713e2d1..5c228ea8f9 100644
--- a/packages/app/ui/components/PostContent/contentUtils.tsx
+++ b/packages/app/ui/components/PostContent/contentUtils.tsx
@@ -30,16 +30,10 @@ export interface ContentContextProps {
   onPressImage?: (src: string) => void;
   getImageViewerId?: (src: string) => string | undefined;
   onLongPress?: () => void;
-  onA2UIEvent?: (event: A2UIEvent) => void | Promise<void>;
+  onA2UISendMessage?: (text: string) => void | Promise<void>;
   searchQuery?: string;
 }
 
-export type A2UIEvent = {
-  name: 'tlon.sendMessage';
-  text: string;
-  sourceComponentId: string;
-};
-
 export const ContentContext = createStyledContext<ContentContextProps>();
 
 export const useContentContext = () => useContext(ContentContext);

From 5b2bb2328a4a65459a371d1d1b22bd58bc86a5eb Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 02:00:27 -0400
Subject: [PATCH 04/25] update a2ui approval fixtures

---
 packages/app/fixtures/A2UI.fixture.tsx | 70 +++++++++++++++++---------
 1 file changed, 46 insertions(+), 24 deletions(-)

diff --git a/packages/app/fixtures/A2UI.fixture.tsx b/packages/app/fixtures/A2UI.fixture.tsx
index e14a2fa10a..63fc859e14 100644
--- a/packages/app/fixtures/A2UI.fixture.tsx
+++ b/packages/app/fixtures/A2UI.fixture.tsx
@@ -178,20 +178,40 @@ const weatherA2UI: PostBlobDataEntryA2UI = {
 
 function makeApprovalA2UI({
   surfaceId,
+  eyebrow,
   title,
+  metadata,
   copy,
   allowNote,
   requestId,
 }: {
   surfaceId: string;
+  eyebrow: string;
   title: string;
+  metadata: string[];
   copy?: string;
   allowNote: string;
   requestId: string;
 }): PostBlobDataEntryA2UI {
+  const metadataChildren = metadata.map((_, index) => `metadata-${index}`);
   const bodyChildren = copy
-    ? ['eyebrow', 'title', 'copy', 'divider', 'details', 'actions']
-    : ['eyebrow', 'title', 'divider', 'details', 'actions'];
+    ? [
+        'eyebrow',
+        'title',
+        ...metadataChildren,
+        'copy',
+        'divider',
+        'details',
+        'actions',
+      ]
+    : [
+        'eyebrow',
+        'title',
+        ...metadataChildren,
+        'divider',
+        'details',
+        'actions',
+      ];
 
   return {
     type: 'a2ui',
@@ -220,7 +240,7 @@ function makeApprovalA2UI({
               id: 'eyebrow',
               component: 'Text',
               variant: 'caption',
-              text: 'Approval request',
+              text: eyebrow,
             },
             {
               id: 'title',
@@ -228,6 +248,15 @@ function makeApprovalA2UI({
               variant: 'h3',
               text: title,
             },
+            ...metadata.map(
+              (line, index) =>
+                ({
+                  id: `metadata-${index}`,
+                  component: 'Text',
+                  variant: 'caption',
+                  text: line,
+                }) as const
+            ),
             ...(copy
               ? [
                   {
@@ -242,7 +271,7 @@ function makeApprovalA2UI({
             {
               id: 'details',
               component: 'Column',
-              children: ['allowNote', 'rejectNote', 'banNote'],
+              children: ['allowNote'],
             },
             {
               id: 'allowNote',
@@ -250,18 +279,6 @@ function makeApprovalA2UI({
               variant: 'caption',
               text: allowNote,
             },
-            {
-              id: 'rejectNote',
-              component: 'Text',
-              variant: 'caption',
-              text: 'Reject declines this request. They can try again later.',
-            },
-            {
-              id: 'banNote',
-              component: 'Text',
-              variant: 'caption',
-              text: 'Ban blocks this ship from contacting the bot.',
-            },
             {
               id: 'actions',
               component: 'Row',
@@ -304,7 +321,7 @@ function makeApprovalA2UI({
                 },
               },
             },
-            { id: 'banLabel', component: 'Text', text: 'Ban' },
+            { id: 'banLabel', component: 'Text', text: 'Block' },
           ],
         },
       },
@@ -314,25 +331,30 @@ function makeApprovalA2UI({
 
 const confirmationA2UI = makeApprovalA2UI({
   surfaceId: 'confirm-dm-sampel',
-  title: 'DM request from ~sampel-palnet',
+  eyebrow: 'DM access',
+  title: 'Allow ~sampel-palnet to DM the bot?',
+  metadata: ['Sender: ~sampel-palnet'],
   copy: 'Message: "Hello, I would like to chat with your bot..."',
-  allowNote: 'Allow lets the bot process and respond to DMs from this user.',
+  allowNote: 'The bot will be able to read and reply to future DMs from this user.',
   requestId: 'da1b2',
 });
 
 const channelApprovalA2UI = makeApprovalA2UI({
   surfaceId: 'confirm-channel-littel',
-  title: '~littel-wolfur mentioned the bot in Design',
+  eyebrow: 'Channel access',
+  title: 'Let the bot reply to ~littel-wolfur?',
+  metadata: ['Sender: ~littel-wolfur', 'Channel: Design in Garden Club'],
   copy: 'Message: "@bearclawd can you review this build before I merge?"',
-  allowNote: 'Allow lets the bot process and respond to this ship in this channel.',
+  allowNote: 'The bot will be able to read and reply to this user in this channel.',
   requestId: 'c3d4e',
 });
 
 const groupApprovalA2UI = makeApprovalA2UI({
   surfaceId: 'confirm-group-robin',
-  title: 'Group invite from ~robin-dasler',
-  copy: 'Garden Club (~robin-dasler/garden-club)',
-  allowNote: 'Allow joins this group so the bot can participate there.',
+  eyebrow: 'Group invite',
+  title: 'Let the bot join Garden Club?',
+  metadata: ['Inviter: ~robin-dasler', 'Group ID: ~robin-dasler/garden-club'],
+  allowNote: 'The bot will be able to read and respond in channels it joins.',
   requestId: 'g5f6a',
 });
 

From 0eba1bdf11fce3f1d8a9096f9666455a90c46a2c Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 13:26:03 -0400
Subject: [PATCH 05/25] refine a2ui approval fixtures

---
 packages/app/fixtures/A2UI.fixture.tsx        | 23 ++++++++++++-------
 .../ui/components/PostContent/A2UIBlock.tsx   |  1 -
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/packages/app/fixtures/A2UI.fixture.tsx b/packages/app/fixtures/A2UI.fixture.tsx
index 63fc859e14..0dbb8e8432 100644
--- a/packages/app/fixtures/A2UI.fixture.tsx
+++ b/packages/app/fixtures/A2UI.fixture.tsx
@@ -198,6 +198,7 @@ function makeApprovalA2UI({
     ? [
         'eyebrow',
         'title',
+        'titleDivider',
         ...metadataChildren,
         'copy',
         'divider',
@@ -207,6 +208,7 @@ function makeApprovalA2UI({
     : [
         'eyebrow',
         'title',
+        'titleDivider',
         ...metadataChildren,
         'divider',
         'details',
@@ -248,6 +250,7 @@ function makeApprovalA2UI({
               variant: 'h3',
               text: title,
             },
+            { id: 'titleDivider', component: 'Divider' },
             ...metadata.map(
               (line, index) =>
                 ({
@@ -332,8 +335,8 @@ function makeApprovalA2UI({
 const confirmationA2UI = makeApprovalA2UI({
   surfaceId: 'confirm-dm-sampel',
   eyebrow: 'DM access',
-  title: 'Allow ~sampel-palnet to DM the bot?',
-  metadata: ['Sender: ~sampel-palnet'],
+  title: 'Allow Sam Palnet to DM the bot?',
+  metadata: ['Sender: Sam Palnet (~sampel-palnet)'],
   copy: 'Message: "Hello, I would like to chat with your bot..."',
   allowNote: 'The bot will be able to read and reply to future DMs from this user.',
   requestId: 'da1b2',
@@ -342,8 +345,12 @@ const confirmationA2UI = makeApprovalA2UI({
 const channelApprovalA2UI = makeApprovalA2UI({
   surfaceId: 'confirm-channel-littel',
   eyebrow: 'Channel access',
-  title: 'Let the bot reply to ~littel-wolfur?',
-  metadata: ['Sender: ~littel-wolfur', 'Channel: Design in Garden Club'],
+  title: 'Let the bot reply to Littel Wolfur in Design?',
+  metadata: [
+    'Sender: Littel Wolfur (~littel-wolfur)',
+    'Channel: Design',
+    'Group: Garden Club',
+  ],
   copy: 'Message: "@bearclawd can you review this build before I merge?"',
   allowNote: 'The bot will be able to read and reply to this user in this channel.',
   requestId: 'c3d4e',
@@ -353,7 +360,7 @@ const groupApprovalA2UI = makeApprovalA2UI({
   surfaceId: 'confirm-group-robin',
   eyebrow: 'Group invite',
   title: 'Let the bot join Garden Club?',
-  metadata: ['Inviter: ~robin-dasler', 'Group ID: ~robin-dasler/garden-club'],
+  metadata: ['Inviter: Robin Dasler (~robin-dasler)', 'Group: Garden Club'],
   allowNote: 'The bot will be able to read and respond in channels it joins.',
   requestId: 'g5f6a',
 });
@@ -566,19 +573,19 @@ const weatherPost = makePost(
 
 const confirmationPost = makePost(
   exampleContacts.groupAdmin,
-  [verse.inline('DM request from ~sampel-palnet')],
+  [verse.inline('DM request from Sam Palnet (~sampel-palnet)')],
   { blob: appendToPostBlob(undefined, confirmationA2UI), replyCount: 0 }
 );
 
 const channelApprovalPost = makePost(
   exampleContacts.mark,
-  [verse.inline('Channel mention request from ~littel-wolfur')],
+  [verse.inline('Channel mention request from Littel Wolfur (~littel-wolfur)')],
   { blob: appendToPostBlob(undefined, channelApprovalA2UI), replyCount: 0 }
 );
 
 const groupApprovalPost = makePost(
   exampleContacts.groupAdmin,
-  [verse.inline('Group invite request from ~robin-dasler')],
+  [verse.inline('Group invite request from Robin Dasler (~robin-dasler)')],
   { blob: appendToPostBlob(undefined, groupApprovalA2UI), replyCount: 0 }
 );
 
diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index 578d72c591..b917ac46ac 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -179,7 +179,6 @@ export function A2UIBlock({
               key={component.id}
               size={getTextSize(component)}
               color={getTextColor(component)}
-              lineHeight={component.variant === 'h1' ? 44 : undefined}
               textAlign={getTextAlign(options.parentAlign)}
               flex={getComponentFlex(component)}
             >

From bdf01ae7212f5159bb27d49a031da2ce9cfdd30c Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 13:32:26 -0400
Subject: [PATCH 06/25] format a2ui fixtures

---
 packages/app/fixtures/A2UI.fixture.tsx | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/packages/app/fixtures/A2UI.fixture.tsx b/packages/app/fixtures/A2UI.fixture.tsx
index 0dbb8e8432..ea4233c17b 100644
--- a/packages/app/fixtures/A2UI.fixture.tsx
+++ b/packages/app/fixtures/A2UI.fixture.tsx
@@ -338,7 +338,8 @@ const confirmationA2UI = makeApprovalA2UI({
   title: 'Allow Sam Palnet to DM the bot?',
   metadata: ['Sender: Sam Palnet (~sampel-palnet)'],
   copy: 'Message: "Hello, I would like to chat with your bot..."',
-  allowNote: 'The bot will be able to read and reply to future DMs from this user.',
+  allowNote:
+    'The bot will be able to read and reply to future DMs from this user.',
   requestId: 'da1b2',
 });
 
@@ -352,7 +353,8 @@ const channelApprovalA2UI = makeApprovalA2UI({
     'Group: Garden Club',
   ],
   copy: 'Message: "@bearclawd can you review this build before I merge?"',
-  allowNote: 'The bot will be able to read and reply to this user in this channel.',
+  allowNote:
+    'The bot will be able to read and reply to this user in this channel.',
   requestId: 'c3d4e',
 });
 
@@ -468,7 +470,12 @@ const basicComponentsA2UI: PostBlobDataEntryA2UI = {
             justify: 'center',
             children: ['centerA', 'centerB'],
           },
-          { id: 'centerA', component: 'Text', variant: 'caption', text: 'center' },
+          {
+            id: 'centerA',
+            component: 'Text',
+            variant: 'caption',
+            text: 'center',
+          },
           { id: 'centerB', component: 'Text', text: 'aligned row' },
           {
             id: 'rowEnd',
@@ -476,7 +483,12 @@ const basicComponentsA2UI: PostBlobDataEntryA2UI = {
             justify: 'end',
             children: ['endLabel', 'endValue'],
           },
-          { id: 'endLabel', component: 'Text', variant: 'caption', text: 'end' },
+          {
+            id: 'endLabel',
+            component: 'Text',
+            variant: 'caption',
+            text: 'end',
+          },
           { id: 'endValue', component: 'Text', text: 'aligned row' },
           { id: 'buttonDivider', component: 'Divider' },
           {

From c996b2943e605ea76f83eda36309cbff59702879 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 13:49:20 -0400
Subject: [PATCH 07/25] clean up a2ui api namespace

---
 packages/api/package.json                     |   2 +-
 packages/api/src/__tests__/a2ui.test.ts       |   7 +-
 packages/api/src/client/a2ui.ts               | 196 +++++++++---------
 packages/api/src/client/content-helpers.ts    |   4 +-
 packages/api/src/client/postContent.ts        |   4 +-
 packages/app/fixtures/A2UI.fixture.tsx        |   8 +-
 .../ui/components/PostContent/A2UIBlock.tsx   |  48 ++---
 7 files changed, 131 insertions(+), 138 deletions(-)

diff --git a/packages/api/package.json b/packages/api/package.json
index d77f986525..036e2df754 100644
--- a/packages/api/package.json
+++ b/packages/api/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tloncorp/api",
-  "version": "0.0.6",
+  "version": "0.0.8-a2ui.1",
   "type": "module",
   "files": [
     "dist",
diff --git a/packages/api/src/__tests__/a2ui.test.ts b/packages/api/src/__tests__/a2ui.test.ts
index 1ca843acd5..feaf444187 100644
--- a/packages/api/src/__tests__/a2ui.test.ts
+++ b/packages/api/src/__tests__/a2ui.test.ts
@@ -1,10 +1,9 @@
 import { describe, expect, test } from 'vitest';
 
-import type { PostBlobDataEntryA2UI } from '../client/a2ui';
-import { validateA2UIBlobEntry } from '../client/a2ui';
+import { A2UI } from '../client/a2ui';
 import { appendToPostBlob, parsePostBlob } from '../client/content-helpers';
 
-const a2uiBlobEntry: PostBlobDataEntryA2UI = {
+const a2uiBlobEntry: A2UI.BlobEntry = {
   type: 'a2ui',
   version: 1,
   messages: [
@@ -49,7 +48,7 @@ const a2uiBlobEntry: PostBlobDataEntryA2UI = {
 
 describe('a2ui blob entries', () => {
   test('validates supported a2ui payloads', () => {
-    expect(validateA2UIBlobEntry(a2uiBlobEntry)).toBe(true);
+    expect(A2UI.validateBlobEntry(a2uiBlobEntry)).toBe(true);
   });
 
   test('parsePostBlob parses supported a2ui entries', () => {
diff --git a/packages/api/src/client/a2ui.ts b/packages/api/src/client/a2ui.ts
index 633e23e2d7..2f652d435a 100644
--- a/packages/api/src/client/a2ui.ts
+++ b/packages/api/src/client/a2ui.ts
@@ -1,85 +1,80 @@
 import { z } from 'zod';
 
-export const TLON_A2UI_ACTION_SEND_MESSAGE = 'tlon.sendMessage';
+const ACTION_SEND_MESSAGE = 'tlon.sendMessage';
 
-type A2UIComponentBase = {
+type ComponentBase = {
   id: string;
   weight?: number;
 };
 
-export type A2UITextComponent = A2UIComponentBase & {
-  component: 'Text';
-  text: string;
-  variant?: 'body' | 'caption' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5';
-};
+export namespace A2UI {
+  export type Text = ComponentBase & {
+    component: 'Text';
+    text: string;
+    variant?: 'body' | 'caption' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5';
+  };
 
-export type A2UIContainerComponent = A2UIComponentBase & {
-  component: 'Row' | 'Column';
-  children: string[];
-  justify?: 'start' | 'center' | 'end' | 'spaceBetween' | 'spaceAround';
-  align?: 'start' | 'center' | 'end' | 'stretch';
-};
+  export type Container = ComponentBase & {
+    component: 'Row' | 'Column';
+    children: string[];
+    justify?: 'start' | 'center' | 'end' | 'spaceBetween' | 'spaceAround';
+    align?: 'start' | 'center' | 'end' | 'stretch';
+  };
 
-export type A2UICardComponent = A2UIComponentBase & {
-  component: 'Card';
-  child: string;
-};
+  export type Card = ComponentBase & {
+    component: 'Card';
+    child: string;
+  };
 
-export type A2UIDividerComponent = A2UIComponentBase & {
-  component: 'Divider';
-};
+  export type Divider = ComponentBase & {
+    component: 'Divider';
+  };
 
-export type A2UIButtonComponent = A2UIComponentBase & {
-  component: 'Button';
-  child: string;
-  disabled?: boolean;
-  variant?: 'default' | 'primary' | 'secondary' | 'borderless';
-  action: {
-    event: {
-      name: typeof TLON_A2UI_ACTION_SEND_MESSAGE;
-      context?: {
-        text?: string;
+  export type Button = ComponentBase & {
+    component: 'Button';
+    child: string;
+    disabled?: boolean;
+    variant?: 'default' | 'primary' | 'secondary' | 'borderless';
+    action: {
+      event: {
+        name: typeof ACTION_SEND_MESSAGE;
+        context?: {
+          text?: string;
+        };
       };
     };
   };
-};
 
-export type A2UIComponent =
-  | A2UITextComponent
-  | A2UIContainerComponent
-  | A2UICardComponent
-  | A2UIDividerComponent
-  | A2UIButtonComponent;
-
-export type A2UICreateSurfaceMessage = {
-  version: 'v0.9';
-  createSurface: {
-    surfaceId: string;
-    catalogId: string;
+  export type Component = Text | Container | Card | Divider | Button;
+
+  export type CreateSurfaceMessage = {
+    version: 'v0.9';
+    createSurface: {
+      surfaceId: string;
+      catalogId: string;
+    };
   };
-};
 
-export type A2UIUpdateComponentsMessage = {
-  version: 'v0.9';
-  updateComponents: {
-    surfaceId: string;
-    components: A2UIComponent[];
-    root?: string;
+  export type UpdateComponentsMessage = {
+    version: 'v0.9';
+    updateComponents: {
+      surfaceId: string;
+      components: Component[];
+      root?: string;
+    };
   };
-};
 
-export type A2UIMessage =
-  | A2UICreateSurfaceMessage
-  | A2UIUpdateComponentsMessage;
+  export type Message = CreateSurfaceMessage | UpdateComponentsMessage;
 
-export type PostBlobDataEntryA2UI = {
-  type: 'a2ui';
-  version: 1;
-  messages: A2UIMessage[];
-  recipe?: unknown;
-};
+  export type BlobEntry = {
+    type: 'a2ui';
+    version: 1;
+    messages: Message[];
+    recipe?: unknown;
+  };
+}
 
-const A2UI_LIMITS = {
+const LIMITS = {
   maxBytes: 32 * 1024,
   maxComponents: 50,
   maxDepth: 8,
@@ -90,7 +85,7 @@ const A2UI_LIMITS = {
   maxTotalTextLength: 8000,
 } as const;
 
-const A2UI_CONTAINER_JUSTIFY_VALUES = [
+const CONTAINER_JUSTIFY_VALUES = [
   'start',
   'center',
   'end',
@@ -98,12 +93,7 @@ const A2UI_CONTAINER_JUSTIFY_VALUES = [
   'spaceAround',
 ] as const;
 
-const A2UI_CONTAINER_ALIGN_VALUES = [
-  'start',
-  'center',
-  'end',
-  'stretch',
-] as const;
+const CONTAINER_ALIGN_VALUES = ['start', 'center', 'end', 'stretch'] as const;
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -126,8 +116,8 @@ function isValidWeight(value: unknown): boolean {
 function isValidContainerJustify(value: unknown): boolean {
   return (
     value === undefined ||
-    A2UI_CONTAINER_JUSTIFY_VALUES.includes(
-      value as (typeof A2UI_CONTAINER_JUSTIFY_VALUES)[number]
+    CONTAINER_JUSTIFY_VALUES.includes(
+      value as (typeof CONTAINER_JUSTIFY_VALUES)[number]
     )
   );
 }
@@ -135,13 +125,13 @@ function isValidContainerJustify(value: unknown): boolean {
 function isValidContainerAlign(value: unknown): boolean {
   return (
     value === undefined ||
-    A2UI_CONTAINER_ALIGN_VALUES.includes(
-      value as (typeof A2UI_CONTAINER_ALIGN_VALUES)[number]
+    CONTAINER_ALIGN_VALUES.includes(
+      value as (typeof CONTAINER_ALIGN_VALUES)[number]
     )
   );
 }
 
-function validateA2UIComponent(component: unknown): component is A2UIComponent {
+function validateComponent(component: unknown): component is A2UI.Component {
   if (!isPlainObject(component) || !isNonEmptyString(component.id)) {
     return false;
   }
@@ -153,13 +143,13 @@ function validateA2UIComponent(component: unknown): component is A2UIComponent {
     case 'Text':
       return (
         typeof component.text === 'string' &&
-        component.text.length <= A2UI_LIMITS.maxTextNodeLength
+        component.text.length <= LIMITS.maxTextNodeLength
       );
     case 'Row':
     case 'Column':
       return (
         Array.isArray(component.children) &&
-        component.children.length <= A2UI_LIMITS.maxChildren &&
+        component.children.length <= LIMITS.maxChildren &&
         component.children.every((child) => isNonEmptyString(child)) &&
         isValidContainerJustify(component.justify) &&
         isValidContainerAlign(component.align)
@@ -176,12 +166,12 @@ function validateA2UIComponent(component: unknown): component is A2UIComponent {
         isNonEmptyString(component.child) &&
         isPlainObject(action) &&
         isPlainObject(event) &&
-        event.name === TLON_A2UI_ACTION_SEND_MESSAGE &&
+        event.name === ACTION_SEND_MESSAGE &&
         (context === undefined || isPlainObject(context)) &&
         (context === undefined ||
           context.text === undefined ||
           (typeof context.text === 'string' &&
-            context.text.length <= A2UI_LIMITS.maxButtonMessageLength))
+            context.text.length <= LIMITS.maxButtonMessageLength))
       );
     }
     default:
@@ -189,21 +179,19 @@ function validateA2UIComponent(component: unknown): component is A2UIComponent {
   }
 }
 
-export function getA2UIUpdateMessage(
-  entry: PostBlobDataEntryA2UI
-): A2UIUpdateComponentsMessage | null {
+export function getUpdateMessage(
+  entry: A2UI.BlobEntry
+): A2UI.UpdateComponentsMessage | null {
   return (
     entry.messages.find(
-      (message): message is A2UIUpdateComponentsMessage =>
+      (message): message is A2UI.UpdateComponentsMessage =>
         'updateComponents' in message
     ) ?? null
   );
 }
 
-export function getA2UIRootComponentId(
-  entry: PostBlobDataEntryA2UI
-): string | null {
-  const update = getA2UIUpdateMessage(entry);
+export function getRootComponentId(entry: A2UI.BlobEntry): string | null {
+  const update = getUpdateMessage(entry);
   if (!update) {
     return null;
   }
@@ -214,14 +202,12 @@ export function getA2UIRootComponentId(
   );
 }
 
-export function validateA2UIBlobEntry(
-  entry: unknown
-): entry is PostBlobDataEntryA2UI {
+export function validateBlobEntry(entry: unknown): entry is A2UI.BlobEntry {
   if (!isPlainObject(entry) || entry.type !== 'a2ui' || entry.version !== 1) {
     return false;
   }
 
-  if (JSON.stringify(entry).length > A2UI_LIMITS.maxBytes) {
+  if (JSON.stringify(entry).length > LIMITS.maxBytes) {
     return false;
   }
 
@@ -230,11 +216,11 @@ export function validateA2UIBlobEntry(
   }
 
   const createMessage = entry.messages.find(
-    (message): message is A2UICreateSurfaceMessage =>
+    (message): message is A2UI.CreateSurfaceMessage =>
       isPlainObject(message) && 'createSurface' in message
   );
   const updateMessage = entry.messages.find(
-    (message): message is A2UIUpdateComponentsMessage =>
+    (message): message is A2UI.UpdateComponentsMessage =>
       isPlainObject(message) && 'updateComponents' in message
   );
 
@@ -260,16 +246,16 @@ export function validateA2UIBlobEntry(
     !isNonEmptyString(catalogId) ||
     !Array.isArray(components) ||
     components.length === 0 ||
-    components.length > A2UI_LIMITS.maxComponents
+    components.length > LIMITS.maxComponents
   ) {
     return false;
   }
 
-  if (!components.every(validateA2UIComponent)) {
+  if (!components.every(validateComponent)) {
     return false;
   }
 
-  const byId = new Map<string, A2UIComponent>();
+  const byId = new Map<string, A2UI.Component>();
   let buttonCount = 0;
   let totalTextLength = 0;
 
@@ -287,8 +273,8 @@ export function validateA2UIBlobEntry(
   }
 
   if (
-    buttonCount > A2UI_LIMITS.maxButtons ||
-    totalTextLength > A2UI_LIMITS.maxTotalTextLength
+    buttonCount > LIMITS.maxButtons ||
+    totalTextLength > LIMITS.maxTotalTextLength
   ) {
     return false;
   }
@@ -302,7 +288,7 @@ export function validateA2UIBlobEntry(
   const visited = new Set<string>();
 
   function visit(id: string, depth: number): boolean {
-    if (depth > A2UI_LIMITS.maxDepth || visiting.has(id)) {
+    if (depth > LIMITS.maxDepth || visiting.has(id)) {
       return false;
     }
     if (visited.has(id)) {
@@ -319,7 +305,7 @@ export function validateA2UIBlobEntry(
         : component.component === 'Card' || component.component === 'Button'
           ? [component.child]
           : [];
-    if (children.length > A2UI_LIMITS.maxChildren) {
+    if (children.length > LIMITS.maxChildren) {
       return false;
     }
     for (const child of children) {
@@ -335,6 +321,14 @@ export function validateA2UIBlobEntry(
   return visit(root, 1);
 }
 
-export const PostBlobDataEntryA2UISchema = z.custom<PostBlobDataEntryA2UI>(
-  validateA2UIBlobEntry
-);
+export const blobEntrySchema = z.custom<A2UI.BlobEntry>(validateBlobEntry);
+
+export const A2UI = {
+  action: {
+    sendMessage: ACTION_SEND_MESSAGE,
+  },
+  getUpdateMessage,
+  getRootComponentId,
+  validateBlobEntry,
+  blobEntrySchema,
+} as const;
diff --git a/packages/api/src/client/content-helpers.ts b/packages/api/src/client/content-helpers.ts
index 9411362f6d..7badceb8c7 100644
--- a/packages/api/src/client/content-helpers.ts
+++ b/packages/api/src/client/content-helpers.ts
@@ -20,7 +20,7 @@ import {
   constructStory,
   pathToCite,
 } from '../urbit';
-import { PostBlobDataEntryA2UISchema } from './a2ui';
+import { A2UI } from './a2ui';
 
 export * from './a2ui';
 
@@ -682,7 +682,7 @@ const postBlobDataEntryDefinitions = [
   PostBlobDataEntryFileSchema,
   PostBlobDataEntryVoiceMemoSchema,
   PostBlobDataEntryVideoSchema,
-  PostBlobDataEntryA2UISchema,
+  A2UI.blobEntrySchema,
 ] as const;
 
 export const PostBlobDataEntrySchema = z.union(postBlobDataEntryDefinitions);
diff --git a/packages/api/src/client/postContent.ts b/packages/api/src/client/postContent.ts
index 26ea18124e..a80da29930 100644
--- a/packages/api/src/client/postContent.ts
+++ b/packages/api/src/client/postContent.ts
@@ -1,4 +1,4 @@
-import type { PostBlobDataEntryA2UI } from '../client/a2ui';
+import type { A2UI } from '../client/a2ui';
 import { formatUd } from '../client/apiUtils';
 import {
   PostBlobDataEntryFile,
@@ -119,7 +119,7 @@ export type VoiceMemoBlockData = {
 
 export type A2UIBlockData = {
   type: 'a2ui';
-  a2ui: PostBlobDataEntryA2UI;
+  a2ui: A2UI.BlobEntry;
 };
 
 export type LinkBlockData = {
diff --git a/packages/app/fixtures/A2UI.fixture.tsx b/packages/app/fixtures/A2UI.fixture.tsx
index ea4233c17b..f1069de711 100644
--- a/packages/app/fixtures/A2UI.fixture.tsx
+++ b/packages/app/fixtures/A2UI.fixture.tsx
@@ -1,7 +1,7 @@
 // tamagui-ignore
 import type { JSONContent } from '@tloncorp/api/urbit';
 import type { JSONValue } from '@tloncorp/shared';
-import type { PostBlobDataEntryA2UI } from '@tloncorp/shared/logic';
+import type { A2UI } from '@tloncorp/shared/logic';
 import { appendToPostBlob } from '@tloncorp/shared/logic';
 import React, { PropsWithChildren, useMemo, useState } from 'react';
 
@@ -15,7 +15,7 @@ import { FixtureWrapper } from './FixtureWrapper';
 import { exampleContacts, makePost, verse } from './contentHelpers';
 import { group, tlonLocalIntros } from './fakeData';
 
-const weatherA2UI: PostBlobDataEntryA2UI = {
+const weatherA2UI: A2UI.BlobEntry = {
   type: 'a2ui',
   version: 1,
   messages: [
@@ -192,7 +192,7 @@ function makeApprovalA2UI({
   copy?: string;
   allowNote: string;
   requestId: string;
-}): PostBlobDataEntryA2UI {
+}): A2UI.BlobEntry {
   const metadataChildren = metadata.map((_, index) => `metadata-${index}`);
   const bodyChildren = copy
     ? [
@@ -367,7 +367,7 @@ const groupApprovalA2UI = makeApprovalA2UI({
   requestId: 'g5f6a',
 });
 
-const basicComponentsA2UI: PostBlobDataEntryA2UI = {
+const basicComponentsA2UI: A2UI.BlobEntry = {
   type: 'a2ui',
   version: 1,
   messages: [
diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index b917ac46ac..7b57445871 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -1,4 +1,4 @@
-import * as cn from '@tloncorp/shared/logic';
+import { A2UI, type A2UIBlockData } from '@tloncorp/shared/logic';
 import { Button, Text } from '@tloncorp/ui';
 import React, { ComponentProps, useCallback, useMemo } from 'react';
 import { View, XStack, YStack } from 'tamagui';
@@ -7,10 +7,10 @@ import { useContentContext } from './contentUtils';
 
 type RenderOptions = {
   cardDepth?: number;
-  parentAlign?: cn.A2UIContainerComponent['align'];
+  parentAlign?: A2UI.Container['align'];
 };
 
-function getTextSize(component: cn.A2UITextComponent) {
+function getTextSize(component: A2UI.Text) {
   switch (component.variant) {
     case 'h1':
       return '$title/l';
@@ -25,13 +25,13 @@ function getTextSize(component: cn.A2UITextComponent) {
   }
 }
 
-function getTextColor(component: cn.A2UITextComponent) {
+function getTextColor(component: A2UI.Text) {
   return component.variant === 'caption' ? '$secondaryText' : '$primaryText';
 }
 
 function getComponentGap(
-  component: cn.A2UIContainerComponent,
-  components: Map<string, cn.A2UIComponent>
+  component: A2UI.Container,
+  components: Map<string, A2UI.Component>
 ) {
   const hasButton = component.children.some(
     (child) => components.get(child)?.component === 'Button'
@@ -52,15 +52,15 @@ function getComponentGap(
 }
 
 function hasButtonChild(
-  component: cn.A2UIContainerComponent,
-  components: Map<string, cn.A2UIComponent>
+  component: A2UI.Container,
+  components: Map<string, A2UI.Component>
 ) {
   return component.children.some(
     (child) => components.get(child)?.component === 'Button'
   );
 }
 
-function getButtonTreatment(component: cn.A2UIButtonComponent) {
+function getButtonTreatment(component: A2UI.Button) {
   switch (component.variant) {
     case 'primary':
       return { fill: 'solid', intent: 'primary' } as const;
@@ -71,7 +71,7 @@ function getButtonTreatment(component: cn.A2UIButtonComponent) {
   }
 }
 
-function getJustifyContent(justify?: cn.A2UIContainerComponent['justify']) {
+function getJustifyContent(justify?: A2UI.Container['justify']) {
   switch (justify) {
     case 'center':
       return 'center';
@@ -87,7 +87,7 @@ function getJustifyContent(justify?: cn.A2UIContainerComponent['justify']) {
 }
 
 function getAlignItems(
-  align?: cn.A2UIContainerComponent['align'],
+  align?: A2UI.Container['align'],
   fallback: 'center' | 'stretch' = 'center'
 ) {
   switch (align) {
@@ -102,17 +102,17 @@ function getAlignItems(
   }
 }
 
-function getComponentFlex(component: cn.A2UIComponent) {
+function getComponentFlex(component: A2UI.Component) {
   return component.weight === undefined ? undefined : component.weight;
 }
 
-function getTextAlign(align?: cn.A2UIContainerComponent['align']) {
+function getTextAlign(align?: A2UI.Container['align']) {
   return align === 'center' ? 'center' : undefined;
 }
 
-function getA2UIComponentText(
-  component: cn.A2UIComponent | undefined,
-  components: Map<string, cn.A2UIComponent>
+function getComponentText(
+  component: A2UI.Component | undefined,
+  components: Map<string, A2UI.Component>
 ): string {
   if (!component) {
     return '';
@@ -122,11 +122,11 @@ function getA2UIComponentText(
       return component.text;
     case 'Button':
     case 'Card':
-      return getA2UIComponentText(components.get(component.child), components);
+      return getComponentText(components.get(component.child), components);
     case 'Row':
     case 'Column':
       return component.children
-        .map((child) => getA2UIComponentText(components.get(child), components))
+        .map((child) => getComponentText(components.get(child), components))
         .filter(Boolean)
         .join(' ');
     case 'Divider':
@@ -137,10 +137,10 @@ function getA2UIComponentText(
 export function A2UIBlock({
   block,
   ...props
-}: { block: cn.A2UIBlockData } & ComponentProps<typeof YStack>) {
+}: { block: A2UIBlockData } & ComponentProps<typeof YStack>) {
   const context = useContentContext();
-  const update = cn.getA2UIUpdateMessage(block.a2ui);
-  const root = cn.getA2UIRootComponentId(block.a2ui);
+  const update = A2UI.getUpdateMessage(block.a2ui);
+  const root = A2UI.getRootComponentId(block.a2ui);
   const components = useMemo(() => {
     return new Map(
       update?.updateComponents.components.map((component) => [
@@ -151,10 +151,10 @@ export function A2UIBlock({
   }, [update]);
 
   const handleButtonPress = useCallback(
-    (component: cn.A2UIButtonComponent) => {
+    (component: A2UI.Button) => {
       const text =
         component.action.event.context?.text ??
-        getA2UIComponentText(components.get(component.child), components);
+        getComponentText(components.get(component.child), components);
 
       if (!text.trim()) {
         return;
@@ -261,7 +261,7 @@ export function A2UIBlock({
           );
         case 'Button': {
           const disabled = component.disabled || !context.onA2UISendMessage;
-          const label = getA2UIComponentText(
+          const label = getComponentText(
             components.get(component.child),
             components
           );

From b073592535f88d817094fd5b2a2a5010110c57f6 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 16:42:10 -0400
Subject: [PATCH 08/25] tune a2ui button styles

---
 packages/app/ui/components/PostContent/A2UIBlock.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index 7b57445871..586becffc7 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -63,11 +63,11 @@ function hasButtonChild(
 function getButtonTreatment(component: A2UI.Button) {
   switch (component.variant) {
     case 'primary':
-      return { fill: 'solid', intent: 'primary' } as const;
+      return { fill: 'solid', intent: 'positive' } as const;
     case 'secondary':
     case 'borderless':
     default:
-      return { fill: 'ghost', intent: 'secondary' } as const;
+      return { fill: 'outline', intent: 'secondary' } as const;
   }
 }
 

From 8f6105fac8c97aa8948825abf823de422c3d4438 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 17:44:50 -0400
Subject: [PATCH 09/25] split a2ui validation helpers

---
 packages/api/src/client/a2ui.ts | 102 +++++++++++++++++++++-----------
 1 file changed, 68 insertions(+), 34 deletions(-)

diff --git a/packages/api/src/client/a2ui.ts b/packages/api/src/client/a2ui.ts
index 2f652d435a..2072ec2d77 100644
--- a/packages/api/src/client/a2ui.ts
+++ b/packages/api/src/client/a2ui.ts
@@ -179,40 +179,23 @@ function validateComponent(component: unknown): component is A2UI.Component {
   }
 }
 
-export function getUpdateMessage(
-  entry: A2UI.BlobEntry
-): A2UI.UpdateComponentsMessage | null {
-  return (
-    entry.messages.find(
-      (message): message is A2UI.UpdateComponentsMessage =>
-        'updateComponents' in message
-    ) ?? null
-  );
-}
-
-export function getRootComponentId(entry: A2UI.BlobEntry): string | null {
-  const update = getUpdateMessage(entry);
-  if (!update) {
-    return null;
-  }
-  return (
-    update.updateComponents.root ??
-    update.updateComponents.components[0]?.id ??
-    null
-  );
-}
+type ValidatedEnvelope = {
+  createMessage: A2UI.CreateSurfaceMessage;
+  updateMessage: A2UI.UpdateComponentsMessage;
+  components: A2UI.Component[];
+};
 
-export function validateBlobEntry(entry: unknown): entry is A2UI.BlobEntry {
+function validateEnvelope(entry: unknown): ValidatedEnvelope | null {
   if (!isPlainObject(entry) || entry.type !== 'a2ui' || entry.version !== 1) {
-    return false;
+    return null;
   }
 
   if (JSON.stringify(entry).length > LIMITS.maxBytes) {
-    return false;
+    return null;
   }
 
   if (!Array.isArray(entry.messages)) {
-    return false;
+    return null;
   }
 
   const createMessage = entry.messages.find(
@@ -232,7 +215,7 @@ export function validateBlobEntry(entry: unknown): entry is A2UI.BlobEntry {
     !isPlainObject(createMessage.createSurface) ||
     !isPlainObject(updateMessage.updateComponents)
   ) {
-    return false;
+    return null;
   }
 
   const surfaceId = createMessage.createSurface.surfaceId;
@@ -248,20 +231,26 @@ export function validateBlobEntry(entry: unknown): entry is A2UI.BlobEntry {
     components.length === 0 ||
     components.length > LIMITS.maxComponents
   ) {
-    return false;
+    return null;
   }
 
   if (!components.every(validateComponent)) {
-    return false;
+    return null;
   }
 
+  return { createMessage, updateMessage, components };
+}
+
+function indexComponents(
+  components: A2UI.Component[]
+): Map<string, A2UI.Component> | null {
   const byId = new Map<string, A2UI.Component>();
   let buttonCount = 0;
   let totalTextLength = 0;
 
   for (const component of components) {
     if (byId.has(component.id)) {
-      return false;
+      return null;
     }
     byId.set(component.id, component);
     if (component.component === 'Button') {
@@ -276,11 +265,17 @@ export function validateBlobEntry(entry: unknown): entry is A2UI.BlobEntry {
     buttonCount > LIMITS.maxButtons ||
     totalTextLength > LIMITS.maxTotalTextLength
   ) {
-    return false;
+    return null;
   }
 
-  const root = updateMessage.updateComponents.root ?? components[0]?.id;
-  if (!isNonEmptyString(root) || !byId.has(root)) {
+  return byId;
+}
+
+function validateReachableTree(
+  root: string,
+  components: Map<string, A2UI.Component>
+): boolean {
+  if (!isNonEmptyString(root) || !components.has(root)) {
     return false;
   }
 
@@ -294,7 +289,7 @@ export function validateBlobEntry(entry: unknown): entry is A2UI.BlobEntry {
     if (visited.has(id)) {
       return true;
     }
-    const component = byId.get(id);
+    const component = components.get(id);
     if (!component) {
       return false;
     }
@@ -321,6 +316,45 @@ export function validateBlobEntry(entry: unknown): entry is A2UI.BlobEntry {
   return visit(root, 1);
 }
 
+export function getUpdateMessage(
+  entry: A2UI.BlobEntry
+): A2UI.UpdateComponentsMessage | null {
+  return (
+    entry.messages.find(
+      (message): message is A2UI.UpdateComponentsMessage =>
+        'updateComponents' in message
+    ) ?? null
+  );
+}
+
+export function getRootComponentId(entry: A2UI.BlobEntry): string | null {
+  const update = getUpdateMessage(entry);
+  if (!update) {
+    return null;
+  }
+  return (
+    update.updateComponents.root ??
+    update.updateComponents.components[0]?.id ??
+    null
+  );
+}
+
+export function validateBlobEntry(entry: unknown): entry is A2UI.BlobEntry {
+  const envelope = validateEnvelope(entry);
+  if (!envelope) {
+    return false;
+  }
+
+  const components = indexComponents(envelope.components);
+  if (!components) {
+    return false;
+  }
+
+  const root =
+    envelope.updateMessage.updateComponents.root ?? envelope.components[0]?.id;
+  return validateReachableTree(root, components);
+}
+
 export const blobEntrySchema = z.custom<A2UI.BlobEntry>(validateBlobEntry);
 
 export const A2UI = {

From 1f7ffa9b67e79922241d8d516369f7b96c5bbbee Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 18:28:01 -0400
Subject: [PATCH 10/25] chore(api): release 0.0.8

---
 packages/api/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/api/package.json b/packages/api/package.json
index 036e2df754..5799e46e66 100644
--- a/packages/api/package.json
+++ b/packages/api/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tloncorp/api",
-  "version": "0.0.8-a2ui.1",
+  "version": "0.0.8",
   "type": "module",
   "files": [
     "dist",

From 37ae198fbf83d51a009946dc4be3321894fd23ff Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 18:55:10 -0400
Subject: [PATCH 11/25] rename a2ui action handler

---
 .../components/ChatMessage/StaticChatMessage.tsx   | 14 ++++++++++----
 .../app/ui/components/PostContent/A2UIBlock.tsx    | 10 +++++-----
 .../ui/components/PostContent/ContentRenderer.tsx  |  4 ++--
 .../app/ui/components/PostContent/contentUtils.tsx |  7 +++++--
 4 files changed, 22 insertions(+), 13 deletions(-)

diff --git a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
index 00d43c925b..ee06d76a7b 100644
--- a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
+++ b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
@@ -1,4 +1,5 @@
 import * as db from '@tloncorp/shared/db';
+import { A2UI } from '@tloncorp/shared/logic';
 import { Text } from '@tloncorp/ui';
 import { ComponentProps, useCallback } from 'react';
 import { View, XStack, YStack, isWeb } from 'tamagui';
@@ -90,12 +91,17 @@ export function StaticChatMessage({
     }
   }, [onPressRetry, post]);
 
-  const handleA2UISendMessage = useCallback(
-    async (message: string) => {
+  const handleA2UIAction = useCallback(
+    async (action: A2UI.Button['action'], fallbackText: string) => {
       if (!draftInputContext || draftInputContext.canStartDraft === false) {
         return;
       }
 
+      if (action.event.name !== A2UI.action.sendMessage) {
+        return;
+      }
+
+      const message = action.event.context?.text ?? fallbackText;
       const text = message.trim();
       if (!text) {
         return;
@@ -187,9 +193,9 @@ export function StaticChatMessage({
             onPressImage={handleImagePressed}
             getImageViewerId={(src) => getPostImageViewerId(post.id, src)}
             onLongPress={handleLongPress}
-            onA2UISendMessage={
+            onA2UIAction={
               draftInputContext && draftInputContext.canStartDraft !== false
-                ? handleA2UISendMessage
+                ? handleA2UIAction
                 : undefined
             }
             searchQuery={searchQuery}
diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index 586becffc7..7445548bd0 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -152,15 +152,15 @@ export function A2UIBlock({
 
   const handleButtonPress = useCallback(
     (component: A2UI.Button) => {
-      const text =
+      const fallbackText =
         component.action.event.context?.text ??
         getComponentText(components.get(component.child), components);
 
-      if (!text.trim()) {
+      if (!fallbackText.trim()) {
         return;
       }
 
-      context.onA2UISendMessage?.(text);
+      context.onA2UIAction?.(component.action, fallbackText);
     },
     [components, context]
   );
@@ -260,7 +260,7 @@ export function A2UIBlock({
             />
           );
         case 'Button': {
-          const disabled = component.disabled || !context.onA2UISendMessage;
+          const disabled = component.disabled || !context.onA2UIAction;
           const label = getComponentText(
             components.get(component.child),
             components
@@ -290,7 +290,7 @@ export function A2UIBlock({
         }
       }
     },
-    [components, context.onA2UISendMessage, handleButtonPress]
+    [components, context.onA2UIAction, handleButtonPress]
   );
 
   if (!root) {
diff --git a/packages/app/ui/components/PostContent/ContentRenderer.tsx b/packages/app/ui/components/PostContent/ContentRenderer.tsx
index 252e06476e..d0eb28c4c0 100644
--- a/packages/app/ui/components/PostContent/ContentRenderer.tsx
+++ b/packages/app/ui/components/PostContent/ContentRenderer.tsx
@@ -56,7 +56,7 @@ function ContentRenderer({
   onPressImage,
   getImageViewerId,
   onLongPress,
-  onA2UISendMessage,
+  onA2UIAction,
   isNotice,
   searchQuery,
   ...rest
@@ -68,7 +68,7 @@ function ContentRenderer({
       onPressImage={onPressImage}
       getImageViewerId={getImageViewerId}
       onLongPress={onLongPress}
-      onA2UISendMessage={onA2UISendMessage}
+      onA2UIAction={onA2UIAction}
       isNotice={isNotice}
       searchQuery={searchQuery}
     >
diff --git a/packages/app/ui/components/PostContent/contentUtils.tsx b/packages/app/ui/components/PostContent/contentUtils.tsx
index 5c228ea8f9..56cc2d7c95 100644
--- a/packages/app/ui/components/PostContent/contentUtils.tsx
+++ b/packages/app/ui/components/PostContent/contentUtils.tsx
@@ -1,5 +1,5 @@
 import { Post } from '@tloncorp/shared/db';
-import { BlockData, convertContent } from '@tloncorp/shared/logic';
+import { BlockData, convertContent, type A2UI } from '@tloncorp/shared/logic';
 import { useContext, useMemo } from 'react';
 import { createStyledContext } from 'tamagui';
 
@@ -30,7 +30,10 @@ export interface ContentContextProps {
   onPressImage?: (src: string) => void;
   getImageViewerId?: (src: string) => string | undefined;
   onLongPress?: () => void;
-  onA2UISendMessage?: (text: string) => void | Promise<void>;
+  onA2UIAction?: (
+    action: A2UI.Button['action'],
+    fallbackText: string
+  ) => void | Promise<void>;
   searchQuery?: string;
 }
 

From 2761d34050846e674ab2cb70f1c9c49699982960 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 19:02:43 -0400
Subject: [PATCH 12/25] name a2ui button action types

---
 packages/api/src/client/a2ui.ts | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/packages/api/src/client/a2ui.ts b/packages/api/src/client/a2ui.ts
index 2072ec2d77..976592718d 100644
--- a/packages/api/src/client/a2ui.ts
+++ b/packages/api/src/client/a2ui.ts
@@ -30,19 +30,25 @@ export namespace A2UI {
     component: 'Divider';
   };
 
+  export type SendMessageEvent = {
+    name: typeof ACTION_SEND_MESSAGE;
+    context?: {
+      text?: string;
+    };
+  };
+
+  export type EventAction = {
+    event: SendMessageEvent;
+  };
+
+  export type ButtonAction = EventAction;
+
   export type Button = ComponentBase & {
     component: 'Button';
     child: string;
     disabled?: boolean;
     variant?: 'default' | 'primary' | 'secondary' | 'borderless';
-    action: {
-      event: {
-        name: typeof ACTION_SEND_MESSAGE;
-        context?: {
-          text?: string;
-        };
-      };
-    };
+    action: ButtonAction;
   };
 
   export type Component = Text | Container | Card | Divider | Button;

From a9fba842d879be04f4b0010559c45ed221d3db16 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 19:09:31 -0400
Subject: [PATCH 13/25] always pass a2ui action handler

---
 .../app/ui/components/ChatMessage/StaticChatMessage.tsx     | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
index ee06d76a7b..9e019f7c6c 100644
--- a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
+++ b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
@@ -193,11 +193,7 @@ export function StaticChatMessage({
             onPressImage={handleImagePressed}
             getImageViewerId={(src) => getPostImageViewerId(post.id, src)}
             onLongPress={handleLongPress}
-            onA2UIAction={
-              draftInputContext && draftInputContext.canStartDraft !== false
-                ? handleA2UIAction
-                : undefined
-            }
+            onA2UIAction={handleA2UIAction}
             searchQuery={searchQuery}
           />
         )}

From ba4570f49af3296c6f646ab77f9f1e3491636b91 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 19:11:28 -0400
Subject: [PATCH 14/25] check a2ui action before draft state

---
 packages/app/ui/components/ChatMessage/StaticChatMessage.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
index 9e019f7c6c..490856fcf7 100644
--- a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
+++ b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
@@ -93,11 +93,11 @@ export function StaticChatMessage({
 
   const handleA2UIAction = useCallback(
     async (action: A2UI.Button['action'], fallbackText: string) => {
-      if (!draftInputContext || draftInputContext.canStartDraft === false) {
+      if (action.event.name !== A2UI.action.sendMessage) {
         return;
       }
 
-      if (action.event.name !== A2UI.action.sendMessage) {
+      if (!draftInputContext || draftInputContext.canStartDraft === false) {
         return;
       }
 

From dfd87c1ad4a8a8baa571aa46fa17ce68c538b527 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 19:15:19 -0400
Subject: [PATCH 15/25] remove a2ui card shadow

---
 packages/app/ui/components/PostContent/A2UIBlock.tsx | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index 7445548bd0..46cf595070 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -233,10 +233,6 @@ export function A2UIBlock({
               }
               padding={isNestedCard ? '$2xl' : '$l'}
               gap={isNestedCard ? '$l' : '$m'}
-              shadowColor="$shadow"
-              shadowOffset={{ width: 0, height: 8 }}
-              shadowOpacity={isNestedCard ? 0.04 : 0.08}
-              shadowRadius={isNestedCard ? 12 : 20}
               flex={getComponentFlex(component)}
               width={isNestedCard ? '100%' : undefined}
               alignSelf={isNestedCard ? 'stretch' : 'flex-start'}

From 4b955d552e1925ad1943c29b0926147ac8b466f4 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 19:22:56 -0400
Subject: [PATCH 16/25] format a2ui content utils import

---
 packages/app/ui/components/PostContent/contentUtils.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/app/ui/components/PostContent/contentUtils.tsx b/packages/app/ui/components/PostContent/contentUtils.tsx
index 56cc2d7c95..5b6149e17e 100644
--- a/packages/app/ui/components/PostContent/contentUtils.tsx
+++ b/packages/app/ui/components/PostContent/contentUtils.tsx
@@ -1,5 +1,5 @@
 import { Post } from '@tloncorp/shared/db';
-import { BlockData, convertContent, type A2UI } from '@tloncorp/shared/logic';
+import { type A2UI, BlockData, convertContent } from '@tloncorp/shared/logic';
 import { useContext, useMemo } from 'react';
 import { createStyledContext } from 'tamagui';
 

From 7f6b07de01c0f8f34323ea12c71943cdf7a5a8c8 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 19:29:26 -0400
Subject: [PATCH 17/25] address a2ui review comments

---
 packages/api/src/__tests__/a2ui.test.ts       | 64 +++++++++++++++++++
 packages/api/src/client/a2ui.ts               | 19 ++++++
 .../ChatMessage/StaticChatMessage.tsx         |  3 +
 .../ui/components/PostContent/A2UIBlock.tsx   | 12 +++-
 .../PostContent/ContentRenderer.tsx           |  2 +
 .../components/PostContent/contentUtils.tsx   |  1 +
 6 files changed, 99 insertions(+), 2 deletions(-)

diff --git a/packages/api/src/__tests__/a2ui.test.ts b/packages/api/src/__tests__/a2ui.test.ts
index feaf444187..6f3398d350 100644
--- a/packages/api/src/__tests__/a2ui.test.ts
+++ b/packages/api/src/__tests__/a2ui.test.ts
@@ -96,4 +96,68 @@ describe('a2ui blob entries', () => {
       )
     ).toEqual([{ type: 'unknown' }, { type: 'unknown' }]);
   });
+
+  test('rejects malformed a2ui button optional fields', () => {
+    expect(
+      A2UI.validateBlobEntry({
+        ...a2uiBlobEntry,
+        messages: [
+          a2uiBlobEntry.messages[0],
+          {
+            version: 'v0.9',
+            updateComponents: {
+              surfaceId: 'weather-card',
+              root: 'root',
+              components: [
+                {
+                  id: 'root',
+                  component: 'Button',
+                  child: 'label',
+                  disabled: 'false',
+                  action: {
+                    event: {
+                      name: 'tlon.sendMessage',
+                      context: { text: 'refresh weather' },
+                    },
+                  },
+                },
+                { id: 'label', component: 'Text', text: 'Refresh' },
+              ],
+            },
+          },
+        ],
+      })
+    ).toBe(false);
+
+    expect(
+      A2UI.validateBlobEntry({
+        ...a2uiBlobEntry,
+        messages: [
+          a2uiBlobEntry.messages[0],
+          {
+            version: 'v0.9',
+            updateComponents: {
+              surfaceId: 'weather-card',
+              root: 'root',
+              components: [
+                {
+                  id: 'root',
+                  component: 'Button',
+                  child: 'label',
+                  variant: 'danger',
+                  action: {
+                    event: {
+                      name: 'tlon.sendMessage',
+                      context: { text: 'refresh weather' },
+                    },
+                  },
+                },
+                { id: 'label', component: 'Text', text: 'Refresh' },
+              ],
+            },
+          },
+        ],
+      })
+    ).toBe(false);
+  });
 });
diff --git a/packages/api/src/client/a2ui.ts b/packages/api/src/client/a2ui.ts
index 976592718d..8fe1873c05 100644
--- a/packages/api/src/client/a2ui.ts
+++ b/packages/api/src/client/a2ui.ts
@@ -101,6 +101,13 @@ const CONTAINER_JUSTIFY_VALUES = [
 
 const CONTAINER_ALIGN_VALUES = ['start', 'center', 'end', 'stretch'] as const;
 
+const BUTTON_VARIANT_VALUES = [
+  'default',
+  'primary',
+  'secondary',
+  'borderless',
+] as const;
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -137,6 +144,15 @@ function isValidContainerAlign(value: unknown): boolean {
   );
 }
 
+function isValidButtonVariant(value: unknown): boolean {
+  return (
+    value === undefined ||
+    BUTTON_VARIANT_VALUES.includes(
+      value as (typeof BUTTON_VARIANT_VALUES)[number]
+    )
+  );
+}
+
 function validateComponent(component: unknown): component is A2UI.Component {
   if (!isPlainObject(component) || !isNonEmptyString(component.id)) {
     return false;
@@ -170,6 +186,9 @@ function validateComponent(component: unknown): component is A2UI.Component {
       const context = isPlainObject(event) ? event.context : undefined;
       return (
         isNonEmptyString(component.child) &&
+        (component.disabled === undefined ||
+          typeof component.disabled === 'boolean') &&
+        isValidButtonVariant(component.variant) &&
         isPlainObject(action) &&
         isPlainObject(event) &&
         event.name === ACTION_SEND_MESSAGE &&
diff --git a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
index 490856fcf7..46fdc5339e 100644
--- a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
+++ b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
@@ -121,6 +121,8 @@ export function StaticChatMessage({
 
   const content = usePostContent(post);
   const lastEditContent = usePostLastEditContent(post);
+  const canHandleA2UIAction =
+    !!draftInputContext && draftInputContext.canStartDraft !== false;
 
   const shouldRenderReplies =
     showReplies && post.replyCount && post.replyTime && post.replyContactIds;
@@ -194,6 +196,7 @@ export function StaticChatMessage({
             getImageViewerId={(src) => getPostImageViewerId(post.id, src)}
             onLongPress={handleLongPress}
             onA2UIAction={handleA2UIAction}
+            canHandleA2UIAction={canHandleA2UIAction}
             searchQuery={searchQuery}
           />
         )}
diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index 46cf595070..cb04867501 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -256,7 +256,10 @@ export function A2UIBlock({
             />
           );
         case 'Button': {
-          const disabled = component.disabled || !context.onA2UIAction;
+          const disabled =
+            component.disabled ||
+            !context.onA2UIAction ||
+            context.canHandleA2UIAction === false;
           const label = getComponentText(
             components.get(component.child),
             components
@@ -286,7 +289,12 @@ export function A2UIBlock({
         }
       }
     },
-    [components, context.onA2UIAction, handleButtonPress]
+    [
+      components,
+      context.canHandleA2UIAction,
+      context.onA2UIAction,
+      handleButtonPress,
+    ]
   );
 
   if (!root) {
diff --git a/packages/app/ui/components/PostContent/ContentRenderer.tsx b/packages/app/ui/components/PostContent/ContentRenderer.tsx
index d0eb28c4c0..bcbf2d4daa 100644
--- a/packages/app/ui/components/PostContent/ContentRenderer.tsx
+++ b/packages/app/ui/components/PostContent/ContentRenderer.tsx
@@ -57,6 +57,7 @@ function ContentRenderer({
   getImageViewerId,
   onLongPress,
   onA2UIAction,
+  canHandleA2UIAction,
   isNotice,
   searchQuery,
   ...rest
@@ -69,6 +70,7 @@ function ContentRenderer({
       getImageViewerId={getImageViewerId}
       onLongPress={onLongPress}
       onA2UIAction={onA2UIAction}
+      canHandleA2UIAction={canHandleA2UIAction}
       isNotice={isNotice}
       searchQuery={searchQuery}
     >
diff --git a/packages/app/ui/components/PostContent/contentUtils.tsx b/packages/app/ui/components/PostContent/contentUtils.tsx
index 5b6149e17e..dd0a842030 100644
--- a/packages/app/ui/components/PostContent/contentUtils.tsx
+++ b/packages/app/ui/components/PostContent/contentUtils.tsx
@@ -34,6 +34,7 @@ export interface ContentContextProps {
     action: A2UI.Button['action'],
     fallbackText: string
   ) => void | Promise<void>;
+  canHandleA2UIAction?: boolean;
   searchQuery?: string;
 }
 

From 0f902dfaa7f1fc99eafe9be9c06c62d9438ffb89 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Wed, 13 May 2026 19:33:16 -0400
Subject: [PATCH 18/25] revert a2ui action availability flag

---
 .../ui/components/ChatMessage/StaticChatMessage.tsx  |  3 ---
 packages/app/ui/components/PostContent/A2UIBlock.tsx | 12 ++----------
 .../ui/components/PostContent/ContentRenderer.tsx    |  2 --
 .../app/ui/components/PostContent/contentUtils.tsx   |  1 -
 4 files changed, 2 insertions(+), 16 deletions(-)

diff --git a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
index 46fdc5339e..490856fcf7 100644
--- a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
+++ b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
@@ -121,8 +121,6 @@ export function StaticChatMessage({
 
   const content = usePostContent(post);
   const lastEditContent = usePostLastEditContent(post);
-  const canHandleA2UIAction =
-    !!draftInputContext && draftInputContext.canStartDraft !== false;
 
   const shouldRenderReplies =
     showReplies && post.replyCount && post.replyTime && post.replyContactIds;
@@ -196,7 +194,6 @@ export function StaticChatMessage({
             getImageViewerId={(src) => getPostImageViewerId(post.id, src)}
             onLongPress={handleLongPress}
             onA2UIAction={handleA2UIAction}
-            canHandleA2UIAction={canHandleA2UIAction}
             searchQuery={searchQuery}
           />
         )}
diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index cb04867501..46cf595070 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -256,10 +256,7 @@ export function A2UIBlock({
             />
           );
         case 'Button': {
-          const disabled =
-            component.disabled ||
-            !context.onA2UIAction ||
-            context.canHandleA2UIAction === false;
+          const disabled = component.disabled || !context.onA2UIAction;
           const label = getComponentText(
             components.get(component.child),
             components
@@ -289,12 +286,7 @@ export function A2UIBlock({
         }
       }
     },
-    [
-      components,
-      context.canHandleA2UIAction,
-      context.onA2UIAction,
-      handleButtonPress,
-    ]
+    [components, context.onA2UIAction, handleButtonPress]
   );
 
   if (!root) {
diff --git a/packages/app/ui/components/PostContent/ContentRenderer.tsx b/packages/app/ui/components/PostContent/ContentRenderer.tsx
index bcbf2d4daa..d0eb28c4c0 100644
--- a/packages/app/ui/components/PostContent/ContentRenderer.tsx
+++ b/packages/app/ui/components/PostContent/ContentRenderer.tsx
@@ -57,7 +57,6 @@ function ContentRenderer({
   getImageViewerId,
   onLongPress,
   onA2UIAction,
-  canHandleA2UIAction,
   isNotice,
   searchQuery,
   ...rest
@@ -70,7 +69,6 @@ function ContentRenderer({
       getImageViewerId={getImageViewerId}
       onLongPress={onLongPress}
       onA2UIAction={onA2UIAction}
-      canHandleA2UIAction={canHandleA2UIAction}
       isNotice={isNotice}
       searchQuery={searchQuery}
     >
diff --git a/packages/app/ui/components/PostContent/contentUtils.tsx b/packages/app/ui/components/PostContent/contentUtils.tsx
index dd0a842030..5b6149e17e 100644
--- a/packages/app/ui/components/PostContent/contentUtils.tsx
+++ b/packages/app/ui/components/PostContent/contentUtils.tsx
@@ -34,7 +34,6 @@ export interface ContentContextProps {
     action: A2UI.Button['action'],
     fallbackText: string
   ) => void | Promise<void>;
-  canHandleA2UIAction?: boolean;
   searchQuery?: string;
 }
 

From 0d6a43928a239c5da67f5ef6a875039ba018283c Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Thu, 14 May 2026 12:36:16 -0400
Subject: [PATCH 19/25] fix nested a2ui card styling

---
 packages/app/ui/components/PostContent/A2UIBlock.tsx | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index 46cf595070..53c2295532 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -201,7 +201,10 @@ export function A2UIBlock({
               flex={getComponentFlex(component)}
             >
               {component.children.map((child) =>
-                renderComponent(child, { parentAlign: component.align })
+                renderComponent(child, {
+                  cardDepth: options.cardDepth,
+                  parentAlign: component.align,
+                })
               )}
             </XStack>
           );
@@ -215,7 +218,10 @@ export function A2UIBlock({
               flex={getComponentFlex(component)}
             >
               {component.children.map((child) =>
-                renderComponent(child, { parentAlign: component.align })
+                renderComponent(child, {
+                  cardDepth: options.cardDepth,
+                  parentAlign: component.align,
+                })
               )}
             </YStack>
           );

From e163a0754b4bdd96f7dd1f02ddb2c2049ff75a47 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Thu, 14 May 2026 12:56:23 -0400
Subject: [PATCH 20/25] tighten a2ui validation

---
 packages/api/src/__tests__/a2ui.test.ts | 52 +++++++++++++++++++++++++
 packages/api/src/client/a2ui.ts         | 21 +++++++++-
 2 files changed, 72 insertions(+), 1 deletion(-)

diff --git a/packages/api/src/__tests__/a2ui.test.ts b/packages/api/src/__tests__/a2ui.test.ts
index 6f3398d350..6004e44899 100644
--- a/packages/api/src/__tests__/a2ui.test.ts
+++ b/packages/api/src/__tests__/a2ui.test.ts
@@ -160,4 +160,56 @@ describe('a2ui blob entries', () => {
       })
     ).toBe(false);
   });
+
+  test('rejects malformed a2ui text optional fields', () => {
+    expect(
+      A2UI.validateBlobEntry({
+        ...a2uiBlobEntry,
+        messages: [
+          a2uiBlobEntry.messages[0],
+          {
+            version: 'v0.9',
+            updateComponents: {
+              surfaceId: 'weather-card',
+              root: 'root',
+              components: [
+                {
+                  id: 'root',
+                  component: 'Text',
+                  text: 'Weather',
+                  variant: 999,
+                },
+              ],
+            },
+          },
+        ],
+      })
+    ).toBe(false);
+  });
+
+  test('rejects duplicate child references in containers', () => {
+    expect(
+      A2UI.validateBlobEntry({
+        ...a2uiBlobEntry,
+        messages: [
+          a2uiBlobEntry.messages[0],
+          {
+            version: 'v0.9',
+            updateComponents: {
+              surfaceId: 'weather-card',
+              root: 'root',
+              components: [
+                {
+                  id: 'root',
+                  component: 'Column',
+                  children: ['summary', 'summary'],
+                },
+                { id: 'summary', component: 'Text', text: '72F and clear' },
+              ],
+            },
+          },
+        ],
+      })
+    ).toBe(false);
+  });
 });
diff --git a/packages/api/src/client/a2ui.ts b/packages/api/src/client/a2ui.ts
index 8fe1873c05..385dd60ac6 100644
--- a/packages/api/src/client/a2ui.ts
+++ b/packages/api/src/client/a2ui.ts
@@ -101,6 +101,16 @@ const CONTAINER_JUSTIFY_VALUES = [
 
 const CONTAINER_ALIGN_VALUES = ['start', 'center', 'end', 'stretch'] as const;
 
+const TEXT_VARIANT_VALUES = [
+  'body',
+  'caption',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+] as const;
+
 const BUTTON_VARIANT_VALUES = [
   'default',
   'primary',
@@ -144,6 +154,13 @@ function isValidContainerAlign(value: unknown): boolean {
   );
 }
 
+function isValidTextVariant(value: unknown): boolean {
+  return (
+    value === undefined ||
+    TEXT_VARIANT_VALUES.includes(value as (typeof TEXT_VARIANT_VALUES)[number])
+  );
+}
+
 function isValidButtonVariant(value: unknown): boolean {
   return (
     value === undefined ||
@@ -165,7 +182,8 @@ function validateComponent(component: unknown): component is A2UI.Component {
     case 'Text':
       return (
         typeof component.text === 'string' &&
-        component.text.length <= LIMITS.maxTextNodeLength
+        component.text.length <= LIMITS.maxTextNodeLength &&
+        isValidTextVariant(component.variant)
       );
     case 'Row':
     case 'Column':
@@ -173,6 +191,7 @@ function validateComponent(component: unknown): component is A2UI.Component {
         Array.isArray(component.children) &&
         component.children.length <= LIMITS.maxChildren &&
         component.children.every((child) => isNonEmptyString(child)) &&
+        new Set(component.children).size === component.children.length &&
         isValidContainerJustify(component.justify) &&
         isValidContainerAlign(component.align)
       );

From fb962b43608c10a93baa7206703737b8be251660 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Thu, 14 May 2026 13:30:04 -0400
Subject: [PATCH 21/25] fix a2ui review comments

---
 packages/api/src/__tests__/a2ui.test.ts       | 49 +++++++++++++++++++
 packages/api/src/client/a2ui.ts               | 11 +++--
 .../ui/components/PostContent/A2UIBlock.tsx   |  2 +
 3 files changed, 57 insertions(+), 5 deletions(-)

diff --git a/packages/api/src/__tests__/a2ui.test.ts b/packages/api/src/__tests__/a2ui.test.ts
index 6004e44899..45eb323653 100644
--- a/packages/api/src/__tests__/a2ui.test.ts
+++ b/packages/api/src/__tests__/a2ui.test.ts
@@ -212,4 +212,53 @@ describe('a2ui blob entries', () => {
       })
     ).toBe(false);
   });
+
+  test('rejects shared child references that expand beyond render limits', () => {
+    const layerIds = ['a', 'b', 'c', 'd', 'e', 'f', 'g'].map((prefix) =>
+      Array.from({ length: 7 }, (_, index) => `${prefix}${index}`)
+    );
+    const components: A2UI.Component[] = [
+      { id: 'root', component: 'Column', children: layerIds[0] },
+      ...layerIds.flatMap((ids, layerIndex) =>
+        ids.map((id) =>
+          layerIndex === layerIds.length - 1
+            ? ({ id, component: 'Text', text: 'x' } as const)
+            : ({
+                id,
+                component: 'Column',
+                children: layerIds[layerIndex + 1],
+              } as const)
+        )
+      ),
+    ];
+
+    expect(components).toHaveLength(50);
+    expect(
+      A2UI.validateBlobEntry({
+        ...a2uiBlobEntry,
+        messages: [
+          a2uiBlobEntry.messages[0],
+          {
+            version: 'v0.9',
+            updateComponents: {
+              surfaceId: 'weather-card',
+              root: 'root',
+              components,
+            },
+          },
+        ],
+      })
+    ).toBe(false);
+  });
+
+  test('ignores non-object messages when finding update message', () => {
+    const entry = {
+      ...a2uiBlobEntry,
+      messages: [42, ...a2uiBlobEntry.messages],
+    } as unknown as A2UI.BlobEntry;
+
+    expect(A2UI.validateBlobEntry(entry)).toBe(true);
+    expect(A2UI.getUpdateMessage(entry)).toEqual(a2uiBlobEntry.messages[1]);
+    expect(A2UI.getRootComponentId(entry)).toBe('root');
+  });
 });
diff --git a/packages/api/src/client/a2ui.ts b/packages/api/src/client/a2ui.ts
index 385dd60ac6..43bbf6702d 100644
--- a/packages/api/src/client/a2ui.ts
+++ b/packages/api/src/client/a2ui.ts
@@ -324,14 +324,16 @@ function validateReachableTree(
   }
 
   const visiting = new Set<string>();
-  const visited = new Set<string>();
+  let expandedComponentCount = 0;
+  const maxExpandedComponents = LIMITS.maxComponents * LIMITS.maxChildren;
 
   function visit(id: string, depth: number): boolean {
     if (depth > LIMITS.maxDepth || visiting.has(id)) {
       return false;
     }
-    if (visited.has(id)) {
-      return true;
+    expandedComponentCount += 1;
+    if (expandedComponentCount > maxExpandedComponents) {
+      return false;
     }
     const component = components.get(id);
     if (!component) {
@@ -353,7 +355,6 @@ function validateReachableTree(
       }
     }
     visiting.delete(id);
-    visited.add(id);
     return true;
   }
 
@@ -366,7 +367,7 @@ export function getUpdateMessage(
   return (
     entry.messages.find(
       (message): message is A2UI.UpdateComponentsMessage =>
-        'updateComponents' in message
+        isPlainObject(message) && 'updateComponents' in message
     ) ?? null
   );
 }
diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index 53c2295532..7d205818a4 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -93,6 +93,8 @@ function getAlignItems(
   switch (align) {
     case 'start':
       return 'flex-start';
+    case 'center':
+      return 'center';
     case 'end':
       return 'flex-end';
     case 'stretch':

From 5f0aac45d24eae61477165abbd640950f30e31a1 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Mon, 18 May 2026 14:05:57 -0400
Subject: [PATCH 22/25] disable a2ui actions without draft access

---
 packages/app/ui/components/ChatMessage/StaticChatMessage.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
index 490856fcf7..fada709f0c 100644
--- a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
+++ b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
@@ -118,6 +118,8 @@ export function StaticChatMessage({
     },
     [draftInputContext]
   );
+  const canHandleA2UIAction =
+    !!draftInputContext && draftInputContext.canStartDraft !== false;
 
   const content = usePostContent(post);
   const lastEditContent = usePostLastEditContent(post);
@@ -193,7 +195,7 @@ export function StaticChatMessage({
             onPressImage={handleImagePressed}
             getImageViewerId={(src) => getPostImageViewerId(post.id, src)}
             onLongPress={handleLongPress}
-            onA2UIAction={handleA2UIAction}
+            onA2UIAction={canHandleA2UIAction ? handleA2UIAction : undefined}
             searchQuery={searchQuery}
           />
         )}

From 9e7cbce7f3fb006a95c5aa247039fc97d9f72043 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Mon, 18 May 2026 14:13:02 -0400
Subject: [PATCH 23/25] render a2ui only in dms

---
 .../ChatMessage/StaticChatMessage.tsx         | 26 ++++++++++++++++---
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
index fada709f0c..386cc05441 100644
--- a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
+++ b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
@@ -1,7 +1,8 @@
+import { isDmChannelId } from '@tloncorp/api/client';
 import * as db from '@tloncorp/shared/db';
 import { A2UI } from '@tloncorp/shared/logic';
 import { Text } from '@tloncorp/ui';
-import { ComponentProps, useCallback } from 'react';
+import { ComponentProps, useCallback, useMemo } from 'react';
 import { View, XStack, YStack, isWeb } from 'tamagui';
 
 import { CHAT_REF_LIKE_MAX_WIDTH } from '../../../constants';
@@ -118,11 +119,28 @@ export function StaticChatMessage({
     },
     [draftInputContext]
   );
+  const canRenderA2UI = isDmChannelId(post.channelId);
   const canHandleA2UIAction =
-    !!draftInputContext && draftInputContext.canStartDraft !== false;
+    canRenderA2UI &&
+    !!draftInputContext &&
+    draftInputContext.canStartDraft !== false;
 
-  const content = usePostContent(post);
-  const lastEditContent = usePostLastEditContent(post);
+  const postContent = usePostContent(post);
+  const lastEditPostContent = usePostLastEditContent(post);
+  const content = useMemo(
+    () =>
+      canRenderA2UI
+        ? postContent
+        : postContent.filter((block) => block.type !== 'a2ui'),
+    [canRenderA2UI, postContent]
+  );
+  const lastEditContent = useMemo(
+    () =>
+      canRenderA2UI
+        ? lastEditPostContent
+        : lastEditPostContent.filter((block) => block.type !== 'a2ui'),
+    [canRenderA2UI, lastEditPostContent]
+  );
 
   const shouldRenderReplies =
     showReplies && post.replyCount && post.replyTime && post.replyContactIds;

From f0309c2914bd90c0b7babb957714c1e9b4af56ea Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Mon, 18 May 2026 17:43:19 -0400
Subject: [PATCH 24/25] document a2ui post blobs

---
 docs/post-blobs.md                            | 28 +++++++++++++++++--
 .../ui/components/PostContent/A2UIBlock.tsx   |  7 -----
 2 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/docs/post-blobs.md b/docs/post-blobs.md
index 9e82b01ca7..b55e25fe48 100644
--- a/docs/post-blobs.md
+++ b/docs/post-blobs.md
@@ -14,7 +14,7 @@ When no extra data is needed, the field is `null` (`blob=~` in Hoon).
 
 ## Entry schema
 
-Blob entries are a discriminated union keyed on `type` and `version`. Definitions live in `packages/api/src/lib/content-helpers.ts` and are registered in `postBlobDataEntryDefinitions`, which drives both write-time validation and read-time parsing.
+Blob entries are a discriminated union keyed on `type` and `version`. Definitions live in `packages/api/src/client/content-helpers.ts` and are registered in `postBlobDataEntryDefinitions`, which drives both write-time validation and read-time parsing.
 
 Each concrete entry type should have:
 
@@ -68,9 +68,31 @@ Video upload metadata.
 | `duration`  | `number` (optional) |
 | `posterUri` | `string` (optional) |
 
+### `a2ui` v1
+
+A2UI presentation metadata. This lets a post carry a small validated A2UI v0.9 component tree alongside normal text content.
+
+Definitions and validation helpers live in `packages/api/src/client/a2ui.ts`; the entry is registered with the shared blob union through `A2UI.blobEntrySchema`.
+
+| field      | type               |
+| ---------- | ------------------ |
+| `type`     | `'a2ui'`           |
+| `version`  | `1`                |
+| `messages` | `A2UI.Message[]`   |
+| `recipe`   | `unknown` optional |
+
+The current renderer expects one `createSurface` message and one `updateComponents` message in the entry. The `updateComponents` message describes the component tree rendered for that post. It does not update surfaces in previous messages or elsewhere in message history.
+
+The supported v1 client subset is intentionally small:
+
+- components: `Card`, `Column`, `Row`, `Text`, `Divider`, and `Button`
+- button actions: `tlon.sendMessage`, which sends visible text in the current DM
+- rendering policy: A2UI blocks render only in direct messages for now
+- validation limits: component count, tree depth, text length, button count, and expanded render size
+
 ## Read/write behavior
 
-- Writes happen through helpers in `packages/api/src/lib/content-helpers.ts`. `appendToPostBlob` is the base helper; `appendFileUploadToPostBlob` and `appendVideoToPostBlob` are convenience wrappers.
+- Writes happen through helpers in `packages/api/src/client/content-helpers.ts`. `appendToPostBlob` is the base helper; `appendFileUploadToPostBlob` and `appendVideoToPostBlob` are convenience wrappers.
 - `toPostData` builds blobs from finalized attachments.
 - `PostDataDraft` does not store `blob`; blob is computed during finalization from attachments.
 - The edit transport can carry a blob, but current frontend edit flows do not implement blob editing. Network edits preserve the original blob.
@@ -89,7 +111,7 @@ Video upload metadata.
 
 ## Adding a new entry type
 
-1. Add a named schema and inferred type in `packages/api/src/lib/content-helpers.ts`.
+1. Add a named schema and inferred type in `packages/api/src/client/content-helpers.ts`.
 2. Add that schema to `postBlobDataEntryDefinitions`.
 3. Add an `appendXToPostBlob` helper if the new entry will be written from more than one place.
 4. Update the relevant attachment unions in `packages/api/src/types/attachment.ts` so the new entry can be finalized and passed into `toPostData`.
diff --git a/packages/app/ui/components/PostContent/A2UIBlock.tsx b/packages/app/ui/components/PostContent/A2UIBlock.tsx
index 7d205818a4..11492dacf4 100644
--- a/packages/app/ui/components/PostContent/A2UIBlock.tsx
+++ b/packages/app/ui/components/PostContent/A2UIBlock.tsx
@@ -33,17 +33,10 @@ function getComponentGap(
   component: A2UI.Container,
   components: Map<string, A2UI.Component>
 ) {
-  const hasButton = component.children.some(
-    (child) => components.get(child)?.component === 'Button'
-  );
   const isTextOnly = component.children.every(
     (child) => components.get(child)?.component === 'Text'
   );
 
-  if (hasButton) {
-    return '$m';
-  }
-
   if (isTextOnly) {
     return component.component === 'Row' ? '$s' : '$xs';
   }

From acad299c7e9fc1cf53d7e8e10d79545153c71068 Mon Sep 17 00:00:00 2001
From: Dan Brewster <dnbrwstr@gmail.com>
Date: Mon, 18 May 2026 19:32:29 -0400
Subject: [PATCH 25/25] restrict a2ui rendering paths

---
 packages/app/fixtures/A2UI.fixture.tsx        | 32 ++++++++++++++++---
 .../ChatMessage/StaticChatMessage.tsx         |  4 +++
 .../components/PostContent/BlockRenderer.tsx  |  2 +-
 3 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/packages/app/fixtures/A2UI.fixture.tsx b/packages/app/fixtures/A2UI.fixture.tsx
index f1069de711..8fe0fe6513 100644
--- a/packages/app/fixtures/A2UI.fixture.tsx
+++ b/packages/app/fixtures/A2UI.fixture.tsx
@@ -15,6 +15,8 @@ import { FixtureWrapper } from './FixtureWrapper';
 import { exampleContacts, makePost, verse } from './contentHelpers';
 import { group, tlonLocalIntros } from './fakeData';
 
+const dmChannelId = '~sampel-palnet';
+
 const weatherA2UI: A2UI.BlobEntry = {
   type: 'a2ui',
   version: 1,
@@ -580,31 +582,51 @@ const basicComponentsA2UI: A2UI.BlobEntry = {
 const weatherPost = makePost(
   exampleContacts.mark,
   [verse.inline('Weather: 22903 is 57F and partly cloudy.')],
-  { blob: appendToPostBlob(undefined, weatherA2UI), replyCount: 0 }
+  {
+    blob: appendToPostBlob(undefined, weatherA2UI),
+    channelId: dmChannelId,
+    replyCount: 0,
+  }
 );
 
 const confirmationPost = makePost(
   exampleContacts.groupAdmin,
   [verse.inline('DM request from Sam Palnet (~sampel-palnet)')],
-  { blob: appendToPostBlob(undefined, confirmationA2UI), replyCount: 0 }
+  {
+    blob: appendToPostBlob(undefined, confirmationA2UI),
+    channelId: dmChannelId,
+    replyCount: 0,
+  }
 );
 
 const channelApprovalPost = makePost(
   exampleContacts.mark,
   [verse.inline('Channel mention request from Littel Wolfur (~littel-wolfur)')],
-  { blob: appendToPostBlob(undefined, channelApprovalA2UI), replyCount: 0 }
+  {
+    blob: appendToPostBlob(undefined, channelApprovalA2UI),
+    channelId: dmChannelId,
+    replyCount: 0,
+  }
 );
 
 const groupApprovalPost = makePost(
   exampleContacts.groupAdmin,
   [verse.inline('Group invite request from Robin Dasler (~robin-dasler)')],
-  { blob: appendToPostBlob(undefined, groupApprovalA2UI), replyCount: 0 }
+  {
+    blob: appendToPostBlob(undefined, groupApprovalA2UI),
+    channelId: dmChannelId,
+    replyCount: 0,
+  }
 );
 
 const basicComponentsPost = makePost(
   exampleContacts.mark,
   [verse.inline('Basic A2UI component catalog.')],
-  { blob: appendToPostBlob(undefined, basicComponentsA2UI), replyCount: 0 }
+  {
+    blob: appendToPostBlob(undefined, basicComponentsA2UI),
+    channelId: dmChannelId,
+    replyCount: 0,
+  }
 );
 
 const examplePosts = [
diff --git a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
index 386cc05441..a0cd1482aa 100644
--- a/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
+++ b/packages/app/ui/components/ChatMessage/StaticChatMessage.tsx
@@ -8,6 +8,7 @@ import { View, XStack, YStack, isWeb } from 'tamagui';
 import { CHAT_REF_LIKE_MAX_WIDTH } from '../../../constants';
 import { getPostImageViewerId } from '../../../utils/mediaViewer';
 import AuthorRow from '../AuthorRow';
+import { A2UIBlock } from '../PostContent/A2UIBlock';
 import { DefaultRendererProps } from '../PostContent/BlockRenderer';
 import { createContentRenderer } from '../PostContent/ContentRenderer';
 import {
@@ -258,6 +259,9 @@ const WebChatVideoRenderer: DefaultRendererProps['video'] = {
 };
 
 const ChatContentRenderer = createContentRenderer({
+  blockRenderers: {
+    a2ui: A2UIBlock,
+  },
   blockSettings: {
     blockWrapper: {
       paddingLeft: 0,
diff --git a/packages/app/ui/components/PostContent/BlockRenderer.tsx b/packages/app/ui/components/PostContent/BlockRenderer.tsx
index 353c509660..819595895e 100644
--- a/packages/app/ui/components/PostContent/BlockRenderer.tsx
+++ b/packages/app/ui/components/PostContent/BlockRenderer.tsx
@@ -699,7 +699,7 @@ export const defaultBlockRenderers: BlockRendererConfig = {
   lineText: LineText,
   blockquote: BlockquoteBlock,
   paragraph: ParagraphBlock,
-  a2ui: A2UIBlock,
+  a2ui: () => null,
   link: LinkBlock,
   image: ImageBlock,
   video: VideoBlock,