[Flutter] An onError listener that calls setState misses errors found while A2uiSurface mounts #3612

The a2ui_flutter README tells every app that an onError listener which calls setState (to show the error in the UI, say) must defer it to the next frame:

Without that workaround, if there is an error in the agent's first message, the listener's setState will be cancelled.

To better understand, consider the usual flow the agent creates a surface and fills it in one go, and the app then puts an A2uiSurface for it on screen. If one of those components is broken (e.g. an unknown type), the adapter finds the error while the widget mounts, the onError listener's setState runs during build, which Flutter does not allow. The banner never appears.

Motivation. I noticed this when reviewing agent-drafted code for #3094. It wrapped every update of its error log in a runOutsideBuild helper that pushes the call to a post-frame callback, which struck me as a smelly workaround.

Cause

A2uiSurface builds its NodeResolver in initState:

The resolver delivers what it found synchronously when its update ends, so the listener runs inside the build:

Flutter's "setState() called during build" assertion is then caught and logged by EventNotifier, so nothing visible fails:

The same happens each time a widget is built again for an existing surface, such as when a list scrolls back to it. Fixing this lets the gallery delete runOutsideBuild and the README drop its note.

testWidgets('onError listener can show an error found at mount', (tester) async {
  final processor = MessageProcessor<ComponentImplementation>(
    catalogs: [basicCatalog()],
    defaultVersion: A2uiProtocolVersion.v0_9,
  );
  processor.processMessages(
    AgentToRendererMessagePayload.fromJson([
      {
        'version': 'v0.9',
        'createSurface': {'surfaceId': 's', 'catalogId': basicCatalog().id},
      },
      {
        'version': 'v0.9',
        'updateComponents': {
          'surfaceId': 's',
          'components': [
            {'id': 'root', 'component': 'Bogus'},
          ],
        },
      },
    ], protocolVersion: A2uiProtocolVersion.v0_9),
  );

  await tester.pumpWidget(
    MaterialApp(home: _ErrorCount(processor.model.getSurface('s')!)),
  );
  await tester.pump();

  expect(find.text('errors: 1'), findsOneWidget); // Fails: 'errors: 0'.
});

class _ErrorCount extends StatefulWidget {
  const _ErrorCount(this.surface);
  final SurfaceModel<ComponentImplementation> surface;
  @override
  State<_ErrorCount> createState() => _ErrorCountState();
}

class _ErrorCountState extends State<_ErrorCount> {
  int _errors = 0;

  @override
  void initState() {
    super.initState();
    widget.surface.onError.subscribe((_) => setState(() => _errors++));
  }

  @override
  Widget build(BuildContext context) => Scaffold(
    body: Column(
      children: [
        Text('errors: $_errors'),
        Expanded(child: A2uiSurface(surface: widget.surface)),
      ],
    ),
  );
}

Suggestion, Errors and warnings should reach their listeners after the call that found them returns, outside the build, so a listener can call setState directly.

_{🧑 Human-generated}