@elabs-ai/components-ai 4.2.0 → 5.0.0

package/src/a2ui/core/complete-json.ts

@@ -0,0 +1,81 @@
+/**
+ * complete-json.ts — close a PARTIAL JSON document so a streaming surface can be
+ * parsed and drawn before the model has finished (the A2UI counterpart of
+ * `JSXPreview`'s `completeJsxTag`).
+ *
+ * Strategy: one linear scan tracking the bracket stack, string state and escape
+ * state; then (1) close an open string, (2) drop a dangling `,` or supply `null`
+ * for a dangling `"key":`, (3) close every open bracket in reverse. The result is
+ * always syntactically valid JSON for any prefix of a valid document that has
+ * passed its first `{`. Semantic gaps (a half-typed prop value, a node without
+ * its `type` yet) are the validator's business — the renderer prunes what does
+ * not validate while streaming and keeps the last good tree.
+ */
+export function completeJson(text: string): string {
+  const stack: string[] = [];
+  let inString = false;
+  let escaped = false;
+  // Index just after the last STRUCTURALLY complete token, so a half-typed key
+  // (`{"ty`) can be cut rather than closed into `{"ty":null}`.
+  let lastGood = 0;
+  let lastNonWs = "";
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i] as string;
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') {
+        inString = false;
+        lastNonWs = ch;
+        lastGood = i + 1;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (ch === "{" || ch === "[") stack.push(ch === "{" ? "}" : "]");
+    else if (ch === "}" || ch === "]") stack.pop();
+    if (!/\s/.test(ch)) {
+      lastNonWs = ch;
+      lastGood = i + 1;
+    }
+  }
+
+  let out = text;
+  if (inString) {
+    // Inside a value string → close it. Inside a KEY (the string follows `{` or
+    // `,` inside an object) → cut it: a key without a value is not renderable.
+    const top = stack[stack.length - 1];
+    if (top === "}" && (lastNonWs === "{" || lastNonWs === ",")) out = text.slice(0, lastGood);
+    else out = escaped ? `${text.slice(0, -1)}"` : `${text}"`;
+    lastNonWs = out.trimEnd().slice(-1);
+  }
+  out = out.trimEnd();
+  if (lastNonWs === ",") out = out.slice(0, -1);
+  else if (lastNonWs === ":") out = `${out}null`;
+  // A `"key"` with no colon yet (`{"type"`) is also unfinished — cut it.
+  else if (lastNonWs === '"' && stack[stack.length - 1] === "}") {
+    const m = /(?:^|[{,])\s*"(?:[^"\\]|\\.)*"$/.exec(out);
+    if (m) out = out.slice(0, m.index + (out[m.index] === "{" || out[m.index] === "," ? 1 : 0));
+  }
+  out = out.replace(/,\s*$/, "");
+  return out + stack.reverse().join("");
+}
+
+/**
+ * Parse `text`, completing it first when `partial`. Returns `null` (never throws)
+ * when even the completed text is not JSON — the caller treats that as "no tree
+ * yet".
+ */
+export function parseSurfaceJson(text: string, partial = false): unknown | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(partial ? completeJson(trimmed) : trimmed);
+  } catch {
+    return null;
+  }
+}

package/src/a2ui/core/index.ts

@@ -0,0 +1,10 @@
+/**
+ * The engine-free A2UI core: protocol types, the catalog schema, the validator,
+ * the streaming JSON completer and the JSON-Schema builder. No React here —
+ * `pnpm gen` bundles this folder into the `brand-ui a2ui` CLI verbs.
+ */
+export * from "./spec";
+export * from "./validate";
+export * from "./complete-json";
+export * from "./schema";
+export { A2UI_CATALOG_SCHEMA, A2UI_CATALOG_VERSION } from "./catalog.generated";

package/src/a2ui/core/schema.ts

