fix(v0.9): make createSurface idempotent + fix React README quick-start by andrewkolos · Pull Request #1225 · google/A2UI

andrewkolos · 2026-04-17T12:36:06Z

Fixes #1223. Fixes #1224. Bug descriptions and repro steps can be found on the issues.

Also augments the quick-start example with some messages so that the user actually seeing something instead of [Loading root...] forever.

Pre-launch Checklist

I signed the CLA.
I read the Contributors Guide.
I read the Style Guide.
I have added updates to the CHANGELOG.
I updated/added relevant documentation.
My code changes (if any) have tests.

If you need help, consider asking for advice on the discussion board.

gemini-code-assist

Code Review

This pull request makes the createSurface operation idempotent in the MessageProcessor, updating the implementation, tests, and documentation accordingly. The React README example is also expanded to show a more complete message processing flow. Feedback focuses on improving the React example to handle existing surfaces when components remount and moving the idempotency check in the core logic to better handle malformed retry attempts.

andrewkolos · 2026-04-17T12:55:34Z

I'm going to address each issue in separate PRs since I'm conflating problems here.

andrewkolos · 2026-04-17T13:29:48Z

Reopening. I had to think about apps using useEffect should just guard themselves against calling non-idempotent APIs twice, but I recalled there are other reasons we want idempotency anyway as documented in #1223.

andrewkolos · 2026-04-17T14:47:03Z

Side note from testing: A2uiSurface requires the root component to have exactly id: 'root'. If you use a different id, you get [Loading root...] forever with no console diagnostic. Might be worth calling this out in the quick-start comments or the component docs.

ditman · 2026-04-17T18:21:29Z


    if (this.model.getSurface(surfaceId)) {
-      throw new A2uiStateError(`Surface ${surfaceId} already exists.`);
+      return;


I'm not sure about this, I think this is a feature, not a bug, I'd follow up with @jacobsimionato here. However, in case we want to hide the surface duplication, we should at least console.warn so users are aware that maybe their agent is misbehaving, instead of hiding this silently.

AFAICT Jacob already blessed this approach in #1186: #1186 (comment)

Re: console.warn: in the React StrictMode case (which is what the quick-start hits), a warning would fire on every dev-mode render, adding noise. The React strict mode It could be avoided but it would need additional "already-initialized?" guard logic that would bloat the example code more than it already is. Even with that adjustment, the error would appear even more often when #1186 lands barring some major overhaul.

In the interest of getting to a state where the quick start example it runs, I will change this to console.warn anyway.

Re: console.warn: in the React StrictMode case (which is what the quick-start hits), a warning would fire on every dev-mode render, adding noise. The React strict mode It could be avoided but it would need additional "already-initialized?" guard logic that would bloat the example code more than it already is.

I think this is all right, the browser console should collapse two console entries that are identical:

Even with that adjustment, the error would appear even more often when #1186 lands barring some major overhaul.

Yeah, the sample code needs some love; in my case it's duplicating every protocol message, and I'm not sure if that's expected

AFAICT Jacob already blessed this approach in #1186: #1186 (comment)

Hmmm, I'm not sure he approves of this approach in that text. The protocol is not very clear, but it seems to indicate that duplicate createSurfaces are an error. Also, what'd be the behavior? IMO we should not drop the newer messages, but instead overwrite the previously existing ones maybe?

Hey! Sorry in my previous PR I was trying all kinds of hacks to resolve this, but I never fully understood the underlying problem here of the useEffect behavior. Thank you for drilling to the root issue!

I agree with @ditman that the renderer library should fail here. We discussed an intention for duplicate createSurface messages with the same surfaceId to fail, partly to cover a collision scenario where two independent subagents try to create a surface with the same ID - one of them should fail. But I see that this never made it into the specification. I'll send a PR to clarify this.

Re how to deal with this issue practically, I'm not a React expert, but I think that we should rearchitect the system as necessary to avoid message duplication. I believe that useEffect has this behavior in dev because it's intended to be used to drive idempotent actions, e.g. rendering. But A2UI messages are not all idempotent, so I guess useEffect is not the right way to add placeholder content or convey messages from the transport layer to the MessageProcessor. Could we resolve this by avoiding ever calling messageProcessor.processMessage() or messageProcessor.processMessages() etc from useEffect?

Apologies that I likely caused this issue to emerge by relying on useEffect in the wrong place! I really appreciate having your real React expertise here to fix this kind of stuff.

Mailed you #1238 to update the spec :-D

ditman

I think the throwiness of the message-processor is intended! /cc @jacobsimionato for a 2nd opinion :)

