@ulearning/ai-generative-frame 0.0.0-stage → 1.0.0-next.0

package/src/spec/pointer.ts

@@ -0,0 +1,170 @@
+/** Splits a JSON Pointer (RFC 6901) into unescaped tokens. `""` is the whole document. */
+export function parsePointer(pointer: string): string[] {
+  if (pointer === "") return [];
+  if (!pointer.startsWith("/")) {
+    throw new Error(`Invalid JSON Pointer "${pointer}": must start with "/"`);
+  }
+  return pointer
+    .slice(1)
+    .split("/")
+    .map((token) => token.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+export const escapePointerToken = (token: string | number): string =>
+  String(token).replace(/~/g, "~0").replace(/\//g, "~1");
+
+export const joinPointer = (tokens: readonly (string | number)[]): string =>
+  tokens.map((token) => `/${escapePointerToken(token)}`).join("");
+
+const isContainer = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const ARRAY_INDEX = /^(0|[1-9]\d*)$/;
+
+/** Reads the value at a pointer, or `undefined` when any step is missing. */
+export function getAtPointer(
+  doc: unknown,
+  pointer: string | string[],
+): unknown {
+  const tokens = typeof pointer === "string" ? parsePointer(pointer) : pointer;
+  let current = doc;
+  for (const token of tokens) {
+    if (Array.isArray(current)) {
+      if (!ARRAY_INDEX.test(token) || !Object.hasOwn(current, token)) {
+        return undefined;
+      }
+      current = current[Number(token)];
+    } else if (isContainer(current)) {
+      if (!Object.hasOwn(current, token)) return undefined;
+      current = current[token];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+export type WriteMode = "add" | "replace" | "remove";
+
+export type WriteOptions = {
+  /** Create missing intermediate objects instead of failing. */
+  createMissing?: boolean;
+};
+
+const FORBIDDEN = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * Returns a copy of `doc` with the value at `tokens` added, replaced, or
+ * removed. Containers along the path are copied; everything else is shared.
+ */
+export function writeAtPointer(
+  doc: unknown,
+  tokens: readonly string[],
+  mode: WriteMode,
+  value?: unknown,
+  options: WriteOptions = {},
+  arrayParents: readonly string[] = [],
+): unknown {
+  return writeAtPointerAt(doc, tokens, mode, value, options, arrayParents, []);
+}
+
+function writeAtPointerAt(
+  doc: unknown,
+  tokens: readonly string[],
+  mode: WriteMode,
+  value: unknown,
+  options: WriteOptions,
+  arrayParents: readonly string[],
+  prefix: readonly string[],
+): unknown {
+  if (tokens.length === 0) {
+    if (mode === "remove") throw new Error("Cannot remove the whole document");
+    return value;
+  }
+  const [token, ...rest] = tokens as [string, ...string[]];
+  if (FORBIDDEN.has(token)) throw new Error(`Forbidden path token "${token}"`);
+  const last = rest.length === 0;
+
+  if (Array.isArray(doc)) {
+    const copy = doc.slice();
+    if (token === "-") {
+      if (!last || mode !== "add") {
+        throw new Error('"-" can only be the last token of an add');
+      }
+      copy.push(value);
+      return copy;
+    }
+    if (!ARRAY_INDEX.test(token)) {
+      throw new Error(`"${token}" is not an array index`);
+    }
+    const index = Number(token);
+    if (last) {
+      if (mode === "add") {
+        if (index > copy.length) {
+          throw new Error(`Index ${index} is out of bounds`);
+        }
+        copy.splice(index, 0, value);
+      } else {
+        if (index >= copy.length) {
+          throw new Error(`Index ${index} is out of bounds`);
+        }
+        if (mode === "remove") copy.splice(index, 1);
+        else copy[index] = value;
+      }
+      return copy;
+    }
+    if (index >= copy.length)
+      throw new Error(`Index ${index} is out of bounds`);
+    copy[index] = writeAtPointerAt(
+      copy[index],
+      rest,
+      mode,
+      value,
+      options,
+      arrayParents,
+      [...prefix, token],
+    );
+    return copy;
+  }
+
+  if (!isContainer(doc)) {
+    if (options.createMissing && doc === undefined && mode !== "remove") {
+      // An array the write went through is recreated as one, so `-` and its indices do not become object keys; an index it does not have still fails, so no item appears that the user never wrote.
+      return writeAtPointerAt(
+        arrayParents.includes(joinPointer(prefix)) ? [] : {},
+        tokens,
+        mode,
+        value,
+        options,
+        arrayParents,
+        prefix,
+      );
+    }
+    throw new Error(`Path segment "${token}" does not exist`);
+  }
+
+  const copy: Record<string, unknown> = { ...doc };
+  if (last) {
+    if (mode === "remove" || (mode === "replace" && !options.createMissing)) {
+      if (!Object.hasOwn(copy, token)) {
+        throw new Error(`Path segment "${token}" does not exist`);
+      }
+    }
+    if (mode === "remove") delete copy[token];
+    else copy[token] = value;
+    return copy;
+  }
+  if (!Object.hasOwn(copy, token) && !options.createMissing) {
+    throw new Error(`Path segment "${token}" does not exist`);
+  }
+  copy[token] = writeAtPointerAt(
+    copy[token],
+    rest,
+    mode,
+    value,
+    options,
+    arrayParents,
+    [...prefix, token],
+  );
+  return copy;
+}

package/src/spec/prompt.ts

@@ -0,0 +1,243 @@
+import type { SpecStreamMode } from "./stream";
+import { describeSchema } from "../json-schema";
+import type { Catalog } from "./catalog";
+
+export type SpecPromptOptions = {
+  /**
+   * `jsonl`: the output is only JSONL patches, e.g. the `patches`
+   * argument of `render_spec`. `inline`: patches go in a ```spec fence inside
+   * a normal reply. Defaults to `jsonl`.
+   */
+  mode?: SpecStreamMode;
+  /** Extra rules appended to the built-in ones. */
+  customRules?: readonly string[];
+  /** Leave out the worked example. */
+  omitExample?: boolean;
+  /** Built-in actions the host handles, which the guidance then describes: `prompt` for `sendMessage`, `modelContext` for `updateModelContext`, `clipboard` for `copyText`. All default to false. */
+  hostApi?: { prompt?: boolean; modelContext?: boolean; clipboard?: boolean };
+};
+
+const list = (items: readonly string[]) =>
+  items.map((item) => `- ${item}`).join("\n");
+
+const joinClauses = (clauses: readonly string[], conjunction = "and") =>
+  clauses.length > 2
+    ? `${clauses.slice(0, -1).join(", ")}, ${conjunction} ${clauses.at(-1)}`
+    : clauses.join(` ${conjunction} `);
+
+/** How to compose an answer from the catalog's components, naming only the ones it has and only uses their slots and events allow. */
+const compositionRules = (catalog: Catalog) => {
+  const has = (type: string) => catalog.component(type) !== undefined;
+  const nests = (type: string) =>
+    catalog.component(type)?.slots?.includes("default") ?? false;
+  const emits = (type: string) =>
+    (catalog.component(type)?.events?.length ?? 0) > 0;
+  const nestsAny = Object.keys(catalog.components).some(nests);
+  const rules = [
+    has("Header") && has("Text")
+      ? "Open with a `Header` that names the answer and a `Text` with the one-line takeaway, then give each part of the answer its own section."
+      : "Open with a heading that names the answer and its one-line takeaway, then give each part of the answer its own section.",
+  ];
+  const modules = [
+    ...(nests("Card")
+      ? [
+          "Make each module a `Card`: a summary, a checklist, a form, or one option, with running prose outside cards.",
+        ]
+      : []),
+    ...(nests("Row") && has("Fact")
+      ? ["Put the answer's key figures side by side in a `Row` of `Fact`s."]
+      : []),
+    ...(has("Badge")
+      ? ["Show short tags, such as a duration or a price tier, as `Badge`s."]
+      : []),
+  ];
+  if (modules.length) rules.push(modules.join(" "));
+  const layouts = [
+    ...(has("Map") ? ["put places with coordinates on a `Map`"] : []),
+    ...(has("Timeline")
+      ? ["lay out a schedule or itinerary as a `Timeline`"]
+      : []),
+    ...(has("Steps") ? ["write instructions as `Steps`"] : []),
+    ...(has("Table")
+      ? ["compare options attribute by attribute in a `Table`"]
+      : []),
+  ];
+  if (layouts.length) {
+    const sentence = joinClauses(layouts);
+    rules.push(`${sentence[0]!.toUpperCase()}${sentence.slice(1)}.`);
+  }
+  if (has("Image")) {
+    const placements = [
+      ...(nestsAny
+        ? [`lead with two or three photos${nests("Row") ? " in a `Row`" : ""}`]
+        : []),
+      ...(nests("Card") ? ["open each option's `Card` with its photo"] : []),
+      ...(nests("Row") ? ["put a small photo beside each item's text"] : []),
+    ];
+    rules.push(
+      `Show what can be seen with \`Image\`, but only from an image URL a tool returned, never one you write yourself${placements.length ? `: ${joinClauses(placements, "or")}` : ""}.`,
+    );
+  }
+  if (emits("Button") && nestsAny) {
+    rules.push(
+      `For a number the user adjusts, such as guests or servings, put it between a \`-\` and a \`+\` \`Button\`${nests("Row") ? " in a `Row`" : ""}, each stepping it with a \`setState\` whose \`$calc\` value stays in a sensible range, and compute every amount that depends on it with \`$calc\`.`,
+    );
+  }
+  if (nestsAny) {
+    rules.push(
+      "Keep lists in `/state` and render them with `repeat`, except a list a component takes as a prop, such as table rows or chart series, which you bind to that prop.",
+    );
+  }
+  rules.push(
+    "Keep the tree shallow and give every element a job: no filler, and no decoration that adds nothing.",
+  );
+  return rules;
+};
+
+/** The rules every spec follows: how to compose an answer, then the app's own. `render_spec` carries them in its description too. */
+export const specRules = (
+  catalog: Catalog,
+  customRules: readonly string[] = [],
+) => [...compositionRules(catalog), ...customRules];
+
+const componentSection = (catalog: Catalog) => {
+  const entries = Object.entries(catalog.components).map(([name, def]) => {
+    const lines = [`### ${name}`, def.description];
+    const props = catalog.propsSchema(name);
+    lines.push(`props: ${props ? describeSchema(props) : "none"}`);
+    const propDocs = Object.entries(props?.properties ?? {})
+      .filter(([, schema]) => schema.description)
+      .map(([key, schema]) => `  - ${key}: ${schema.description}`);
+    if (propDocs.length) lines.push(...propDocs);
+    const slots = def.slots ?? [];
+    lines.push(
+      slots.length === 0
+        ? "children: none"
+        : `children: ${slots
+            .map((slot) =>
+              slot === "default" ? "`children`" : `\`slots.${slot}\``,
+            )
+            .join(", ")}`,
+    );
+    if (def.events?.length) {
+      lines.push(`events: ${def.events.map((e) => `\`${e}\``).join(", ")}`);
+    }
+    return lines.join("\n");
+  });
+  return `## Components\n\nUse only these types.\n\n${entries.join("\n\n")}`;
+};
+
+const actionSection = (
+  catalog: Catalog,
+  hostApi: NonNullable<SpecPromptOptions["hostApi"]>,
+) => {
+  const entries = [
+    "- `setState` — params `{ path: string; value?: unknown }`. Writes `value` at the JSON Pointer `path` in state. Built in.",
+    ...(hostApi.prompt
+      ? [
+          "- `sendMessage` — params `{ text: string }`. Sends `text` as the user's next message, as if they typed it. Use it behind a button for a follow-up the user asks for. Built in.",
+        ]
+      : []),
+    ...(hostApi.clipboard
+      ? [
+          '- `copyText` — params `{ text: string }`. Copies `text` to the user\'s clipboard, such as a shopping list behind a "Copy list" button; follow it with a `setState` that shows a short confirmation. Built in.',
+        ]
+      : []),
+    ...(hostApi.modelContext
+      ? [
+          "- `updateModelContext` — params `{ text?: string; data?: unknown }`. Tells you what the user chose in this UI, with every later message, replacing what it shared before, and clears it when both are missing; nothing is sent. Use it when a choice should shape your next answer, such as the option the user picked. Built in.",
+        ]
+      : []),
+    ...Object.entries(catalog.actions).map(([name, def]) => {
+      const params = catalog.paramsSchema(name);
+      const schema = params ? describeSchema(params) : undefined;
+      return `- \`${name}\` — ${schema && schema !== "unknown" ? `params \`${schema}\`. ` : ""}${def.description}`;
+    }),
+  ];
+  return `## Actions
+
+Bind actions to a component's events with \`on\`: \`"on": { "press": { "action": "setState", "params": { "path": "/tab", "value": "b" } } }\`. A list runs in order. Params may use expressions, and \`{ "$event": "" }\` reads the payload the event carried.
+
+${entries.join("\n")}`;
+};
+
+const protocolSection = (mode: SpecStreamMode) => `## Output protocol
+
+A spec is flat: \`{ "root": id, "elements": { id: element }, "state": { … } }\`. An element is \`{ "type", "props", "children": [ids], "slots"?, "visible"?, "repeat"?, "on"?, "watch"? }\`. Children are ids, never nested elements.
+
+Build it with JSON Patch (RFC 6902) operations, one JSON object per line (JSONL), so the UI renders while you write:
+
+${list([
+  'Set the root first: `{"op":"add","path":"/root","value":"main"}`.',
+  'Then add each element whole, parents before children, in reading order: `{"op":"add","path":"/elements/main","value":{…}}`. A child id may be listed before its element is added.',
+  'Put initial state under `/state` before elements that read it: `{"op":"add","path":"/state/filter","value":"all"}`.',
+  "Append to an array with `-`: `/elements/main/children/-`. Escape `/` in a key as `~1` and `~` as `~0`.",
+  "To change something, `replace` or `remove` its path; do not repeat unchanged elements.",
+  "Ids are short, unique, kebab-case, and describe the element (`revenue-card`).",
+])}
+
+${
+  mode === "inline"
+    ? "Write your reply as usual and put the patch lines in a fenced block that starts with ```spec and ends with ```. Text outside the fence is shown to the user as prose; keep it short and do not repeat what the UI shows."
+    : "Output only patch lines: no prose, no code fences, no comments."
+}`;
+
+const expressionSection = () => `## Expressions
+
+Any prop or action param, or any value nested inside one, may be an expression object instead of a literal:
+
+${list([
+  '`{ "$state": "/path" }` reads state.',
+  '`{ "$bindState": "/path" }` reads state and lets the component write it back (inputs, toggles, selects).',
+  '`{ "$template": "Hello ${/user/name}" }` fills `${…}` placeholders with state values; outside `$template` and `$calc`, a placeholder shows as written.',
+  '`{ "$cond": condition, "$then": a, "$else": b }` picks a value.',
+  "`{ \"$calc\": \"round(${/guests} * 0.5, 1) + ' lb'\" }` computes a value with a formula over `${…}` references, numbers, and `'text'`: `+ - * / %`, `== != < <= > >=`, `a ? b : c`, and `&& || !`, which give `true` or `false` (write a default as `${/name} ? ${/name} : 'Guest'`). Functions: `round(x, digits)`, `floor`, `ceil`, `abs`, `clamp(x, low, high)`, `min` and `max` (of numbers, or of a list), `count(list)`, `sum(list)` and `avg(list)` (or of a field, `sum(list, '/price')`), and, formatting in en-US, `number(x, digits)`, `currency(x, 'USD')`, `percent(fraction)`, `time(minutesAfterMidnight)`, and `plural(n, 'item', 'items')`. `+` joins text when either side is text. A formula that cannot compute gives `null`.",
+  'Inside `repeat`: `{ "$item": "/field" }`, `{ "$bindItem": "/field" }`, `{ "$index": true }`, and `${$item/field}` in templates.',
+])}
+
+## Visibility and repetition
+
+${list([
+  '`"visible"` takes a condition: `true`/`false`, `{ "$state": "/open" }` (truthy), a comparison `{ "$state": "/count", "gt": 0 }` with `eq`, `neq`, `gt`, `gte`, `lt`, or `lte`, a formula `{ "$calc": "${/count} > 2" }`, `{ "not": condition }`, `{ "$or": [ … ] }`, `{ "$and": [ … ] }`, or an array (all must hold).',
+  '`"repeat": { "path": "/items", "key": "id" }` renders the element\'s children once per item of the state array at `path`.',
+  '`"watch": { "/path": action }` runs an action whenever that state value changes.',
+])}`;
+
+const EXAMPLE = `## Example
+
+{"op":"add","path":"/root","value":"main"}
+{"op":"add","path":"/state","value":{"count":0}}
+{"op":"add","path":"/elements/main","value":{"type":"Stack","props":{"gap":"md"},"children":["title","counter","bump"]}}
+{"op":"add","path":"/elements/title","value":{"type":"Heading","props":{"text":"Clicks"}}}
+{"op":"add","path":"/elements/counter","value":{"type":"Text","props":{"text":{"$template":"Clicked \${/count} times"}}}}
+{"op":"add","path":"/elements/bump","value":{"type":"Button","props":{"label":"Click"},"on":{"press":{"action":"setState","params":{"path":"/count","value":{"$calc":"\${/count} + 1"}}}}}}
+
+(The example's types are illustrative; use the components listed above.)`;
+
+/**
+ * Model guidance for a catalog: the component and action reference, the
+ * JSONL patch protocol, expressions, and rules. Deterministic for a given
+ * catalog and options.
+ */
+export function buildSpecPrompt(
+  catalog: Catalog,
+  options: SpecPromptOptions = {},
+): string {
+  const mode = options.mode ?? "jsonl";
+  const rules = [
+    "Use only the listed component types, props, events, and actions.",
+    "Every id in `children` or `slots` must be added as an element; every element except the root must be someone's child.",
+    "Give props literal values unless they depend on state; keep data (rows, series) in props or `/state`, not in text.",
+    ...specRules(catalog, options.customRules),
+  ];
+  return [
+    "# Declarative UI",
+    "You describe UI as a spec of trusted components that the host renders with its own design system. You choose components and data; the host owns styling.",
+    protocolSection(mode),
+    componentSection(catalog),
+    actionSection(catalog, options.hostApi ?? {}),
+    expressionSection(),
+    `## Rules\n\n${list(rules)}`,
+    ...(options.omitExample ? [] : [EXAMPLE]),
+  ].join("\n\n");
+}

package/src/spec/render-spec.ts

@@ -0,0 +1,144 @@
+import type { GuidanceModule, ToolDefinition } from "../tools/define";
+import type { Catalog } from "./catalog";
+import { specRules, type SpecPromptOptions } from "./prompt";
+import { parseSpecStream } from "./stream";
+import { emptySpec, type Spec } from "./types";
+import { formatSpecIssues, validateSpec, type SpecIssue } from "./validate";
+
+export type RenderSpecInput = {
+  title: string;
+  /** JSONL patch operations, one per line. Applied onto the title's previous spec if there is one. */
+  patches?: string;
+  /** A complete spec, replacing the title's previous one. */
+  spec?: Spec;
+};
+
+export type RenderSpecResult = {
+  ok: boolean;
+  title: string;
+  version: number;
+  elementCount: number;
+  issues: SpecIssue[];
+  /** The issues as model-readable text for a repair round. */
+  feedback: string;
+};
+
+export type RenderSpecTool = ToolDefinition<RenderSpecInput, RenderSpecResult>;
+
+export type SpecTools = { render_spec: RenderSpecTool };
+
+export type CreateSpecToolsOptions = {
+  /** Latest spec per title, shared with the host so it can render them. */
+  specs?: Map<string, { spec: Spec; version: number }>;
+  /** The app's rules for a spec, added to the tool's description after the built-in ones so they hold even when the model never loads the spec guidance. */
+  customRules?: readonly string[];
+};
+
+/**
+ * The rule that tells a model where the assistant-ui spec toolkit mounts the
+ * results of earlier tool calls. In backend execution, add it to the server's
+ * `customRules` for both `createSpecTools` and `specGuidanceModule`, and pass
+ * `toolResults: true` to `createSpecToolkit`.
+ */
+export const SPEC_TOOL_RESULTS_RULE =
+  'Results of earlier tool calls are in state under `/tools/<toolName>/<n>`, newest first: `0` is the latest call to that tool before this `render_spec` call, `1` the one before it, and so on. Show their values with `{ "$state": "/tools/<toolName>/<n>/..." }` rather than copying them, and never write `tools` in `state`. Indexes count back from each `render_spec` call, so when a patch follows another call to the same tool, update any binding that should keep showing the older result.';
+
+const TITLE_SCHEMA = {
+  type: "string",
+  description:
+    "Short snake_case identifier for the UI, unique in this conversation (e.g. `q3_revenue_by_region`). Reuse it to replace or patch the UI.",
+} as const;
+
+/**
+ * The `render_spec` tool for a catalog: validates the spec the model streams
+ * as JSONL patches (or a complete spec) and returns the issues to fix.
+ * Combine it with the widget tools through `createWidgetTools({ extraTools })`.
+ */
+export function createSpecTools(
+  catalog: Catalog,
+  options: CreateSpecToolsOptions = {},
+): SpecTools {
+  const specs =
+    options.specs ?? new Map<string, { spec: Spec; version: number }>();
+  const render_spec: RenderSpecTool = {
+    name: "render_spec",
+    description: [
+      "Shows declarative UI built from the host's components, streaming it as you write. Follow the spec guidance in the system prompt; only when it has none, load the `spec` module with read_me, if read_me offers one. Pass `patches` (JSONL patch operations, one per line) or a complete `spec`. Patches on a title you already rendered apply to that spec, so fix or update it with small patches. The result lists validation issues to fix.",
+      "",
+      "Every spec follows these rules:",
+      ...specRules(catalog, options.customRules).map((rule) => `- ${rule}`),
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: TITLE_SCHEMA,
+        patches: {
+          type: "string",
+          description:
+            "RFC 6902 JSON Patch operations as JSONL: one operation object per line, root first, then elements parent before child.",
+        },
+        spec: {
+          type: "object",
+          description:
+            "A complete spec { root, elements, state }. Prefer patches, which stream.",
+        },
+      },
+      required: ["title"],
+      additionalProperties: false,
+    },
+    async execute(input) {
+      const previous = specs.get(input.title);
+      const issues: SpecIssue[] = [];
+      let spec: Spec;
+      if (input.spec && typeof input.spec === "object") {
+        spec = { state: {}, ...input.spec };
+      } else if (typeof input.patches === "string" && input.patches.trim()) {
+        const parsed = parseSpecStream(input.patches, {
+          initial: previous?.spec ?? emptySpec(),
+        });
+        spec = parsed.spec;
+        for (const error of parsed.errors) {
+          issues.push({
+            code: "invalid-patch",
+            severity: "error",
+            path: "",
+            message: `Patch line ${error.line} was skipped: ${error.message}. Line: ${error.text}`,
+          });
+        }
+      } else {
+        spec = previous?.spec ?? emptySpec();
+        issues.push({
+          code: "invalid-patch",
+          severity: "error",
+          path: "",
+          message: "Pass `patches` or `spec`.",
+        });
+      }
+      issues.push(...validateSpec(spec, catalog).issues);
+      const version = (previous?.version ?? 0) + 1;
+      specs.set(input.title, { spec, version });
+      return {
+        ok: !issues.some((issue) => issue.severity === "error"),
+        title: input.title,
+        version,
+        elementCount: Object.keys(spec.elements ?? {}).length,
+        issues,
+        feedback: formatSpecIssues(issues),
+      };
+    },
+  };
+  return { render_spec };
+}
+
+/** The `spec` module for `read_me` (`createWidgetTools({ modules })`), documenting a catalog. */
+export function specGuidanceModule(
+  catalog: Catalog,
+  options: Omit<SpecPromptOptions, "mode"> = {},
+): GuidanceModule {
+  return {
+    name: "spec",
+    summary:
+      "declarative UI built from the host's own components, rendered with render_spec",
+    guidance: () => catalog.prompt({ ...options, mode: "jsonl" }),
+  };
+}

package/src/spec/resolve.ts

@@ -0,0 +1,123 @@
+import { evaluateCondition, resolveProps, resolveValue } from "./expressions";
+import { childIdsOf, repeatItems, type RepeatScope } from "./tree";
+import type { ActionBinding, Spec } from "./types";
+
+/** An action bound to an element's event, with its params resolved. */
+export type ResolvedAction = {
+  action: string;
+  params: Record<string, unknown>;
+};
+
+/** One element of a resolved spec. */
+export type ResolvedElement = {
+  /** The element id. The children a `repeat` renders keep their ids, once per item. */
+  id: string;
+  type: string;
+  props: Record<string, unknown>;
+  /** The state path behind each prop bound with `$bindState` or `$bindItem`. */
+  bindings: Record<string, string>;
+  /** The actions bound to each event. */
+  on: Record<string, ResolvedAction[]>;
+  children: ResolvedElement[];
+  /** Named slots other than `default`. */
+  slots: Record<string, ResolvedElement[]>;
+  /** The key of the `repeat` item a child of a `repeat` renders for. */
+  key?: string;
+  /** The state path of the `repeat` item an element inside a `repeat` renders for, which `$item` reads resolve against. */
+  itemPath?: string;
+};
+
+export type ResolveSpecOptions = {
+  /** The state to resolve against, such as a store's `getState()` after the user's changes. Defaults to `spec.state`. */
+  state?: unknown;
+};
+
+/**
+ * Resolves a spec into the tree the renderer draws for one state, for a
+ * target that cannot run the renderer, such as a chat platform's message
+ * format. An element whose `visible` condition fails is left out, `repeat`
+ * renders its children once per item, and props and action params hold
+ * plain values, with `{ $event }` read as `undefined`. Missing elements and
+ * cycles are left out, `watch` does not run, and types are not checked
+ * against a catalog.
+ */
+export function resolveSpec(
+  spec: Spec,
+  options: ResolveSpecOptions = {},
+): ResolvedElement | null {
+  const state =
+    options.state === undefined ? (spec.state ?? {}) : options.state;
+  const resolve = (
+    id: unknown,
+    scope: RepeatScope,
+    ancestors: readonly string[],
+    key?: string,
+  ): ResolvedElement | null => {
+    if (
+      typeof id !== "string" ||
+      ancestors.includes(id) ||
+      !Object.hasOwn(spec.elements, id)
+    ) {
+      return null;
+    }
+    const element = spec.elements[id];
+    if (
+      !element ||
+      typeof element !== "object" ||
+      typeof element.type !== "string"
+    ) {
+      return null;
+    }
+    const ctx = { ...scope, state };
+    if (!evaluateCondition(element.visible, ctx)) return null;
+    const { props, bindings } = resolveProps(element.props, ctx);
+    const on: Record<string, ResolvedAction[]> = {};
+    for (const [event, bound] of Object.entries(element.on ?? {})) {
+      on[event] = (Array.isArray(bound) ? bound : [bound])
+        .filter(
+          (binding: unknown): binding is ActionBinding =>
+            typeof (binding as ActionBinding | null)?.action === "string",
+        )
+        .map((binding) => ({
+          action: binding.action,
+          params: (resolveValue(binding.params ?? {}, ctx) ?? {}) as Record<
+            string,
+            unknown
+          >,
+        }));
+    }
+    const inside = [...ancestors, id];
+    const list = (
+      ids: readonly unknown[],
+      childScope: RepeatScope,
+      itemKey?: string,
+    ) =>
+      ids.flatMap(
+        (childId) => resolve(childId, childScope, inside, itemKey) ?? [],
+      );
+    const children =
+      element.repeat && typeof element.repeat.path === "string"
+        ? (repeatItems(element.repeat, state) ?? []).flatMap((item) =>
+            list(childIdsOf(element, "default"), item.scope, item.key),
+          )
+        : list(childIdsOf(element, "default"), scope);
+    const slots: Record<string, ResolvedElement[]> = {};
+    for (const [slot, ids] of Object.entries(element.slots ?? {})) {
+      if (slot !== "default" && Array.isArray(ids)) {
+        slots[slot] = list(ids, scope);
+      }
+    }
+    return {
+      id,
+      type: element.type,
+      props,
+      bindings,
+      on,
+      children,
+      slots,
+      ...(key !== undefined ? { key } : {}),
+      ...(scope.itemPath !== undefined ? { itemPath: scope.itemPath } : {}),
+    };
+  };
+  return resolve(spec.root, {}, []);
+}