@@ -0,0 +1,111 @@
+/**
+ * schema.ts — the A2UI surface as a JSON Schema (draft 2020-12), built from the
+ * catalog so editors, structured-output modes and JSON-Schema validators see the
+ * SAME contract `validateA2uiSurface` enforces. Published as
+ * `@elabs-ai/components-ai/a2ui/schema.json` and printed by `brand-ui a2ui schema`.
+ */
+import {
+  A2UI_COMMON_PROPS,
+  A2UI_VERSION,
+  type A2uiCatalogSchema,
+  type A2uiCatalogTypeSchema,
+  type A2uiPropSchema,
+} from "./spec";
+
+export const A2UI_SURFACE_SCHEMA_ID =
+  "https://github.com/mreimitz/elabs-components/packages/ai/schemas/a2ui-surface.v1.schema.json";
+
+type JsonSchema = Record<string, unknown>;
+
+function propSchema(p: A2uiPropSchema): JsonSchema {
+  const base: JsonSchema = {};
+  if (p.description) base.description = p.description;
+  if (p.default !== undefined) base.default = p.default;
+  if (p.enum) return { ...base, enum: p.enum };
+  switch (p.type) {
+    case "string":
+    case "number":
+    case "boolean":
+    case "array":
+    case "object":
+      return { ...base, type: p.type };
+    case "node":
+      return {
+        ...base,
+        anyOf: [
+          { type: "string" },
+          { type: "number" },
+          { $ref: "#/$defs/element" },
+          { type: "array", items: { $ref: "#/$defs/node" } },
+        ],
+      };
+    default:
+      return base;
+  }
+}
+
+function elementSchema(type: string, entry: A2uiCatalogTypeSchema): JsonSchema {
+  const props = entry.builtin ? entry.props : { ...A2UI_COMMON_PROPS, ...entry.props };
+  const required = Object.entries(entry.props)
+    .filter(([, p]) => p.required)
+    .map(([name]) => name);
+  const properties: JsonSchema = {
+    type: { const: type },
+    id: { type: "string" },
+    props: {
+      type: "object",
+      properties: Object.fromEntries(Object.entries(props).map(([n, p]) => [n, propSchema(p)])),
+      ...(required.length ? { required } : {}),
+      additionalProperties: false,
+    },
+    on: {
+      type: "object",
+      properties: Object.fromEntries(
+        Object.keys(entry.events).map((ev) => [ev, { $ref: "#/$defs/action" }]),
+      ),
+      additionalProperties: false,
+    },
+  };
+  if (entry.children) properties.children = { type: "array", items: { $ref: "#/$defs/node" } };
+  return {
+    type: "object",
+    ...(entry.summary ? { description: entry.summary } : {}),
+    properties,
+    required: required.length ? ["type", "props"] : ["type"],
+    additionalProperties: false,
+  };
+}
+
+/** Build the JSON Schema document for `catalog`. Deterministic: sorted types. */
+export function buildA2uiSurfaceSchema(catalog: A2uiCatalogSchema): JsonSchema {
+  const types = Object.keys(catalog).sort();
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: A2UI_SURFACE_SCHEMA_ID,
+    title: "A2UI surface v1 (brand-ui)",
+    description:
+      "An agent-designed screen as data: a tree of brand-ui catalog nodes. Every `type` is a catalog entry, props are checked per type, and `on` binds catalog events to host actions. Text is a plain string child.",
+    type: "object",
+    properties: {
+      a2ui: { const: A2UI_VERSION },
+      title: { type: "string", description: "Accessible name of the surface region." },
+      root: { $ref: "#/$defs/node" },
+    },
+    required: ["a2ui", "root"],
+    additionalProperties: false,
+    $defs: {
+      action: {
+        type: "object",
+        properties: {
+          name: { type: "string", minLength: 1, description: "The host-side verb." },
+          payload: { description: "Free JSON attached to the action." },
+        },
+        required: ["name"],
+        additionalProperties: false,
+      },
+      node: { anyOf: [{ type: "string" }, { $ref: "#/$defs/element" }] },
+      element: { oneOf: types.map((t) => ({ $ref: `#/$defs/${t}` })) },
+      ...Object.fromEntries(types.map((t) => [t, elementSchema(t, catalog[t]!)])),
+    },
+  };
+}

