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']); + }); + }); });