Implement Client Data Model Synchronization in web_core v0.9 and Update Renderer Guide

[jacobsimionato]

This issue tracks the implementation of the client-side data model synchronization mechanism as specified in the A2UI v0.9 protocol. This feature enables the client to send its current data model state back to the server alongside user actions.

Key requirements:

1. Implement the synchronization logic in @renderers/web_core/src/v0_9/.
2. Update the @specification/v0_9/docs/renderer_guide.md to document the architectural changes and API requirements for all A2UI renderers (including SurfaceModel and MessageProcessor changes) to support this feature consistently.

[jacobsimionato]

Coding agent prompt:

Objective:
Implement the "Client Data Model Synchronization" feature in @renderers/web_core/src/v0_9/ based on the A2UI v0.9 specification and update the renderer architectural guide.

Implementation Strategy:

1. Schema Definitions:

   • Create @renderers/web_core/src/v0_9/schema/client-to-server.ts.
   • Implement Zod schemas for:
     • A2uiClientAction: Must match action in @specification/v0_9/json/client_to_server.json.
     • A2uiClientError: Must match error in @specification/v0_9/json/client_to_server.json.
     • A2uiClientDataModel: Must match @specification/v0_9/json/client_data_model.json.
   • Export these in @renderers/web_core/src/v0_9/schema/index.ts.

2. SurfaceModel Updates:

   • Modify @renderers/web_core/src/v0_9/state/surface-model.ts:
     • Add readonly sendDataModel: boolean to the constructor.
     • Update dispatchAction(payload: any, sourceComponentId: string) to require the component ID and include logic to emit a structured action payload.

3. MessageProcessor Updates:

   • Modify @renderers/web_core/src/v0_9/processing/message-processor.ts:
     • Update processCreateSurfaceMessage to extract sendDataModel from the envelope and pass it to SurfaceModel.
     • Implement getClientDataModel(): A2uiClientDataModel | undefined. This method iterates over all surfaces and returns a map of data models for those where sendDataModel is true.

4. Context & Binder Wiring:

   • Modify @renderers/web_core/src/v0_9/rendering/component-context.ts:
     • Ensure dispatchAction passes this.componentModel.id to the surface.

5. Documentation Update:

   • Update @specification/v0_9/docs/renderer_guide.md.
   • Document the sendDataModel property in SurfaceModel.
   • Update the dispatchAction signature to include sourceComponentId in the architectural diagrams and code snippets.
   • Document the getClientDataModel() requirement in MessageProcessor.
   • Explain how renderers should use these APIs to populate transport metadata (e.g., a2uiClientDataModel).

Testing Requirements:

• Schema Tests: Create @renderers/web_core/src/v0_9/schema/client-to-server.test.ts to verify the Zod schemas match the official JSON specs.
• Sync Logic Tests: Add tests to @renderers/web_core/src/v0_9/processing/message-processor.test.ts to verify getClientDataModel() correctly filters surfaces based on the `sendDataModel flag.
• Action Metadata Tests: Verify that dispatched actions now include a valid ISO timestamp and the correct sourceComponentId.

Context References:

• @renderers/web_core/src/v0_9/
• @specification/v0_9/json/client_to_server.json
• @specification/v0_9/json/client_data_model.json
• @specification/v0_9/docs/a2ui_protocol.md
• @specification/v0_9/docs/renderer_guide.md