Refine renderer guide, add Gallery App specifications, and strengthen generic constraints#821
Conversation
- Enhanced the Standard Observer Pattern details with clear Unsubscribe Pattern notes and Payload Support specifics. - Added clarification that the instantiating system is responsible for extracting functions from the Catalog. - Replaced the brief overview with a highly detailed section on 'Generating Client Capabilities and Schema Types'. - Inserted a new rationale detailing observability consistency and function categorizations. - Replaced the brief 'Demo Application' outline with the full, detailed 'The Gallery App' documentation.
![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 renderer_guide.md by adding more detail, examples, and new sections. The changes improve clarity on the observer pattern, DataContext responsibilities, and client capabilities generation. The new sections on "Function Implementation Rationale" and "The Gallery App" are excellent additions that provide valuable guidance for developers. The "Agent Implementation Guide" has also been updated consistently. I've identified a couple of minor areas for improvement to enhance clarity and consistency in the documentation.
| 1. It translates the definition into a raw JSON Schema. | ||
| 2. It traverses the schema tree looking for string descriptions starting with the `REF:` tag. | ||
| 3. It strips the tag and replaces the entire node with a valid JSON Schema `$ref` object. | ||
| 3. It strips the tag and replaces the entire node with a valid JSON Schema `$ref` object, preserving any actual developer descriptions using a separator token. |
There was a problem hiding this comment.
The documentation mentions a "separator token" for preserving developer descriptions alongside REF: tags, but it doesn't specify what this token is. For clarity, it would be helpful to explicitly state that the separator is a pipe character (|) and provide an example, like REF:common_types.json#/$defs/DynamicString|This is a developer description.. This would make it easier for implementers to follow the specification.
| 3. It strips the tag and replaces the entire node with a valid JSON Schema `$ref` object, preserving any actual developer descriptions using a separator token. | |
| 3. It strips the tag and replaces the entire node with a valid JSON Schema `$ref` object, preserving any actual developer descriptions using a separator token (the pipe character `|`). |
| * **Reactive Logic**: Opening the "Capitalize Text" sample and typing into the input must result in the upper-case version of the text appearing dynamically in the associated output component. | ||
| * **Action Context Scoping**: Opening the "Incremental List" sample and clicking a "Book now" button must emit an action containing the correctly resolved restaurant name (e.g., "The Golden Fork") in its context, proving that dynamic values within actions are correctly scoped to their containing list item. |
There was a problem hiding this comment.
The integration testing requirements mention the "Capitalize Text" and "Incremental List" samples. However, these sample files don't seem to be present in the repository under specification/v0_9/json/catalogs/minimal/examples/ or specification/v0_9/json/catalogs/basic/examples/. To avoid confusion for developers trying to implement and run these tests, it would be beneficial to either add these missing sample files or update the documentation to reference existing examples that demonstrate the same concepts.
jacobsimionato
changed the title
…ers, Typed Catalogs, and Custom Catalogs
jacobsimionato
changed the title
| ## Implementation Topologies | ||
| ## 1. Unified Architecture Overview | ||
|
|
||
| The A2UI client architecture follows a strict, unidirectional data flow that bridges language-agnostic data structures with native UI frameworks. |
There was a problem hiding this comment.
It's not really unidirectional, though, right? There are events that go the other direction.
There was a problem hiding this comment.
Fair. I removed this!
2 participants
Description of Changes
SurfaceLifecycleListener,SurfaceGroupModel,SurfaceModel,MessageProcessor,ComponentContext, andCatalogto extendComponentApi.FunctionInvoker.a2uiClientCapabilitiespayload, including schema type locations, detectable common types via tags (REF:), and required test cases.Catalog,ComponentApi,FunctionApi, andFunctionImplementation. Added guidelines on function observability and return types.Rationale
Testing/Running Instructions
specification/v0_9/docs/renderer_guide.mdfor accuracy, formatting, and readability.