@assistant-ui/react-generative-ui 0.0.20 → 0.0.22

package/src/vocabulary/interactive.dom.test.tsx

@@ -0,0 +1,1699 @@
+// @vitest-environment jsdom
+
+import { act, useState } from "react";
+import { createRoot, hydrateRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { convertSurfaceToUISpec } from "../a2ui/convert";
+import { A2uiBindingContext } from "../a2ui/BindingContext";
+import { applyA2uiOperations } from "../a2ui/reducer";
+import { A2uiPresentRenderer } from "../a2ui/PresentRenderer";
+import { createActionRegistry, type ActionHandler } from "../actionRegistry";
+import { AnsweredValuesProvider } from "../answeredValues";
+import type { GenerativeUIDispatch, GenerativeUILibrary } from "../types";
+import { renderGenerativeUI } from "../renderGenerativeUI";
+import { defaultGenerativeUILibrary } from "./index";
+
+(
+  globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const toppings = [
+  { label: "Basil", value: "basil" },
+  { label: "Olives", value: "olives" },
+  { label: "Onion", value: "onion" },
+];
+
+let root: Root | undefined;
+
+afterEach(async () => {
+  await act(async () => root?.unmount());
+  root = undefined;
+  document.body.innerHTML = "";
+  vi.useRealTimers();
+});
+
+const view = (node: unknown, dispatch?: GenerativeUIDispatch) => (
+  <div data-aui="root">
+    {renderGenerativeUI(node, defaultGenerativeUILibrary, {
+      status: "done",
+      ...(dispatch ? { dispatch } : {}),
+    })}
+  </div>
+);
+
+const mount = async (
+  node: unknown,
+  handlers: Readonly<Record<string, ActionHandler>>,
+  parent: HTMLElement = document.body,
+) => {
+  const container = document.createElement("div");
+  parent.append(container);
+  const registry = createActionRegistry(handlers);
+  root = createRoot(container);
+  await act(async () => {
+    root!.render(view(node, registry.dispatch));
+  });
+  return container;
+};
+
+describe("Input", () => {
+  it("keeps password and number single-line when multiline is set", async () => {
+    const container = await mount(
+      [
+        {
+          $type: "Input",
+          name: "password",
+          inputType: "password",
+          multiline: true,
+        },
+        {
+          $type: "Input",
+          name: "number",
+          inputType: "number",
+          multiline: true,
+        },
+        { $type: "Input", name: "text", inputType: "text", multiline: true },
+        { $type: "Input", name: "default", multiline: true },
+      ],
+      {},
+    );
+
+    expect(
+      Array.from(container.querySelectorAll("input, textarea")).map(
+        (control) =>
+          control instanceof HTMLInputElement
+            ? control.type
+            : control.tagName.toLowerCase(),
+      ),
+    ).toEqual(["password", "number", "textarea", "textarea"]);
+  });
+});
+
+describe("RadioGroup", () => {
+  it("keeps repeated logical fields exclusive within one root without a form", async () => {
+    const save = vi.fn();
+    const container = await mount(
+      {
+        $type: "Col",
+        children: [
+          { $type: "RadioGroup", name: "choice", options: toppings },
+          { $type: "RadioGroup", name: "choice", options: toppings },
+          {
+            $type: "Button",
+            label: "Save",
+            $action: { type: "save", choice: { $field: "choice" } },
+          },
+        ],
+      },
+      { save },
+    );
+    const inputs = container.querySelectorAll("input");
+    await act(async () => inputs[4]!.click());
+    await act(async () => inputs[0]!.click());
+    await act(async () => container.querySelector("button")!.click());
+
+    expect(inputs[4]!.checked).toBe(false);
+    expect(save).toHaveBeenCalledWith({
+      payload: { type: "save", choice: "basil" },
+    });
+  });
+
+  it.each(["Form", "Card"])(
+    "keeps repeated logical names mutually exclusive inside a %s form",
+    async ($type) => {
+      const save = vi.fn();
+      const container = await mount(
+        {
+          $type,
+          ...($type === "Form"
+            ? { $action: { type: "save" } }
+            : {
+                asForm: true,
+                confirm: { label: "Save", $action: { type: "save" } },
+              }),
+          children: [
+            { $type: "RadioGroup", name: "choice", options: toppings },
+            {
+              $type: "Card",
+              children: {
+                $type: "RadioGroup",
+                name: "choice",
+                options: toppings,
+              },
+            },
+            ...($type === "Form"
+              ? [{ $type: "Button", label: "Save", submit: true }]
+              : []),
+          ],
+        },
+        { save },
+      );
+      const inputs = container.querySelectorAll("input");
+      await act(async () => inputs[4]!.click());
+      await act(async () => inputs[0]!.click());
+      await act(async () => container.querySelector("button")!.click());
+
+      expect(inputs[4]!.checked).toBe(false);
+      expect(save).toHaveBeenCalledWith({
+        payload: { type: "save", $input: { choice: "basil" } },
+      });
+    },
+  );
+
+  it("preserves independent selections across separately rendered and hydrated roots", async () => {
+    const save = vi.fn();
+    const registry = createActionRegistry({ save });
+    const tree = view(
+      {
+        $type: "Col",
+        children: [
+          { $type: "RadioGroup", name: "choice", options: toppings },
+          {
+            $type: "Button",
+            label: "Save",
+            $action: { type: "save", choice: { $field: "choice" } },
+          },
+        ],
+      },
+      registry.dispatch,
+    );
+    const containers = ["first-", "second-"].map((identifierPrefix) => {
+      const container = document.createElement("div");
+      container.innerHTML = renderToString(tree, { identifierPrefix });
+      document.body.append(container);
+      return { container, identifierPrefix };
+    });
+    const hydratedRoots: Root[] = [];
+    const onRecoverableError = vi.fn();
+    try {
+      await act(async () => {
+        for (const { container, identifierPrefix } of containers) {
+          hydratedRoots.push(
+            hydrateRoot(container, tree, {
+              identifierPrefix,
+              onRecoverableError,
+            }),
+          );
+        }
+      });
+      for (const [index, { container }] of containers.entries()) {
+        await act(async () =>
+          container.querySelectorAll("input")[index]!.click(),
+        );
+      }
+      for (const { container } of containers) {
+        await act(async () => container.querySelector("button")!.click());
+      }
+
+      expect(save.mock.calls.map(([{ payload }]) => payload)).toEqual([
+        { type: "save", choice: "basil" },
+        { type: "save", choice: "olives" },
+      ]);
+      expect(onRecoverableError).not.toHaveBeenCalled();
+    } finally {
+      await act(async () => hydratedRoots.forEach((item) => item.unmount()));
+    }
+  });
+
+  it("keeps same-named groups in separate roots independent and resolves their field values", async () => {
+    const save = vi.fn();
+    const registry = createActionRegistry({ save });
+    const container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+    const card = (id: string) => ({
+      $type: "Col",
+      children: [
+        { $type: "RadioGroup", name: "choice", options: toppings },
+        {
+          $type: "Button",
+          label: "Save",
+          $action: { type: "save", id, choice: { $field: "choice" } },
+        },
+      ],
+    });
+    await act(async () => {
+      root!.render(
+        <>
+          {view(card("first"), registry.dispatch)}
+          {view(card("second"), registry.dispatch)}
+        </>,
+      );
+    });
+    const inputs = container.querySelectorAll("input");
+    const [firstSave, secondSave] = container.querySelectorAll("button");
+
+    await act(async () => inputs[0]!.click());
+    await act(async () => inputs[4]!.click());
+    await act(async () => firstSave!.click());
+    await act(async () => secondSave!.click());
+
+    expect(save.mock.calls.map(([{ payload }]) => payload)).toEqual([
+      { type: "save", id: "first", choice: "basil" },
+      { type: "save", id: "second", choice: "olives" },
+    ]);
+    expect(inputs[0]!.checked).toBe(true);
+    expect(inputs[4]!.checked).toBe(true);
+
+    await act(async () => inputs[2]!.click());
+    expect(inputs[0]!.checked).toBe(false);
+    expect(inputs[2]!.checked).toBe(true);
+    expect(inputs[4]!.checked).toBe(true);
+  });
+
+  it("submits logical field names and omits unnamed groups", async () => {
+    const save = vi.fn();
+    const container = await mount(
+      {
+        $type: "Form",
+        $action: { type: "save" },
+        children: [
+          { $type: "RadioGroup", name: "choice", options: toppings },
+          { $type: "RadioGroup", options: toppings },
+          { $type: "Button", label: "Save", submit: true },
+        ],
+      },
+      { save },
+    );
+    const inputs = container.querySelectorAll("input");
+    await act(async () => inputs[0]!.click());
+    await act(async () => inputs[4]!.click());
+    await act(async () => container.querySelector("button")!.click());
+
+    expect(save).toHaveBeenCalledWith({
+      payload: { type: "save", $input: { choice: "basil" } },
+    });
+  });
+});
+
+describe("option identity", () => {
+  it.each(["CheckboxGroup", "RadioGroup", "Select"])(
+    "%s preserves the submitted choice when options move or their labels change",
+    async (type) => {
+      const save = vi.fn();
+      const registry = createActionRegistry({ save });
+      const form = (options: typeof toppings) => ({
+        $type: "Form",
+        $action: { type: "save" },
+        children: [
+          { $type: type, name: "choice", options },
+          { $type: "Button", label: "Save", submit: true },
+        ],
+      });
+      const container = await mount(form(toppings), { save });
+      if (type === "Select") {
+        container.querySelector("select")!.value = "olives";
+      } else {
+        await act(async () => container.querySelectorAll("input")[1]!.click());
+      }
+      await act(async () => container.querySelector("button")!.click());
+
+      await act(async () => {
+        root!.render(
+          view(
+            form([
+              { label: "Pepper", value: "pepper" },
+              ...[...toppings].reverse().map((option) => ({
+                ...option,
+                label: option.label.toUpperCase(),
+              })),
+            ]),
+            registry.dispatch,
+          ),
+        );
+      });
+      await act(async () => container.querySelector("button")!.click());
+
+      const payload = {
+        type: "save",
+        $input: { choice: type === "CheckboxGroup" ? ["olives"] : "olives" },
+      };
+      expect(save.mock.calls.map(([call]) => call.payload)).toEqual([
+        payload,
+        payload,
+      ]);
+    },
+  );
+
+  it.each(["CheckboxGroup", "RadioGroup", "Select"])(
+    "%s retains duplicate-valued options without duplicate React keys",
+    async (type) => {
+      const errors = vi.spyOn(console, "error").mockImplementation(() => {});
+      try {
+        const container = await mount(
+          {
+            $type: type,
+            options: [
+              { label: "First", value: "same" },
+              { label: "Second", value: "same" },
+              { label: "Third", value: "same:1" },
+            ],
+          },
+          {},
+        );
+        expect(container.querySelectorAll("input, option")).toHaveLength(3);
+        expect(errors).not.toHaveBeenCalled();
+      } finally {
+        errors.mockRestore();
+      }
+    },
+  );
+});
+
+describe("CheckboxGroup", () => {
+  it("dispatches its checked option values in option order on every change", async () => {
+    const pick = vi.fn();
+    const container = await mount(
+      {
+        $type: "CheckboxGroup",
+        options: toppings,
+        defaultValue: ["onion"],
+        $action: { type: "pick" },
+        children: { $type: "Checkbox", label: "Extra cheese" },
+      },
+      { pick },
+    );
+    const [basil, , onion, cheese] = container.querySelectorAll("input");
+
+    await act(async () => basil!.click());
+    await act(async () => cheese!.click());
+    await act(async () => onion!.click());
+
+    expect(pick.mock.calls.map(([{ payload }]) => payload)).toEqual([
+      { type: "pick", $input: ["basil", "onion"] },
+      { type: "pick", $input: ["basil"] },
+    ]);
+  });
+
+  it("renders a converted A2UI multipleSelection ChoicePicker with its bound values checked", async () => {
+    const { state } = applyA2uiOperations(new Map(), [
+      { version: "v0.9", createSurface: { surfaceId: "s" } },
+      {
+        version: "v0.9",
+        updateComponents: {
+          surfaceId: "s",
+          components: [
+            {
+              id: "root",
+              component: "ChoicePicker",
+              variant: "multipleSelection",
+              options: toppings,
+              value: { path: "/picked" },
+            },
+          ],
+        },
+      },
+      {
+        version: "v0.9",
+        updateDataModel: {
+          surfaceId: "s",
+          path: "/",
+          value: { picked: ["basil", "onion"] },
+        },
+      },
+    ]);
+    const container = await mount(
+      convertSurfaceToUISpec(state.get("s")!).spec,
+      {},
+    );
+
+    expect(
+      [...container.querySelectorAll("input")].map((input) => input.checked),
+    ).toEqual([true, false, true]);
+  });
+
+  it("submits each group in a Form as its checked values keyed by name", async () => {
+    const submit = vi.fn();
+    const container = await mount(
+      {
+        $type: "Form",
+        $action: { type: "submit" },
+        children: [
+          {
+            $type: "CheckboxGroup",
+            name: "toppings",
+            options: toppings,
+            defaultValue: ["olives"],
+          },
+          {
+            $type: "CheckboxGroup",
+            name: "sides",
+            options: [{ label: "Fries", value: "fries" }],
+          },
+          { $type: "Button", label: "Order", submit: true },
+        ],
+      },
+      { submit },
+    );
+
+    await act(async () => container.querySelector("input")!.click());
+    await act(async () => container.querySelector("button")!.click());
+
+    expect(submit).toHaveBeenCalledWith({
+      payload: {
+        type: "submit",
+        $input: { toppings: ["basil", "olives"], sides: [] },
+      },
+    });
+  });
+});
+
+describe("Button undo window", () => {
+  it("keeps counting down while a bound input changes and dispatches its latest value", async () => {
+    vi.useFakeTimers();
+    const save = vi.fn();
+    const container = document.createElement("div");
+    document.body.append(container);
+    const registry = createActionRegistry({ save });
+    const BindingContext = A2uiBindingContext!;
+    const Surface = () => {
+      const [name, setName] = useState("Initial");
+      return (
+        <BindingContext.Provider
+          value={{
+            fields: new Map([["/name", { value: name, arrayValue: false }]]),
+            update: (_path, value) => setName(String(value)),
+          }}
+        >
+          <div data-aui="root">
+            {renderGenerativeUI(
+              [
+                { $type: "Input", name: "/name", value: name },
+                {
+                  $type: "Button",
+                  label: "Save",
+                  undoable: true,
+                  $action: { type: "save", name: { $field: "/name" } },
+                },
+              ],
+              defaultGenerativeUILibrary,
+              { status: "done", dispatch: registry.dispatch },
+            )}
+          </div>
+        </BindingContext.Provider>
+      );
+    };
+    root = createRoot(container);
+    await act(async () => root!.render(<Surface />));
+    const button = container.querySelector<HTMLButtonElement>("button")!;
+    const input = container.querySelector<HTMLInputElement>("input")!;
+    await act(async () => button.click());
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500);
+    });
+    await act(async () => {
+      Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        "value",
+      )!.set!.call(input, "Edited");
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500);
+    });
+    expect(button.textContent).toContain("Undo 4");
+    for (let seconds = 0; seconds < 4; seconds++) {
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(1_000);
+      });
+    }
+    expect(save).toHaveBeenCalledWith({
+      payload: { type: "save", name: "Edited" },
+    });
+  });
+
+  it("counts down for five seconds before firing once", async () => {
+    vi.useFakeTimers();
+    const purchase = vi.fn();
+    const container = await mount(
+      {
+        $type: "Button",
+        label: "Purchase",
+        undoable: true,
+        $action: { type: "purchase" },
+      },
+      { purchase },
+    );
+    const button = container.querySelector<HTMLButtonElement>("button")!;
+
+    await act(async () => button.click());
+
+    expect(button.dataset.auiState).toBe("pending");
+    expect(button.textContent).toContain("Undo 5");
+    expect(button.getAttribute("aria-label")).toBe("Undo Purchase");
+    expect(container.querySelector('[role="status"]')?.textContent).toBe(
+      "Purchase in 5 seconds",
+    );
+    expect(purchase).not.toHaveBeenCalled();
+
+    for (const seconds of [4, 3, 2, 1]) {
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(1_000);
+      });
+      expect(button.textContent).toContain(`Undo ${seconds}`);
+      expect(purchase).not.toHaveBeenCalled();
+    }
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1_000);
+    });
+
+    expect(purchase).toHaveBeenCalledTimes(1);
+    expect(purchase).toHaveBeenCalledWith({ payload: { type: "purchase" } });
+    expect(button.dataset.auiState).toBeUndefined();
+    expect(button.textContent).toBe("Purchase");
+  });
+
+  it("keeps the generic undo label when its text label is empty", async () => {
+    vi.useFakeTimers();
+    const remove = vi.fn();
+    const container = await mount(
+      {
+        $type: "Button",
+        label: "",
+        undoable: true,
+        $action: { type: "remove" },
+      },
+      { remove },
+    );
+    const button = container.querySelector<HTMLButtonElement>("button")!;
+
+    await act(async () => button.click());
+
+    expect(button.getAttribute("aria-label")).toBe("Undo");
+  });
+
+  it("cancels when clicked again", async () => {
+    vi.useFakeTimers();
+    const send = vi.fn();
+    const container = await mount(
+      {
+        $type: "Button",
+        label: "Send",
+        undoable: true,
+        $action: { type: "send" },
+      },
+      { send },
+    );
+    const button = container.querySelector<HTMLButtonElement>("button")!;
+
+    await act(async () => button.click());
+    await act(async () => button.click());
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5_000);
+    });
+
+    expect(send).not.toHaveBeenCalled();
+    expect(button.dataset.auiState).toBeUndefined();
+    expect(button.textContent).toBe("Send");
+  });
+
+  it("cancels when Escape is pressed while focused", async () => {
+    vi.useFakeTimers();
+    const remove = vi.fn();
+    const container = await mount(
+      {
+        $type: "Button",
+        label: "Delete",
+        undoable: true,
+        $action: { type: "remove" },
+      },
+      { remove },
+    );
+    const button = container.querySelector<HTMLButtonElement>("button")!;
+
+    await act(async () => button.click());
+    button.focus();
+    await act(async () => {
+      button.dispatchEvent(
+        new KeyboardEvent("keydown", { bubbles: true, key: "Escape" }),
+      );
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5_000);
+    });
+
+    expect(remove).not.toHaveBeenCalled();
+    expect(button.dataset.auiState).toBeUndefined();
+    expect(button.textContent).toBe("Delete");
+  });
+
+  it("clears the timer on unmount", async () => {
+    vi.useFakeTimers();
+    const purchase = vi.fn();
+    const container = await mount(
+      {
+        $type: "Button",
+        label: "Purchase",
+        undoable: true,
+        $action: { type: "purchase" },
+      },
+      { purchase },
+    );
+
+    await act(async () => container.querySelector("button")!.click());
+    await act(async () => root!.unmount());
+    root = undefined;
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5_000);
+    });
+
+    expect(purchase).not.toHaveBeenCalled();
+  });
+
+  it("leaves an undoable button without a dispatcher unchanged", async () => {
+    vi.useFakeTimers();
+    const container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+    await act(async () => {
+      root!.render(
+        view({
+          $type: "Button",
+          label: "Purchase",
+          undoable: true,
+          $action: { type: "purchase" },
+        }),
+      );
+    });
+    const button = container.querySelector<HTMLButtonElement>("button")!;
+
+    await act(async () => button.click());
+
+    expect(button.dataset.auiState).toBeUndefined();
+    expect(button.textContent).toBe("Purchase");
+  });
+});
+
+describe("Slider", () => {
+  it("renders a labelled range with its current value and unit", async () => {
+    const container = await mount(
+      {
+        $type: "Slider",
+        name: "volume",
+        label: "Volume",
+        min: 0,
+        max: 10,
+        defaultValue: 4,
+        unit: "%",
+      },
+      {},
+    );
+    const slider = container.querySelector<HTMLInputElement>(
+      '[data-aui="slider"]',
+    )!;
+
+    expect(slider.type).toBe("range");
+    expect(slider.getAttribute("aria-valuetext")).toBe("4 %");
+    expect(
+      container.querySelector('[data-aui="slider-value"]')?.textContent,
+    ).toBe("4 %");
+  });
+
+  it("normalizes malformed range props before rendering", () => {
+    function Slider() {
+      return defaultGenerativeUILibrary.Slider!.render({
+        $status: "done",
+        min: Number.NaN,
+        max: Number.POSITIVE_INFINITY,
+        step: Number.NEGATIVE_INFINITY,
+        defaultValue: Number.NaN,
+      });
+    }
+
+    const markup = renderToString(<Slider />);
+
+    expect(markup).toContain('min="0"');
+    expect(markup).toContain('max="100"');
+    expect(markup).toContain('step="1"');
+    expect(markup).toContain('value="0"');
+  });
+
+  it("fires once with a number for a committed adjustment", async () => {
+    const setVolume = vi.fn();
+    const container = await mount(
+      {
+        $type: "Slider",
+        name: "volume",
+        min: 0,
+        max: 10,
+        $action: { type: "set_volume" },
+      },
+      { set_volume: setVolume },
+    );
+    const slider = container.querySelector<HTMLInputElement>(
+      '[data-aui="slider"]',
+    )!;
+
+    await act(async () => {
+      slider.dispatchEvent(new Event("pointerdown", { bubbles: true }));
+      slider.value = "7";
+      slider.dispatchEvent(new Event("input", { bubbles: true }));
+      slider.dispatchEvent(new Event("change", { bubbles: true }));
+      slider.dispatchEvent(new Event("pointerup", { bubbles: true }));
+      slider.dispatchEvent(new Event("change", { bubbles: true }));
+    });
+
+    expect(setVolume).toHaveBeenCalledTimes(1);
+    expect(setVolume).toHaveBeenCalledWith({
+      payload: { type: "set_volume", $input: 7 },
+    });
+  });
+
+  it("does not dispatch when a pointer interaction keeps the initial value", async () => {
+    const setVolume = vi.fn();
+    const container = await mount(
+      {
+        $type: "Slider",
+        min: 0,
+        max: 10,
+        defaultValue: 4,
+        $action: { type: "set_volume" },
+      },
+      { set_volume: setVolume },
+    );
+    const slider = container.querySelector<HTMLInputElement>(
+      '[data-aui="slider"]',
+    )!;
+
+    await act(async () => {
+      slider.dispatchEvent(new Event("pointerdown", { bubbles: true }));
+      slider.dispatchEvent(new Event("pointerup", { bubbles: true }));
+    });
+
+    expect(setVolume).not.toHaveBeenCalled();
+  });
+
+  it("collects as a number in a Form", async () => {
+    const submit = vi.fn();
+    const container = await mount(
+      {
+        $type: "Form",
+        $action: { type: "submit" },
+        children: [
+          {
+            $type: "Slider",
+            name: "volume",
+            min: 0,
+            max: 10,
+            defaultValue: 3,
+          },
+          { $type: "Button", label: "Save", submit: true },
+        ],
+      },
+      { submit },
+    );
+
+    await act(async () => container.querySelector("button")!.click());
+
+    expect(submit).toHaveBeenCalledWith({
+      payload: { type: "submit", $input: { volume: 3 } },
+    });
+  });
+
+  it("restores an answered numeric value", () => {
+    function Slider() {
+      return defaultGenerativeUILibrary.Slider!.render({
+        $status: "done",
+        name: "volume",
+        min: 0,
+        max: 10,
+        defaultValue: 3,
+      });
+    }
+
+    const markup = renderToString(
+      <AnsweredValuesProvider values={{ volume: 7 }}>
+        <Slider />
+      </AnsweredValuesProvider>,
+    );
+
+    expect(markup).toContain('value="7"');
+  });
+});
+
+describe("Checkbox and option descriptions", () => {
+  it("renders a switch role and preserves its boolean form value", async () => {
+    const submit = vi.fn();
+    const container = await mount(
+      {
+        $type: "Form",
+        $action: { type: "submit" },
+        children: [
+          {
+            $type: "Checkbox",
+            name: "enabled",
+            label: "Enabled",
+            variant: "switch",
+            defaultChecked: true,
+          },
+          { $type: "Button", label: "Save", submit: true },
+        ],
+      },
+      { submit },
+    );
+
+    expect(container.querySelector('input[role="switch"]')).not.toBeNull();
+    await act(async () => container.querySelector("button")!.click());
+    expect(submit).toHaveBeenCalledWith({
+      payload: { type: "submit", $input: { enabled: true } },
+    });
+  });
+
+  it.each(["RadioGroup", "CheckboxGroup"])(
+    "renders an option description for %s",
+    async ($type) => {
+      const container = await mount(
+        {
+          $type,
+          options: [
+            {
+              label: "Free",
+              description: "For personal projects",
+              value: "free",
+            },
+          ],
+        },
+        {},
+      );
+
+      expect(
+        container.querySelector('[data-aui="option-description"]')?.textContent,
+      ).toBe("For personal projects");
+    },
+  );
+});
+
+describe("$field references", () => {
+  it("resolve from the enclosing form, or else the generative UI root, at the moment the action fires", async () => {
+    const save = vi.fn();
+    const container = await mount(
+      {
+        $type: "Col",
+        children: [
+          { $type: "Input", name: "title", defaultValue: "Draft" },
+          {
+            $type: "Select",
+            name: "size",
+            options: [
+              { label: "Medium", value: "m" },
+              { label: "Large", value: "l" },
+            ],
+            defaultValue: "l",
+          },
+          {
+            $type: "Form",
+            $action: { type: "submit" },
+            children: [
+              { $type: "Input", name: "note" },
+              {
+                $type: "Button",
+                label: "Save note",
+                $action: {
+                  type: "save",
+                  note: { $field: "note" },
+                  title: { $field: "title" },
+                },
+              },
+            ],
+          },
+          {
+            $type: "Button",
+            label: "Save",
+            $action: {
+              type: "save",
+              fields: [{ $field: "title" }, { $field: "missing" }],
+              size: { $field: "size" },
+              note: { $field: "note" },
+              missing: { $field: "missing" },
+            },
+          },
+        ],
+      },
+      { save },
+    );
+    const [title, note] = container.querySelectorAll("input");
+    const [saveNote, saveAll] = container.querySelectorAll("button");
+
+    expect(title!.value).toBe("Draft");
+    expect(container.querySelector("select")!.value).toBe("l");
+    title!.value = "Final";
+    note!.value = "Ship it";
+    await act(async () => saveNote!.click());
+    await act(async () => saveAll!.click());
+
+    expect(save.mock.calls.map(([{ payload }]) => payload)).toEqual([
+      { type: "save", note: "Ship it" },
+      { type: "save", fields: ["Final"], size: "l", note: "Ship it" },
+    ]);
+  });
+  it("never read a control inside a nested generative UI root", async () => {
+    const save = vi.fn();
+    const container = await mount(
+      {
+        $type: "Col",
+        children: [
+          { $type: "Input", name: "note", defaultValue: "outer" },
+          {
+            $type: "Button",
+            label: "Save",
+            $action: { type: "save", note: { $field: "note" } },
+          },
+        ],
+      },
+      { save },
+    );
+    const nested = document.createElement("div");
+    nested.setAttribute("data-aui", "root");
+    nested.innerHTML = '<input name="note" value="inner">';
+    container.querySelector('[data-aui="root"]')!.append(nested);
+
+    await act(async () => container.querySelector("button")!.click());
+
+    expect(save).toHaveBeenCalledWith({
+      payload: { type: "save", note: "outer" },
+    });
+  });
+
+  it("never read a host form around the generative UI root", async () => {
+    const save = vi.fn();
+    const hostForm = document.createElement("form");
+    hostForm.innerHTML = '<input name="secret" value="host">';
+    document.body.append(hostForm);
+    const container = await mount(
+      {
+        $type: "Button",
+        label: "Save",
+        $action: { type: "save", secret: { $field: "secret" } },
+      },
+      { save },
+      hostForm,
+    );
+
+    await act(async () => container.querySelector("button")!.click());
+
+    expect(save).toHaveBeenCalledWith({ payload: { type: "save" } });
+  });
+  it("read nothing outside a vocabulary form when the tree has no generative UI root", async () => {
+    const save = vi.fn();
+    const registry = createActionRegistry({ save });
+    const hostForm = document.createElement("form");
+    hostForm.innerHTML = '<input name="secret" value="host">';
+    const inHost = document.createElement("div");
+    const standalone = document.createElement("div");
+    hostForm.append(inHost);
+    document.body.append(hostForm, standalone);
+    const roots = [createRoot(inHost), createRoot(standalone)];
+    await act(async () => {
+      roots[0]!.render(
+        renderGenerativeUI(
+          {
+            $type: "Button",
+            label: "Save",
+            $action: { type: "save", secret: { $field: "secret" } },
+          },
+          defaultGenerativeUILibrary,
+          { status: "done", dispatch: registry.dispatch },
+        ),
+      );
+      roots[1]!.render(
+        renderGenerativeUI(
+          {
+            $type: "Form",
+            children: [
+              { $type: "Input", name: "note", defaultValue: "kept" },
+              {
+                $type: "Button",
+                label: "Save note",
+                $action: { type: "save", note: { $field: "note" } },
+              },
+            ],
+          },
+          defaultGenerativeUILibrary,
+          { status: "done", dispatch: registry.dispatch },
+        ),
+      );
+    });
+
+    await act(async () => inHost.querySelector("button")!.click());
+    await act(async () => standalone.querySelector("button")!.click());
+    await act(async () => roots.forEach((r) => r.unmount()));
+
+    expect(save.mock.calls.map(([{ payload }]) => payload)).toEqual([
+      { type: "save" },
+      { type: "save", note: "kept" },
+    ]);
+  });
+});
+
+describe("A2UI two-way binding", () => {
+  it("renders bound input values and sends the values the user entered as the action context", async () => {
+    const { state } = applyA2uiOperations(new Map(), [
+      { version: "v0.9", createSurface: { surfaceId: "s" } },
+      {
+        version: "v0.9",
+        updateComponents: {
+          surfaceId: "s",
+          components: [
+            {
+              id: "root",
+              component: "Column",
+              children: ["name", "plan", "send"],
+            },
+            {
+              id: "name",
+              component: "TextField",
+              label: "Name",
+              value: { path: "/form/name" },
+            },
+            {
+              id: "plan",
+              component: "ChoicePicker",
+              options: [
+                { label: "Free", value: "free" },
+                { label: "Pro", value: "pro" },
+              ],
+              value: { path: "/form/plan" },
+            },
+            {
+              id: "send",
+              component: "Button",
+              label: "Send",
+              action: {
+                event: {
+                  name: "send",
+                  context: {
+                    name: { path: "/form/name" },
+                    form: { path: "/form" },
+                  },
+                },
+              },
+            },
+          ],
+        },
+      },
+      {
+        version: "v0.9",
+        updateDataModel: {
+          surfaceId: "s",
+          path: "/",
+          value: { form: { name: "Ada", plan: ["free"], id: 7 } },
+        },
+      },
+    ]);
+    const send = vi.fn();
+    const container = await mount(
+      convertSurfaceToUISpec(state.get("s")!).spec,
+      { "a2ui:action": send },
+    );
+    const name = container.querySelector<HTMLInputElement>(
+      'input[data-aui="input"]',
+    )!;
+    const [free, pro] = container.querySelectorAll<HTMLInputElement>(
+      'input[type="radio"]',
+    );
+
+    expect(name.value).toBe("Ada");
+    expect(free!.checked).toBe(true);
+    name.value = "Grace";
+    await act(async () => pro!.click());
+    await act(async () => container.querySelector("button")!.click());
+
+    expect(send).toHaveBeenCalledWith({
+      payload: {
+        type: "a2ui:action",
+        name: "send",
+        surfaceId: "s",
+        sourceComponentId: "send",
+        context: {
+          name: "Grace",
+          form: { name: "Grace", plan: ["pro"], id: 7 },
+        },
+      },
+    });
+  });
+
+  it("sends a userMessage bound to an input as the text the user entered", async () => {
+    const { state } = applyA2uiOperations(new Map(), [
+      {
+        version: "v1.0",
+        createSurface: {
+          surfaceId: "s",
+          dataModel: { note: "Draft" },
+          components: [
+            { id: "root", component: "Column", children: ["note", "send"] },
+            { id: "note", component: "TextField", value: { path: "/note" } },
+            {
+              id: "send",
+              component: "Button",
+              label: "Send",
+              action: {
+                event: { name: "send", userMessage: { path: "/note" } },
+              },
+            },
+          ],
+        },
+      },
+    ]);
+    const send = vi.fn();
+    const container = await mount(
+      convertSurfaceToUISpec(state.get("s")!).spec,
+      { "a2ui:action": send },
+    );
+
+    container.querySelector<HTMLInputElement>(
+      'input[data-aui="input"]',
+    )!.value = "Ship it";
+    await act(async () => container.querySelector("button")!.click());
+
+    expect(send).toHaveBeenCalledWith({
+      payload: {
+        type: "a2ui:action",
+        name: "send",
+        surfaceId: "s",
+        sourceComponentId: "send",
+        userMessage: "Ship it",
+      },
+    });
+  });
+
+  it("sends the agent's values when an overridden Button dispatches $action itself", async () => {
+    const { state } = applyA2uiOperations(new Map(), [
+      { version: "v0.9", createSurface: { surfaceId: "s" } },
+      {
+        version: "v0.9",
+        updateComponents: {
+          surfaceId: "s",
+          components: [
+            { id: "root", component: "Column", children: ["email", "send"] },
+            {
+              id: "email",
+              component: "TextField",
+              value: { path: "/form/email" },
+            },
+            {
+              id: "send",
+              component: "Button",
+              label: "Send",
+              action: {
+                event: {
+                  name: "send",
+                  context: {
+                    email: { path: "/form/email" },
+                    form: { path: "/form" },
+                  },
+                },
+              },
+            },
+          ],
+        },
+      },
+      {
+        version: "v0.9",
+        updateDataModel: {
+          surfaceId: "s",
+          path: "/",
+          value: { form: { email: "old@example.com" } },
+        },
+      },
+    ]);
+    const button = defaultGenerativeUILibrary.Button!;
+    const library: GenerativeUILibrary = {
+      ...defaultGenerativeUILibrary,
+      Button: {
+        properties: button.properties,
+        description: button.description,
+        render: ({ label, $action, $dispatch }) => (
+          <button
+            type="button"
+            onClick={() => ($action ? $dispatch?.($action) : undefined)}
+          >
+            {label}
+          </button>
+        ),
+      },
+    };
+    const send = vi.fn();
+    const registry = createActionRegistry({ "a2ui:action": send });
+    const container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+    await act(async () => {
+      root!.render(
+        <div data-aui="root">
+          {renderGenerativeUI(
+            convertSurfaceToUISpec(state.get("s")!).spec,
+            library,
+            { status: "done", dispatch: registry.dispatch },
+          )}
+        </div>,
+      );
+    });
+
+    container.querySelector<HTMLInputElement>(
+      'input[data-aui="input"]',
+    )!.value = "new@example.com";
+    await act(async () => container.querySelector("button")!.click());
+
+    expect(send).toHaveBeenCalledWith({
+      payload: {
+        type: "a2ui:action",
+        name: "send",
+        surfaceId: "s",
+        sourceComponentId: "send",
+        context: {
+          email: "old@example.com",
+          form: { email: "old@example.com" },
+        },
+      },
+    });
+  });
+
+  it("keeps what the user entered until the agent updates the bound value", async () => {
+    const options = [
+      { label: "Free", value: "free" },
+      { label: "Pro", value: "pro" },
+      { label: "Team", value: "team" },
+    ];
+    const surface = (data: Record<string, unknown>) =>
+      convertSurfaceToUISpec(
+        applyA2uiOperations(new Map(), [
+          { version: "v0.9", createSurface: { surfaceId: "s" } },
+          {
+            version: "v0.9",
+            updateComponents: {
+              surfaceId: "s",
+              components: [
+                {
+                  id: "root",
+                  component: "Column",
+                  children: ["name", "agree", "plan", "size", "extras", "day"],
+                },
+                {
+                  id: "name",
+                  component: "TextField",
+                  value: { path: "/name" },
+                },
+                {
+                  id: "agree",
+                  component: "CheckBox",
+                  value: { path: "/agree" },
+                },
+                {
+                  id: "plan",
+                  component: "ChoicePicker",
+                  options,
+                  value: { path: "/plan" },
+                },
+                {
+                  id: "size",
+                  component: "ChoicePicker",
+                  displayStyle: "chips",
+                  options,
+                  value: { path: "/size" },
+                },
+                {
+                  id: "extras",
+                  component: "ChoicePicker",
+                  variant: "multipleSelection",
+                  options,
+                  value: { path: "/extras" },
+                },
+                {
+                  id: "day",
+                  component: "DateTimeInput",
+                  value: { path: "/day" },
+                },
+              ],
+            },
+          },
+          {
+            version: "v0.9",
+            updateDataModel: { surfaceId: "s", path: "/", value: data },
+          },
+        ]).state.get("s")!,
+      ).spec;
+    const initial = {
+      name: "Ada",
+      agree: false,
+      plan: ["free"],
+      size: ["free"],
+      extras: [],
+      day: "2026-01-02",
+    };
+    const container = await mount(surface(initial), {});
+    const read = () => ({
+      name: container.querySelector<HTMLInputElement>(
+        'input[data-aui="input"]',
+      )!.value,
+      agree: container.querySelector<HTMLInputElement>(
+        'label[data-aui="checkbox"] input',
+      )!.checked,
+      plan: container.querySelector<HTMLInputElement>(
+        'input[type="radio"]:checked',
+      )?.value,
+      size: container.querySelector<HTMLInputElement>(
+        'input[data-aui-field-name="/size"]:checked',
+      )?.value,
+      extras: [
+        ...container.querySelectorAll<HTMLInputElement>(
+          'fieldset[data-aui="checkboxgroup"] input:checked',
+        ),
+      ].map((input) => input.value),
+      day: container.querySelector<HTMLInputElement>('input[type="date"]')!
+        .value,
+    });
+    const edited = {
+      name: "Grace",
+      agree: false,
+      plan: "pro",
+      size: "pro",
+      extras: ["pro"],
+      day: "2026-03-04",
+    };
+    container.querySelector<HTMLInputElement>(
+      'input[data-aui="input"]',
+    )!.value = edited.name;
+    container.querySelectorAll<HTMLInputElement>(
+      'input[type="radio"]',
+    )[1]!.checked = true;
+    container.querySelector<HTMLInputElement>(
+      'input[data-aui-field-name="/size"][value="pro"]',
+    )!.checked = true;
+    container.querySelectorAll<HTMLInputElement>(
+      'fieldset[data-aui="checkboxgroup"] input',
+    )[1]!.checked = true;
+    container.querySelector<HTMLInputElement>('input[type="date"]')!.value =
+      edited.day;
+
+    await act(async () => root!.render(view(surface(initial))));
+    expect(read()).toEqual(edited);
+
+    await act(async () =>
+      root!.render(
+        view(
+          surface({
+            name: "Hopper",
+            agree: true,
+            plan: ["team"],
+            size: ["team"],
+            extras: ["team"],
+            day: "2026-05-06",
+          }),
+        ),
+      ),
+    );
+    expect(read()).toEqual({
+      name: "Hopper",
+      agree: true,
+      plan: "team",
+      size: "team",
+      extras: ["team"],
+      day: "2026-05-06",
+    });
+  });
+});
+
+describe.each([
+  { version: "v0.9", live: false },
+  { version: "v0.9", live: true },
+  { version: "v0.9.1", live: false },
+  { version: "v0.9.1", live: true },
+])("A2UI input contracts ($version, live: $live)", ({ version, live }) => {
+  const mountSurface = async (
+    field: Record<string, unknown>,
+    initial: unknown,
+    previewPath = "/form/value",
+  ) => {
+    const send = vi.fn();
+    const registry = createActionRegistry({ "a2ui:action": send });
+    const container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+    const render = async (value: unknown) => {
+      const operations = [
+        { version, createSurface: { surfaceId: "s" } },
+        {
+          version,
+          updateComponents: {
+            surfaceId: "s",
+            components: [
+              {
+                id: "root",
+                component: "Column",
+                children: ["field", "preview", "send"],
+              },
+              {
+                id: "field",
+                label: "Value",
+                ...field,
+                value: { path: "/form/value" },
+              },
+              { id: "preview", component: "Text", text: { path: previewPath } },
+              {
+                id: "send",
+                component: "Button",
+                label: "Send",
+                action: {
+                  event: {
+                    name: "send",
+                    context: {
+                      value: { path: "/form/value" },
+                      form: { path: "/form" },
+                    },
+                  },
+                },
+              },
+            ],
+          },
+        },
+        {
+          version,
+          updateDataModel: {
+            surfaceId: "s",
+            path: "/",
+            value: { form: value === undefined ? {} : { value } },
+          },
+        },
+      ];
+      const surface = applyA2uiOperations(new Map(), operations).state.get(
+        "s",
+      )!;
+      const converted = convertSurfaceToUISpec(surface);
+      expect(converted.warnings).toEqual([]);
+      await act(async () =>
+        root!.render(
+          live ? (
+            <div data-aui="root">
+              <A2uiPresentRenderer
+                surfaceId="s"
+                operations={operations}
+                fallback={converted.spec}
+                library={defaultGenerativeUILibrary}
+                status="done"
+                dispatch={registry.dispatch}
+              />
+            </div>
+          ) : (
+            view(converted.spec, registry.dispatch)
+          ),
+        ),
+      );
+    };
+    await render(initial);
+    const submit = async (value: unknown) => {
+      await act(async () => container.querySelector("button")!.click());
+      expect(send).toHaveBeenLastCalledWith({
+        payload: {
+          type: "a2ui:action",
+          name: "send",
+          surfaceId: "s",
+          sourceComponentId: "send",
+          context: { value, form: { value } },
+        },
+      });
+    };
+    return { container, render, submit };
+  };
+
+  it.each([
+    {
+      title: "obscured text",
+      field: { component: "TextField", variant: "obscured" },
+      initial: "s3cret",
+      edited: "  new secret  ",
+      type: "password",
+    },
+    {
+      title: "number text",
+      field: { component: "TextField", variant: "number" },
+      initial: "3",
+      edited: "12.5",
+      type: "number",
+    },
+    {
+      title: "date and time",
+      field: { component: "DateTimeInput", enableDate: true, enableTime: true },
+      initial: "2025-12-15T17:00:00Z",
+      edited: "2025-12-16T08:30:45+02:00",
+      type: "text",
+    },
+    {
+      title: "timestamp in date mode",
+      field: { component: "DateTimeInput", enableDate: true },
+      initial: "2025-12-15T17:00:00Z",
+      edited: "2025-12-16T08:30:00Z",
+      type: "text",
+    },
+    {
+      title: "time only",
+      field: { component: "DateTimeInput", enableTime: true },
+      initial: "17:00:00",
+      edited: "08:30:45",
+      type: "text",
+    },
+    {
+      title: "omitted temporal flags",
+      field: { component: "DateTimeInput" },
+      initial: "2025-12-15",
+      edited: "2025-12-16",
+      type: "date",
+    },
+    {
+      title: "disabled temporal flags",
+      field: {
+        component: "DateTimeInput",
+        enableDate: false,
+        enableTime: false,
+      },
+      initial: "",
+      edited: "2025-12-16",
+      type: "date",
+    },
+    {
+      title: "date only",
+      field: { component: "DateTimeInput", enableDate: true },
+      initial: "2025-12-15",
+      edited: "2025-12-16",
+      type: "date",
+    },
+    {
+      title: "unresolved obscured text",
+      field: { component: "TextField", variant: "obscured" },
+      initial: undefined,
+      edited: "s3cret",
+      type: "password",
+    },
+    {
+      title: "unresolved number text",
+      field: { component: "TextField", variant: "number" },
+      initial: undefined,
+      edited: "12.5",
+      type: "number",
+    },
+    {
+      title: "unresolved date and time",
+      field: { component: "DateTimeInput", enableDate: true, enableTime: true },
+      initial: undefined,
+      edited: "2025-12-15T17:00:00Z",
+      type: "text",
+    },
+  ])(
+    "preserves untouched, edited, and cleared $title values",
+    async ({ field, initial, edited, type }) => {
+      const { container, render, submit } = await mountSurface(field, initial);
+      const input = () =>
+        container.querySelector<HTMLInputElement>('input[name="/form/value"]')!;
+      const preview = () =>
+        container.querySelector('[data-aui="markdown"]')?.textContent ?? "";
+      const edit = async (value: string) => {
+        await act(async () => {
+          const control = input();
+          Object.getOwnPropertyDescriptor(
+            HTMLInputElement.prototype,
+            "value",
+          )!.set!.call(control, value);
+          control.dispatchEvent(new Event("input", { bubbles: true }));
+        });
+      };
+
+      expect(input().type).toBe(type);
+      expect(input().getAttribute("aria-label")).toBe("Value");
+      expect(input().value).toBe(initial ?? "");
+      if (type === "number") expect(input().step).toBe("any");
+      await submit(initial ?? "");
+
+      await edit(edited);
+      expect(input().value).toBe(edited);
+      if (type === "number") expect(input().validity.stepMismatch).toBe(false);
+      if (live) expect(preview()).toBe(edited);
+      await submit(edited);
+
+      await edit("");
+      expect(input().type).toBe(type);
+      expect(input().value).toBe("");
+      if (live) expect(preview()).toBe("");
+      await submit("");
+
+      await render(initial);
+      expect(input().value).toBe("");
+      await submit("");
+      await render(edited);
+      expect(input().value).toBe(edited);
+      expect(preview()).toBe(edited);
+      await submit(edited);
+    },
+  );
+
+  it.each([undefined, "Pick one"])(
+    "keeps chips empty until selected with placeholder %s",
+    async (placeholder) => {
+      const { container, render, submit } = await mountSurface(
+        {
+          component: "ChoicePicker",
+          displayStyle: "chips",
+          placeholder,
+          options: [
+            { label: "A", value: "a" },
+            { label: "B", value: "b" },
+          ],
+        },
+        [],
+        "/form/value/0",
+      );
+      const radios = () => [
+        ...container.querySelectorAll<HTMLInputElement>('input[type="radio"]'),
+      ];
+      const selected = () =>
+        radios()
+          .filter((input) => input.checked)
+          .map((input) => input.value);
+
+      await submit([]);
+      expect(container.querySelector("select")).toBeNull();
+      expect(radios()).toHaveLength(2);
+      expect(
+        container.querySelector("fieldset")?.getAttribute("aria-label"),
+      ).toBe("Value");
+      expect(selected()).toEqual([]);
+
+      await act(async () => radios()[1]!.click());
+      expect(selected()).toEqual(["b"]);
+      if (live)
+        expect(
+          container.querySelector('[data-aui="markdown"]')?.textContent,
+        ).toBe("b");
+      await submit(["b"]);
+      await render([]);
+      expect(selected()).toEqual(["b"]);
+      await submit(["b"]);
+      await render(["a"]);
+      expect(selected()).toEqual(["a"]);
+      await submit(["a"]);
+      await render([]);
+      expect(selected()).toEqual([]);
+      await submit([]);
+    },
+  );
+});