A2uiSurfaceComponent

Angular component that renders a single A2UI surface. It converts the surface's component map and data model into a json-render Spec, then delegates rendering to RenderSpecComponent.

Import:

import { A2uiSurfaceComponent } from '@threadplane/chat';

Selector: a2ui-surface

#Inputs

#Outputs

The events output forwards all RenderEvent emissions from the render engine. This includes events triggered by the default A2UI handlers (a2ui:event and a2ui:localAction) as well as any state change or lifecycle events. The action output is the agent-bound path: when a surface's event action fires, the component builds an A2uiActionMessage and emits it here so you can send it back to the agent.

#How It Works

A2uiSurfaceComponent bridges the A2UI surface model to the json-render engine in three steps:

1. Convert surface to Spec (surfaceToSpec)

The internal surface-to-spec conversion walks the flat component map and produces a json-render Spec. It uses a component with id: 'root' when present; otherwise it uses the first component in the map as the render root. Empty component maps render nothing.

2. Resolve dynamic values

Before the spec is emitted, each component prop is evaluated against the surface's data model. A prop can be:

• A literal value — passed through as-is
• A path reference { path: '/some/pointer' } — resolved via JSON Pointer against dataModel

3. Map actions to on bindings

The internal conversion maps each component's A2UI action prop into a render-spec on binding on the corresponding element. Actions map to the a2ui:event handler, which builds an A2uiActionMessage for the (action) output.

4. Expand template children

When a component's children field is an A2uiChildTemplate ({ template: { componentId, dataBinding } }), the surface component expands it over the array at the dataBinding JSON Pointer in the data model. Each array item gets its own cloned element with props resolved in that item's scope.

5. Render via RenderSpecComponent

The final Spec is passed to RenderSpecComponent along with the ViewRegistry (converted to an Angular registry via toRenderRegistry). Rendering is fully reactive — when the surface signal updates, the spec recomputes and only affected elements re-render.

#Usage Outside ChatComponent

A2uiSurfaceComponent is used internally by ChatComponent, but you can also use it directly to embed a surface in any Angular template.

import { Component, signal } from '@angular/core';
import { A2uiSurfaceComponent, createA2uiSurfaceStore, a2uiBasicCatalog } from '@threadplane/chat';
import { createA2uiMessageParser } from '@threadplane/a2ui';
 
@Component({
  selector: 'app-agent-panel',
  standalone: true,
  imports: [A2uiSurfaceComponent],
  template: `
    @if (store.surface('dashboard')() as surface) {
      <a2ui-surface [surface]="surface" [catalog]="catalog" />
    }
  `,
})
export class AgentPanelComponent {
  readonly catalog = a2uiBasicCatalog();
  readonly store = createA2uiSurfaceStore();
  private readonly parser = createA2uiMessageParser();
 
  receiveChunk(chunk: string): void {
    for (const msg of this.parser.push(chunk)) {
      this.store.apply(msg);
    }
  }
}

#Wiring handlers and actions

The example above renders a surface but ignores interaction. To run client-owned behavior and forward agent-bound events, pass [handlers] and bind (action) / (events). Consumer handlers run for a2ui:localAction; the (action) output carries the agent-bound A2uiActionMessage.

import { Component, inject, signal } from '@angular/core';
import { Router } from '@angular/router';
import { A2uiSurfaceComponent, a2uiBasicCatalog } from '@threadplane/chat';
import { injectAgent } from '@threadplane/langgraph';
import type { A2uiActionMessage, A2uiSurface } from '@threadplane/chat';
import type { RenderEvent } from '@threadplane/render';
 
@Component({
  selector: 'app-interactive-surface',
  standalone: true,
  imports: [A2uiSurfaceComponent],
  template: `
    <a2ui-surface
      [surface]="surface()"
      [catalog]="catalog"
      [handlers]="handlers"
      (action)="sendToAgent($event)"
      (events)="onEvent($event)"
    />
  `,
})
export class InteractiveSurfaceComponent {
  private readonly router = inject(Router);
  private readonly agent = injectAgent();
 
  readonly catalog = a2uiBasicCatalog();
  readonly surface = signal<A2uiSurface | undefined>(undefined);
 
  // Client-owned local actions (a2ui:localAction).
  readonly handlers = {
    openDetails: async (args: Record<string, unknown>) => {
      await this.router.navigate(['/orders', args['orderId']]);
    },
  };
 
  // Agent-bound action: forward it back to the agent loop.
  sendToAgent(message: A2uiActionMessage) {
    this.agent.submit({ resume: message });
  }
 
  onEvent(event: RenderEvent) {
    console.log('render event', event);
  }
}

#Internal conversion

A2uiSurfaceComponent handles surface-to-spec conversion internally when it receives a legacy surface input. That conversion returns no rendered output for an empty component map. Otherwise it produces a complete json-render Spec, preferring a root component when present and falling back to the first component ID.

The conversion helper is not part of the public @threadplane/chat API. Use A2uiSurfaceComponent or createA2uiSurfaceStore() for supported integration points.

#What's Next