diff --git a/libs/react/README.md b/libs/react/README.md
index c0c383898..0a43a2173 100644
--- a/libs/react/README.md
+++ b/libs/react/README.md
@@ -751,6 +751,11 @@ comes from your function: pass the content to `A2uiMessageSurfaces` from
and render `A2uiSurface` yourself, returning `skeleton` until a surface is
ready.
+`sourceDetails: true` adds a closed "Details" disclosure under each surface
+that shows the message content it was built from, headed "Layout source" for a
+spec and "Response source" for A2UI. Pass `{ summary, spec, a2ui }` instead of
+`true` to replace that text. A placeholder and a message left as text get none.
+
A message shown as a surface gets no built-in message actions. A custom
`renderMessage` keeps full ownership of its rows.
diff --git a/libs/react/src/chat/generative-ui.tsx b/libs/react/src/chat/generative-ui.tsx
index 406484e0d..006707ed2 100644
--- a/libs/react/src/chat/generative-ui.tsx
+++ b/libs/react/src/chat/generative-ui.tsx
@@ -46,6 +46,16 @@ export interface MessageRenderEvent {
readonly event: RenderEvent;
}
+/** Text of the source disclosure under a surface; see `MessageGenerativeUi.sourceDetails`. */
+export interface MessageSourceLabels {
+ /** The disclosure's toggle. Defaults to "Details". */
+ readonly summary?: string;
+ /** Heading over a spec's source. Defaults to "Layout source". */
+ readonly spec?: string;
+ /** Heading over A2UI source. Defaults to "Response source". */
+ readonly a2ui?: string;
+}
+
/**
* Turns on generated UI inside the transcript. Each part is separate: an
* assistant message is rendered as a surface only for the kinds configured
@@ -85,6 +95,12 @@ export interface MessageGenerativeUi {
* with `A2uiSurface`; return `content.skeleton` until one is ready.
*/
readonly renderA2ui?: (content: MessageA2uiContent) => ReactNode;
+ /**
+ * Adds a closed "Details" disclosure under each surface that shows the
+ * message content the surface was built from. Pass labels to replace its
+ * text. Off unless set.
+ */
+ readonly sourceDetails?: boolean | MessageSourceLabels;
/** Placeholder text while a surface is being built. Defaults to "Building UI…". */
readonly skeletonLabel?: string;
}
@@ -190,6 +206,32 @@ function renderable(
};
}
+/** The message content a surface was built from, closed until the reader opens it. */
+function SourceDetails({
+ kind,
+ content,
+ options,
+}: {
+ readonly kind: 'spec' | 'a2ui';
+ readonly content: string;
+ readonly options: MessageGenerativeUi;
+}) {
+ const { sourceDetails } = options;
+ if (sourceDetails === undefined || sourceDetails === false) return null;
+ const labels = sourceDetails === true ? {} : sourceDetails;
+ return (
+
+ {labels.summary ?? 'Details'}
+
+ {kind === 'spec'
+ ? labels.spec ?? 'Layout source'
+ : labels.a2ui ?? 'Response source'}
+
+ {content}
+
+ );
+}
+
/** Content from the agent must not take the transcript down: a surface that throws gives way to `fallback`. */
class SurfaceBoundary extends Component<
{
@@ -275,22 +317,25 @@ function SpecSurface({
loading: streaming,
};
return (
-
- {store === undefined ? (
-
- ) : (
-
- )}
-
+ <>
+
+ {store === undefined ? (
+
+ ) : (
+
+ )}
+
+
+ >
);
}
@@ -359,6 +404,7 @@ export function GenerativeUiContent({
}}
/>
+
);
}
diff --git a/libs/react/src/chat/index.ts b/libs/react/src/chat/index.ts
index fe4e2ef09..e25ec3928 100644
--- a/libs/react/src/chat/index.ts
+++ b/libs/react/src/chat/index.ts
@@ -111,6 +111,7 @@ export type {
MessageA2uiContent,
MessageGenerativeUi,
MessageRenderEvent,
+ MessageSourceLabels,
} from './generative-ui.js';
export { Reasoning, type ReasoningProps } from './reasoning.js';
export { Trace, type TraceProps, type TraceState } from './trace.js';
diff --git a/libs/react/src/chat/message-list-source-details.spec.tsx b/libs/react/src/chat/message-list-source-details.spec.tsx
new file mode 100644
index 000000000..74b8f9dcc
--- /dev/null
+++ b/libs/react/src/chat/message-list-source-details.spec.tsx
@@ -0,0 +1,137 @@
+import { cleanup, render } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+ completeDelivery,
+ streamingDelivery,
+ type AgentSnapshot,
+ type Message,
+} from '@threadplane/core';
+import { createMessageContent } from '@threadplane/content/messages';
+import { MessageList, type MessageGenerativeUi } from './index';
+
+afterEach(cleanup);
+
+const SPEC = JSON.stringify({
+ root: 'card',
+ elements: { card: { type: 'Card', props: { title: 'Lyon trip' } } },
+});
+const A2UI =
+ '---a2ui_JSON---\n{"version":"v0.9","createSurface":{"surfaceId":"trip"}}\n';
+const registry: NonNullable = {
+ Card: (view) => {String(view.props['title'])},
+};
+const renderA2ui: NonNullable = () => (
+
+);
+
+const assistant = (content: string, id = 'a', streaming = false): Message => ({
+ id,
+ role: 'assistant',
+ content,
+ delivery: streaming ? streamingDelivery('g') : completeDelivery('g', 'success'),
+});
+const snapshot = (messages: readonly Message[]): AgentSnapshot => ({
+ status: 'idle',
+ messages,
+ toolCalls: [],
+});
+const rows = (...messages: Message[]) =>
+ createMessageContent().project(snapshot(messages));
+const details = (container: HTMLElement) =>
+ [...container.querySelectorAll('details.tp-chat-generative-ui__source')];
+
+describe('MessageList generativeUi sourceDetails', () => {
+ it('adds no disclosure unless sourceDetails is set', () => {
+ const view = render(
+
+ );
+ expect(details(view.container)).toHaveLength(0);
+ view.rerender(
+
+ );
+ expect(details(view.container)).toHaveLength(0);
+ });
+
+ it('shows a closed disclosure with the source under each surface', () => {
+ const view = render(
+
+ );
+ const [spec, a2ui] = details(view.container);
+ expect(details(view.container)).toHaveLength(2);
+ expect(spec.open).toBe(false);
+ expect(spec.getAttribute('data-kind')).toBe('spec');
+ expect(spec.querySelector('summary')?.textContent).toBe('Details');
+ expect(spec.querySelector('p')?.textContent).toBe('Layout source');
+ expect(spec.querySelector('pre')?.textContent).toBe(SPEC);
+ // It follows its surface inside the same message body.
+ const surface = spec.previousElementSibling as HTMLElement;
+ expect(surface.className).toBe('tp-chat-generative-ui');
+ expect(surface.textContent).toBe('Lyon trip');
+ expect(spec.closest('.tp-chat-message__body')).not.toBeNull();
+
+ expect(a2ui.getAttribute('data-kind')).toBe('a2ui');
+ expect(a2ui.querySelector('p')?.textContent).toBe('Response source');
+ expect(a2ui.querySelector('pre')?.textContent).toBe(A2UI);
+ expect((a2ui.previousElementSibling as HTMLElement).textContent).toBe('surface');
+ });
+
+ it('takes its text from labels', () => {
+ const view = render(
+
+ );
+ const [spec, a2ui] = details(view.container);
+ expect(spec.querySelector('summary')?.textContent).toBe('Source');
+ expect(spec.querySelector('p')?.textContent).toBe('Layout');
+ expect(a2ui.querySelector('summary')?.textContent).toBe('Source');
+ expect(a2ui.querySelector('p')?.textContent).toBe('Envelopes');
+ });
+
+ it('adds none to text, to content that is not a spec, or to a placeholder', () => {
+ const options: MessageGenerativeUi = { registry, sourceDetails: true };
+ const view = render(
+
+ );
+ expect(view.getByRole('status')).not.toBeNull();
+ expect(details(view.container)).toHaveLength(0);
+ });
+
+ it('keeps the disclosure open while its message streams', () => {
+ const content = createMessageContent();
+ const at = (length: number, streaming = true) =>
+ content.project(snapshot([assistant(SPEC.slice(0, length), 'a', streaming)]));
+ const options: MessageGenerativeUi = { registry, sourceDetails: true };
+ const view = render(
+
+ );
+ const [open] = details(view.container);
+ open.open = true;
+ view.rerender();
+ expect(details(view.container)[0]).toBe(open);
+ expect(open.open).toBe(true);
+ expect(open.querySelector('pre')?.textContent).toBe(SPEC);
+ });
+});
diff --git a/libs/react/src/chat/styles.css b/libs/react/src/chat/styles.css
index da5ae7e01..0f8a42496 100644
--- a/libs/react/src/chat/styles.css
+++ b/libs/react/src/chat/styles.css
@@ -2873,6 +2873,21 @@
.tp-chat-message__body:has(> .tp-chat-generative-ui) > .tp-chat-message__caret {
display: none;
}
+/* The source a surface was built from, for a reader who wants to check it. */
+.tp-chat-generative-ui__source {
+ margin-block: 12px;
+ color: var(--tp-chat-muted, var(--ds-text-secondary, GrayText));
+ font-size: 12px;
+}
+.tp-chat-generative-ui__source > summary {
+ cursor: pointer;
+}
+.tp-chat-generative-ui__source > pre {
+ max-block-size: 280px;
+ overflow: auto;
+ white-space: pre-wrap;
+ overflow-wrap: anywhere;
+}
.tp-genui-skeleton {
display: block;
diff --git a/scripts/react-parity/dispositions.json b/scripts/react-parity/dispositions.json
index 5d4d5b6da..240225b64 100644
--- a/scripts/react-parity/dispositions.json
+++ b/scripts/react-parity/dispositions.json
@@ -18653,6 +18653,14 @@
"target": "libs/react/src/chat/generative-ui.tsx",
"reason": "What onRenderEvent receives: the ID of the message whose spec tree produced the event, and the RenderSpec event (an action that ran, a state write, or a reported result)."
},
+ {
+ "id": "export:libs/react/src/chat/index.ts#MessageSourceLabels",
+ "taskIds": ["T19", "T27"],
+ "treatment": "react",
+ "status": "in-progress",
+ "target": "libs/react/src/chat/generative-ui.tsx",
+ "reason": "Replacement text for the opt-in source disclosure under a surface: its toggle and the headings over a spec's and an A2UI message's source."
+ },
{
"id": "source:libs/react/src/chat/typing-indicator.tsx",
"taskIds": ["T23"],