From 311619adb01f0a5b2420f953c278bb4448bd5fea Mon Sep 17 00:00:00 2001 From: Brian Love Date: Tue, 17 Nov 2026 15:50:33 -0800 Subject: [PATCH 1/3] feat(react): show A2UI actions by their label in the transcript A2UI action sent as the next user turn rendered as its serialized JSON in React. Chat and MessageList take an opt-in a2uiActionLabels switch that shows the pressed control's label instead, or the action name in plain words when the message carries none. Other messages and custom renderMessage rows are unchanged. --- .../react/chat/a2ui/surface-component.mdx | 2 + libs/react/README.md | 11 ++ libs/react/src/chat/chat.tsx | 4 + libs/react/src/chat/chat.type-test.tsx | 3 + .../src/chat/internal/a2ui-action-label.ts | 30 ++++ .../message-list-a2ui-action-label.spec.tsx | 151 ++++++++++++++++++ libs/react/src/chat/message-list.tsx | 37 ++++- 7 files changed, 230 insertions(+), 8 deletions(-) create mode 100644 libs/react/src/chat/internal/a2ui-action-label.ts create mode 100644 libs/react/src/chat/message-list-a2ui-action-label.spec.tsx diff --git a/apps/website/content/docs/react/chat/a2ui/surface-component.mdx b/apps/website/content/docs/react/chat/a2ui/surface-component.mdx index 7af284cee..4d830b998 100644 --- a/apps/website/content/docs/react/chat/a2ui/surface-component.mdx +++ b/apps/website/content/docs/react/chat/a2ui/surface-component.mdx @@ -117,6 +117,8 @@ The `context` is read from the data model at the moment of the press, so it carr When the agent created the surface with `sendDataModel: true`, the whole data model rides along as `metadata.a2uiClientDataModel`. How the message reaches the agent is your decision (most applications send it as the next turn of the conversation). +When you send it as a user message, pass `a2uiActionLabels` to `Chat` or `MessageList` so the transcript shows the button's label, such as "Search flights", in place of the serialized message. +An action from a control without literal text shows its name in plain words, so `bookingSubmit` reads "Booking submit". Without `onAction`, buttons that would send an action are disabled, so a read-only surface cannot look pressable. ## What happens when a check fails? diff --git a/libs/react/README.md b/libs/react/README.md index b12ea107b..a58b0797b 100644 --- a/libs/react/README.md +++ b/libs/react/README.md @@ -2151,6 +2151,17 @@ retries and what the conversation shows are your application's decisions. `createA2uiActionMessage(surface, componentId)` from `@threadplane/content/a2ui` builds the same message outside React. +An application that sends the message as the next user turn would see its JSON +in the transcript. Pass `a2uiActionLabels` to `Chat` or `MessageList` and a +user message that is a serialized action shows the `label` instead ("Search +flights"), or the action name in plain words when there is none +(`bookingSubmit` reads "Booking submit"). The stored message is unchanged, and +every other message renders as before. It is off unless set. + +```tsx + +``` + A Button with an event action is disabled when there is no `onAction`. A Button with no action, or whose `disabled` prop is true, is disabled too. A Button used as a `Modal` trigger opens the modal and needs no action. diff --git a/libs/react/src/chat/chat.tsx b/libs/react/src/chat/chat.tsx index 46a9fe400..2475ce272 100644 --- a/libs/react/src/chat/chat.tsx +++ b/libs/react/src/chat/chat.tsx @@ -111,6 +111,8 @@ export interface ChatProps readonly renderMessageActivity?: MessageListProps['renderMessageActivity']; /** One reasoning disclosure per multi-step turn; see `MessageListProps.mergeReasoning`. Defaults to true. */ readonly mergeReasoning?: MessageListProps['mergeReasoning']; + /** Shows an A2UI action sent as a user message by its label; see `MessageListProps.a2uiActionLabels`. Off unless set. */ + readonly a2uiActionLabels?: MessageListProps['a2uiActionLabels']; /** * The waiting indicator in the transcript; see `MessageListProps.typingIndicator`. Pass * `{ announce: false }` when the app already announces progress, such as a status in @@ -223,6 +225,7 @@ export function Chat({ generativeUi, markdownComponents, mergeReasoning, + a2uiActionLabels, renderMessageActivity, typingIndicator, welcome, @@ -404,6 +407,7 @@ export function Chat({ generativeUi={generativeUi} markdownComponents={markdownComponents} mergeReasoning={mergeReasoning} + a2uiActionLabels={a2uiActionLabels} renderMessageActivity={renderMessageActivity} typingIndicator={typingIndicator} renderScrollControl={(controls) => diff --git a/libs/react/src/chat/chat.type-test.tsx b/libs/react/src/chat/chat.type-test.tsx index d9ee94be4..e411e32be 100644 --- a/libs/react/src/chat/chat.type-test.tsx +++ b/libs/react/src/chat/chat.type-test.tsx @@ -71,6 +71,9 @@ ok.className = 'x'; ; // @ts-expect-error Options are value and label records, not strings. undefined }} />; +; +// @ts-expect-error Action labels are a switch, not a renderer. + 'Go'} />; void missing; import type { ReactNode } from 'react'; diff --git a/libs/react/src/chat/internal/a2ui-action-label.ts b/libs/react/src/chat/internal/a2ui-action-label.ts new file mode 100644 index 000000000..c825c485b --- /dev/null +++ b/libs/react/src/chat/internal/a2ui-action-label.ts @@ -0,0 +1,30 @@ +const record = (value: unknown): value is Record => + value != null && typeof value === 'object' && !Array.isArray(value); + +/** + * The words to show for a message whose content is a serialized A2UI action + * (`{"version":"v0.9","action":{…}}`): the pressed control's own label, or the + * action name in plain words ("bookingSubmit" reads "Booking submit"). Null + * for any other content. + */ +export function a2uiActionLabel(content: string): string | null { + const trimmed = content.trimStart(); + if (!trimmed.startsWith('{')) return null; + let parsed: unknown; + try { + parsed = JSON.parse(trimmed); + } catch { + return null; + } + if (!record(parsed)) return null; + const version = parsed['version']; + if (typeof version !== 'string' || !version.startsWith('v')) return null; + const action = parsed['action']; + if (!record(action)) return null; + const name = action['name']; + if (typeof name !== 'string' || name === '') return null; + const label = action['label']; + if (typeof label === 'string' && label !== '') return label; + const words = name.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase(); + return words.charAt(0).toUpperCase() + words.slice(1); +} diff --git a/libs/react/src/chat/message-list-a2ui-action-label.spec.tsx b/libs/react/src/chat/message-list-a2ui-action-label.spec.tsx new file mode 100644 index 000000000..7465a8bc9 --- /dev/null +++ b/libs/react/src/chat/message-list-a2ui-action-label.spec.tsx @@ -0,0 +1,151 @@ +import { cleanup, render } from '@testing-library/react'; +import { afterEach, describe, expect, it } from 'vitest'; +import { + completeDelivery, + type AgentSession, + type AgentSnapshot, + type Message, +} from '@threadplane/core'; +import { createA2uiActionMessage } from '@threadplane/content/a2ui'; +import { createMessageContent } from '@threadplane/content/messages'; +import { Chat, MessageList } from './index'; + +afterEach(cleanup); + +const msg = (id: string, role: Message['role'], content: string): Message => + Object.freeze({ id, role, content, delivery: completeDelivery(id, 'success') }) as Message; +const snapshot = (messages: Message[]) => + Object.freeze({ status: 'idle', messages, toolCalls: [] }) as AgentSnapshot; +const project = (messages: Message[]) => createMessageContent().project(snapshot(messages)); +const action = (fields: Record) => + JSON.stringify({ version: 'v0.9', action: { surfaceId: 's', sourceComponentId: 'b', context: {}, ...fields } }); +const bubble = (view: ReturnType) => + view.container.querySelector('.tp-chat-message--user'); +// The message text alone, without the row's screen-reader role prefix. +const text = (view: ReturnType) => + view.container.querySelector('.tp-chat-message--user .tp-markdown')?.textContent; + +describe('MessageList A2UI action labels', () => { + it('leaves the serialized action in place unless asked', () => { + const view = render( + + ); + expect(bubble(view)?.textContent).toContain('"bookingSubmit"'); + expect(view.container.querySelector('[data-a2ui-action]')).toBeNull(); + }); + + it('shows the pressed control label in place of the JSON', () => { + const view = render( + + ); + expect(text(view)).toBe('Search flights'); + expect(bubble(view)?.querySelector('.tp-markdown[data-a2ui-action] > p')).not.toBeNull(); + }); + + it('labels the message the shared builder produces for a Button', () => { + const message = createA2uiActionMessage( + { + surfaceId: 's', + components: [ + { id: 'go', component: 'Button', child: 'go-text', action: { event: { name: 'bookingSubmit' } } }, + { id: 'go-text', component: 'Text', text: 'Search flights' }, + ], + dataModel: {}, + } as never, + 'go', + '2026-11-17T00:00:00.000Z' + ); + const view = render( + + ); + expect(text(view)).toBe('Search flights'); + }); + + it('puts the action name in plain words when no label was sent', () => { + for (const [name, words] of [ + ['bookingSubmit', 'Booking submit'], + ['addToCart', 'Add to cart'], + ['refresh', 'Refresh'], + ]) { + const view = render( + + ); + expect(text(view)).toBe(words); + cleanup(); + } + }); + + it('leaves every other user message as written', () => { + for (const content of [ + 'Find me a flight', + '{"city":"Paris"}', + '{not json', + '{"version":"v0.9"}', + '{"version":"v0.9","action":{"label":"No name"}}', + '{"version":1,"action":{"name":"go"}}', + '[{"version":"v0.9","action":{"name":"go"}}]', + ]) { + const plain = render(); + const expected = bubble(plain)?.innerHTML; + cleanup(); + const view = render(); + expect(bubble(view)?.innerHTML).toBe(expected); + cleanup(); + } + }); + + it('never relabels an assistant message that quotes an action', () => { + const content = action({ name: 'bookingSubmit', label: 'Search flights' }); + const view = render(); + const row = view.container.querySelector('.tp-chat-message--assistant'); + expect(row?.textContent).toContain('"bookingSubmit"'); + expect(row?.querySelector('[data-a2ui-action]')).toBeNull(); + }); + + it('renders the label as text, not markup', () => { + const view = render( + ' }))])} + /> + ); + expect(text(view)).toBe('**Bold** '); + expect(bubble(view)?.querySelector('img, strong')).toBeNull(); + }); + + it('leaves a custom renderMessage in charge of the row', () => { + const view = render( + {row.message.content.length}} + rows={project([msg('u', 'user', action({ name: 'go', label: 'Go' }))])} + /> + ); + expect(view.container.querySelector('[data-custom]')).not.toBeNull(); + expect(view.container.querySelector('[data-a2ui-action]')).toBeNull(); + }); +}); + +describe('Chat A2UI action labels', () => { + const session = (messages: Message[]): AgentSession => { + const value = snapshot(messages); + return { + getSnapshot: () => value, + subscribe: () => () => undefined, + submit: async () => undefined, + stop: async () => undefined, + } as unknown as AgentSession; + }; + const messages = [msg('u', 'user', action({ name: 'bookingSubmit', label: 'Search flights' }))]; + + it('passes the choice through to its transcript', () => { + const off = render(); + expect(bubble(off)?.textContent).toContain('"bookingSubmit"'); + cleanup(); + const on = render(); + expect(text(on)).toBe('Search flights'); + }); +}); diff --git a/libs/react/src/chat/message-list.tsx b/libs/react/src/chat/message-list.tsx index 2b3091ed0..917ddc663 100644 --- a/libs/react/src/chat/message-list.tsx +++ b/libs/react/src/chat/message-list.tsx @@ -26,6 +26,7 @@ import { withoutStaleRetry, } from './tool-outcome.js'; import { Reasoning } from './reasoning.js'; +import { a2uiActionLabel } from './internal/a2ui-action-label.js'; import { isTyping, TypingIndicator } from './typing-indicator.js'; import { BuiltInActions, @@ -190,6 +191,13 @@ export interface MessageListProps { * reasoning on its own message. Custom renderMessage retains full row ownership. */ readonly mergeReasoning?: boolean; + /** + * Shows a user message that is a serialized A2UI action as the pressed + * control's label ("Search flights") in place of its JSON. Without a label + * the action name is put in plain words. Off unless set; other messages are + * unchanged, and custom renderMessage retains full row ownership. + */ + readonly a2uiActionLabels?: boolean; /** Typesets math in message text; see `MarkdownProps.math`. Keep stable; custom renderMessage retains full ownership. */ readonly math?: MarkdownProps['math']; /** @@ -393,8 +401,10 @@ function RowView({ generativeUi, markdownComponents, mergeReasoning, + a2uiActionLabels, renderMessageActivity, }: { + readonly a2uiActionLabels?: boolean; readonly renderMessageActivity?: ( context: MessageActivityContext ) => ReactNode; @@ -525,14 +535,23 @@ function RowView({ }); // The plan and Stop belong to the row's last built-in group, the one the turn is still running. const planGroup = [...runs].reverse().find((run) => 'activities' in run); - const text = ( - - ); + const actionLabel = + a2uiActionLabels === true && row.role === 'user' + ? a2uiActionLabel(row.message.content) + : null; + const text = + actionLabel !== null ? ( +
+

