cortena-ui 1.1.0 → 1.2.0

package/src/a2ui/index.ts

@@ -0,0 +1,73 @@
+/**
+ * cortena-ui A2UI entry point.
+ *
+ * Layer 1 of `cortenaUI&Design/05-agent-ui.md`: the declarative vocabulary an
+ * agent draws with, bound to this package, plus the React renderer that turns
+ * an A2UI payload into cortena-ui components and user events back into
+ * structured actions.
+ *
+ * ```tsx
+ * import { A2UIRenderer, defaultCatalogue } from "cortena-ui";
+ *
+ * <A2UIRenderer
+ *   message={customEvent.value}          // the AG-UI CUSTOM event payload
+ *   catalogue={defaultCatalogue}
+ *   onAction={(action) => run.send(action)}
+ *   resolveDataSource={(id) => tableSources[id]}
+ * />
+ * ```
+ */
+
+export {
+  A2UI_CATALOGUE_ID,
+  catalogueNames,
+  defaultCatalogue,
+} from "./catalogue";
+export type { A2UICatalogue, A2UICatalogueEntry, A2UIExample, A2UIGroup } from "./catalogue";
+export { buildCatalogueDoc, catalogueMarkdown, exampleMessages } from "./catalogue-doc";
+export type { A2UICatalogueDoc, A2UIComponentDoc, JsonSchema } from "./catalogue-doc";
+export {
+  A2UI_DEFAULT_SURFACE_ID,
+  A2UI_VERSION,
+  foldMessages,
+  getAtPointer,
+  isDataBinding,
+  parseA2UIMessages,
+  pointerSegments,
+  readAction,
+  readChildren,
+  readComponent,
+  resolvePointer,
+  resolveValue,
+  setAtPointer,
+} from "./message";
+export type {
+  A2UIAction,
+  A2UIActionSpec,
+  A2UIBeginRendering,
+  A2UIChildList,
+  A2UIChildren,
+  A2UIComponentSpec,
+  A2UICreateSurface,
+  A2UIDataBinding,
+  A2UIDeleteSurface,
+  A2UIFoldResult,
+  A2UIMessage,
+  A2UIMessageInput,
+  A2UIPropertyValue,
+  A2UISurface,
+  A2UIUpdateComponents,
+  A2UIUpdateDataModel,
+} from "./message";
+export { A2UIRenderer } from "./renderer";
+export type { A2UIRendererProps } from "./renderer";
+export { A2UIErrorCard } from "./views";
+export type {
+  A2UIColumn,
+  A2UINodeInfo,
+  A2UIResolvedAction,
+  A2UIRow,
+  A2UITableSource,
+  A2UIView,
+  A2UIViewProps,
+} from "./views";

package/src/a2ui/message.ts

