Skip to content

The Open Standard for Generative UI

16.1 KB
Raw Blame
import type { LibraryJSONSchema } from "@openuidev/lang-core";
import { describe, expect, it, vi } from "vitest";
import { A2UIFunctionError, createA2UIClient } from "../client";
import {
  applyDataModelUpdate,
  dataModelToOpenUIState,
  mergeOpenUIStateIntoDataModel,
} from "../json-pointer";
import type { RendererToAgentMessage } from "../types";

const schema: LibraryJSONSchema = {
  $defs: {
    Stack: {
      properties: { children: {} },
      required: ["children"],
    },
    TextContent: {
      properties: { text: {}, variant: {} },
      required: ["text"],
    },
  },
};

function createSurface(client: ReturnType<typeof createA2UIClient>) {
  return client.process({
    version: "v1.0",
    createSurface: {
      surfaceId: "main",
      catalogId: "com.example:openui",
      dataModel: { user: { name: "Alice" } },
    },
  });
}

describe("A2UIClient", () => {
  it("runs the A2UI surface lifecycle with incremental OpenUI Lang updates", async () => {
    const client = createA2UIClient({ schema });

    expect((await createSurface(client)).ok).toBe(true);
    expect(
      (
        await client.process({
          version: "v1.0",
          updateComponents: {
            surfaceId: "main",
            components: ["root = Stack([title])", 'title = TextContent("Hello")'],
          },
        })
      ).ok,
    ).toBe(true);

    let surface = client.getSurface("main");
    expect(surface?.parseResult?.root?.typeName).toBe("Stack");
    expect(surface?.parseResult?.root?.props.children).toEqual([
      expect.objectContaining({
        typeName: "TextContent",
        statementId: "title",
        props: { text: "Hello", variant: undefined },
      }),
    ]);

    await client.process({
      version: "v1.0",
      updateComponents: {
        surfaceId: "main",
        components: ['title = TextContent("Updated")'],
      },
    });
    expect(client.getSurface("main")?.source).toContain('title = TextContent("Updated")');
    expect(client.getSurface("main")?.source).not.toContain('TextContent("Hello")');

    await client.process({
      version: "v1.0",
      updateDataModel: { surfaceId: "main", path: "/user/name", value: "Bob" },
    });
    surface = client.getSurface("main");
    expect(surface?.dataModel).toEqual({ user: { name: "Bob" } });

    expect(
      (
        await client.process({
          version: "v1.0",
          deleteSurface: { surfaceId: "main" },
        })
      ).ok,
    ).toBe(true);
    expect(client.getSurface("main")).toBeUndefined();
  });

  it("supports single-message creation with Lang components and no catalogId", async () => {
    const client = createA2UIClient({ schema });
    const result = await client.process({
      version: "v1.0",
      createSurface: {
        surfaceId: "main",
        components: ["root = Stack([title])", 'title = TextContent("Created inline")'],
      },
    });

    expect(result.ok).toBe(true);
    expect(client.getSurface("main")?.catalogId).toBeUndefined();
    expect(client.getSurface("main")?.parseResult?.root?.props.children).toEqual([
      expect.objectContaining({ props: { text: "Created inline", variant: undefined } }),
    ]);
  });

  it("preserves components that are referenced by a later incremental update", async () => {
    const client = createA2UIClient({ schema });
    await createSurface(client);
    await client.process({
      version: "v1.0",
      updateComponents: {
        surfaceId: "main",
        components: ["root = Stack([a])", 'a = TextContent("A")'],
      },
    });
    await client.process({
      version: "v1.0",
      updateComponents: { surfaceId: "main", components: ['b = TextContent("B")'] },
    });
    const result = await client.process({
      version: "v1.0",
      updateComponents: { surfaceId: "main", components: ["root = Stack([a, b])"] },
    });

    expect(result.ok).toBe(true);
    expect(client.getSurface("main")?.source).toContain('b = TextContent("B")');
    expect(client.getSurface("main")?.parseResult?.root?.props.children).toEqual([
      expect.objectContaining({ statementId: "a" }),
      expect.objectContaining({ statementId: "b" }),
    ]);
  });

  it("merges multiline blocks and deletes statements by ID", async () => {
    const client = createA2UIClient({ schema });
    await createSurface(client);

    await client.process({
      version: "v1.0",
      updateComponents: {
        surfaceId: "main",
        components: [
          `root = Stack([
            title
          ])
          title = TextContent("Before")`,
        ],
      },
    });
    const result = await client.process({
      version: "v1.0",
      updateComponents: {
        surfaceId: "main",
        components: ["title = null", "root = Stack([])"],
      },
    });

    expect(result.ok).toBe(true);
    expect(client.getSurface("main")?.source).toBe("root = Stack([])");
  });

  it("validates malformed transport input without throwing or corrupting state", async () => {
    const client = createA2UIClient({ schema });
    await createSurface(client);

    const missingComponents = await client.process({
      version: "v1.0",
      updateComponents: { surfaceId: "main" },
    });
    expect(missingComponents.ok).toBe(false);
    expect(missingComponents.issues?.[0]?.path).toBe("/updateComponents/components");
    expect(missingComponents.outbound[0]).toMatchObject({
      error: {
        code: "VALIDATION_FAILED",
        surfaceId: "main",
        path: "/updateComponents/components",
      },
    });

    const missingSurfaceId = await client.process({
      version: "v1.0",
      createSurface: { catalogId: "com.example:openui" },
    });
    expect(missingSurfaceId.ok).toBe(false);
    expect(missingSurfaceId.issues?.length).toBeGreaterThan(0);
    expect(client.getSurfaces()).toHaveLength(1);

    const wrongVersion = await client.process({ version: "v0.9", unknown: {} });
    expect(wrongVersion).toMatchObject({ ok: false, outbound: [], issues: expect.any(Array) });
  });

  it("emits the current A2UI action shape", async () => {
    const messages: RendererToAgentMessage[] = [];
    const client = createA2UIClient({
      schema,
      onMessage: (message) => messages.push(message),
      now: () => new Date("2026-07-24T10:00:00.000Z"),
    });
    await createSurface(client);

    client.dispatchAction({
      surfaceId: "main",
      sourceComponentId: "submitButton",
      name: "submit",
      userMessage: "Save profile",
      context: { intent: "save" },
      metadata: { extensions: { trace_id: "trace-1" } },
    });

    expect(messages.at(-1)).toEqual({
      version: "v1.0",
      action: {
        name: "submit",
        userMessage: "Save profile",
        surfaceId: "main",
        sourceComponentId: "submitButton",
        timestamp: "2026-07-24T10:00:00.000Z",
        context: { intent: "save" },
        metadata: { extensions: { trace_id: "trace-1" } },
      },
    });
  });

  it("calls agent functions and resolves agentFunctionResponse", async () => {
    const messages: RendererToAgentMessage[] = [];
    const client = createA2UIClient({
      schema,
      createId: () => "agent-call-1",
      onMessage: (message) => messages.push(message),
    });
    await createSurface(client);
    const response = client.callAgentFunction({
      surfaceId: "main",
      call: "lookup",
      args: { id: 42 },
    });

    expect(messages.at(-1)).toEqual({
      version: "v1.0",
      callAgentFunction: {
        surfaceId: "main",
        functionCallId: "agent-call-1",
        callFunction: { call: "lookup", args: { id: 42 } },
      },
    });

    await client.process({
      version: "v1.0",
      agentFunctionResponse: {
        functionCallId: "agent-call-1",
        value: { found: true },
      },
    });

    await expect(response).resolves.toEqual({ found: true });
  });

  it("rejects agent function errors", async () => {
    const client = createA2UIClient({ schema, createId: () => "agent-call-2" });
    await createSurface(client);
    const response = client.callAgentFunction({ surfaceId: "main", call: "save" });

    await client.process({
      version: "v1.0",
      agentFunctionResponse: {
        functionCallId: "agent-call-2",
        error: { code: "REJECTED", message: "Nope" },
      },
    });

    await expect(response).rejects.toEqual(
      expect.objectContaining<A2UIFunctionError>({ code: "REJECTED", message: "Nope" }),
    );
  });

  it("executes callRendererFunction and returns rendererFunctionResponse", async () => {
    const lookup = vi.fn(async ({ id }: { id?: unknown }) => ({ id: String(id), found: true }));
    const client = createA2UIClient({
      schema,
      functions: {
        lookup: {
          catalogId: "com.example:functions",
          allowedCallers: "agentOnly",
          handler: lookup as never,
        },
      },
    });

    const result = await client.process({
      version: "v1.0",
      callRendererFunction: {
        functionCallId: "function-1",
        callFunction: {
          call: "lookup",
          catalogId: "com.example:functions",
          args: { id: 42 },
        },
      },
    });

    expect(lookup).toHaveBeenCalledWith({ id: 42 });
    expect(result).toEqual({
      ok: true,
      outbound: [
        {
          version: "v1.0",
          rendererFunctionResponse: {
            functionCallId: "function-1",
            value: { id: "42", found: true },
          },
        },
      ],
    });
  });

  it("enforces allowedCallers and catalog identity for agent-initiated function calls", async () => {
    const client = createA2UIClient({
      schema,
      functions: {
        localOnly: {
          catalogId: "com.example:functions",
          allowedCallers: "rendererOnly",
          handler: () => ({ ok: true }),
        },
      },
    });

    const result = await client.process({
      version: "v1.0",
      callRendererFunction: {
        functionCallId: "function-local",
        callFunction: { call: "localOnly", catalogId: "com.example:functions" },
      },
    });

    expect(result.ok).toBe(false);
    expect(result.outbound[0]).toMatchObject({
      error: {
        code: "INVALID_FUNCTION_CALL",
        functionCallId: "function-local",
      },
    });
  });

  it("maps OpenUI action context, form state, and source statement to A2UI", async () => {
    const messages: RendererToAgentMessage[] = [];
    const client = createA2UIClient({ schema, onMessage: (message) => messages.push(message) });
    await createSurface(client);

    client.dispatchOpenUIAction(
      "main",
      {
        type: "submit",
        params: { mode: "fast" },
        humanFriendlyMessage: "Submit",
        formState: { contact: { email: { value: "[email protected]", componentType: "Input" } } },
        formName: "contact",
      },
      { sourceComponentId: "submitButton" },
    );

    expect(messages.at(-1)).toMatchObject({
      action: {
        name: "submit",
        sourceComponentId: "submitButton",
        context: {
          mode: "fast",
          formState: { contact: { email: "[email protected]" } },
        },
      },
    });
  });

  it("keeps renderer data-model metadata in sync with local OpenUI state", async () => {
    const client = createA2UIClient({ schema });
    await client.process({
      version: "v1.0",
      createSurface: {
        surfaceId: "main",
        catalogId: "com.example:openui",
        sendDataModel: true,
        dataModel: { user: { name: "Alice" } },
      },
    });

    expect(
      client.updateSurfaceFromOpenUIState("main", {
        $user: { name: "Carol" },
        contact: { email: { value: "[email protected]", componentType: "Input" } },
      }),
    ).toBe(true);
    expect(client.getRendererDataModel()).toEqual({
      version: "v1.0",
      surfaces: {
        main: {
          user: { name: "Carol" },
          contact: { email: "[email protected]" },
        },
      },
    });
  });

  it("filters renderer metadata to opted-in surfaces and includes capabilities", async () => {
    const metadata: unknown[] = [];
    const client = createA2UIClient({
      schema,
      rendererCapabilities: {
        "v1.0": { supportedCatalogIds: ["com.example:openui"] },
      },
      onMessage: (_message, nextMetadata) => metadata.push(nextMetadata),
    });
    await client.process({
      version: "v1.0",
      createSurface: {
        surfaceId: "shared",
        catalogId: "com.example:openui",
        sendDataModel: true,
        dataModel: { shared: true },
      },
    });
    await client.process({
      version: "v1.0",
      createSurface: {
        surfaceId: "private",
        catalogId: "com.example:openui",
        dataModel: { private: true },
      },
    });

    client.dispatchAction({
      surfaceId: "shared",
      sourceComponentId: "button",
      name: "submit",
    });

    expect(metadata.at(-1)).toEqual({
      a2uiRendererCapabilities: {
        "v1.0": { supportedCatalogIds: ["com.example:openui"] },
      },
      a2uiRendererDataModel: {
        version: "v1.0",
        surfaces: { shared: { shared: true } },
      },
    });
  });

  it("rejects a catalog outside configured renderer capabilities", async () => {
    const client = createA2UIClient({
      schema,
      rendererCapabilities: {
        "v1.0": { supportedCatalogIds: ["com.example:supported"] },
      },
    });

    const result = await client.process({
      version: "v1.0",
      createSurface: { surfaceId: "main", catalogId: "com.example:unsupported" },
    });

    expect(result.ok).toBe(false);
    expect(result.outbound[0]).toMatchObject({
      error: { code: "UNSUPPORTED_CATALOG", surfaceId: "main" },
    });
  });
});

