Mlola Render

Sometimes an agent should show interface instead of writing code for it: a form inside a chat, a status card in an agent's own app, a table of results a tool just fetched. With Mlola Render it describes the surface as A2UI messages, Mlola checks them against its catalog, and the surface is drawn with Mlola components in your theme.

How it works

The agent picks components and named values (tone, variant, size) from the catalog and never writes a color, a size or a class, so what it composes is accessible and on brand by construction. Before anything renders, the check holds it to the catalog and to what makes a surface usable, and answers in A2UI's own error shape so the agent can fix its messages itself.

The catalog is generated from the components: a value a component does not offer cannot be in it. Its A2UI catalog (JSON Schema) is served at https://ui.mlola.com/a2ui/catalog/v1, the catalogId every surface names. What passes is drawn by Render Surface in React, by @mlola-ui/behavior/render on a page without a framework, or inside a chat by the render_ui MCP App, all three from the same host, so they mean the same by every message.

For an agent

Both MCP servers, npx mlola-ui mcp and https://ui.mlola.com/mcp, offer two tools. An agent reads the catalog once, composes, and checks before it sends:

Terminal

get_render_catalog              # once: components, props, values, examples
check_render { "messages": [...] }   # before sending; fix every error, check again

A form whose values are bound to the data model and come back with the button's action. This is one of the catalog's examples, and it passes the check:

A sign-up form

[
  {"version":"v0.9.1","createSurface":{"surfaceId":"signup","catalogId":"https://ui.mlola.com/a2ui/catalog/v1","theme":{"name":"graphite","mode":"system"}}},
  {"version":"v0.9.1","updateComponents":{"surfaceId":"signup","components":[
    {"id":"root","component":"Card","children":["title","form"]},
    {"id":"title","component":"Heading","level":2,"text":"Create your workspace"},
    {"id":"form","component":"Stack","children":["name","email","plan","actions"]},
    {"id":"name","component":"Input","label":"Workspace name","value":{"path":"/form/name"},"required":true},
    {"id":"email","component":"Input","type":"email","label":"Work email","value":{"path":"/form/email"},"required":true},
    {"id":"plan","component":"RadioGroup","label":"Plan","options":[{"label":"Free","value":"free"},{"label":"Team","value":"team"}],"value":{"path":"/form/plan"}},
    {"id":"actions","component":"Row","children":["submit"]},
    {"id":"submit","component":"Button","variant":"primary","text":"Create workspace","action":{"event":{"name":"create_workspace","context":{"form":{"path":"/form"}}}}}
  ]}},
  {"version":"v0.9.1","updateDataModel":{"surfaceId":"signup","path":"/form","value":{"name":"","email":"","plan":"free"}}}
]

And this is what it draws, with Render Surface:

Create your workspace

Fill it in and press the button to see what the agent receives.

In a chat that shows MCP Apps, render_ui draws the same surface in the conversation, and the person's press comes back to the agent as their next message.

Data and actions

Fields bind to the surface's data model with {"path": "/form/email"}, and updateDataModel gives them their starting values. A container's children can be a template that repeats one component for each item of an array: {"componentId": "row", "path": "/items"}, where relative paths like {"path": "name"} read the item.

When a person fills in the example's form and presses its button, the agent receives an A2UI action with the button's event name and its context, each binding replaced by its value at that moment:

JSON

{
  "version": "v0.9.1",
  "action": {
    "name": "create_workspace",
    "surfaceId": "signup",
    "sourceComponentId": "submit",
    "timestamp": "2026-10-09T09:30:00Z",
    "context": {
      "form": {
        "name": "Atlas Studio",
        "email": "lena@company.com",
        "plan": "free"
      }
    }
  }
}

The context is what a person typed. Check it on the server, as you would a form post, before the agent acts on it.

What the check says

A first try, with a name borrowed from A2UI's basic catalog, a color, a field with no label and a wrong case:

JSON

[
  {"version":"v0.9.1","createSurface":{"surfaceId":"feedback","catalogId":"https://ui.mlola.com/a2ui/catalog/v1","theme":{"name":"graphite","primaryColor":"#2563eb"}}},
  {"version":"v0.9.1","updateComponents":{"surfaceId":"feedback","components":[
    {"id":"root","component":"Column","children":["title","note","send"]},
    {"id":"title","component":"Heading","level":2,"text":"How was your order?"},
    {"id":"note","component":"Textarea","placeholder":"Tell us more"},
    {"id":"send","component":"Button","variant":"Primary","text":"Send","action":{"event":{"name":"send_feedback","context":{"note":{"path":"/note"}}}}}
  ]}}
]

Terminal

