From 16c1ff6a8fca9d791d87ba22daebb9098b9085c6 Mon Sep 17 00:00:00 2001 From: Brian Love Date: Sun, 15 Nov 2026 22:07:13 -0800 Subject: [PATCH] feat(react): add an opt-in source disclosure under transcript surfaces generativeUi.sourceDetails adds a closed Details disclosure under each spec or A2UI surface in the transcript, showing the message content the surface was built from. Labels replace its text. It is off unless set, and a placeholder or a message left as text gets none. --- libs/react/README.md | 5 + libs/react/src/chat/generative-ui.tsx | 78 ++++++++-- libs/react/src/chat/index.ts | 1 + .../chat/message-list-source-details.spec.tsx | 137 ++++++++++++++++++ libs/react/src/chat/styles.css | 15 ++ scripts/react-parity/dispositions.json | 8 + 6 files changed, 228 insertions(+), 16 deletions(-) create mode 100644 libs/react/src/chat/message-list-source-details.spec.tsx 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 = () => ( +
surface
+); + +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"],