describe("A2UI data model bridge", () => {
  it("supports RFC 6901 escaping, arrays, deletion, and root replacement", () => {
    let model = applyDataModelUpdate({}, "/a~1b/~0key", ["first", "second"]);
    expect(model).toEqual({ "a/b": { "~key": ["first", "second"] } });

    model = applyDataModelUpdate(model, "/a~1b/~0key/0", null);
    expect(model).toEqual({ "a/b": { "~key": ["second"] } });

    model = applyDataModelUpdate(model, "/", { replaced: true });
    expect(model).toEqual({ replaced: true });
  });

  it("converts A2UI data-model keys to Lang bindings and unwraps form state", () => {
    expect(dataModelToOpenUIState({ user: { name: "Alice" } })).toEqual({
      $user: { name: "Alice" },
    });
    expect(dataModelToOpenUIState({ user: { name: "Alice" } }, ["user"])).toEqual({
      $user: { name: "Alice" },
      user: { name: "Alice" },
    });
    expect(
      mergeOpenUIStateIntoDataModel(
        { untouched: true },
        { form: { field: { value: "hello", componentType: "Input" } } },
      ),
    ).toEqual({ untouched: true, form: { field: "hello" } });
  });

  it("selects whichever binding or form copy changed from the current model", () => {
    expect(
      mergeOpenUIStateIntoDataModel(
        { contact: { email: "[email protected]" } },
        {
          $contact: { email: "[email protected]" },
          contact: { email: { value: "[email protected]", componentType: "Input" } },
        },
      ),
    ).toEqual({ contact: { email: "[email protected]" } });

    expect(
      mergeOpenUIStateIntoDataModel({ filter: "all" }, { $filter: "active", filter: "all" }),
    ).toEqual({ filter: "all" });

    expect(mergeOpenUIStateIntoDataModel({ filter: "all" }, { $filter: "active" })).toEqual({
      filter: "active",
    });
  });

  it("does not let a stale binding mirror revert a user-edited form", async () => {
    const client = createA2UIClient({ schema });
    await client.process({
      version: "v1.0",
      createSurface: {
        surfaceId: "main",
        dataModel: { contact: { email: "[email protected]" } },
      },
    });
    const state = {
      $contact: { email: "[email protected]" },
      contact: {
        email: { value: "[email protected]", componentType: "Input" },
      },
    };

    expect(client.updateSurfaceFromOpenUIState("main", state)).toBe(true);
    const revision = client.getSurface("main")?.revision;
    expect(client.getSurface("main")?.dataModel).toEqual({
      contact: { email: "[email protected]" },
    });

    expect(client.updateSurfaceFromOpenUIState("main", state)).toBe(false);
    expect(client.getSurface("main")?.revision).toBe(revision);
    expect(client.getSurface("main")?.dataModel).toEqual({
      contact: { email: "[email protected]" },
    });
  });
});