4 errors: nothing renders until they are fixed.
error /0/createSurface/theme/primaryColor [feedback]: Colors, type and shape come from the theme; pick one by name instead of setting "primaryColor": "graphite", "atelier", "machined", "aerogel", "nordic".
error /1/updateComponents/components/0/component [feedback]: "Column" is not in the Mlola catalog; use "Stack".
error /1/updateComponents/components/2 [feedback]: Textarea needs "label": the field's name.
error /1/updateComponents/components/3/variant [feedback]: Button "variant" is "primary", not "Primary": values are case-sensitive.

Beyond the schema it holds one root with real children and no loops, a name a screen reader reads on every field and control, headings that do not skip a level, values inside their range and among their options, data paths that cannot reach an object's prototype, and actions that send named events, never code. Every error is VALIDATION_FAILED with a JSON Pointer to what needs fixing. What agents bring from the basic catalog (Column, Image, a Button's child, weight) is answered with what to use instead, and the catalog's guide lists it up front.

For a developer

In React, add the component with npx mlola-ui add render-surface. Pass the same array with more messages at its end as they arrive; nothing that fails the check is drawn, and what was refused reaches onError as A2UI's error message, ready to send back to the agent.

TSX

import { RenderSurface } from "@/components/render-surface";

<RenderSurface
  messages={messagesFromTheAgent}
  streaming={stillArriving}
  onAction={(message) => sendToTheAgent(message)}
  onError={(refused) => sendToTheAgent(refused)}
/>

Without a framework, the same surfaces draw as the components' markup, with the runtime's tabs, select, slider and switch attached:

HTML

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mlola-ui/engine@1/generated/mlola.css" />
<div id="agent-ui"></div>
<script type="module">
  import { mountRender } from "https://cdn.jsdelivr.net/npm/@mlola-ui/behavior@1/src/render/dom.js";
  import rules from "https://cdn.jsdelivr.net/npm/@mlola-ui/behavior@1/src/render/rules.js";

  const view = mountRender(document.querySelector("#agent-ui"), { rules, onAction: sendToTheAgent, onError: sendToTheAgent });
  view.receive(messagesFromTheAgent);
</script>

The same check runs from a terminal, where it exits with 1 on an error so it can gate CI, and in code, where a model's output passes through your server. It uses no Node or browser API, so it runs in a server, an edge function or a page, and mlola-ui/render and mlola-ui/render/rules carry their TypeScript types.

Terminal

npx mlola-ui render check ui.json         # an array, one message, or JSON Lines
npx mlola-ui render check ui.json --json  # the result as data
npx mlola-ui render catalog               # the guide an agent reads
npx mlola-ui render catalog --schema      # the A2UI catalog

TSX

import { validateRender } from "mlola-ui/render";
import rules from "mlola-ui/render/rules" with { type: "json" };

const result = validateRender(messagesFromTheModel, rules);
if (!result.valid) {
  // Each error is { code, surfaceId, path, message }: hand them back to the model.
  return retryWith(result.errors);
}

The details, from streaming to required fields and the limits the check holds, are in docs/render.md.

With your own model

Mlola never calls a model. Your server calls yours, with your key, and mlola-ui/render/ai is what goes around that call: what to tell the model, how to read what it answers, and what to answer when the check refuses it. Nothing a person types and nothing a model writes passes through Mlola.

TSX

import { composeRender } from "mlola-ui/render/ai";
import rules from "mlola-ui/render/rules" with { type: "json" };

const { valid, messages, result, turns } = await composeRender({
  rules,
  request: "A form to book a table for tonight",
  generate, // your function: ({ system, messages }) => the model's reply as text
});

if (valid) sendToTheClient(messages); // draw them with Render Surface or mountRender
else log(result.errors); // the model did not get there in three tries

composeRender asks the model, reads its reply, checks it, and hands a refused reply back with the errors as the next turn, three times unless you set attempts. When the person presses a button, continue from turns with A2UI's action as their next turn, and the model answers with the next surface:

TSX

const next = await composeRender({
  rules,
  request: [...turns, { role: "user", content: JSON.stringify(action) }],
  generate,
});

The one function you write

generate takes the system prompt and the turns, and answers with the model's text. Name the model you use where these say MODEL; each reads its key from the environment, where your server keeps it. All three are run by the library's tests against a stand-in for the service.

A server that speaks chat completions, which most hosted and local models do:

Chat completions

async function generate({ system, messages }) {
  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: { "content-type": "application/json", authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
    body: JSON.stringify({ model: MODEL, messages: [{ role: "system", content: system }, ...messages] }),
  });
  if (!response.ok) throw new Error(`The model's server answered ${response.status}.`);
  const reply = await response.json();
  return reply.choices?.[0]?.message?.content ?? "";
}