package/src/a2ui/core/spec.ts

@@ -0,0 +1,148 @@
+/**
+ * spec.ts — the A2UI surface protocol (D2, the generative-UI path: "the agent
+ * describes a screen as DATA, validated against a catalog").
+ *
+ * An `A2uiSurface` is plain JSON an agent emits — a tree of catalog nodes. It is
+ * NOT JSX (that is `JSXPreview`, the escape hatch) and it carries no code: every
+ * `type` must exist in the catalog, every prop is checked against that type's
+ * schema, and interaction is a named `on` binding the HOST app resolves
+ * (`onAction`). brand-ui renders the tree; the app owns the model call and what
+ * an action means (D5).
+ *
+ * Engine-free on purpose (no React import): `validateA2uiSurface` runs in the
+ * browser, in Node, and — bundled by `pnpm gen` — inside the dependency-free
+ * `brand-ui a2ui` CLI, so the CLI and `@elabs-ai/components-ai` can never
+ * disagree about what a valid surface is.
+ */
+
+/** Protocol version this module understands (`"a2ui": "1"` on the root). */
+export const A2UI_VERSION = "1";
+
+/**
+ * A JSON value an agent may place in a prop. The `object` arm is there for
+ * authoring: an app hands typed records (an interface for a KPI, a chart row) to
+ * a spec literal without an index-signature cast; the runtime validator, not the
+ * type, is what decides whether a value is acceptable.
+ */
+export type A2uiJson =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | readonly A2uiJson[]
+  | { readonly [key: string]: A2uiJson }
+  | object;
+
+/**
+ * A node's prop value: a JSON value, or — for props the catalog types as `node`
+ * (`title`, `description`, `actions`, …) — a nested node or list of nodes.
+ */
+export type A2uiPropValue = A2uiJson | A2uiNode | A2uiNode[];
+
+/** What a bound event sends to the host: a NAME (the app's verb) and a payload. */
+export interface A2uiAction {
+  /** The host-side verb, e.g. `"approve"`, `"open-order"`. Never a code string. */
+  name: string;
+  /** Free JSON the agent attaches (an id, a row, a form draft). */
+  payload?: A2uiJson;
+}
+
+/** An element node. Text nodes are plain strings inside `children`. */
+export interface A2uiElement {
+  /** A catalog type — `"Card"`, `"Button"`, `"Stack"`, … Unknown types are errors. */
+  type: string;
+  /** Optional stable id (→ `data-a2ui-id`), useful for the host to address a node. */
+  id?: string;
+  /** Props checked against the catalog entry's schema. */
+  props?: Record<string, A2uiPropValue>;
+  /** Child nodes — only for catalog types that accept children. */
+  children?: A2uiNode[];
+  /**
+   * Event bindings by the catalog's event vocabulary (`click`, `change`, …) →
+   * the action the host receives. The renderer wires the React handler.
+   */
+  on?: Record<string, A2uiAction>;
+}
+
+export type A2uiNode = string | A2uiElement;
+
+/** The document an agent emits (the whole tool-call result / message part). */
+export interface A2uiSurfaceSpec {
+  /** Protocol version — currently always `"1"`. */
+  a2ui: string;
+  /** Optional accessible name for the surface region. */
+  title?: string;
+  /** The root node — usually a `Stack`, `Grid` or `Card`. */
+  root: A2uiNode;
+}
+
+/** The value shape of one prop in a catalog entry. */
+export type A2uiPropType = "string" | "number" | "boolean" | "node" | "array" | "object" | "any";
+
+export interface A2uiPropSchema {
+  type: A2uiPropType;
+  /** Closed set of allowed values (strings or numbers); `type` is then informational. */
+  enum?: (string | number)[];
+  required?: boolean;
+  default?: A2uiJson;
+  description?: string;
+}
+
+/** One catalog type — what an agent may emit for it. */
+export interface A2uiCatalogTypeSchema {
+  /** Drawn by the renderer itself (`Stack`, `Grid`), not a library component. */
+  builtin?: boolean;
+  /** May carry `children`. */
+  children: boolean;
+  /** One line for the agent (rendered by `brand-ui a2ui catalog`). */
+  summary?: string;
+  /** Prop name → schema. Anything not listed (and not in `A2UI_COMMON_PROPS`) is an error. */
+  props: Record<string, A2uiPropSchema>;
+  /** Event vocabulary → React handler prop (`click` → `onClick`). */
+  events: Record<string, string>;
+  /** Where the component comes from (`@elabs-ai/components-ui`) or `"builtin"`. */
+  source: string;
+}
+
+export type A2uiCatalogSchema = Record<string, A2uiCatalogTypeSchema>;
+
+/**
+ * Props every non-builtin element accepts on top of its own schema: the DOM
+ * attributes that are safe for an agent to set. Deliberately NO `className` or
+ * `style` — a surface inherits the app's theme and tokens; it never restyles.
+ */
+export const A2UI_COMMON_PROPS: Record<string, A2uiPropSchema> = {
+  id: { type: "string" },
+  title: { type: "string" },
+  role: { type: "string" },
+  hidden: { type: "boolean" },
+  lang: { type: "string" },
+  dir: { type: "string", enum: ["ltr", "rtl", "auto"] },
+  "aria-label": { type: "string" },
+  "aria-labelledby": { type: "string" },
+  "aria-describedby": { type: "string" },
+  "aria-hidden": { type: "boolean" },
+};
+
+/** Machine-readable problem codes from `validateA2uiSurface`. */
+export type A2uiErrorCode =
+  | "invalid-root"
+  | "unsupported-version"
+  | "invalid-node"
+  | "unknown-type"
+  | "unknown-prop"
+  | "missing-prop"
+  | "invalid-value"
+  | "children-not-allowed"
+  | "unknown-event"
+  | "invalid-action";
+
+export interface A2uiError {
+  /** JSON-pointer-ish path: `root.children[2].props.variant`. */
+  path: string;
+  /** The path of the NODE that owns the problem (`root.children[2]`) — what a streaming renderer prunes. */
+  node: string;
+  code: A2uiErrorCode;
+  message: string;
+}