processCreateSurfaceMessage threw when a surface with the same ID already existed. This crashes in three real-world scenarios: 1. React StrictMode double-fires useEffect, creating the surface twice. The published README quick-start hits this immediately. 2. A2A streaming: status-update events carry cumulative message parts, redelivering createSurface on every chunk. 3. ADK conversation history replay: the full history is sent with each new request, including prior createSurface messages. The spec says "once a surface is created, its surfaceId and catalogId are fixed; to reconfigure them, the surface must be deleted and recreated." A duplicate createSurface is a no-op by spec intent. Change the throw to a silent return. Update the existing test that asserted the throw to instead assert the no-op behavior.

…nt return

…o protocol docs

andrewkolos · 2026-04-17T19:36:34Z

/gemini review

gemini-code-assist

Code Review

This pull request updates the MessageProcessor to log a warning instead of throwing an error when a duplicate createSurface message is encountered. It also enhances the React renderer's README with a more complete example of the A2UI protocol and includes relevant test updates and a changelog entry. I have no feedback to provide.

andrewkolos · 2026-04-21T20:30:59Z

I've decided to supersede this with a new PR, as it drops the "make createSurface idempotent" idea: #1250

github-project-automation Bot added this to A2UI Apr 17, 2026

github-project-automation Bot moved this to Todo in A2UI Apr 17, 2026

gemini-code-assist Bot reviewed Apr 17, 2026

View reviewed changes

Comment thread renderers/react/README.md

Comment thread renderers/web_core/src/v0_9/processing/message-processor.ts

andrewkolos force-pushed the fix/web_core-idempotent-create-surface branch from bd9b434 to 3deb0ee Compare April 17, 2026 12:39

andrewkolos closed this Apr 17, 2026

github-project-automation Bot moved this from Todo to Done in A2UI Apr 17, 2026

andrewkolos reopened this Apr 17, 2026

andrewkolos force-pushed the fix/web_core-idempotent-create-surface branch from d031c1a to 0e1b913 Compare April 17, 2026 15:38

andrewkolos requested a review from ditman April 17, 2026 18:18

ditman reviewed Apr 17, 2026

View reviewed changes

Comment thread renderers/react/README.md

andrewkolos added 4 commits April 17, 2026 19:16

docs: add CHANGELOG entry for idempotent createSurface

b619418

fix(web_core): log warning on duplicate createSurface instead of sile…

c674012

…nt return

docs(react): add explanation paragraph after quick-start with links t…

e24d3f0

…o protocol docs

andrewkolos force-pushed the fix/web_core-idempotent-create-surface branch from 036511a to e24d3f0 Compare April 17, 2026 19:17

andrewkolos added 2 commits April 17, 2026 19:20

docs: update CHANGELOG to reflect warning instead of silent ignore

82d5172

style: fix prettier formatting on console.warn

468c177

gemini-code-assist Bot reviewed Apr 17, 2026

View reviewed changes

andrewkolos requested a review from ditman April 17, 2026 19:53

andrewkolos mentioned this pull request Apr 21, 2026

docs(react,0.9): fix quick-start example #1250

Merged

6 tasks

andrewkolos closed this Apr 21, 2026

Conversation

andrewkolos commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

andrewkolos commented Apr 17, 2026

Uh oh!

andrewkolos commented Apr 17, 2026

Uh oh!

andrewkolos commented Apr 17, 2026

Uh oh!

ditman Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

andrewkolos Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

ditman Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

jacobsimionato Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

jacobsimionato Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

ditman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

andrewkolos commented Apr 17, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

andrewkolos commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

andrewkolos commented Apr 17, 2026 •

edited

Loading