docs(v0.9): update renderer guide architecture and implementation details#812
docs(v0.9): update renderer guide architecture and implementation details#812jacobsimionato wants to merge 2 commits intogoogle:mainfrom
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly enhances the v0.9 renderer guide by adding detailed architecture and implementation guidance. The new sections on the Catalog API, Binder Layer, Gallery App, and Agent Implementation Guide are well-structured and provide crucial information for developers building A2UI renderers. My review focuses on ensuring consistency and clarity in the new documentation. I've identified a minor inconsistency in a code example and a case of redundant content that could be consolidated. Overall, these are excellent improvements to the documentation.
Note: Security Review has been skipped due to the limited scope of the PR.
| Widget renderButton(ComponentContext context, Widget Function(String) buildChild) { | ||
| // Manually observe the dynamic value and manage the stream | ||
| return StreamBuilder( | ||
| stream: context.dataContext.observeDynamicValue(context.componentModel.properties['label']), |
There was a problem hiding this comment.
The method observeDynamicValue is used here, which is a reasonable name for a Dart/Flutter implementation that returns a Stream. However, the DataContext API described earlier in the guide and in the web_core implementation uses subscribeDynamicValue with a callback pattern. To prevent confusion for implementers, it would be beneficial to add a brief note clarifying that observeDynamicValue is an illustrative, framework-specific adaptation for reactive stream integration (like StreamBuilder).
| ### Component Subscription Lifecycle Rules | ||
| To ensure performance and prevent memory leaks, framework adapters MUST strictly manage their subscriptions: | ||
| 1. **Lazy Subscription**: Only bind and subscribe to data paths or property updates when the component is actually mounted/attached to the UI. | ||
| 2. **Path Stability**: If a component's property changes via an `updateComponents` message, the adapter/binder MUST unsubscribe from the old path before subscribing to the new one. | ||
| 3. **Destruction / Cleanup**: When a component is removed from the UI (e.g., via a `deleteSurface` message), the framework binding MUST hook into its native lifecycle to trigger `binding.dispose()`. | ||
| 4. **Remount Resilience**: Many declarative frameworks (e.g., React Strict Mode, virtualized lists in mobile) frequently unmount and immediately remount UI components. The binding architecture should support re-establishing severed data subscriptions (e.g. using a connect/disconnect pattern) if a component is remounted after being disposed. |
There was a problem hiding this comment.
This new 'Component Subscription Lifecycle Rules' section is a great addition. It appears to supersede the existing 'Component Subscription Lifecycle' section found later in the document under 'Component Traits'. The new section is more comprehensive. To avoid redundancy and potential confusion, consider removing the older, less detailed section.
1 participant
This PR updates the v0.9
renderer_guide.mdwith expanded architecture and implementation details for renderer development.Changes Included:
DataContext.ComponentContextorComponentBinding.README.mdthat covers sample app usage, chat interface integration, catalog extension, and client logic (functions) implementation.