client: implement reactive surface state with signals (google#903)

nan-yu · web-flow · commit 9303e317b1c8 · 2026-03-20T09:19:53.000-07:00
* client: implement reactive surface state with signals - Introduces surfacesSignal inside the Angular MessageProcessor to act as a reactive wrapper around Core's Surface map. Angular's new signal-based change detection operates on strict reference equality. During streaming execution, the web core A2uiMessageProcessor mutates the underlying surface models in-place for fast iteration. Because the memory references are unchanged, the Angular UI doesn't know it needs to re-render. By overriding processMessages and shallow-cloning the active surfaces into a brand new Map via a notify() broadcast, we force Angular to observe the mutated data model and reliably trigger UI updates. - Adds @if (child) structural directives to iterative component templates (e.g. Row, Column, List, Modal) to safely render nested children as properties incrementally arrive over the network. * feat(streaming): implement reactive client-side streaming support By default, the Angular client uses the non-streaming API to communicate with the agent. To enable streaming, set the `ENABLE_STREAMIING` env var to `true. ```bash export ENABLE_STREAMING=true npm start -- contact ```
diff --git a/renderers/angular/src/v0_8/components/button.ts b/renderers/angular/src/v0_8/components/button.ts
@@ -29,11 +29,13 @@ import { Renderer } from '../rendering/renderer';
       [style]="theme.additionalStyles?.Button"
       (click)="handleClick()"
     >
-      <ng-container
-        a2ui-renderer
-        [surfaceId]="surfaceId()!"
-        [component]="child() ?? component().properties.child"
-      />
+      @if (child()) {
+        <ng-container
+          a2ui-renderer
+          [surfaceId]="surfaceId()!"
+          [component]="child() ?? component().properties.child"
+        />
+      }
     </button>
   `,
   styles: `
diff --git a/renderers/angular/src/v0_8/components/column.ts b/renderers/angular/src/v0_8/components/column.ts
@@ -79,8 +79,10 @@ import { Renderer } from '../rendering/renderer';
   `,
   template: `
     <section [class]="classes()" [style]="theme.additionalStyles?.Column">
-      @for (child of children() ?? component().properties.children; track child) {
-        <ng-container a2ui-renderer [surfaceId]="surfaceId()!" [component]="child" />
+      @for (child of children() ?? component().properties.children; track child?.id ?? child) {
+        @if (child) {
+          <ng-container a2ui-renderer [surfaceId]="surfaceId()!" [component]="child" />
+        }
       }
     </section>
   `,
diff --git a/renderers/angular/src/v0_8/components/list.ts b/renderers/angular/src/v0_8/components/list.ts
@@ -56,10 +56,12 @@ import { Renderer } from '../rendering/renderer';
   `,
   template: `
     <section [class]="theme.components.List" [style]="theme.additionalStyles?.List">
-      @for (child of children() ?? component().properties.children; track child) {
-        <div class="a2ui-list-item">
-          <ng-container a2ui-renderer [surfaceId]="surfaceId()!" [component]="child" />
-        </div>
+      @for (child of children() ?? component().properties.children; track child?.id ?? child) {
+        @if (child) {
+          <div class="a2ui-list-item">
+            <ng-container a2ui-renderer [surfaceId]="surfaceId()!" [component]="child" />
+          </div>
+        }
       }
     </section>
   `,
diff --git a/renderers/angular/src/v0_8/components/modal.ts b/renderers/angular/src/v0_8/components/modal.ts
@@ -24,13 +24,25 @@ import { Types } from '../types';
   imports: [Renderer],
   template: `
     <div class="a2ui-modal-entry-point" (click)="openModal()">
-      <ng-container a2ui-renderer [surfaceId]="surfaceId()!" [component]="entryPointChild()" />
+      @if (entryPointChild()) {
+        <ng-container
+          a2ui-renderer
+          [surfaceId]="surfaceId()!"
+          [component]="entryPointChild()!"
+        />
+      }
     </div>
 
     @if (isOpen()) {
       <div [class]="theme.components.Modal.backdrop" (click)="closeModal()">
         <div [class]="theme.components.Modal.element" (click)="$event.stopPropagation()">
-          <ng-container a2ui-renderer [surfaceId]="surfaceId()!" [component]="contentChild()" />
+          @if (contentChild()) {
+            <ng-container
+              a2ui-renderer
+              [surfaceId]="surfaceId()!"
+              [component]="contentChild()!"
+            />
+          }
         </div>
       </div>
     }
diff --git a/renderers/angular/src/v0_8/components/multiple-choice.ts b/renderers/angular/src/v0_8/components/multiple-choice.ts
@@ -31,7 +31,7 @@ import { Types } from '../types';
       <select
         [class]="theme.components.MultipleChoice.element"
         [id]="selectId"
-        [value]="resolvedSelections()[0] ?? ''"
+        [value]="resolvedSelections()[0] || ''"
         (change)="onChange($event)"
       >
         @for (option of resolvedOptions(); track option.value) {
diff --git a/renderers/angular/src/v0_8/components/row.ts b/renderers/angular/src/v0_8/components/row.ts
@@ -83,8 +83,10 @@ import { Types } from '../types';
   `,
   template: `
     <section [class]="classes()" [style]="theme.additionalStyles?.Row">
-      @for (child of children() ?? component().properties.children; track child) {
-        <ng-container a2ui-renderer [surfaceId]="surfaceId()!" [component]="child" />
+      @for (child of children() ?? component().properties.children; track child?.id ?? child) {
+        @if (child) {
+          <ng-container a2ui-renderer [surfaceId]="surfaceId()!" [component]="child" />
+        }
       }
     </section>
   `,
diff --git a/renderers/angular/src/v0_8/components/text.ts b/renderers/angular/src/v0_8/components/text.ts
@@ -77,7 +77,7 @@ export class Text extends DynamicComponent<Types.TextNode> {
     let value = super.resolvePrimitive(this.text());
 
     if (value == null) {
-      return Promise.resolve('(empty)');
+      return Promise.resolve('');
     }
 
     switch (usageHint) {
diff --git a/renderers/angular/src/v0_8/data/processor.ts b/renderers/angular/src/v0_8/data/processor.ts
@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { Injectable } from '@angular/core';
+import { Injectable, signal } from '@angular/core';
 import { Subject, Observable } from 'rxjs';
 import * as WebCore from '@a2ui/web_core/v0_8';
 
@@ -35,13 +35,28 @@ export class MessageProcessor {
 
   private readonly eventsSubject = new Subject<A2UIClientEvent>();
   readonly events: Observable<A2UIClientEvent> = this.eventsSubject.asObservable();
+  readonly surfacesSignal = signal<ReadonlyMap<string, WebCore.Surface>>(new Map());
 
   constructor() {
     this.baseProcessor = new WebCore.A2uiMessageProcessor();
   }
 
+  private notify() {
+    // Angular signals (and change detection) are based on reference equality for
+    // objects. During streaming, the base MessageProcessor updates surfaces in-place.
+    // By shallow-cloning the surface objects into a new Map, we ensure that
+    // anything watching surfacesSignal() correctly detects that the data has
+    // changed, even if only internal properties of a surface were updated.
+    const clonedSurfaces = new Map<string, WebCore.Surface>();
+    for (const [id, surface] of this.getSurfaces()) {
+      clonedSurfaces.set(id, { ...surface });
+    }
+    this.surfacesSignal.set(clonedSurfaces);
+  }
+
   processMessages(messages: Types.ServerToClientMessage[]) {
     this.baseProcessor.processMessages(messages as WebCore.ServerToClientMessage[]);
+    this.notify();
   }
 
   dispatch(message: Types.A2UIClientEventMessage): Promise<Types.ServerToClientMessage[]> {
@@ -67,6 +82,7 @@ export class MessageProcessor {
 
   setData(node: Types.AnyComponentNode | null, path: string, value: any, surfaceId: string) {
     this.baseProcessor.setData(node as WebCore.AnyComponentNode | null, path, value, surfaceId);
+    this.notify();
   }
 
   resolvePath(path: string, dataContextPath?: string): string {
diff --git a/samples/client/angular/README.md b/samples/client/angular/README.md
@@ -41,6 +41,15 @@ Here are the instructions if you want to do each step manually.
   * `npm start -- gallery` (Client-only, no server required)
 5. Open http://localhost:4200/
 
+## Streaming
+
+By default, the Angular client uses the non-streaming API to communicate with the agent. To enable streaming, set the `ENABLE_STREAMING` environment variable to `true`:
+
+```bash
+export ENABLE_STREAMING=true
+npm start -- contact
+```
+
 Important: The sample code provided is for demonstration purposes and illustrates the mechanics of A2UI and the Agent-to-Agent (A2A) protocol. When building production applications, it is critical to treat any agent operating outside of your direct control as a potentially untrusted entity.
 
 All operational data received from an external agent—including its AgentCard, messages, artifacts, and task statuses—should be handled as untrusted input. For example, a malicious agent could provide crafted data in its fields (e.g., name, skills.description) that, if used without sanitization to construct prompts for a Large Language Model (LLM), could expose your application to prompt injection attacks.
diff --git a/samples/client/angular/projects/contact/src/app/app.css b/samples/client/angular/projects/contact/src/app/app.css
@@ -100,6 +100,23 @@ h1 {
   }
 }
 
+.rendering-indicator {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 16px;
+  color: var(--p-40);
+  font-size: 14px;
+  border-top: 1px solid var(--n-90);
+  margin-top: 16px;
+  margin-top: 16px;
+
+  & .g-icon {
+    margin-right: 8px;
+    font-size: 16px;
+  }
+}
+
 .g-icon {
   font-family: "Google Symbols";
   font-weight: normal;
diff --git a/samples/client/angular/projects/contact/src/app/app.html b/samples/client/angular/projects/contact/src/app/app.html
@@ -14,37 +14,29 @@
  limitations under the License.
 -->
 
-@if (client.isLoading()) {
-  <div class="pending">
-    <span class="g-icon filled-heavy rotate">progress_activity</span>
-    Awaiting an answer...
-  </div>
-} @else if (!hasData()) {
+<div class="container">
+  @if (!hasData()) {
   <form (submit)="handleSubmit($event)">
     <h1>Contact Finder</h1>
     <div>
-      <input
-        required
-        value="Casey Smith"
-        autocomplete="off"
-        id="body"
-        name="body"
-        type="text"
-        [disabled]="client.isLoading()"
-      />
-
+      <input [value]="userInput()" (input)="userInput.set($any($event.target).value)"
+        placeholder="Search for a contact..." />
       <button type="submit" [disabled]="client.isLoading()">
         <span class="g-icon filled-heavy">send</span>
       </button>
     </div>
   </form>
-} @else {
+  } @else {
   <div class="surfaces">
-    @let surfaces = processor.getSurfaces();
-
-    @for (entry of surfaces; track $index) {
-      <a2ui-surface [surfaceId]="entry[0]" [surface]="entry[1]"/>
+    @if (statusText(); as text) {
+    <div [class]="surfaces().length === 0 ? 'pending' : 'rendering-indicator'">
+      <span class="g-icon filled-heavy rotate">progress_activity</span>
+      {{ text }}
+    </div>
+    }
+    @for (entry of surfaces(); track entry[0]) {
+    <a2ui-surface [surfaceId]="entry[0]" [surface]="entry[1]" />
     }
   </div>
-}
-
+  }
+</div>
diff --git a/samples/client/angular/projects/contact/src/app/app.ts b/samples/client/angular/projects/contact/src/app/app.ts
@@ -15,37 +15,45 @@
  */
 
 import { MessageProcessor, Surface } from '@a2ui/angular';
-import * as Types from '@a2ui/web_core/types/types';
-import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core';
+import { ChangeDetectionStrategy, Component, computed, inject, signal } from '@angular/core';
 import { Client } from './client';
 
 @Component({
   selector: 'app-root',
   templateUrl: './app.html',
   styleUrl: 'app.css',
   imports: [Surface],
-  changeDetection: ChangeDetectionStrategy.Eager,
+  changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class App {
   protected client = inject(Client);
   protected processor = inject(MessageProcessor);
 
   protected hasData = signal(false);
+  protected userInput = signal('Casey Smith');
+  protected surfaces = computed(() => {
+    return Array.from(this.processor.surfacesSignal().entries());
+  });
+
+  protected statusText = computed(() => {
+    if (!this.client.isLoading()) return null;
+    return this.surfaces().length === 0 ? 'Awaiting an answer...' : 'Rendering UI...';
+  });
 
   protected async handleSubmit(event: SubmitEvent) {
     event.preventDefault();
 
-    if (!(event.target instanceof HTMLFormElement)) {
-      return;
-    }
+    const message = this.userInput().trim();
+    if (!message) return;
 
-    const data = new FormData(event.target);
-    const body = data.get('body') ?? null;
+    this.hasData.set(true);
+    // Clear the input after submission
+    this.userInput.set('');
 
-    if (body) {
-      const message = body as Types.A2UIClientEventMessage;
+    try {
       await this.client.makeRequest(message);
-      this.hasData.set(true);
+    } catch (error) {
+      console.error('Error sending message:', error);
     }
   }
 }
diff --git a/samples/client/angular/projects/contact/src/app/client.ts b/samples/client/angular/projects/contact/src/app/client.ts
diff --git a/samples/client/angular/projects/contact/src/server.ts b/samples/client/angular/projects/contact/src/server.ts

Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,7 @@ import { Types } from '../types';`
`31`	`31`	`<select`
`32`	`32`	`[class]="theme.components.MultipleChoice.element"`
`33`	`33`	`[id]="selectId"`
`34`		`- [value]="resolvedSelections()[0] ?? ''"`
	`34`	`+ [value]="resolvedSelections()[0] \|\| ''"`
`35`	`35`	`(change)="onChange($event)"`
`36`	`36`	`>`
`37`	`37`	`@for (option of resolvedOptions(); track option.value) {`
Original file line number	Diff line number	Diff line change
`@@ -77,7 +77,7 @@ export class Text extends DynamicComponent<Types.TextNode> {`
`77`	`77`	`let value = super.resolvePrimitive(this.text());`
`78`	`78`
`79`	`79`	`if (value == null) {`
`80`		`- return Promise.resolve('(empty)');`
	`80`	`+ return Promise.resolve('');`
`81`	`81`	`}`
`82`	`82`
`83`	`83`	`switch (usageHint) {`