From 6aa26e4910f982766c5e73733f74484921fbf75c Mon Sep 17 00:00:00 2001 From: Brian Love Date: Tue, 17 Nov 2026 17:19:14 -0800 Subject: [PATCH] feat(react): stream generated UI elements as they arrive Angular materializes a streaming json-render spec on every chunk, so elements and their string props render while the message streams, and chat-generative-ui seeds spec.state path by path. React kept only elements whose JSON had finished and seeded state once the whole object had, so elements popped in one at a time. PR #1604 described that behavior but gave no safety reason for it. generativeUi.progressive (off unless set) renders an element once its type has finished, lets its string props grow as they stream, and applies other props, child IDs, visible and repeat only once each has finished. on bindings apply only once the whole element has, so no action runs with half-written params. A spec's own state is seeded one top-level path at a time; the own store is rebuilt rather than written, so seeding reports no stateChange, and a value a view already wrote is kept. A finished spec renders the same either way. Co-Authored-By: Claude Opus 5.5 --- .../docs/react/chat/guides/generative-ui.mdx | 2 +- libs/react/README.md | 9 ++ libs/react/src/chat/generative-ui.tsx | 122 +++++++++++++++--- .../chat/message-list-generative-ui.spec.tsx | 107 +++++++++++++++ .../chat/message-list-interactive-ui.spec.tsx | 65 ++++++++++ 5 files changed, 285 insertions(+), 20 deletions(-) diff --git a/apps/website/content/docs/react/chat/guides/generative-ui.mdx b/apps/website/content/docs/react/chat/guides/generative-ui.mdx index 3ddf8070d..b56e7e689 100644 --- a/apps/website/content/docs/react/chat/guides/generative-ui.mdx +++ b/apps/website/content/docs/react/chat/guides/generative-ui.mdx @@ -11,7 +11,7 @@ The native React APIs on this page are experimental, private source-build packag ## Compose text and generated content -The application continues to use `MessageList`, Markdown, and tool observations for the conversation. For an admitted dashboard specification it adds `RenderSpec` with a closed registry and the matching state. Keeping those paths explicit lets ordinary text remain readable while generated content uses a controlled set of components. This example waits for a confirmed layout rather than promising Angular’s progressive rendering behavior. +The application continues to use `MessageList`, Markdown, and tool observations for the conversation. For an admitted dashboard specification it adds `RenderSpec` with a closed registry and the matching state. Keeping those paths explicit lets ordinary text remain readable while generated content uses a controlled set of components. This example waits for a confirmed layout rather than promising Angular’s progressive rendering behavior. When a spec is carried by an assistant message, `generativeUi` on `MessageList` and `Chat` renders it in the transcript, and `progressive: true` matches the Angular behavior: each element appears once its type arrives, its string props grow as they stream, and its `on` bindings wait until the whole element has finished, so no action runs with partial params. The [React conversation walkthrough](/docs/react/langgraph/concepts/conversation-turns) connects this capability to requests, tools, UI state, and saved history. diff --git a/libs/react/README.md b/libs/react/README.md index b12ea107b..ad5cebd20 100644 --- a/libs/react/README.md +++ b/libs/react/README.md @@ -781,6 +781,15 @@ and `skeletonLabel` replaces the placeholder text. Finished content that is not a spec stays text, and a view that throws gives way to the message text instead of taking the transcript down. +Set `progressive: true` to render a streaming spec as it arrives, as Angular +does, instead of one finished element at a time. An element appears once its +`type` has finished and its string props grow as they stream; other props, +child IDs, `visible` and `repeat` apply once each has finished, and its `on` +bindings only once the whole element has, so no action runs with half-written +params. A spec's own `state` is seeded one top-level path at a time as each +value finishes, keeping anything a view already wrote. A finished spec renders +the same either way. + The tree is read-only until you set `handlers`, `store` or `onRenderEvent`. With any of them, views get `emit` and `set`, as they do from `RenderSpec` with a `store`: diff --git a/libs/react/src/chat/generative-ui.tsx b/libs/react/src/chat/generative-ui.tsx index 006707ed2..b2f8dc574 100644 --- a/libs/react/src/chat/generative-ui.tsx +++ b/libs/react/src/chat/generative-ui.tsx @@ -65,11 +65,23 @@ export interface MessageGenerativeUi { /** * Views by component name. With it, an assistant message whose content is a * json-render spec (`{ "root": …, "elements": … }`) renders as that tree in - * place of its text. Elements appear as each one finishes streaming, and a - * placeholder stands in until the root element has. The tree is read-only - * unless `handlers`, `store` or `onRenderEvent` is set. + * place of its text. Elements appear as each one finishes streaming (see + * `progressive`), and a placeholder stands in until the root element has. + * The tree is read-only unless `handlers`, `store` or `onRenderEvent` is set. */ readonly registry?: ReactRenderRegistry; + /** + * Renders a streaming spec as it arrives instead of one finished element at + * a time. An element appears once its `type` has finished, its string props + * grow as they stream, and other props, child IDs, `visible` and `repeat` + * apply once each has finished. Its `on` bindings apply only once the whole + * element has, so no action runs with half-written params. A spec's own + * `state` is seeded one top-level path at a time as each value finishes, + * and a value a view has already written is kept. Views can tell a partial + * element by `loading`. A finished spec renders the same either way. Off + * unless set. + */ + readonly progressive?: boolean; /** Computed functions for spec props; see `RenderSpecProps.functions`. */ readonly functions?: ReactRenderFunctions; /** Rendered for a spec component the registry lacks; see `RenderSpecProps.fallback`. */ @@ -160,13 +172,66 @@ function props(value: unknown): Record { ); } +type JsonValue = Extract['value'][string]; +const finished = (node: JsonNode | undefined): boolean => + node?.status === 'complete'; + +/** Props that are safe to render mid-stream: finished values, and strings as far as they have arrived. */ +function partialProps(node: JsonNode | undefined): JsonValue { + if (node === undefined) return undefined; + if (node.kind !== 'object') return finished(node) ? node.value : undefined; + const ready: Record = {}; + for (const [name, prop] of Object.entries(node.children)) + if (finished(prop) || (prop.kind === 'string' && prop.value !== undefined)) + ready[name] = prop.value; + return ready; +} + +/** + * The part of a streaming element that may render now, or null while its type + * or an open `visible` or `repeat` would change what it is. Its `on` bindings + * wait for the whole element, so an action never runs with partial params. + */ +function partialElement( + node: Extract +): Readonly> | null { + if (finished(node)) return node.value; + const { type, props, children, visible, repeat } = node.children; + if (type?.kind !== 'string' || !finished(type)) return null; + if ((visible && !finished(visible)) || (repeat && !finished(repeat))) + return null; + return { + type: type.value, + props: partialProps(props), + children: + children?.kind === 'array' + ? children.children.filter(finished).map((child) => child.value) + : undefined, + ...(visible ? { visible: visible.value } : {}), + ...(repeat ? { repeat: repeat.value } : {}), + }; +} + +/** The top-level `state` entries whose values have finished, in arrival order. */ +function partialState(node: JsonNode | undefined): SpecState | undefined { + if (node?.kind !== 'object') return undefined; + if (finished(node)) return node.value as SpecState; + return Object.fromEntries( + Object.entries(node.children) + .filter(([, value]) => finished(value)) + .map(([key, value]) => [key, value.value]) + ) as SpecState; +} + /** * The renderable part of a spec that may still be streaming: the elements - * whose JSON is finished, once the root key and the root element are. A child - * that has not arrived yet is simply absent, and renders nothing. + * whose JSON is finished (or, when `progressive`, each element as far as it + * may render), once the root key and the root element are. A child that has + * not arrived yet is simply absent, and renders nothing. */ function renderable( - root: JsonNode | null + root: JsonNode | null, + progressive: boolean ): { readonly spec: RenderSpecData; readonly state?: SpecState } | null { if (root?.kind !== 'object') return null; const key = root.children['root']; @@ -180,12 +245,18 @@ function renderable( return null; const elements: Record = Object.create(null); for (const [id, node] of Object.entries(nodes.children)) { - if (node.kind !== 'object' || node.status !== 'complete') continue; - const { type, children, visible, repeat, on } = node.value; + if (node.kind !== 'object') continue; + const value = progressive + ? partialElement(node) + : finished(node) + ? node.value + : null; + if (value === null) continue; + const { type, children, visible, repeat, on } = value; if (typeof type !== 'string') continue; elements[id] = { type, - props: props(node.value['props']), + props: props(value['props']), children: Array.isArray(children) ? [...new Set(children.filter((child) => typeof child === 'string'))] : [], @@ -197,12 +268,14 @@ function renderable( } as RenderElementData; } if (!Object.hasOwn(elements, key.value)) return null; - const state = root.children['state']; + const state = progressive + ? partialState(root.children['state']) + : finished(root.children['state']) && root.children['state'].kind === 'object' + ? (root.children['state'].value as SpecState) + : undefined; return { spec: { root: key.value, elements }, - ...(state?.kind === 'object' && state.status === 'complete' - ? { state: state.value as SpecState } - : {}), + ...(state === undefined ? {} : { state }), }; } @@ -274,6 +347,7 @@ function SpecSurface({ }) { const { content, delivery } = row.message; const streaming = delivery.phase === 'streaming'; + const progressive = options.progressive === true; // Parsed again per change: a spec is small, and the row re-renders only when it changes. const tree = useMemo(() => { const json = createJson({ @@ -283,23 +357,33 @@ function SpecSurface({ }); const { root } = json.getSnapshot(); json.dispose(); - return renderable(root); - }, [content, delivery.generation, delivery.phase]); + return renderable(root, progressive); + }, [content, delivery.generation, delivery.phase, progressive]); const { handlers, onRenderEvent } = options; const interactive = handlers !== undefined || options.store !== undefined || onRenderEvent !== undefined; - // A spec's own state arrives once, when its `state` object finishes. + // A spec's own state arrives once, when its `state` object finishes, or, + // when progressive, one top-level path at a time. const seed = tree?.state; - const seeded = seed !== undefined; - const own = useRef<{ readonly seeded: boolean; readonly store: RenderStore }>( + const seeded = progressive + ? Object.keys(seed ?? {}).join('/') + : String(seed !== undefined); + const own = useRef<{ readonly seeded: string; readonly store: RenderStore }>( undefined ); let store = options.store; if (interactive && store === undefined) { if (own.current?.seeded !== seeded) - own.current = { seeded, store: createRenderState(seed) }; + own.current = { + seeded, + // A new store, not writes to the old one, so seeding reports no + // state change; what a view already wrote wins over a later seed. + store: createRenderState( + progressive ? { ...seed, ...own.current?.store.getSnapshot() } : seed + ), + }; store = own.current.store; } const messageId = row.message.id; diff --git a/libs/react/src/chat/message-list-generative-ui.spec.tsx b/libs/react/src/chat/message-list-generative-ui.spec.tsx index 1771bcbe1..7fd5c8eae 100644 --- a/libs/react/src/chat/message-list-generative-ui.spec.tsx +++ b/libs/react/src/chat/message-list-generative-ui.spec.tsx @@ -219,6 +219,113 @@ describe('MessageList generativeUi', () => { expect(view.container.textContent).toBe('custom a'); }); + describe('progressive', () => { + const progressive: MessageGenerativeUi = { registry, progressive: true }; + const streamed = () => { + const content = createMessageContent(); + return (text: string, length: number, streaming = true) => + content.project(snapshot([assistant(text.slice(0, length), streaming)])); + }; + + it('renders an element before it finishes, its string props growing in place', () => { + const at = streamed(); + // The element type is still open: nothing to render yet. + const view = render( + + ); + expect(view.getByRole('status').textContent).toBe('Building UI…'); + + view.rerender( + + ); + expect(view.queryByRole('status')).toBeNull(); + const card = view.container.querySelector('[data-view="card"]') as HTMLElement; + expect(card.querySelector('h3')?.textContent).toBe('Ly'); + expect(card.getAttribute('data-loading')).toBe('true'); + + view.rerender( + + ); + expect(view.container.querySelector('[data-view="card"]')).toBe(card); + expect(card.querySelector('h3')?.textContent).toBe('Lyon trip'); + + // A child appears while its own JSON is still open. + view.rerender( + + ); + expect(view.container.querySelector('[data-view="card"]')).toBe(card); + expect( + [...card.querySelectorAll('[data-view="line"]')].map((p) => p.textContent) + ).toEqual(['09']); + }); + + it('waits for a child ID to finish before rendering it', () => { + const at = streamed(); + const view = render( + + ); + const card = view.container.querySelector('[data-view="card"]') as HTMLElement; + expect(card).not.toBeNull(); + expect(card.querySelectorAll('[data-view="line"]')).toHaveLength(0); + }); + + it('seeds state path by path as each value finishes', () => { + const STATEFUL = JSON.stringify({ + root: 'card', + elements: { + card: { type: 'Card', props: { title: 'Trip' }, children: ['who', 'where'] }, + who: { type: 'Line', props: { text: { statePath: '/guest' } } }, + where: { type: 'Line', props: { text: { $state: '/city' } } }, + }, + state: { guest: 'Ada', city: 'Lyon' }, + }); + const at = streamed(); + const lines = (container: HTMLElement) => + [...container.querySelectorAll('[data-view="line"]')].map((p) => p.textContent); + const view = render( + + ); + expect(lines(view.container)).toEqual(['Ada', 'undefined']); + view.rerender( + + ); + expect(lines(view.container)).toEqual(['Ada', 'Lyon']); + }); + + it('renders a finished spec exactly as the default does', () => { + const plain = render( + + ).container.innerHTML; + cleanup(); + const at = streamed(); + const view = render( + + ); + view.rerender( + + ); + expect(view.container.innerHTML).toBe(plain); + }); + }); + describe('renderA2ui', () => { const A2UI = '---a2ui_JSON---\n{"version":"v0.9","createSurface":{"surfaceId":"trip"}}\n'; const calls: MessageA2uiContent[] = []; diff --git a/libs/react/src/chat/message-list-interactive-ui.spec.tsx b/libs/react/src/chat/message-list-interactive-ui.spec.tsx index f1a52bf12..18a77c510 100644 --- a/libs/react/src/chat/message-list-interactive-ui.spec.tsx +++ b/libs/react/src/chat/message-list-interactive-ui.spec.tsx @@ -202,4 +202,69 @@ describe('MessageList generativeUi interaction', () => { }); expect(echoes(view.container)).toEqual(['Grace']); }); + + describe('progressive', () => { + const streamed = (text: string) => { + const content = createMessageContent(); + return (length: number, streaming = true) => + content.project(snapshot([assistant(text.slice(0, length), 'a', streaming)])); + }; + + it('runs no action from an element whose JSON is still open', () => { + const book = vi.fn(); + const options: MessageGenerativeUi = { + registry, + handlers: { book }, + progressive: true, + }; + const at = streamed(FORM); + // The button and its label are here; its `on` binding is half written. + const view = render( + + ); + fireEvent.click(view.getByRole('button', { name: 'Book' })); + // The binding has finished, but the element has not. + const closed = FORM.indexOf('}}}}', FORM.indexOf('"params"')) + 4; + view.rerender(); + fireEvent.click(view.getByRole('button', { name: 'Book' })); + expect(book).not.toHaveBeenCalled(); + + view.rerender(); + fireEvent.click(view.getByRole('button', { name: 'Book' })); + expect(book).toHaveBeenCalledTimes(1); + }); + + it('seeds its own state path by path and keeps an edit made between seeds', () => { + const NOTED = JSON.stringify({ + root: 'form', + elements: { + form: { type: 'Box', props: {}, children: ['guest', 'echo', 'note'] }, + guest: { type: 'Field', props: { label: 'Guest', value: { $bindState: '/guest' } } }, + echo: { type: 'Text', props: { text: { $state: '/guest' } } }, + note: { type: 'Text', props: { text: { $state: '/note' } } }, + }, + state: { guest: 'Ada', note: 'Window seat' }, + }); + const events: MessageRenderEvent[] = []; + const options: MessageGenerativeUi = { + registry, + progressive: true, + onRenderEvent: (event) => { + if (event.event.type !== 'lifecycle') events.push(event); + }, + }; + const at = streamed(NOTED); + const view = render( + + ); + expect(echoes(view.container)).toEqual(['Ada', '']); + fireEvent.change(view.getByRole('textbox', { name: 'Guest' }), { + target: { value: 'Grace' }, + }); + view.rerender(); + expect(echoes(view.container)).toEqual(['Grace', 'Window seat']); + // Seeding is not reported as a state write; the edit is. + expect(events.map(({ event }) => event.type)).toEqual(['stateChange']); + }); + }); });