Anthropic's Messages API:

Anthropic

async function generate({ system, messages }) {
  const response = await fetch("https://api.anthropic.com/v1/messages", {
    method: "POST",
    headers: { "content-type": "application/json", "x-api-key": process.env.ANTHROPIC_API_KEY, "anthropic-version": "2023-06-01" },
    body: JSON.stringify({ model: MODEL, max_tokens: 8192, system, messages }),
  });
  if (!response.ok) throw new Error(`The model's server answered ${response.status}.`);
  const reply = await response.json();
  return (reply.content ?? []).map((block) => (block.type === "text" ? block.text : "")).join("");
}

Google's Gemini API:

Gemini

async function generate({ system, messages }) {
  const response = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${MODEL}:generateContent`, {
    method: "POST",
    headers: { "content-type": "application/json", "x-goog-api-key": process.env.GEMINI_API_KEY },
    body: JSON.stringify({
      systemInstruction: { parts: [{ text: system }] },
      contents: messages.map((turn) => ({ role: turn.role === "assistant" ? "model" : "user", parts: [{ text: turn.content }] })),
    }),
  });
  if (!response.ok) throw new Error(`The model's server answered ${response.status}.`);
  const reply = await response.json();
  return (reply.candidates?.[0]?.content?.parts ?? []).map((part) => part.text ?? "").join("");
}

Your brand's theme

A surface drawn with theme="inherit" takes the theme of the page around it, so it wears your own theme, from mlola.theme.json or the Theme Studio, with the contrast that theme was solved for. With theme: "page" the prompt tells the model to leave themes alone.

TSX

await composeRender({ rules, request, generate, theme: "page" });

<RenderSurface messages={messages} theme="inherit" onAction={sendToYourServer} />

A model that also answers in words

In a chat, most answers are words and some are better as a surface. Give the model a tool and it decides. renderTool answers with a name, a description and a JSON Schema, the three parts every provider's tool calling is built from, and checkRenderReply reads the call's arguments whether your SDK parsed them or not.

TSX

import { checkRenderReply, renderSystemPrompt, renderTool } from "mlola-ui/render/ai";

const system = renderSystemPrompt(rules, { output: "tool" });
const tool = renderTool(); // { name: "render_ui", description, inputSchema }

// When the model calls the tool:
const { valid, messages, repair } = checkRenderReply(call.arguments, rules);
if (valid) sendToTheClient(messages);
answerTheCall(valid ? "Shown to the person." : repair);

As it streams

createRenderReader reads messages out of the model's text as it arrives, whatever the model wrapped them in: JSON Lines, an array, a code fence. A reply it could only read in part (a piece that is not JSON, a message still open at the end) is refused whole, with what was wrong. On the page, Render Surface draws nothing that fails the check, so the last good state stays on screen while your server asks again.

One mistake it reads through: a closing brace or bracket a model miscounted at the end of a long line. Where a closer can only mean one thing it is read as that, mended counts the closers added or left out, and the messages go through the check like any other reply. A reply that stops with a message open is still refused, since it may have been cut off.

TSX

import { createRenderReader } from "mlola-ui/render/ai";

const reader = createRenderReader(rules);
for await (const chunk of textFromTheModel) {
  for (const message of reader.push(chunk)) sendToTheClient(message);
}
const { messages, error } = reader.end();

A server that is not JavaScript reads the same prompt from the CLI:

Terminal

npx mlola-ui render prompt                      # the system prompt, for a server in any language
npx mlola-ui render prompt --tool --page-theme  # for a tool, with the page's theme

The catalog

25 free components. get_render_catalog and npx mlola-ui render catalog list every prop and the values it takes.

