feat(genui): support ref schema resolution and validation via SchemaRegistry

[gspencergoog]

Summary

This PR enables validation of component definitions containing $ref schemas (such as references to common_types.json) by integrating a SchemaRegistry to compile and resolve external schema references.

Changes

• Schema Validation & Reference Resolution:

  • Updated component validation logic in packages/genui/lib/src/model/schema_validation.dart to use json_schema_builder's robust schema validation (Schema.validate) instead of a basic hand-rolled implementation.
  • Modified validateComponents (in schema_validation.dart) and SurfaceDefinition.validate (in ui_models.dart) to be asynchronous to support the asynchronous reference validation interface of json_schema_builder.
  • Exported SchemaRegistry in packages/json_schema_builder/lib/json_schema_builder.dart to make it publicly accessible.

• Embedded Schemas & build_runner Builder:

  • Added build and build_runner dev-dependencies to packages/genui/pubspec.yaml.
  • Implemented a custom build_runner builder in packages/genui/tool/schema_builder.dart and registered it in packages/genui/build.yaml. The builder automatically embeds common_types.json and server_to_client.json from the a2ui specification submodule into static string literals in lib/src/primitives/embedded_schemas.g.dart.
  • Updated SurfaceController._getSchemaRegistry to synchronously load and populate the registry with the embedded common types schema.

• Testing and Bug Fixes:

  • Fixed an issue in packages/genui/test/catalog/core_widgets/button_test.dart where manual subscription cancellation on closed stream controllers caused the test runner to hang in FakeAsync zones. Refactored the test to use SurfaceController.dispose() for listener cleanup.
  • Updated unit tests in surface_controller_test.dart and ui_models_test.dart to align with the new asynchronous validation signature.

Impact & Risks

• Breaking Change: The SurfaceDefinition.validate method now returns a Future<void> instead of void. Since this is primarily an internal component representation validation helper, the public integration surface impact is low, but tests that manually validate schemas must be updated to await the validation.
• Added CHANGELOG.md entry in packages/genui documenting this change.

Testing

1. Automatic Verification:

   • Run static analysis:

     dart analyze packages/genui

     Verify that there are no analyzer warnings or errors.
   • Run the full test suite:

     flutter test packages/genui

     Verify that all 279 tests (including the updated button validation and schema matching tests) compile and pass successfully.

2. Re-generating Schemas:

   • Clean and run code generation:

     dart run build_runner build

     Verify that embedded_schemas.g.dart is correctly regenerated.

[github-actions]

Package publishing

If you have publishing permissions, you can use the links below to publish the changes after merging this PR.

Package	Version	Status	Publish tag (post-merge)
package:a2ui_core	0.0.1-wip002	ready to publish	a2ui_core-v0.0.1-wip002
package:genai_primitives	0.2.4	ready to publish	genai_primitives-v0.2.4
package:genui	0.9.2	(error) pubspec version (0.9.2) and changelog (0.10.0) don't agree
package:genui_a2a	0.9.0	(error) pubspec version (0.9.0) and changelog (0.10.0) don't agree
package:json_schema_builder	0.1.6	ready to publish	json_schema_builder-v0.1.6

Documentation at https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.