diff --git a/apps/website/content/docs/react/chat/getting-started/installation.mdx b/apps/website/content/docs/react/chat/getting-started/installation.mdx index 12ca2a46b..46eb9d426 100644 --- a/apps/website/content/docs/react/chat/getting-started/installation.mdx +++ b/apps/website/content/docs/react/chat/getting-started/installation.mdx @@ -50,6 +50,6 @@ npx nx test react npx nx run react:type-tests ~~~ -The binding observes client-side owners; `useAgent` does not support server rendering or hydration. Keep backend credentials on the server and make browser authentication an application responsibility. +`useAgent` renders the snapshot its session holds on the server and subscribes only in the browser, so hydration matches when the browser session holds the same snapshot. Keep backend credentials on the server and make browser authentication an application responsibility. Continue with [Quickstart](/docs/react/chat/getting-started/quickstart). diff --git a/apps/website/content/docs/react/langgraph/getting-started/installation.mdx b/apps/website/content/docs/react/langgraph/getting-started/installation.mdx index f85d0cee6..b8c8f0186 100644 --- a/apps/website/content/docs/react/langgraph/getting-started/installation.mdx +++ b/apps/website/content/docs/react/langgraph/getting-started/installation.mdx @@ -37,4 +37,4 @@ The preview's runtime bridge selects the shared development target or a develope Keep model and provider credentials server-side. If your production browser needs authenticated access, supply an application-controlled endpoint and an appropriate user authentication boundary. Do not bundle provider secrets into React source. -Continue with [Quickstart](/docs/react/langgraph/getting-started/quickstart). The binding is client-side; server rendering and hydration are not supported by `useAgent`. +Continue with [Quickstart](/docs/react/langgraph/getting-started/quickstart). Creating a session performs no network I/O, so `useAgent` can render on the server: it renders the snapshot the session holds at that moment and subscribes only in the browser. Hydration matches only when the browser session holds the same snapshot as the server session, which is normally the empty initial snapshot. diff --git a/libs/react/README.md b/libs/react/README.md index b12ea107b..7c2ed8107 100644 --- a/libs/react/README.md +++ b/libs/react/README.md @@ -1720,7 +1720,7 @@ visited data is unavailable. Plain app-owned data excludes executable objects, accessors and proxies; this view is not an SDK validation boundary. The panel's own data/default props produce deterministic server markup and can -hydrate independently of `useAgent`; this does not extend the hook's SSR contract. +hydrate independently of `useAgent`. After hydration, a supplied application-scoped `storageKey` restores only open, dock and tab preferences, tolerating denied storage. Defaults never overwrite saved preferences during hydration. State, history, IDs, target and selection are never @@ -2099,7 +2099,11 @@ import { A2uiSurface } from '@threadplane/react/a2ui'; import type { A2uiSurfaces } from '@threadplane/content/a2ui'; export function Surfaces({ surfaces }: { readonly surfaces: A2uiSurfaces }) { - const snapshot = useSyncExternalStore(surfaces.subscribe, surfaces.getSnapshot); + const snapshot = useSyncExternalStore( + surfaces.subscribe, + surfaces.getSnapshot, + surfaces.getSnapshot + ); return snapshot.surfaces.map((surface) => ( )); diff --git a/libs/react/src/use-agent.ssr.spec.tsx b/libs/react/src/use-agent.ssr.spec.tsx new file mode 100644 index 000000000..902c5e871 --- /dev/null +++ b/libs/react/src/use-agent.ssr.spec.tsx @@ -0,0 +1,38 @@ +import { renderToString } from 'react-dom/server'; +import { expect, it } from 'vitest'; +import { createFakeAgentSession } from '@threadplane/core/testing'; +import { useAgent } from './use-agent'; + +type Session = ReturnType['session']; + +function Status({ session }: { readonly session: Session }) { + const snapshot = useAgent(session); + return ( +

+ {`${snapshot.status}:${snapshot.messages.map((m) => m.content).join(',')}`} +

+ ); +} + +it('renders the session snapshot on the server without subscribing', () => { + const fake = createFakeAgentSession(); + let subscriptions = 0; + const session: Session = { + ...fake.session, + getSnapshot: () => fake.session.getSnapshot(), + subscribe: (notify) => { + subscriptions += 1; + return fake.session.subscribe(notify); + }, + }; + const html = renderToString(); + expect(html).toContain('idle:'); + expect(subscriptions).toBe(0); +}); + +it('renders the snapshot a session already holds', () => { + const fake = createFakeAgentSession(); + fake.push({ role: 'user', content: 'hello from the server' }); + const html = renderToString(); + expect(html).toContain('hello from the server'); +}); diff --git a/libs/react/src/use-agent.ts b/libs/react/src/use-agent.ts index 733c6f630..e35fa04cf 100644 --- a/libs/react/src/use-agent.ts +++ b/libs/react/src/use-agent.ts @@ -12,5 +12,6 @@ export function useAgent(session: { (notify: () => void) => session.subscribe(notify), [session] ); - return useSyncExternalStore(subscribe, getSnapshot); + // A session does no I/O until it is used, so its current snapshot is also the server snapshot. + return useSyncExternalStore(subscribe, getSnapshot, getSnapshot); }