@@ -0,0 +1,590 @@
+/**
+ * A2UI message layer.
+ *
+ * The wire format cortena-ui accepts, and the fold from a stream of messages
+ * onto a set of surfaces. Deliberately free of React so it can be reused by a
+ * canvas host, a test fixture, or the catalogue doc generator.
+ *
+ * ## Two dialects, one fold
+ *
+ * **v0.9** is the current A2UI protocol (`createSurface`, `updateComponents`,
+ * `updateDataModel`, `deleteSurface`) and is what an agent should emit.
+ *
+ * **v0.8** is what Cortena already speaks: core bundles Google's A2UI Lit
+ * renderer at `src/canvas-host/a2ui/` and its `A2uiMessageProcessor` handles
+ * `beginRendering`, `surfaceUpdate`, `dataModelUpdate` and `deleteSurface`.
+ * The `canvas` agent tool pushes exactly those, as JSON lines, through
+ * `canvas.a2ui.pushJSONL`. Accepting both means one renderer serves the chat,
+ * the web canvas panel and every payload already written against the native
+ * nodes.
+ *
+ * ## Transport
+ *
+ * Per `05-agent-ui.md`, an A2UI block travels as an AG-UI `CUSTOM` event. The
+ * event value is a message, an array of messages, or the JSONL text the canvas
+ * tool sends; {@link parseA2UIMessages} takes all three.
+ */
+
+/** Surface id used when a message omits one, matching core's Lit processor. */
+export const A2UI_DEFAULT_SURFACE_ID = "@default";
+
+/** Protocol version this package speaks. */
+export const A2UI_VERSION = "v0.9";
+
+/** A reference to a value in the surface's data model, as a JSON pointer. */
+export interface A2UIDataBinding {
+  path: string;
+}
+
+/**
+ * A property value as an agent writes it: a literal, a data binding, or one of
+ * the v0.8 literal wrappers the Lit renderer accepts.
+ */
+export type A2UIPropertyValue =
+  | string
+  | number
+  | boolean
+  | null
+  | A2UIDataBinding
+  | { literal: unknown }
+  | { literalString: string }
+  | readonly A2UIPropertyValue[]
+  | { readonly [key: string]: unknown };
+
+/**
+ * A component's children. v0.9 uses a plain id array or a `{ componentId, path }`
+ * template; v0.8 wraps the same two in `explicitList` / `template`.
+ */
+export type A2UIChildList =
+  | readonly string[]
+  | { componentId: string; path: string }
+  | { explicitList: readonly string[] }
+  | { template: { componentId: string; dataBinding: string } };
+
+/** An action an agent attaches to an interactive property. */
+export type A2UIActionSpec =
+  | string
+  | { event: { name: string; context?: Record<string, unknown> } }
+  | { name: string; context?: Record<string, unknown> };
+
+/**
+ * One component in a surface.
+ *
+ * v0.9 is flat — `{ id, component: "Text", text: "hi" }` — and v0.8 wraps the
+ * properties under the type name — `{ id, component: { Text: { text: "hi" } } }`.
+ */
+export interface A2UIComponentSpec {
+  id: string;
+  component: string | Record<string, Record<string, unknown>>;
+  children?: A2UIChildList;
+  /** v0.8 flex weight; carried through but not used for layout here. */
+  weight?: number | string;
+  [property: string]: unknown;
+}
+
+export interface A2UICreateSurface {
+  surfaceId?: string;
+  catalogId?: string;
+  /** Not in the v0.9 schema; accepted so a single message can seed a surface. */
+  root?: string;
+  sendDataModel?: boolean;
+}
+
+export interface A2UIUpdateComponents {
+  surfaceId?: string;
+  components: A2UIComponentSpec[];
+  root?: string;
+}
+
+export interface A2UIUpdateDataModel {
+  surfaceId?: string;
+  path?: string;
+  value?: unknown;
+  /** v0.8 spelling of `value`. */
+  contents?: unknown;
+}
+
+export interface A2UIBeginRendering {
+  surfaceId?: string;
+  root?: string;
+  styles?: Record<string, unknown>;
+}
+
+export interface A2UIDeleteSurface {
+  surfaceId?: string;
+}
+
+/** One message on the wire. Exactly one operation key is read per message. */
+export interface A2UIMessage {
+  version?: string;
+  createSurface?: A2UICreateSurface;
+  updateComponents?: A2UIUpdateComponents;
+  updateDataModel?: A2UIUpdateDataModel;
+  deleteSurface?: A2UIDeleteSurface;
+  /** v0.8 */
+  beginRendering?: A2UIBeginRendering;
+  /** v0.8 */
+  surfaceUpdate?: A2UIUpdateComponents;
+  /** v0.8 */
+  dataModelUpdate?: A2UIUpdateDataModel;
+}
+
+/**
+ * Everything the renderer's `message` prop takes: one message, a list of them
+ * (the AG-UI `CUSTOM` payload), or JSONL / a JSON array as text (the canvas
+ * tool's `a2ui_push`).
+ */
+export type A2UIMessageInput = A2UIMessage | readonly A2UIMessage[] | string | null | undefined;
+
+/** A folded surface: what the renderer draws. */
+export interface A2UISurface {
+  id: string;
+  /** Id of the root component; `undefined` until a message names one. */
+  root: string | undefined;
+  components: ReadonlyMap<string, A2UIComponentSpec>;
+  dataModel: Record<string, unknown>;
+  styles: Record<string, unknown>;
+}
+
+export interface A2UIFoldResult {
+  surfaces: A2UISurface[];
+  /** One line per malformed message; the renderer shows these in an error card. */
+  errors: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** True when a value is a `{ path }` data binding rather than a literal object. */
+export function isDataBinding(value: unknown): value is A2UIDataBinding {
+  return isRecord(value) && typeof value.path === "string" && Object.keys(value).length === 1;
+}
+
+/**
+ * Parse whatever arrived into a message list.
+ *
+ * A string is tried as JSON first (an array or a single message) and then as
+ * JSONL, which is the form `canvas.a2ui.pushJSONL` sends. A line that does not
+ * parse is reported rather than dropped: silently rendering three of four
+ * pushed messages is the failure mode this returns errors for.
+ */
+export function parseA2UIMessages(input: A2UIMessageInput): {
+  messages: A2UIMessage[];
+  errors: string[];
+} {
+  if (input === null || input === undefined) {
+    return { messages: [], errors: [] };
+  }
+  if (typeof input === "string") {
+    const trimmed = input.trim();
+    if (!trimmed) {
+      return { messages: [], errors: [] };
+    }
+    if (trimmed.startsWith("[")) {
+      try {
+        const parsed: unknown = JSON.parse(trimmed);
+        if (Array.isArray(parsed)) {
+          return collect(parsed);
+        }
+        return { messages: [], errors: ["Expected an array of A2UI messages."] };
+      } catch (error) {
+        return { messages: [], errors: [`Malformed JSON: ${errorText(error)}`] };
+      }
+    }
+    const messages: A2UIMessage[] = [];
+    const errors: string[] = [];
+    const lines = trimmed.split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = (lines[index] ?? "").trim();
+      if (!line) {
+        continue;
+      }
+      try {
+        const parsed: unknown = JSON.parse(line);
+        const one = collect([parsed]);
+        messages.push(...one.messages);
+        errors.push(...one.errors.map((text) => `Line ${index + 1}: ${text}`));
+      } catch (error) {
+        errors.push(`Line ${index + 1}: malformed JSON (${errorText(error)}).`);
+      }
+    }
+    return { messages, errors };
+  }
+  return collect(Array.isArray(input) ? input : [input]);
+}
+
+function collect(values: readonly unknown[]): { messages: A2UIMessage[]; errors: string[] } {
+  const messages: A2UIMessage[] = [];
+  const errors: string[] = [];
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (!isRecord(value)) {
+      errors.push(`Message ${index + 1} is not an object.`);
+      continue;
+    }
+    messages.push(value as A2UIMessage);
+  }
+  return { messages, errors };
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+interface MutableSurface {
+  id: string;
+  root: string | undefined;
+  components: Map<string, A2UIComponentSpec>;
+  dataModel: Record<string, unknown>;
+  styles: Record<string, unknown>;
+}
+
+/**
+ * Fold a message stream onto surfaces.
+ *
+ * Updates accumulate: a later `updateComponents` replaces the components it
+ * names and leaves the rest, and a later `updateDataModel` writes at its path
+ * only. That is what makes the JSONL push form work — the agent sends the
+ * shell, then the rows, then a correction, and each one folds onto the same
+ * surface.
+ */
+export function foldMessages(input: A2UIMessageInput): A2UIFoldResult {
+  const { messages, errors } = parseA2UIMessages(input);
+  const surfaces = new Map<string, MutableSurface>();
+  const order: string[] = [];
+
+  const surfaceFor = (id: string | undefined): MutableSurface => {
+    const key = id && id.trim() ? id : A2UI_DEFAULT_SURFACE_ID;
+    let surface = surfaces.get(key);
+    if (!surface) {
+      surface = { id: key, root: undefined, components: new Map(), dataModel: {}, styles: {} };
+      surfaces.set(key, surface);
+      order.push(key);
+    }
+    return surface;
+  };
+
+  const applyComponents = (payload: A2UIUpdateComponents | undefined, index: number): void => {
+    if (!payload) {
+      return;
+    }
+    const surface = surfaceFor(payload.surfaceId);
+    if (!Array.isArray(payload.components)) {
+      errors.push(`Message ${index + 1}: components must be an array.`);
+      return;
+    }
+    for (const spec of payload.components) {
+      if (!isRecord(spec) || typeof spec.id !== "string" || !spec.id) {
+        errors.push(`Message ${index + 1}: a component is missing a string id.`);
+        continue;
+      }
+      surface.components.set(spec.id, spec as A2UIComponentSpec);
+    }
+    if (typeof payload.root === "string" && payload.root) {
+      surface.root = payload.root;
+    }
+  };
+
+  const applyData = (payload: A2UIUpdateDataModel | undefined): void => {
+    if (!payload) {
+      return;
+    }
+    const surface = surfaceFor(payload.surfaceId);
+    const value = payload.value !== undefined ? payload.value : payload.contents;
+    const path = payload.path && payload.path.trim() ? payload.path : "/";
+    surface.dataModel = setAtPointer(surface.dataModel, path, value);
+  };
+
+  for (let index = 0; index < messages.length; index += 1) {
+    const message = messages[index];
+    if (!message) {
+      continue;
+    }
+    if (message.createSurface) {
+      const surface = surfaceFor(message.createSurface.surfaceId);
+      if (typeof message.createSurface.root === "string" && message.createSurface.root) {
+        surface.root = message.createSurface.root;
+      }
+    }
+    if (message.beginRendering) {
+      const surface = surfaceFor(message.beginRendering.surfaceId);
+      if (typeof message.beginRendering.root === "string" && message.beginRendering.root) {
+        surface.root = message.beginRendering.root;
+      }
+      if (isRecord(message.beginRendering.styles)) {
+        surface.styles = { ...surface.styles, ...message.beginRendering.styles };
+      }
+    }
+    applyComponents(message.updateComponents, index);
+    applyComponents(message.surfaceUpdate, index);
+    applyData(message.updateDataModel);
+    applyData(message.dataModelUpdate);
+    if (message.deleteSurface) {
+      const key = message.deleteSurface.surfaceId ?? A2UI_DEFAULT_SURFACE_ID;
+      surfaces.delete(key);
+      const at = order.indexOf(key);
+      if (at !== -1) {
+        order.splice(at, 1);
+      }
+    }
+    const known =
+      message.createSurface ??
+      message.updateComponents ??
+      message.updateDataModel ??
+      message.deleteSurface ??
+      message.beginRendering ??
+      message.surfaceUpdate ??
+      message.dataModelUpdate;
+    if (!known) {
+      errors.push(
+        `Message ${index + 1}: no known operation (createSurface, updateComponents, updateDataModel, deleteSurface, beginRendering, surfaceUpdate, dataModelUpdate).`,
+      );
+    }
+  }
+
+  const result: A2UISurface[] = [];
+  for (const key of order) {
+    const surface = surfaces.get(key);
+    if (!surface) {
+      continue;
+    }
+    result.push({
+      id: surface.id,
+      root: surface.root ?? defaultRoot(surface.components),
+      components: surface.components,
+      dataModel: surface.dataModel,
+      styles: surface.styles,
+    });
+  }
+  return { surfaces: result, errors };
+}
+
+/** No explicit root: prefer the conventional `root` id, else the first component. */
+function defaultRoot(components: ReadonlyMap<string, A2UIComponentSpec>): string | undefined {
+  if (components.has("root")) {
+    return "root";
+  }
+  for (const id of components.keys()) {
+    return id;
+  }
+  return undefined;
+}
+
+/** Split a JSON pointer into its unescaped segments. */
+export function pointerSegments(pointer: string): string[] {
+  const trimmed = pointer.trim();
+  if (!trimmed || trimmed === "/" || trimmed === ".") {
+    return [];
+  }
+  const body = trimmed.startsWith("/") ? trimmed.slice(1) : trimmed;
+  return body
+    .split("/")
+    .filter((segment) => segment !== "")
+    .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+/** Resolve a possibly relative pointer against a data context. */
+export function resolvePointer(path: string, contextPath: string): string {
+  if (path.startsWith("/")) {
+    return path;
+  }
+  const relative = path === "." || path === "" ? "" : path.replace(/^\.?\//, "");
+  const base = contextPath === "/" || !contextPath ? "" : contextPath.replace(/\/$/, "");
+  if (!relative) {
+    return base || "/";
+  }
+  return `${base}/${relative}`;
+}
+
+/** Read a JSON pointer out of the data model. */
+export function getAtPointer(model: unknown, pointer: string): unknown {
+  let current: unknown = model;
+  for (const segment of pointerSegments(pointer)) {
+    if (Array.isArray(current)) {
+      const index = Number(segment);
+      current = Number.isInteger(index) ? current[index] : undefined;
+    } else if (isRecord(current)) {
+      current = current[segment];
+    } else {
+      return undefined;
+    }
+    if (current === undefined) {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+/**
+ * Write a JSON pointer into the data model, returning a new model.
+ *
+ * Immutable because the renderer keeps the model in React state: a mutation in
+ * place would not re-render, which is the kind of silent nothing-happens bug
+ * that is hard to see in a browser test.
+ */
+export function setAtPointer(
+  model: Record<string, unknown>,
+  pointer: string,
+  value: unknown,
+): Record<string, unknown> {
+  const segments = pointerSegments(pointer);
+  if (segments.length === 0) {
+    return isRecord(value) ? { ...value } : {};
+  }
+  const clone: Record<string, unknown> = { ...model };
+  let cursor: Record<string, unknown> | unknown[] = clone;
+  for (let index = 0; index < segments.length - 1; index += 1) {
+    const segment = segments[index] ?? "";
+    const nextSegment = segments[index + 1] ?? "";
+    const wantsArray = /^\d+$/.test(nextSegment);
+    const existing: unknown = Array.isArray(cursor)
+      ? cursor[Number(segment)]
+      : (cursor as Record<string, unknown>)[segment];
+    let next: Record<string, unknown> | unknown[];
+    if (Array.isArray(existing)) {
+      next = [...existing];
+    } else if (isRecord(existing)) {
+      next = { ...existing };
+    } else {
+      next = wantsArray ? [] : {};
+    }
+    if (Array.isArray(cursor)) {
+      cursor[Number(segment)] = next;
+    } else {
+      (cursor as Record<string, unknown>)[segment] = next;
+    }
+    cursor = next;
+  }
+  const last = segments[segments.length - 1] ?? "";
+  if (Array.isArray(cursor)) {
+    cursor[Number(last)] = value;
+  } else {
+    (cursor as Record<string, unknown>)[last] = value;
+  }
+  return clone;
+}
+
+/** Normalise the children of a component spec into a single description. */
+export type A2UIChildren =
+  | { kind: "list"; ids: readonly string[] }
+  | { kind: "template"; componentId: string; path: string }
+  | { kind: "none" };
+
+export function readChildren(spec: A2UIComponentSpec, properties: Record<string, unknown>): A2UIChildren {
+  const raw = (spec.children ?? properties.children) as A2UIChildList | undefined;
+  if (!raw) {
+    return { kind: "none" };
+  }
+  if (Array.isArray(raw)) {
+    return { kind: "list", ids: raw.filter((id): id is string => typeof id === "string") };
+  }
+  if (isRecord(raw)) {
+    const record: Record<string, unknown> = raw;
+    const explicitList = record.explicitList;
+    if (Array.isArray(explicitList)) {
+      return {
+        kind: "list",
+        ids: explicitList.filter((id): id is string => typeof id === "string"),
+      };
+    }
+    const template = record.template;
+    if (isRecord(template)) {
+      const { componentId, dataBinding } = template;
+      if (typeof componentId === "string" && typeof dataBinding === "string") {
+        return { kind: "template", componentId, path: dataBinding };
+      }
+    }
+    if (typeof record.componentId === "string" && typeof record.path === "string") {
+      return { kind: "template", componentId: record.componentId, path: record.path };
+    }
+  }
+  return { kind: "none" };
+}
+
+/**
+ * Split a component spec into its type name and its raw (unresolved) properties,
+ * across both dialects. Returns `undefined` when the spec names no type.
+ */
+export function readComponent(
+  spec: A2UIComponentSpec,
+): { name: string; properties: Record<string, unknown> } | undefined {
+  if (typeof spec.component === "string") {
+    const { id: _id, component: _component, children: _children, weight: _weight, ...rest } = spec;
+    return { name: spec.component, properties: rest };
+  }
+  if (isRecord(spec.component)) {
+    const name = Object.keys(spec.component)[0];
+    if (!name) {
+      return undefined;
+    }
+    const properties = (spec.component as Record<string, unknown>)[name];
+    return { name, properties: isRecord(properties) ? properties : {} };
+  }
+  return undefined;
+}
+
+/**
+ * Resolve one property value against the data model.
+ *
+ * `{ path }` reads the model, `{ literal }` / `{ literalString }` unwrap, and
+ * everything else is returned as written, recursing through arrays and objects
+ * so a binding nested inside a prop object still resolves.
+ */
+export function resolveValue(
+  value: unknown,
+  model: Record<string, unknown>,
+  contextPath: string,
+): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveValue(item, model, contextPath));
+  }
+  if (isRecord(value)) {
+    if (isDataBinding(value)) {
+      return getAtPointer(model, resolvePointer(value.path, contextPath));
+    }
+    if ("literalString" in value && typeof value.literalString === "string") {
+      return value.literalString;
+    }
+    if ("literal" in value && Object.keys(value).length === 1) {
+      return value.literal;
+    }
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value)) {
+      out[key] = resolveValue(item, model, contextPath);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** A user action leaving the renderer, shaped like A2UI's client-to-server action. */
+export interface A2UIAction {
+  surfaceId: string;
+  componentId: string;
+  name: string;
+  payload: Record<string, unknown>;
+}
+
+/**
+ * Normalise an action property into `{ name, context }`.
+ *
+ * Accepts v0.9's `{ event: { name, context } }`, the bare `{ name, context }`
+ * shape, and a plain string, which is what an agent writes most often.
+ */
+export function readAction(
+  value: unknown,
+): { name: string; context: Record<string, unknown> } | undefined {
+  if (typeof value === "string" && value.trim()) {
+    return { name: value, context: {} };
+  }
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const event = isRecord(value.event) ? value.event : value;
+  const name = event.name;
+  if (typeof name !== "string" || !name) {
+    return undefined;
+  }
+  return { name, context: isRecord(event.context) ? event.context : {} };
+}