@assistant-ui/react-generative-ui 0.0.23 → 0.1.0

package/src/a2ui/convert.ts

@@ -1,1207 +0,0 @@
-import { ICON_NAMES, type UIElement } from "../ir";
-import { classifyTemporal } from "../temporal";
-import { A2UI_SURFACE_ID, type A2uiSurfaceState } from "./types";
-import {
-  evaluateA2uiValueFunction,
-  type ExpressionPart,
-} from "./valueFunctions";
-import { MAX_AUTO_VIVIFY_ARRAY_INDEX } from "./reducer";
-import type { A2uiBinding } from "./BindingContext";
-import { decodePointer, resolvePointer } from "./dataModel";
-
-const DEPTH_CAP = 32;
-const TEMPLATE_ITEM_CAP = 100;
-const NODE_BUDGET = 5000;
-const EVALUATION_BUDGET = 20_000;
-
-const SUPPORTED_COMPONENTS = new Set([
-  "Text",
-  "Image",
-  "Icon",
-  "Row",
-  "Column",
-  "List",
-  "Card",
-  "Divider",
-  "Button",
-  "TextField",
-  "CheckBox",
-  "ChoicePicker",
-  "DateTimeInput",
-  "Slider",
-]);
-
-const CHILD_LIST_COMPONENTS: ReadonlySet<string> = new Set([
-  "Row",
-  "Column",
-  "List",
-]);
-
-const ICON_NAME_SET: ReadonlySet<string> = new Set(ICON_NAMES);
-const ICON_SIZE_SET: ReadonlySet<string> = new Set(["sm", "md", "lg"]);
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
-const isPlainObject = (value: unknown): value is Record<string, unknown> => {
-  if (!isRecord(value)) return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-};
-
-const setOwnProperty = (
-  target: Record<string, unknown>,
-  key: string,
-  value: unknown,
-) => {
-  if (key === "__proto__") {
-    Object.defineProperty(target, key, {
-      value,
-      enumerable: true,
-      configurable: true,
-      writable: true,
-    });
-  } else {
-    target[key] = value;
-  }
-};
-
-const FUNCTION_CALL_KEYS: ReadonlySet<string> = new Set([
-  "call",
-  "args",
-  "returnType",
-  "catalogId",
-]);
-
-const isFunctionCall = (
-  value: unknown,
-): value is {
-  readonly call: string;
-  readonly args?: Record<string, unknown>;
-} =>
-  isPlainObject(value) &&
-  typeof value["call"] === "string" &&
-  (value["args"] === undefined || isPlainObject(value["args"])) &&
-  Object.keys(value).every((key) => FUNCTION_CALL_KEYS.has(key));
-
-const isBinding = (value: unknown): value is { readonly path: string } =>
-  isPlainObject(value) &&
-  Object.keys(value).length === 1 &&
-  typeof value["path"] === "string";
-
-type ChildTemplate = { readonly componentId: string; readonly path: string };
-
-const childTemplateOf = (children: unknown): ChildTemplate | undefined => {
-  const template =
-    isPlainObject(children) &&
-    Object.keys(children).length === 1 &&
-    isPlainObject(children["template"])
-      ? children["template"]
-      : children;
-  return isPlainObject(template) &&
-    Object.keys(template).length === 2 &&
-    typeof template["componentId"] === "string" &&
-    typeof template["path"] === "string"
-    ? { componentId: template["componentId"], path: template["path"] }
-    : undefined;
-};
-
-const bindingPath = (value: unknown): string | undefined =>
-  isBinding(value) ? value.path : undefined;
-
-type Scope = { readonly data: unknown; readonly path: string };
-
-const pointerIn = (scope: Scope, path: string): string =>
-  (path.startsWith("/") ? "" : scope.path) +
-  decodePointer(path)
-    .map((segment) => `/${segment.replaceAll("~", "~0").replaceAll("/", "~1")}`)
-    .join("");
-
-const setIn = (
-  value: unknown,
-  segments: readonly string[],
-  leaf: unknown,
-): unknown => {
-  const [head, ...rest] = segments;
-  if (head === undefined) return leaf;
-  if (
-    /^(0|[1-9]\d*)$/.test(head) &&
-    (Array.isArray(value) || value === undefined || value === null)
-  ) {
-    const list = Array.isArray(value) ? value : [];
-    const index = Number(head);
-    if (index >= list.length && index > MAX_AUTO_VIVIFY_ARRAY_INDEX) {
-      return value;
-    }
-    const copy = [...list];
-    copy[index] = setIn(copy[index], rest, leaf);
-    return copy;
-  }
-  const copy: Record<string, unknown> = isRecord(value) ? { ...value } : {};
-  setOwnProperty(
-    copy,
-    head,
-    setIn(Object.hasOwn(copy, head) ? copy[head] : undefined, rest, leaf),
-  );
-  return copy;
-};
-
-const withFieldReferences = (
-  value: unknown,
-  pointer: string,
-  fields: ReadonlyMap<string, unknown>,
-): unknown => {
-  if (fields.has(pointer)) return fields.get(pointer);
-  let result = value;
-  for (const [name, field] of fields) {
-    if (name.startsWith(`${pointer}/`)) {
-      result = setIn(result, decodePointer(name.slice(pointer.length)), field);
-    }
-  }
-  return result;
-};
-
-const materializeEntries = (
-  value: Record<string, unknown>,
-  source: unknown,
-  context: ConversionContext,
-  evaluate: boolean,
-  depth: number,
-  positional = false,
-): Record<string, unknown> => {
-  const result: Record<string, unknown> = {};
-  for (const [key, entry] of Object.entries(value)) {
-    // An action's functionCall runs when the button fires, so only its arguments resolve here.
-    const resolved =
-      key === "functionCall" && isFunctionCall(entry)
-        ? {
-            ...entry,
-            ...(entry.args !== undefined
-              ? {
-                  args: materializeEntries(
-                    entry.args,
-                    source,
-                    context,
-                    evaluate,
-                    depth,
-                    true,
-                  ),
-                }
-              : {}),
-          }
-        : materialize(entry, source, context, evaluate, depth, positional);
-    if (resolved !== undefined) {
-      setOwnProperty(result, key, resolved);
-    }
-  }
-  return result;
-};
-
-function materialize(
-  value: unknown,
-  source: unknown,
-  context: ConversionContext,
-  evaluate = true,
-  depth = 0,
-  positional = false,
-): unknown {
-  if (isBinding(value)) {
-    const pointer = pointerIn(
-      { data: source, path: context.scopePath },
-      value.path,
-    );
-    const resolved = resolvePointer(context.surface.dataModel, pointer);
-    context.dependencies?.set(pointer, resolved);
-    return resolved;
-  }
-  if (Array.isArray(value)) {
-    const entries = value.map((entry) =>
-      materialize(entry, source, context, evaluate, depth, positional),
-    );
-    return positional
-      ? entries
-      : entries.filter((entry) => entry !== undefined);
-  }
-  if (!isPlainObject(value)) return value;
-  if (!evaluate || !isFunctionCall(value)) {
-    return materializeEntries(
-      value,
-      source,
-      context,
-      evaluate,
-      depth,
-      positional,
-    );
-  }
-  if (!spendEvaluation(context)) return undefined;
-  if (depth >= DEPTH_CAP) {
-    if (!context.functionDepthWarned) {
-      context.warnings.push(
-        `A2UI function nesting cap of ${DEPTH_CAP} was reached.`,
-      );
-      context.functionDepthWarned = true;
-    }
-    return undefined;
-  }
-  return evaluateA2uiValueFunction(
-    value.call,
-    materializeEntries(
-      value.args ?? {},
-      source,
-      context,
-      true,
-      depth + 1,
-      true,
-    ),
-    {
-      resolve: (part) =>
-        spendEvaluation(context)
-          ? materialize(part, source, context, true, depth + 1)
-          : undefined,
-      warn: (message) => context.warnings.push(message),
-      templates: context.templates,
-    },
-  );
-}
-
-const firstDefined = (
-  props: Record<string, unknown>,
-  keys: readonly string[],
-): unknown => {
-  for (const key of keys) {
-    if (props[key] !== undefined) return props[key];
-  }
-  return undefined;
-};
-
-const stringProp = (
-  props: Record<string, unknown>,
-  keys: readonly string[],
-): string | undefined => {
-  const value = firstDefined(props, keys);
-  return typeof value === "string" ? value : undefined;
-};
-
-const sourceSurfaceId = (surface: A2uiSurfaceState): string =>
-  (surface as A2uiSurfaceState & { [A2UI_SURFACE_ID]?: string })[
-    A2UI_SURFACE_ID
-  ] ?? "";
-
-type ConversionContext = {
-  readonly surface: A2uiSurfaceState;
-  readonly stepModel: unknown;
-  readonly surfaceId: string;
-  readonly warnings: string[];
-  emittedNodes: number;
-  depthWarned: boolean;
-  budgetWarned: boolean;
-  templateCapWarned: boolean;
-  evaluations: number;
-  evaluationBudgetWarned: boolean;
-  functionDepthWarned: boolean;
-  readonly templates: Map<string, ExpressionPart[] | null>;
-  readonly inputFields: Map<string, unknown>;
-  readonly textFields: Map<string, boolean>;
-  readonly boundActionEntries: {
-    readonly target: Record<string, unknown>;
-    readonly key: string;
-    readonly pointer: string;
-  }[];
-  readonly boundUserMessages: {
-    readonly action: Record<string, unknown>;
-    readonly pointer: string;
-  }[];
-  readonly keepUnknownComponents: boolean;
-  readonly bindings: Map<string, A2uiBinding> | undefined;
-  readonly cache: Map<string, CachedComponent> | undefined;
-  dependencies: Map<string, unknown> | undefined;
-  scopePath: string;
-};
-
-type CachedComponent = {
-  readonly props: Record<string, unknown>;
-  readonly mapped: UIElement | undefined;
-  readonly dependencies: ReadonlyMap<string, unknown>;
-  readonly evaluations: number;
-  children?: readonly UIElement[];
-  result?: UIElement;
-};
-
-const BOUND_KEYS = ["text", "value", "binding"] as const;
-
-const INPUT_COMPONENTS: ReadonlySet<string> = new Set([
-  "TextField",
-  "CheckBox",
-  "ChoicePicker",
-  "DateTimeInput",
-  "Slider",
-]);
-
-type DateInputType = "date" | "datetime" | "time";
-
-const dateInputType = (value: string): DateInputType | undefined => {
-  const kind = classifyTemporal(value).kind;
-  if (kind === "date" || kind === "time") return kind;
-  return kind === "floating" || kind === "instant" ? "datetime" : undefined;
-};
-
-const finiteNumber = (value: unknown): number | undefined =>
-  typeof value === "number" && Number.isFinite(value) ? value : undefined;
-
-const decimalPlaces = (value: number): number => {
-  const [mantissa = "", exponent = "0"] = String(value).split("e");
-  return Math.max(0, (mantissa.split(".")[1]?.length ?? 0) - Number(exponent));
-};
-
-// A spec slider without `steps` is continuous, so its step leaves at least a hundred divisions and keeps every bound value on the grid.
-const sliderStep = (
-  min: number,
-  max: number,
-  value: number | undefined,
-  steps: unknown,
-): number | undefined => {
-  if (max <= min) return undefined;
-  if (typeof steps === "number" && Number.isInteger(steps) && steps >= 1) {
-    return (max - min) / steps;
-  }
-  const precision = Math.max(
-    decimalPlaces(min),
-    value === undefined ? 0 : decimalPlaces(value),
-  );
-  return Math.min(
-    10 ** Math.floor(Math.log10((max - min) / 100)),
-    10 ** -precision,
-  );
-};
-
-const recordBindings = (
-  node: Record<string, unknown>,
-  props: Record<string, unknown>,
-  mapped: UIElement,
-  scope: Scope,
-  context: ConversionContext,
-) => {
-  const component = node["component"];
-  const name = mapped["name"];
-  const boundKey = BOUND_KEYS.find((key) => node[key] !== undefined);
-  const value = boundKey === undefined ? undefined : props[boundKey];
-  if (INPUT_COMPONENTS.has(String(component)) && typeof name === "string") {
-    context.textFields.set(
-      name,
-      (!context.textFields.has(name) || context.bindings !== undefined) &&
-        (component === "TextField" || component === "DateTimeInput"),
-    );
-    const field = (fallback: unknown) =>
-      fallback === undefined ? { $field: name } : { $field: name, fallback };
-    // A single-choice picker collects one string, while the spec binds it to a string list.
-    const listValued =
-      component === "ChoicePicker" &&
-      mapped.$type !== "CheckboxGroup" &&
-      typeof value !== "string";
-    context.inputFields.set(
-      name,
-      listValued
-        ? [field(Array.isArray(value) ? value[0] : undefined)]
-        : field(value),
-    );
-  }
-  const action = mapped.$action;
-  const raw = node["action"];
-  if (!action || !isRecord(raw)) return;
-  const functionCall = action.type === "a2ui:functionCall";
-  const event = isRecord(raw["event"]) ? raw["event"] : raw;
-  const userMessage = event["userMessage"];
-  if (!functionCall && isBinding(userMessage)) {
-    context.boundUserMessages.push({
-      action,
-      pointer: pointerIn(scope, userMessage.path),
-    });
-  }
-  const rawEntries = functionCall
-    ? isRecord(raw["functionCall"])
-      ? raw["functionCall"]["args"]
-      : undefined
-    : event["context"];
-  const target = functionCall ? action["args"] : action["context"];
-  if (!isRecord(rawEntries) || !isRecord(target)) return;
-  for (const [key, entry] of Object.entries(rawEntries)) {
-    if (isBinding(entry)) {
-      context.boundActionEntries.push({
-        target,
-        key,
-        pointer: pointerIn(scope, entry.path),
-      });
-    }
-  }
-};
-
-const spendEvaluation = (context: ConversionContext): boolean => {
-  if (context.evaluations < EVALUATION_BUDGET) {
-    context.evaluations++;
-    return true;
-  }
-  if (!context.evaluationBudgetWarned) {
-    context.warnings.push(
-      `A2UI function evaluation budget of ${EVALUATION_BUDGET} was reached.`,
-    );
-    context.evaluationBudgetWarned = true;
-  }
-  return false;
-};
-
-const reserveNode = (context: ConversionContext): boolean => {
-  if (context.emittedNodes >= NODE_BUDGET) {
-    if (!context.budgetWarned) {
-      context.warnings.push(`A2UI node budget of ${NODE_BUDGET} was reached.`);
-      context.budgetWarned = true;
-    }
-    return false;
-  }
-  context.emittedNodes++;
-  return true;
-};
-
-const childReferences = (node: Record<string, unknown>): unknown[] => {
-  const children = node["children"];
-  const references: unknown[] = Array.isArray(children) ? [...children] : [];
-  if (node["child"] !== undefined) references.push(node["child"]);
-  if (node["component"] === "Modal") {
-    references.push(node["trigger"], node["content"]);
-  }
-  if (node["component"] === "Tabs" && Array.isArray(node["tabs"])) {
-    for (const tab of node["tabs"]) {
-      references.push(isRecord(tab) ? tab["child"] : undefined);
-    }
-  }
-  return references;
-};
-
-const childrenOf = (
-  node: Record<string, unknown>,
-  scope: Scope,
-  context: ConversionContext,
-  depth: number,
-  visited: Set<string>,
-): UIElement[] => {
-  const result: UIElement[] = [];
-  for (const childId of childReferences(node)) {
-    if (typeof childId !== "string") {
-      context.warnings.push(
-        `Component "${String(node["id"] ?? "")}" has a malformed child reference.`,
-      );
-      continue;
-    }
-    const child = convertComponent(childId, scope, context, depth + 1, visited);
-    if (child) result.push(child);
-  }
-  return result;
-};
-
-const textLabel = (
-  node: Record<string, unknown>,
-  children: readonly UIElement[],
-  context: ConversionContext,
-): string | undefined => {
-  const references = childReferences(node);
-  const [reference] = references;
-  const [child] = children;
-  if (
-    references.length !== 1 ||
-    children.length !== 1 ||
-    typeof reference !== "string" ||
-    !child ||
-    context.surface.components.get(reference)?.["component"] !== "Text"
-  ) {
-    return undefined;
-  }
-  const text = child.$type === "Header" ? child["text"] : child["value"];
-  return typeof text === "string" ? text : undefined;
-};
-
-const mappedAction = (
-  node: Record<string, unknown>,
-  props: Record<string, unknown>,
-  context: ConversionContext,
-): UIElement["$action"] | undefined => {
-  const action = props["action"];
-  if (action === undefined) return undefined;
-  const source = {
-    surfaceId: context.surfaceId,
-    sourceComponentId: typeof node["id"] === "string" ? node["id"] : "",
-  };
-  const event =
-    isRecord(action) && isRecord(action["event"]) ? action["event"] : action;
-  const actionName =
-    typeof event === "string"
-      ? event
-      : isRecord(event) && typeof event["name"] === "string"
-        ? event["name"]
-        : undefined;
-  if (actionName) {
-    const actionContext = isRecord(event) ? event["context"] : undefined;
-    const userMessage = isRecord(event) ? event["userMessage"] : undefined;
-    return {
-      type: "a2ui:action",
-      name: actionName,
-      ...source,
-      ...(typeof userMessage === "string" ? { userMessage } : {}),
-      ...(actionContext !== undefined ? { context: actionContext } : {}),
-    };
-  }
-  const functionCall = isRecord(action) ? action["functionCall"] : undefined;
-  if (isRecord(functionCall) && typeof functionCall["call"] === "string") {
-    const args = functionCall["args"];
-    return {
-      type: "a2ui:functionCall",
-      call: functionCall["call"],
-      ...source,
-      ...(isRecord(args) ? { args } : {}),
-    };
-  }
-  context.warnings.push(
-    `Component "${String(node["id"] ?? "")}" has a malformed action.`,
-  );
-  return undefined;
-};
-
-const choiceOptions = (value: unknown): { label: string; value: string }[] => {
-  if (!Array.isArray(value)) return [];
-  const options: { label: string; value: string }[] = [];
-  for (const option of value) {
-    if (
-      isRecord(option) &&
-      typeof option["label"] === "string" &&
-      typeof option["value"] === "string"
-    ) {
-      options.push({ label: option["label"], value: option["value"] });
-    }
-  }
-  return options;
-};
-
-const mappedProps = (
-  node: Record<string, unknown>,
-  props: Record<string, unknown>,
-  context: ConversionContext,
-  scope: Scope,
-): UIElement | undefined => {
-  const component = node["component"];
-
-  if (component === "Text") {
-    const text = stringProp(props, ["text", "value"]);
-    const variant = props["variant"];
-    if (typeof variant === "string" && /^h[1-6]$/.test(variant)) {
-      return {
-        $type: "Header",
-        ...(text !== undefined ? { text } : {}),
-      };
-    }
-    if (variant === "caption") {
-      return {
-        $type: "Caption",
-        ...(text !== undefined ? { value: text } : {}),
-      };
-    }
-    return {
-      $type: "Markdown",
-      ...(text !== undefined ? { value: text } : {}),
-    };
-  }
-
-  if (component === "Image") {
-    const src = stringProp(props, ["src", "url"]);
-    const alt = stringProp(props, ["alt", "altText", "description"]);
-    const size = props["size"];
-    const round = props["round"];
-    return {
-      $type: "Image",
-      ...(src !== undefined ? { src } : {}),
-      ...(alt !== undefined ? { alt } : {}),
-      ...(typeof size === "string" || typeof size === "number" ? { size } : {}),
-      ...(typeof round === "boolean" ? { round } : {}),
-    };
-  }
-
-  if (component === "Icon") {
-    const name = stringProp(props, ["name"]);
-    if (!name || !ICON_NAME_SET.has(name)) return undefined;
-    const size = props["size"];
-    return {
-      $type: "Icon",
-      name,
-      ...(typeof size === "string" && ICON_SIZE_SET.has(size) ? { size } : {}),
-    };
-  }
-
-  if (component === "Row") {
-    const gap = props["gap"];
-    const align = firstDefined(props, ["align", "alignment"]);
-    const justify = firstDefined(props, ["justify", "distribution"]);
-    return {
-      $type: "Row",
-      ...(typeof gap === "number" ? { gap } : {}),
-      ...(typeof align === "string" ? { align } : {}),
-      ...(typeof justify === "string" ? { justify } : {}),
-    };
-  }
-
-  if (component === "Column") {
-    const gap = props["gap"];
-    const align = firstDefined(props, ["align", "alignment"]);
-    return {
-      $type: "Col",
-      ...(typeof gap === "number" ? { gap } : {}),
-      ...(typeof align === "string" ? { align } : {}),
-    };
-  }
-
-  if (component === "List") {
-    const direction = props["direction"];
-    const align = props["align"];
-    if (direction === "horizontal") {
-      return {
-        $type: "Row",
-        ...(typeof align === "string" ? { align } : {}),
-      };
-    }
-    return { $type: "ListView" };
-  }
-
-  if (component === "Card") {
-    const title = props["title"];
-    const padding = props["padding"];
-    const background = props["background"];
-    return {
-      $type: "Card",
-      ...(typeof title === "string" ? { title } : {}),
-      ...(typeof padding === "number" ? { padding } : {}),
-      ...(typeof background === "string" ? { background } : {}),
-    };
-  }
-
-  if (component === "Divider") {
-    return {
-      $type: "Divider",
-      ...(typeof props["flush"] === "boolean" ? { flush: props["flush"] } : {}),
-    };
-  }
-
-  if (component === "Button") {
-    const label = stringProp(props, ["label", "text"]);
-    const variantStyle =
-      props["variant"] === "primary"
-        ? "primary"
-        : props["variant"] === "borderless"
-          ? "ghost"
-          : undefined;
-    const buttonStyle =
-      typeof props["buttonStyle"] === "string"
-        ? props["buttonStyle"]
-        : variantStyle;
-    const block = props["block"];
-    const submit = props["submit"];
-    const action = mappedAction(node, props, context);
-    return {
-      $type: "Button",
-      ...(label !== undefined ? { label } : {}),
-      ...(buttonStyle !== undefined ? { buttonStyle } : {}),
-      ...(typeof block === "boolean" ? { block } : {}),
-      ...(typeof submit === "boolean" ? { submit } : {}),
-      ...(action ? { $action: action } : {}),
-    };
-  }
-
-  const bound = bindingPath(firstDefined(node, BOUND_KEYS));
-  const name = bound === undefined ? undefined : pointerIn(scope, bound);
-  const label = stringProp(props, ["label"]);
-
-  if (component === "TextField") {
-    const placeholder = stringProp(props, ["placeholder"]);
-    const inputType =
-      props["variant"] === "obscured"
-        ? "password"
-        : props["variant"] === "number"
-          ? "number"
-          : undefined;
-    const multiline =
-      typeof props["multiline"] === "boolean"
-        ? props["multiline"]
-        : props["variant"] === "longText" ||
-            props["textFieldType"] === "longText"
-          ? true
-          : undefined;
-    const initial = firstDefined(props, ["value", "text"]);
-    const defaultValue =
-      typeof initial === "string"
-        ? initial
-        : typeof initial === "number" && Number.isFinite(initial)
-          ? String(initial)
-          : undefined;
-    return {
-      $type: "Input",
-      ...(inputType !== undefined ? { inputType } : {}),
-      ...(placeholder !== undefined ? { placeholder } : {}),
-      ...(multiline !== undefined ? { multiline } : {}),
-      ...(label !== undefined ? { label } : {}),
-      ...(name !== undefined ? { name } : {}),
-      ...(defaultValue !== undefined ? { defaultValue } : {}),
-    };
-  }
-
-  if (component === "CheckBox") {
-    const defaultChecked = firstDefined(props, ["defaultChecked", "value"]);
-    return {
-      $type: "Checkbox",
-      ...(label !== undefined ? { label } : {}),
-      ...(name !== undefined ? { name } : {}),
-      ...(typeof defaultChecked === "boolean" ? { defaultChecked } : {}),
-    };
-  }
-
-  if (component === "Slider") {
-    const min = finiteNumber(props["min"]) ?? 0;
-    const max = finiteNumber(props["max"]);
-    if (max === undefined || max < min) return undefined;
-    const value = finiteNumber(props["value"]);
-    const step = sliderStep(
-      min,
-      max,
-      name === undefined
-        ? value
-        : finiteNumber(resolvePointer(context.stepModel, name)),
-      props["steps"],
-    );
-    return {
-      $type: "Slider",
-      min,
-      max,
-      ...(step !== undefined ? { step } : {}),
-      ...(value !== undefined ? { defaultValue: value } : {}),
-      ...(label !== undefined ? { label } : {}),
-      ...(name !== undefined ? { name } : {}),
-    };
-  }
-
-  if (component === "ChoicePicker") {
-    const options = choiceOptions(props["options"]);
-    const value = props["value"];
-    const selected =
-      typeof value === "string"
-        ? [value]
-        : Array.isArray(value)
-          ? value.filter((entry): entry is string => typeof entry === "string")
-          : [];
-    if (props["variant"] === "multipleSelection") {
-      return {
-        $type: "CheckboxGroup",
-        options,
-        ...(label !== undefined ? { label } : {}),
-        ...(name !== undefined ? { name } : {}),
-        ...(selected.length > 0 ? { defaultValue: selected } : {}),
-      };
-    }
-    const [defaultValue] = selected;
-    return {
-      $type: "RadioGroup",
-      options,
-      ...(label !== undefined ? { label } : {}),
-      ...(name !== undefined ? { name } : {}),
-      ...(defaultValue !== undefined ? { defaultValue } : {}),
-    };
-  }
-
-  if (component === "DateTimeInput") {
-    const value = stringProp(props, ["value"]);
-    const shapeValue =
-      name === undefined ? value : resolvePointer(context.stepModel, name);
-    const shapeType =
-      typeof shapeValue === "string" ? dateInputType(shapeValue) : undefined;
-    let inputType: DateInputType = shapeType ?? "date";
-    if ("enableDate" in props || "enableTime" in props) {
-      inputType =
-        props["enableTime"] === true
-          ? props["enableDate"] === true
-            ? "datetime"
-            : "time"
-          : "date";
-    }
-    if (
-      typeof shapeValue === "string" &&
-      shapeValue !== "" &&
-      shapeType !== inputType
-    ) {
-      return {
-        $type: "Input",
-        ...(value !== undefined ? { defaultValue: value } : {}),
-        ...(label !== undefined ? { label } : {}),
-        ...(name !== undefined ? { name } : {}),
-      };
-    }
-    // The spec types a bound as a date, a time or a date-time whatever the
-    // enabled flags are, so a date bound on a datetime control is the range of
-    // that whole local day rather than a mismatch.
-    const bound = (edge: "min" | "max"): string | undefined => {
-      const boundValue = stringProp(props, [edge]);
-      if (boundValue === undefined) return undefined;
-      const boundType = dateInputType(boundValue);
-      if (boundType === inputType) return boundValue;
-      if (inputType === "datetime" && boundType === "date") {
-        return `${boundValue}T${edge === "min" ? "00:00" : "23:59:59.999"}`;
-      }
-      context.warnings.push(
-        `A2UI DateTimeInput "${edge}" of "${boundValue}" is not a ${inputType} value and was dropped.`,
-      );
-      return undefined;
-    };
-    const min = bound("min");
-    const max = bound("max");
-    return {
-      $type: "DatePicker",
-      inputType,
-      ...(value !== undefined ? { value } : {}),
-      ...(min !== undefined ? { min } : {}),
-      ...(max !== undefined ? { max } : {}),
-      ...(label !== undefined ? { label } : {}),
-      ...(name !== undefined ? { name } : {}),
-    };
-  }
-
-  return undefined;
-};
-
-const convertTemplate = (
-  node: Record<string, unknown>,
-  template: ChildTemplate,
-  scope: Scope,
-  context: ConversionContext,
-  depth: number,
-  visited: Set<string>,
-  converted: UIElement | undefined,
-): UIElement | null => {
-  if (!reserveNode(context)) return null;
-  const container = converted ?? { $type: "ListView" };
-  const itemized = container.$type === "ListView";
-  const list = resolvePointer(
-    context.surface.dataModel,
-    pointerIn(scope, template.path),
-  );
-  const listPointer = pointerIn(scope, template.path);
-  if (!Array.isArray(list)) {
-    context.warnings.push(
-      `Template on component "${String(node["id"] ?? "")}" did not resolve to a list.`,
-    );
-    return { ...container, children: [] };
-  }
-  const itemCount = Math.min(list.length, TEMPLATE_ITEM_CAP);
-  if (list.length > TEMPLATE_ITEM_CAP && !context.templateCapWarned) {
-    context.warnings.push(
-      `A2UI template expansion was capped at ${TEMPLATE_ITEM_CAP} items.`,
-    );
-    context.templateCapWarned = true;
-  }
-  const children: UIElement[] = [];
-  for (let index = 0; index < itemCount; index++) {
-    if (itemized && !reserveNode(context)) break;
-    const child = convertComponent(
-      template.componentId,
-      { data: list[index], path: `${listPointer}/${index}` },
-      context,
-      depth + 1,
-      visited,
-    );
-    if (itemized) {
-      children.push({
-        $type: "ListViewItem",
-        ...(child ? { children: child } : {}),
-      });
-    } else if (child) {
-      children.push(child);
-    }
-  }
-  return { ...container, children };
-};
-
-function convertComponent(
-  componentId: string,
-  scope: Scope,
-  context: ConversionContext,
-  depth: number,
-  visited: Set<string>,
-): UIElement | null {
-  if (depth >= DEPTH_CAP) {
-    if (!context.depthWarned) {
-      context.warnings.push(`A2UI depth cap of ${DEPTH_CAP} was reached.`);
-      context.depthWarned = true;
-    }
-    return null;
-  }
-  if (visited.has(componentId)) {
-    context.warnings.push(`A2UI component cycle detected at "${componentId}".`);
-    return null;
-  }
-  const node = context.surface.components.get(componentId);
-  if (!node) {
-    context.warnings.push(`A2UI component "${componentId}" was not found.`);
-    return null;
-  }
-  const component = node["component"];
-
-  visited.add(componentId);
-  try {
-    if (typeof component !== "string") {
-      context.warnings.push(
-        `Unknown A2UI component "${String(component ?? "")}" was skipped.`,
-      );
-      return null;
-    }
-    const template = childTemplateOf(node["children"]);
-    if (
-      !SUPPORTED_COMPONENTS.has(component) &&
-      !context.keepUnknownComponents &&
-      !template
-    ) {
-      context.warnings.push(
-        `Unknown A2UI component "${component}" was skipped.`,
-      );
-      return null;
-    }
-    const cacheKey = context.cache
-      ? JSON.stringify([componentId, scope.path, depth])
-      : "";
-    let cached = context.cache?.get(cacheKey);
-    if (
-      cached &&
-      (context.evaluations + cached.evaluations > EVALUATION_BUDGET ||
-        [...cached.dependencies].some(
-          ([path, value]) =>
-            !Object.is(resolvePointer(context.surface.dataModel, path), value),
-        ))
-    )
-      cached = undefined;
-    let props: Record<string, unknown>;
-    let mapped: UIElement | undefined;
-    if (cached) {
-      props = cached.props;
-      mapped = cached.mapped;
-      context.evaluations += cached.evaluations;
-    } else {
-      props = {};
-      const dependencies = new Map<string, unknown>();
-      const evaluations = context.evaluations;
-      context.dependencies = dependencies;
-      context.scopePath = scope.path;
-      for (const [key, value] of Object.entries(node)) {
-        if (
-          key === "id" ||
-          key === "component" ||
-          key === "children" ||
-          key === "child"
-        )
-          continue;
-        const resolved = materialize(
-          value,
-          scope.data,
-          context,
-          key !== "checks",
-        );
-        if (resolved !== undefined) setOwnProperty(props, key, resolved);
-      }
-      context.dependencies = undefined;
-      mapped = mappedProps(node, props, context, scope);
-      if (context.cache && context.warnings.length === 0 && !mapped?.$action) {
-        cached = {
-          props,
-          mapped,
-          dependencies,
-          evaluations: context.evaluations - evaluations,
-        };
-        context.cache.set(cacheKey, cached);
-      }
-    }
-    if (
-      mapped &&
-      context.bindings &&
-      typeof mapped["name"] === "string" &&
-      INPUT_COMPONENTS.has(component)
-    ) {
-      const field = mapped.$type === "Checkbox" ? "checked" : "value";
-      const defaultField =
-        mapped.$type === "Checkbox" ? "defaultChecked" : "defaultValue";
-      const fallback =
-        mapped.$type === "Checkbox"
-          ? false
-          : mapped.$type === "CheckboxGroup"
-            ? []
-            : mapped.$type === "Slider"
-              ? mapped["min"]
-              : "";
-      const { [defaultField]: initialValue, ...rest } = mapped;
-      mapped = { ...rest, [field]: initialValue ?? mapped[field] ?? fallback };
-      context.bindings.set(mapped["name"] as string, {
-        value: mapped[field],
-        arrayValue:
-          component === "ChoicePicker" &&
-          mapped.$type !== "CheckboxGroup" &&
-          typeof props["value"] !== "string",
-      });
-    }
-
-    if (!mapped && SUPPORTED_COMPONENTS.has(component)) {
-      context.warnings.push(
-        `A2UI component "${component}" could not be mapped and was skipped.`,
-      );
-      return null;
-    }
-    const retained =
-      !mapped && context.keepUnknownComponents
-        ? {
-            $type: component,
-            ...Object.fromEntries(
-              Object.entries(props).filter(([key]) => !key.startsWith("$")),
-            ),
-          }
-        : undefined;
-    if (template) {
-      return convertTemplate(
-        node,
-        template,
-        scope,
-        context,
-        depth,
-        visited,
-        CHILD_LIST_COMPONENTS.has(component) ? mapped : retained,
-      );
-    }
-    if (!reserveNode(context)) return null;
-    const converted = mapped ?? retained;
-    if (!converted) return null;
-    recordBindings(node, props, converted, scope, context);
-    const children = childrenOf(node, scope, context, depth, visited);
-    if (mapped?.$type === "Button" && mapped["label"] === undefined) {
-      const label = textLabel(node, children, context);
-      if (label !== undefined) return { ...mapped, label };
-    }
-    const listChildren =
-      component === "List" && mapped?.$type === "ListView"
-        ? children.map((child) => ({ $type: "ListViewItem", children: child }))
-        : children;
-    if (
-      cached?.result &&
-      cached.children?.length === listChildren.length &&
-      cached.children.every((child, index) => child === listChildren[index])
-    )
-      return cached.result;
-    const result = {
-      ...converted,
-      ...(listChildren.length > 0 ? { children: listChildren } : {}),
-    };
-    if (cached) {
-      cached.children = listChildren;
-      cached.result = result;
-    }
-    return result;
-  } finally {
-    visited.delete(componentId);
-  }
-}
-
-export function convertSurfaceToUISpec(
-  surface: A2uiSurfaceState,
-  options: {
-    readonly keepUnknownComponents?: boolean;
-  } = {},
-): {
-  spec: UIElement | null;
-  warnings: string[];
-} {
-  return convertSurface(surface, options.keepUnknownComponents === true);
-}
-
-export const createLiveSurfaceConverter = (surface: A2uiSurfaceState) => {
-  const cache = new Map<string, CachedComponent>();
-  const templates = new Map<string, ExpressionPart[] | null>();
-  return (dataModel: unknown) => {
-    const bindings = new Map<string, A2uiBinding>();
-    const converted = convertSurface(
-      { ...surface, dataModel, [A2UI_SURFACE_ID]: sourceSurfaceId(surface) },
-      false,
-      bindings,
-      cache,
-      templates,
-      surface.dataModel,
-    );
-    return { ...converted, bindings };
-  };
-};
-
-function convertSurface(
-  surface: A2uiSurfaceState & { [A2UI_SURFACE_ID]?: string },
-  keepUnknownComponents: boolean,
-  bindings?: Map<string, A2uiBinding>,
-  cache?: Map<string, CachedComponent>,
-  templates = new Map<string, ExpressionPart[] | null>(),
-  stepModel: unknown = surface.dataModel,
-): { spec: UIElement | null; warnings: string[] } {
-  const warnings: string[] = [];
-  if (!surface.components.has("root")) {
-    return {
-      spec: null,
-      warnings: ['A2UI root component "root" was not found.'],
-    };
-  }
-  const context: ConversionContext = {
-    surface,
-    stepModel,
-    surfaceId: sourceSurfaceId(surface),
-    warnings,
-    emittedNodes: 0,
-    depthWarned: false,
-    budgetWarned: false,
-    templateCapWarned: false,
-    evaluations: 0,
-    evaluationBudgetWarned: false,
-    functionDepthWarned: false,
-    templates,
-    inputFields: new Map(),
-    textFields: new Map(),
-    boundActionEntries: [],
-    boundUserMessages: [],
-    keepUnknownComponents,
-    bindings,
-    cache,
-    dependencies: undefined,
-    scopePath: "",
-  };
-  try {
-    const spec = convertComponent(
-      "root",
-      { data: surface.dataModel, path: "" },
-      context,
-      0,
-      new Set(),
-    );
-    for (const { target, key, pointer } of context.boundActionEntries) {
-      const value = withFieldReferences(
-        target[key],
-        pointer,
-        context.inputFields,
-      );
-      if (value !== undefined) setOwnProperty(target, key, value);
-    }
-    for (const { action, pointer } of context.boundUserMessages) {
-      if (!context.textFields.get(pointer)) continue;
-      const fallback = action["userMessage"];
-      setOwnProperty(
-        action,
-        "userMessage",
-        typeof fallback === "string"
-          ? { $field: pointer, fallback }
-          : { $field: pointer },
-      );
-    }
-    return { spec, warnings };
-  } catch {
-    warnings.push("A2UI surface conversion encountered malformed input.");
-    return { spec: null, warnings };
-  }
-}