Component	What it does
Layout
`Stack`	Places its children in a column with the theme's spacing. Use it as the root of most surfaces.
`Row`	Places its children side by side and wraps them on a narrow screen. Use it for a row of buttons or badges.
`Grid`	Places its children in equal columns that collapse to one column on a phone.
Text
`Heading`	A heading. Levels follow the page outline: never skip a level going deeper.
`Text`	A paragraph of plain text.
Containers
`Card`	Groups related content on a surface of its own.
`Alert`	A message about the surface: a confirmation, a warning or an error. Warnings and errors interrupt a screen reader; calmer tones are announced politely.
`EmptyState`	Says that there is nothing here yet and what to do next.
`Tabs`	Shows one panel at a time, chosen from a row of tabs. Its children are Tab components.
`Tab`	One tab of a Tabs: its name and its panel.
`Accordion`	A list of sections that open and close. Its children are AccordionItem components.
`AccordionItem`	One section of an Accordion: its title and its content.
Forms
`Input`	A one-line text field with its label.
`Textarea`	A text field for several lines, with its label.
`Select`	Picks one value from a list that opens on demand. Use RadioGroup when there are only two to five options and room to show them.
`RadioGroup`	Picks one value from options that are all visible.
`Checkbox`	A yes or no choice with its label.
`Switch`	Turns a setting on or off right away.
`Slider`	Picks a number in a range by dragging or with the arrow keys.
`DatePicker`	A date field that opens a calendar and picks one day. The reader sees the date in their own format; the value is an ISO date.
Actions
`Button`	Sends an action back to the agent. Its text says what happens ("Create workspace", not "Submit").
Data
`Badge`	A short label for a status or a count.
`Progress`	Shows how far along something is.
`Avatar`	A person or a team shown by their initials.
`Table`	Rows of data under named columns. Cells hold text and numbers.

Themes: graphite, atelier, machined, aerogel, nordic, each light, dark or following the reader. Client-side functions and icon-only buttons are not in the catalog yet. Charts, stats and a data grid are in the Pro catalog.

The Pro catalog

Mlola Pro adds charts, stats and a data grid. The Pro catalog is every component above and 6 more, under its own catalogId, https://ui.mlola.com/a2ui/catalog/pro/v1, and Render Pro draws it. Both of these are drawn from the catalog's own examples:

Orders, July to September

Orders

1,284

+18% on the quarter before

New customers

508

+12%

Returning customers

776

60% of orders

1,284 orders, up 18% on the quarter before.

By month

New customers
Returning customers

Orders by month, new and returning customers
month	New customers	Returning customers
July	148	231
August	163	254
September	197	291

By channel

Web
App
Phone

Against the plan

Orders
Plan

Orders each month against the plan
month	Orders	Plan
July	379	400
August	417	420
September	488	440

Autumn price list

Linen throw

2026-10-19

Oak serving board

2026-10-19

Stoneware mug, set of four

2026-11-02

Change a price, then press the button to see the rows the agent receives.

A chart reads rows: one object for each category, with its name in one field and a number in each field a series draws. Rows sit in the component or in the data model, and a chart bound to the data model draws again when an update changes them. This is the bar chart above, and the rows it reads:

JSON

[
  {"version":"v0.9.1","updateComponents":{"surfaceId":"quarter","components":[
    {"id":"by-month-chart","component":"BarChart","label":"Orders by month, new and returning customers","data":{"path":"/months"},"x":"month","series":[{"key":"new","label":"New customers"},{"key":"returning","label":"Returning customers"}],"stacked":true}
  ]}},
  {"version":"v0.9.1","updateDataModel":{"surfaceId":"quarter","path":"/months","value":[{"month":"July","new":148,"returning":231},{"month":"August","new":163,"returning":254},{"month":"September","new":197,"returning":291}]}}
]

The check holds what a chart draws: every row written into it has its name, and a number wherever a series draws one, so "163" in place of 163 is refused with the row it is in. What a person edits in a grid is written to the data model, so a Button whose action sends that path sends the rows as they stand.

Component	What it does
`BarChart`	Amounts for each category as bars, one group or one stack per category. Use it to compare categories; a person reads the exact numbers by pointing or with the arrow keys.
`LineChart`	Values over a sequence as lines: days, months, steps. Use it for a trend; a person reads the exact numbers by pointing or with the arrow keys.
`DonutChart`	Parts of a whole as a ring, with the total in the middle. Use it for a few parts; for more than six, or to compare amounts, use a BarChart.
`Sparkline`	A small trend line with no axes, for beside a number in a Card or a Row.
`Stat`	One number a person looks for first: what it measures, the number, how it moved and a small trend line. Put a few side by side in a Grid at the top; a Stat is a tile of its own, so it does not go inside a Card.
`DataGrid`	Many rows a person works with like a spreadsheet: sort by a column, move with the arrow keys, select and copy cells, and edit the columns you mark editable. For a few rows to read, use a Table.

Render Pro comes with a Mlola Pro license and takes the props of Render Surface. The catalog arrives in your project beside it as plain data, which a server passes to composeRender, renderSystemPrompt and validateRender in place of the free catalog's rules. The MCP tools and the CLI's render commands hold the free catalog.

TSX

npx mlola-ui add render-pro

import { RenderPro } from "@/components/render-pro";
import { renderProRules } from "@/components/render-pro/rules";

// On your server, with a model you call yourself:
const { valid, messages } = await composeRender({ rules: renderProRules, request, generate });

// On the page:
<RenderPro messages={messages} onAction={sendToYourServer} />