package/src/a2ui/core/validate.ts

@@ -0,0 +1,266 @@
+/**
+ * validate.ts — `validateA2uiSurface`: is this JSON a surface the catalog can
+ * render? Never throws, never repairs; every problem is a typed `A2uiError` with
+ * a path, so an agent can fix its own output from the message and a host can
+ * prune the failing subtree while streaming (`invalidNodePaths`).
+ */
+import {
+  A2UI_COMMON_PROPS,
+  A2UI_VERSION,
+  type A2uiAction,
+  type A2uiCatalogSchema,
+  type A2uiCatalogTypeSchema,
+  type A2uiElement,
+  type A2uiError,
+  type A2uiNode,
+  type A2uiPropSchema,
+  type A2uiSurfaceSpec,
+} from "./spec";
+
+export type A2uiValidation =
+  | { ok: true; spec: A2uiSurfaceSpec; errors: [] }
+  | { ok: false; spec: A2uiSurfaceSpec | null; errors: A2uiError[] };
+
+type Report = (e: Omit<A2uiError, "node">) => void;
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** An element-shaped value: an object with a string `type`. */
+export const isA2uiElement = (v: unknown): v is A2uiElement =>
+  isRecord(v) && typeof v.type === "string";
+
+/** Reserved keys on an element — anything else is a typo, not a prop. */
+const ELEMENT_KEYS = new Set(["type", "id", "props", "children", "on"]);
+
+function checkValue(
+  value: unknown,
+  schema: A2uiPropSchema,
+  path: string,
+  report: Report,
+  errors: A2uiError[],
+  catalog: A2uiCatalogSchema,
+): void {
+  if (schema.enum) {
+    if (!schema.enum.includes(value as string | number)) {
+      report({
+        path,
+        code: "invalid-value",
+        message: `must be one of ${schema.enum.map((e) => JSON.stringify(e)).join(", ")}; got ${JSON.stringify(value)}`,
+      });
+    }
+    return;
+  }
+  const t = schema.type;
+  const bad = (expected: string) =>
+    report({
+      path,
+      code: "invalid-value",
+      message: `expected ${expected}; got ${Array.isArray(value) ? "array" : typeof value}`,
+    });
+  switch (t) {
+    case "string":
+      if (typeof value !== "string") bad("a string");
+      break;
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) bad("a number");
+      break;
+    case "boolean":
+      if (typeof value !== "boolean") bad("a boolean");
+      break;
+    case "array":
+      if (!Array.isArray(value)) bad("an array");
+      break;
+    case "object":
+      if (!isRecord(value)) bad("an object");
+      break;
+    case "node": {
+      // Text, a number, one element, or a list of nodes — each element validated.
+      const items = Array.isArray(value) ? value : [value];
+      items.forEach((item, i) => {
+        const p = Array.isArray(value) ? `${path}[${i}]` : path;
+        if (typeof item === "string" || typeof item === "number") return;
+        if (isA2uiElement(item)) return checkNode(item, p, errors, catalog);
+        report({
+          path: p,
+          code: "invalid-value",
+          message: "expected text or a node ({ type, … })",
+        });
+      });
+      break;
+    }
+    case "any":
+      break;
+  }
+}
+
+function checkAction(value: unknown, path: string, report: Report): value is A2uiAction {
+  if (!isRecord(value) || typeof value.name !== "string" || !value.name.trim()) {
+    report({
+      path,
+      code: "invalid-action",
+      message: 'an action is { "name": "<host verb>", "payload"?: <json> }',
+    });
+    return false;
+  }
+  return true;
+}
+
+function checkNode(
+  node: unknown,
+  path: string,
+  errors: A2uiError[],
+  catalog: A2uiCatalogSchema,
+): void {
+  const report: Report = (e) => errors.push({ ...e, node: path });
+  if (typeof node === "string") return;
+  if (!isA2uiElement(node)) {
+    report({
+      path,
+      code: "invalid-node",
+      message: 'a node is a string or { "type": "<catalog type>", … }',
+    });
+    return;
+  }
+  const entry: A2uiCatalogTypeSchema | undefined = catalog[node.type];
+  if (!entry) {
+    report({
+      path: `${path}.type`,
+      code: "unknown-type",
+      message: `"${node.type}" is not in the catalog (run \`brand-ui a2ui catalog\`)`,
+    });
+    return;
+  }
+  for (const key of Object.keys(node)) {
+    if (!ELEMENT_KEYS.has(key)) {
+      report({
+        path: `${path}.${key}`,
+        code: "invalid-node",
+        message: `unknown key "${key}" — a node has type, id, props, children, on`,
+      });
+    }
+  }
+  if (node.id !== undefined && typeof node.id !== "string") {
+    report({ path: `${path}.id`, code: "invalid-value", message: "id must be a string" });
+  }
+  const props = node.props;
+  if (props !== undefined && !isRecord(props)) {
+    report({ path: `${path}.props`, code: "invalid-value", message: "props must be an object" });
+  } else {
+    const allowed: Record<string, A2uiPropSchema> = entry.builtin
+      ? entry.props
+      : { ...A2UI_COMMON_PROPS, ...entry.props };
+    for (const [name, schema] of Object.entries(entry.props)) {
+      if (schema.required && (props === undefined || props[name] === undefined)) {
+        report({
+          path: `${path}.props.${name}`,
+          code: "missing-prop",
+          message: `"${node.type}" requires "${name}"`,
+        });
+      }
+    }
+    if (props) {
+      for (const [name, value] of Object.entries(props)) {
+        const schema = allowed[name];
+        if (!schema) {
+          report({
+            path: `${path}.props.${name}`,
+            code: "unknown-prop",
+            message: `"${name}" is not a prop of "${node.type}" (allowed: ${Object.keys(allowed).join(", ") || "none"})`,
+          });
+          continue;
+        }
+        checkValue(value, schema, `${path}.props.${name}`, report, errors, catalog);
+      }
+    }
+  }
+  if (node.children !== undefined) {
+    if (!entry.children) {
+      report({
+        path: `${path}.children`,
+        code: "children-not-allowed",
+        message: `"${node.type}" does not take children`,
+      });
+    } else if (!Array.isArray(node.children)) {
+      report({
+        path: `${path}.children`,
+        code: "invalid-value",
+        message: "children must be an array of nodes",
+      });
+    } else {
+      node.children.forEach((child, i) =>
+        checkNode(child, `${path}.children[${i}]`, errors, catalog),
+      );
+    }
+  }
+  if (node.on !== undefined) {
+    if (!isRecord(node.on)) {
+      report({ path: `${path}.on`, code: "invalid-value", message: "on must be an object" });
+    } else {
+      for (const [event, action] of Object.entries(node.on)) {
+        if (!entry.events[event]) {
+          report({
+            path: `${path}.on.${event}`,
+            code: "unknown-event",
+            message: `"${node.type}" has no "${event}" event (${Object.keys(entry.events).join(", ") || "none"})`,
+          });
+          continue;
+        }
+        checkAction(action, `${path}.on.${event}`, report);
+      }
+    }
+  }
+}
+
+/**
+ * Validate an untrusted value (a parsed tool result, a streamed JSON prefix)
+ * against `catalog`. `ok: false` carries every problem found, in document order.
+ */
+export function validateA2uiSurface(input: unknown, catalog: A2uiCatalogSchema): A2uiValidation {
+  const errors: A2uiError[] = [];
+  const report: Report = (e) => errors.push({ ...e, node: "root" });
+  if (!isRecord(input)) {
+    return {
+      ok: false,
+      spec: null,
+      errors: [
+        {
+          path: "",
+          node: "root",
+          code: "invalid-root",
+          message: 'expected { "a2ui": "1", "root": … }',
+        },
+      ],
+    };
+  }
+  if (input.a2ui !== A2UI_VERSION) {
+    report({
+      path: "a2ui",
+      code: "unsupported-version",
+      message: `expected "a2ui": "${A2UI_VERSION}"; got ${JSON.stringify(input.a2ui)}`,
+    });
+  }
+  if (input.title !== undefined && typeof input.title !== "string") {
+    report({ path: "title", code: "invalid-value", message: "title must be a string" });
+  }
+  if (input.root === undefined) {
+    report({ path: "root", code: "invalid-root", message: "root is required" });
+  } else {
+    checkNode(input.root, "root", errors, catalog);
+  }
+  const spec = input as unknown as A2uiSurfaceSpec;
+  return errors.length ? { ok: false, spec, errors } : { ok: true, spec, errors: [] };
+}
+
+/**
+ * The set of NODE paths (`root`, `root.children[1]`, …) that own at least one
+ * error — the renderer drops exactly those subtrees while a surface is still
+ * streaming, so a half-arrived node never blanks its finished siblings.
+ */
+export function invalidNodePaths(errors: A2uiError[]): Set<string> {
+  return new Set(errors.map((e) => e.node));
+}
+
+/** Re-export for hosts that want the version without importing the whole spec module. */
+export { A2UI_VERSION };
+export type { A2uiNode };

package/src/a2ui/index.ts

@@ -0,0 +1,7 @@
+/**
+ * A2UI — the generative-UI path (D2): an agent describes a screen as data, brand-ui
+ * validates it against a catalog and renders it with the real components.
+ */
+export * from "./a2ui-surface";
+export * from "./ui-catalog";
+export * from "./core";