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 @@ -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).
Original file line number Diff line number Diff line change
Expand Up @@ -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.
8 changes: 6 additions & 2 deletions libs/react/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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) => (
<A2uiSurface key={surface.surfaceId} surface={surface} surfaces={surfaces} />
));
Expand Down
38 changes: 38 additions & 0 deletions libs/react/src/use-agent.ssr.spec.tsx
Original file line number Diff line number Diff line change
@@ -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<typeof createFakeAgentSession>['session'];

function Status({ session }: { readonly session: Session }) {
const snapshot = useAgent(session);
return (
<p>
{`${snapshot.status}:${snapshot.messages.map((m) => m.content).join(',')}`}
</p>
);
}

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(<Status session={session} />);
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(<Status session={fake.session} />);
expect(html).toContain('hello from the server');
});
3 changes: 2 additions & 1 deletion libs/react/src/use-agent.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,6 @@ export function useAgent<TSnapshot>(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);
}
Loading