Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
9 changes: 9 additions & 0 deletions libs/react/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`:
Expand Down
122 changes: 103 additions & 19 deletions libs/react/src/chat/generative-ui.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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`. */
Expand Down Expand Up @@ -160,13 +172,66 @@ function props(value: unknown): Record<string, unknown> {
);
}

type JsonValue = Extract<JsonNode, { kind: 'object' }>['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<string, JsonValue> = {};
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<JsonNode, { kind: 'object' }>
): Readonly<Record<string, JsonValue>> | 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'];
Expand All @@ -180,12 +245,18 @@ function renderable(
return null;
const elements: Record<string, RenderElementData> = 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'))]
: [],
Expand All @@ -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 }),
};
}

Expand Down Expand Up @@ -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({
Expand All @@ -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;
Expand Down
107 changes: 107 additions & 0 deletions libs/react/src/chat/message-list-generative-ui.spec.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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(
<MessageList
rows={at(SPEC, SPEC.indexOf('Card') + 2)}
generativeUi={progressive}
/>
);
expect(view.getByRole('status').textContent).toBe('Building UI…');

view.rerender(
<MessageList
rows={at(SPEC, SPEC.indexOf('Lyon') + 2)}
generativeUi={progressive}
/>
);
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(
<MessageList
rows={at(SPEC, SPEC.indexOf('Lyon') + 9)}
generativeUi={progressive}
/>
);
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(
<MessageList
rows={at(SPEC, SPEC.indexOf('09:4') + 2)}
generativeUi={progressive}
/>
);
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(
<MessageList
rows={at(SPEC, SPEC.indexOf('"when"') + 3)}
generativeUi={progressive}
/>
);
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(
<MessageList
rows={at(STATEFUL, STATEFUL.indexOf('"city"') + 9)}
generativeUi={progressive}
/>
);
expect(lines(view.container)).toEqual(['Ada', 'undefined']);
view.rerender(
<MessageList rows={at(STATEFUL, STATEFUL.length, false)} generativeUi={progressive} />
);
expect(lines(view.container)).toEqual(['Ada', 'Lyon']);
});

it('renders a finished spec exactly as the default does', () => {
const plain = render(
<MessageList rows={rows(assistant(SPEC))} generativeUi={specs} />
).container.innerHTML;
cleanup();
const at = streamed();
const view = render(
<MessageList rows={at(SPEC, SPEC.length / 2)} generativeUi={progressive} />
);
view.rerender(
<MessageList rows={at(SPEC, SPEC.length, false)} generativeUi={progressive} />
);
expect(view.container.innerHTML).toBe(plain);
});
});

describe('renderA2ui', () => {
const A2UI = '---a2ui_JSON---\n{"version":"v0.9","createSurface":{"surfaceId":"trip"}}\n';
const calls: MessageA2uiContent[] = [];
Expand Down
65 changes: 65 additions & 0 deletions libs/react/src/chat/message-list-interactive-ui.spec.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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(
<MessageList rows={at(FORM.indexOf('"params"'))} generativeUi={options} />
);
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(<MessageList rows={at(closed)} generativeUi={options} />);
fireEvent.click(view.getByRole('button', { name: 'Book' }));
expect(book).not.toHaveBeenCalled();

view.rerender(<MessageList rows={at(closed + 1)} generativeUi={options} />);
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(
<MessageList rows={at(NOTED.indexOf('"note":"') + 9)} generativeUi={options} />
);
expect(echoes(view.container)).toEqual(['Ada', '']);
fireEvent.change(view.getByRole('textbox', { name: 'Guest' }), {
target: { value: 'Grace' },
});
view.rerender(<MessageList rows={at(NOTED.length, false)} generativeUi={options} />);
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']);
});
});
});
Loading