{actionLabel}

+
+ ) : ( + + ); return ( ({ generativeUi, markdownComponents, mergeReasoning, + a2uiActionLabels, renderMessageActivity, children, renderScrollControl, @@ -851,6 +871,7 @@ export function MessageList({ generativeUi={generativeUi} markdownComponents={markdownComponents} mergeReasoning={mergeReasoning !== false} + a2uiActionLabels={a2uiActionLabels} renderMessageActivity={renderMessageActivity} /> {renderApprovalRecords(recordsAfter, row.id)} From 7e86117014df52534fb2f1b359b99e04659a0bb4 Mon Sep 17 00:00:00 2001 From: Brian Love Date: Tue, 17 Nov 2026 15:53:32 -0800 Subject: [PATCH 2/3] feat(react): show A2UI action labels by default --- .../react/chat/a2ui/surface-component.mdx | 3 ++- libs/react/README.md | 14 +++++----- libs/react/src/chat/chat.tsx | 2 +- libs/react/src/chat/chat.type-test.tsx | 2 +- .../message-list-a2ui-action-label.spec.tsx | 26 +++++++++---------- libs/react/src/chat/message-list.tsx | 7 ++--- 6 files changed, 28 insertions(+), 26 deletions(-) diff --git a/apps/website/content/docs/react/chat/a2ui/surface-component.mdx b/apps/website/content/docs/react/chat/a2ui/surface-component.mdx index 4d830b998..e3c37b0e6 100644 --- a/apps/website/content/docs/react/chat/a2ui/surface-component.mdx +++ b/apps/website/content/docs/react/chat/a2ui/surface-component.mdx @@ -117,8 +117,9 @@ The `context` is read from the data model at the moment of the press, so it carr When the agent created the surface with `sendDataModel: true`, the whole data model rides along as `metadata.a2uiClientDataModel`. How the message reaches the agent is your decision (most applications send it as the next turn of the conversation). -When you send it as a user message, pass `a2uiActionLabels` to `Chat` or `MessageList` so the transcript shows the button's label, such as "Search flights", in place of the serialized message. +When you send it as a user message, `Chat` and `MessageList` show the button's label, such as "Search flights", in place of the serialized message. An action from a control without literal text shows its name in plain words, so `bookingSubmit` reads "Booking submit". +Pass `a2uiActionLabels={false}` to show the message as it was sent. Without `onAction`, buttons that would send an action are disabled, so a read-only surface cannot look pressable. ## What happens when a check fails? diff --git a/libs/react/README.md b/libs/react/README.md index a58b0797b..55af958b7 100644 --- a/libs/react/README.md +++ b/libs/react/README.md @@ -2151,15 +2151,15 @@ retries and what the conversation shows are your application's decisions. `createA2uiActionMessage(surface, componentId)` from `@threadplane/content/a2ui` builds the same message outside React. -An application that sends the message as the next user turn would see its JSON -in the transcript. Pass `a2uiActionLabels` to `Chat` or `MessageList` and a -user message that is a serialized action shows the `label` instead ("Search -flights"), or the action name in plain words when there is none -(`bookingSubmit` reads "Booking submit"). The stored message is unchanged, and -every other message renders as before. It is off unless set. +When an application sends the message as the next user turn, `Chat` and +`MessageList` do not show its JSON. A user message that is a serialized action +shows the `label` instead ("Search flights"), or the action name in plain +words when there is none (`bookingSubmit` reads "Booking submit"). The stored +message is unchanged, and every other message renders as before. Pass +`a2uiActionLabels={false}` to show the message as sent. ```tsx - + ``` A Button with an event action is disabled when there is no `onAction`. A diff --git a/libs/react/src/chat/chat.tsx b/libs/react/src/chat/chat.tsx index 2475ce272..d003b6927 100644 --- a/libs/react/src/chat/chat.tsx +++ b/libs/react/src/chat/chat.tsx @@ -111,7 +111,7 @@ export interface ChatProps readonly renderMessageActivity?: MessageListProps['renderMessageActivity']; /** One reasoning disclosure per multi-step turn; see `MessageListProps.mergeReasoning`. Defaults to true. */ readonly mergeReasoning?: MessageListProps['mergeReasoning']; - /** Shows an A2UI action sent as a user message by its label; see `MessageListProps.a2uiActionLabels`. Off unless set. */ + /** Shows an A2UI action sent as a user message by its label; see `MessageListProps.a2uiActionLabels`. Defaults to true. */ readonly a2uiActionLabels?: MessageListProps['a2uiActionLabels']; /** * The waiting indicator in the transcript; see `MessageListProps.typingIndicator`. Pass diff --git a/libs/react/src/chat/chat.type-test.tsx b/libs/react/src/chat/chat.type-test.tsx index e411e32be..105033e2c 100644 --- a/libs/react/src/chat/chat.type-test.tsx +++ b/libs/react/src/chat/chat.type-test.tsx @@ -71,7 +71,7 @@ ok.className = 'x'; ; // @ts-expect-error Options are value and label records, not strings. undefined }} />; -; +; // @ts-expect-error Action labels are a switch, not a renderer. 'Go'} />; void missing; diff --git a/libs/react/src/chat/message-list-a2ui-action-label.spec.tsx b/libs/react/src/chat/message-list-a2ui-action-label.spec.tsx index 7465a8bc9..fbd7a9f10 100644 --- a/libs/react/src/chat/message-list-a2ui-action-label.spec.tsx +++ b/libs/react/src/chat/message-list-a2ui-action-label.spec.tsx @@ -26,18 +26,20 @@ const text = (view: ReturnType) => view.container.querySelector('.tp-chat-message--user .tp-markdown')?.textContent; describe('MessageList A2UI action labels', () => { - it('leaves the serialized action in place unless asked', () => { + it('leaves the serialized action in place when turned off', () => { const view = render( - + ); expect(bubble(view)?.textContent).toContain('"bookingSubmit"'); expect(view.container.querySelector('[data-a2ui-action]')).toBeNull(); }); - it('shows the pressed control label in place of the JSON', () => { + it('shows the pressed control label in place of the JSON by default', () => { const view = render( ); @@ -59,7 +61,7 @@ describe('MessageList A2UI action labels', () => { '2026-11-17T00:00:00.000Z' ); const view = render( - + ); expect(text(view)).toBe('Search flights'); }); @@ -71,7 +73,7 @@ describe('MessageList A2UI action labels', () => { ['refresh', 'Refresh'], ]) { const view = render( - + ); expect(text(view)).toBe(words); cleanup(); @@ -88,10 +90,10 @@ describe('MessageList A2UI action labels', () => { '{"version":1,"action":{"name":"go"}}', '[{"version":"v0.9","action":{"name":"go"}}]', ]) { - const plain = render(); + const plain = render(); const expected = bubble(plain)?.innerHTML; cleanup(); - const view = render(); + const view = render(); expect(bubble(view)?.innerHTML).toBe(expected); cleanup(); } @@ -99,7 +101,7 @@ describe('MessageList A2UI action labels', () => { it('never relabels an assistant message that quotes an action', () => { const content = action({ name: 'bookingSubmit', label: 'Search flights' }); - const view = render(); + const view = render(); const row = view.container.querySelector('.tp-chat-message--assistant'); expect(row?.textContent).toContain('"bookingSubmit"'); expect(row?.querySelector('[data-a2ui-action]')).toBeNull(); @@ -108,7 +110,6 @@ describe('MessageList A2UI action labels', () => { it('renders the label as text, not markup', () => { const view = render( ' }))])} /> ); @@ -119,7 +120,6 @@ describe('MessageList A2UI action labels', () => { it('leaves a custom renderMessage in charge of the row', () => { const view = render( {row.message.content.length}} rows={project([msg('u', 'user', action({ name: 'go', label: 'Go' }))])} /> @@ -142,10 +142,10 @@ describe('Chat A2UI action labels', () => { const messages = [msg('u', 'user', action({ name: 'bookingSubmit', label: 'Search flights' }))]; it('passes the choice through to its transcript', () => { - const off = render(); + const off = render(); expect(bubble(off)?.textContent).toContain('"bookingSubmit"'); cleanup(); - const on = render(); + const on = render(); expect(text(on)).toBe('Search flights'); }); }); diff --git a/libs/react/src/chat/message-list.tsx b/libs/react/src/chat/message-list.tsx index 917ddc663..73585bcd2 100644 --- a/libs/react/src/chat/message-list.tsx +++ b/libs/react/src/chat/message-list.tsx @@ -194,8 +194,9 @@ export interface MessageListProps { /** * Shows a user message that is a serialized A2UI action as the pressed * control's label ("Search flights") in place of its JSON. Without a label - * the action name is put in plain words. Off unless set; other messages are - * unchanged, and custom renderMessage retains full row ownership. + * the action name is put in plain words. Defaults to true; false shows the + * JSON as sent. Other messages are unchanged, and custom renderMessage + * retains full row ownership. */ readonly a2uiActionLabels?: boolean; /** Typesets math in message text; see `MarkdownProps.math`. Keep stable; custom renderMessage retains full ownership. */ @@ -536,7 +537,7 @@ function RowView({ // The plan and Stop belong to the row's last built-in group, the one the turn is still running. const planGroup = [...runs].reverse().find((run) => 'activities' in run); const actionLabel = - a2uiActionLabels === true && row.role === 'user' + a2uiActionLabels !== false && row.role === 'user' ? a2uiActionLabel(row.message.content) : null; const text = From 7c6ba24bef4be68d7a452cfb2d706124cc5c5e53 Mon Sep 17 00:00:00 2001 From: Brian Love Date: Tue, 17 Nov 2026 17:07:45 -0800 Subject: [PATCH 3/3] chore(react-parity): record the A2UI action label helper --- scripts/react-parity/dispositions.json | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/scripts/react-parity/dispositions.json b/scripts/react-parity/dispositions.json index e1f6dc073..55914508a 100644 --- a/scripts/react-parity/dispositions.json +++ b/scripts/react-parity/dispositions.json @@ -15017,6 +15017,17 @@ "reason": "Internal hook projecting snapshots through app-passed message content, or owning one projection per session for Chat; not exported.", "note": "Verified through the Chat DOM tests: owned disposal on unmount and session change, StrictMode recreation, and app-passed content never disposed. Not part of the public surface." }, + { + "id": "source:libs/react/src/chat/internal/a2ui-action-label.ts", + "taskIds": [ + "T22", + "T27" + ], + "treatment": "react", + "status": "in-progress", + "reason": "Internal reader giving the words for a user message that is a serialized A2UI action: its stamped label, or the action name in plain words; not exported.", + "note": "Verified through the MessageList and Chat DOM tests: default label, opt-out, name fallback, untouched non-action and assistant messages, and text-only rendering. Not part of the public surface." + }, { "id": "source:libs/react/src/chat/message-list.tsx", "taskIds": [