A2uiSurface throws on SSR: useSyncExternalStore missing getServerSnapshot

[eugenelim]

Bug

When rendering <A2uiSurface> in a server-rendered React app (Next.js App Router, Remix, etc.), React throws during the server pass:

Error: Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering.

Tracked this down to A2uiSurface calling useSyncExternalStore without a getServerSnapshot argument. React requires this on the server to produce a stable, hydration-safe snapshot — without it the call throws on every SSR render.

Steps to reproduce

1. Install @a2ui/react@0.10.2 in a Next.js 14+ (App Router) project
2. Render <A2uiSurface> anywhere that executes server-side
3. Server logs the above error on first render

Expected vs actual

Expected: the component either renders gracefully on the server (returning a stable snapshot or null) or is documented as client-only with a clear pattern for opting out of SSR.

Actual: React throws during the server render pass. In strict SSR setups (e.g. experimental.serverActions: true or a CI render test) this surfaces as a hard error rather than a recoverable warning.

Workaround

Skip the component server-side via a useEffect-guarded mount flag or a dangerouslySetInnerHTML fallback. Works, but means the surface is effectively non-functional until JS loads.

Environment

• @a2ui/react: 0.10.2
• react: 19.x
• Next.js: 14 (App Router)