# Introduction

> MorphScreen lets a model answer with real UI. It reads the answer as it streams, checks every line against the components your app allows, and draws it on the page.

<figure class="doc-video">
<video src="/docs/media/intro.mp4" poster="/docs/media/intro.jpg" autoplay muted loop playsinline preload="metadata" aria-label="An answer streaming into a page as cards, a chart and a form"></video>
<figcaption>A saved answer from DeepSeek V4 Flash, unedited, streaming into a page through the web SDK at the pace the model wrote it.</figcaption>
</figure>

A model writes its answer as Markdown with a few tags, like `<Card>`, `<Chart>`, `<Quiz>` and `<Form>`. MorphScreen's core reads that text as it arrives, checks each line against the components your app allows, and hands your page something it can draw at once. When a line breaks a rule, the API asks the same model to fix only that line.

[Get a key and make a first call](/docs/quickstart), or [see every component](/docs/components) drawn live.

## How it works

<div class="doc-figure" tabindex="0" role="region" aria-label="How it works: your server sends the conversation to the MorphScreen API, which runs the model, checks and repairs the answer as it streams, and your page draws it with the web SDK.">
<svg viewBox="0 0 720 150" fill="none" aria-hidden="true" focusable="false">
<rect x="1" y="35" width="170" height="80" rx="14" class="dg-box"/>
<text x="86" y="70" text-anchor="middle" class="dg-title">Your server</text>
<text x="86" y="92" text-anchor="middle" class="dg-text">the conversation</text>
<rect x="275" y="15" width="170" height="120" rx="14" class="dg-box dg-box--on"/>
<text x="360" y="48" text-anchor="middle" class="dg-title">MorphScreen API</text>
<text x="360" y="72" text-anchor="middle" class="dg-text">runs the model</text>
<text x="360" y="92" text-anchor="middle" class="dg-text">checks every line</text>
<text x="360" y="112" text-anchor="middle" class="dg-text">repairs what breaks</text>
<rect x="549" y="35" width="170" height="80" rx="14" class="dg-box"/>
<text x="634" y="70" text-anchor="middle" class="dg-title">Your page</text>
<text x="634" y="92" text-anchor="middle" class="dg-text">draws it as it streams</text>
<path d="M175 75h94" class="dg-line"/><path d="M262 69l8 6-8 6" class="dg-line"/>
<path d="M449 75h94" class="dg-line"/><path d="M536 69l8 6-8 6" class="dg-line"/>
</svg>
</div>

### Get a key

Sign up with your email or GitHub. The account comes with a project and its first key.

### Send the chat call you already make

The API speaks OpenAI's chat completions. Point your server's call at `https://api.morphscreen.com/v1`, add the `X-MorphScreen-Key` header, and keep the key on your server.

### Draw what comes back

The web SDK draws the answer while it streams, with plain DOM or React. On a server, `/v1/render` turns a finished answer into HTML that needs no JavaScript.

### Let the reader act

Buttons, forms, quizzes and polls come back to your app as actions. You decide what happens next, usually the model's next turn.

## What's in MorphScreen

- [The format](/docs/format): Markdown with tags, written so half an answer is always a valid start of the whole one.
- [75 components](/docs/components): layout, charts, forms and buttons in the core, and eight packs for data, shopping, scheduling, media, docs, inputs, interaction and the device.
- [Validation and repair](/docs/format/validation): every line checked against your app's catalog, and only the broken lines sent back to the model.
- [Your own components](/docs/format/custom-components): describe them once, and the model, the checks and the renderer all know them.
- [Agents](/docs/agents): the API speaks AG-UI, and `connectAgent` holds a whole conversation with any AG-UI agent.
- [Production](/docs/production): plans and limits, errors you can act on, a dashboard of every call, and nothing of the conversation kept.

## Integrations

The web SDK works with any framework: [React](/docs/integrations/react), [Next.js](/docs/integrations/nextjs), [Vue and Nuxt](/docs/integrations/vue), [Svelte and SvelteKit](/docs/integrations/svelte), [Angular](/docs/integrations/angular), [webpack](/docs/integrations/webpack) and [plain JavaScript](/docs/integrations/vanilla). Each page's code is a small app we install, build and run in Chrome every week, so the snippets work as written. Your server can be [Node.js](/docs/integrations/node), [Python](/docs/integrations/python) or anything that speaks HTTP.


---

# Quick start

> From a key to an answer drawn in your page, in about ten minutes. One route on your server, a few lines in your page.

You need a MorphScreen key, a server that can make an HTTP request (Node.js and Python are shown), and a page that can import an npm package.

## Get a key

Sign up at [app.morphscreen.com](https://app.morphscreen.com/signin) with your email or GitHub. Your first key is shown once on the welcome page. Copy it into your server's environment:

```bash
MORPHSCREEN_KEY=ms_live_...
```

The free plan has 100 calls on our model, so you don't need a model key to try it, then up to 3,000 calls a month on [your own OpenRouter key](/docs/agents/openai-compatible).

## Try a call

The API speaks OpenAI's chat completions. This streams an answer from the model included in your plan:

```bash
curl https://api.morphscreen.com/v1/chat/completions \
  -H "X-MorphScreen-Key: $MORPHSCREEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4.1-flash", "stream": true,
       "messages": [{"role": "user", "content": "Plan a weekend in Lisbon"}]}'
```

Each event's `delta.content` is the next piece of the answer, in [our format](/docs/format): Markdown with a few tags.

## Add a route to your server

Your page talks to your server, and your server talks to MorphScreen with the key. One route carries the page's runs on to `/v1/ui` and streams the events back:

```js
// Your server's one route for the page: each AG-UI run goes on to MorphScreen
// with your key, and the events stream straight back. The key never reaches
// the browser, and the server, not the page, picks the model.
import { createServer } from "node:http";

const API = process.env.MORPHSCREEN_API ?? "https://api.morphscreen.com/v1";
const MODEL = process.env.MODEL ?? "deepseek/deepseek-v4.1-flash";

createServer(async (req, res) => {
  if (req.method !== "POST" || req.url !== "/api/agent") return res.writeHead(404).end();
  let body = "";
  for await (const chunk of req) body += chunk;
  const run = JSON.parse(body);
  run.forwardedProps = { ...run.forwardedProps, model: MODEL };
  const upstream = await fetch(`${API}/ui`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-MorphScreen-Key": process.env.MORPHSCREEN_KEY },
    body: JSON.stringify(run),
  });
  res.writeHead(upstream.status, { "Content-Type": upstream.headers.get("content-type") ?? "text/event-stream" });
  for await (const chunk of upstream.body) res.write(chunk);
  res.end();
}).listen(process.env.PORT ?? 3000);
```

The same route in Python, with only the standard library:

```python
# Your server's one route for the page, with nothing but the standard
# library: each AG-UI run goes on to MorphScreen with your key, and the
# events stream straight back. The key never reaches the browser, and the
# server, not the page, picks the model.
import json
import os
import urllib.error
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

API = os.environ.get("MORPHSCREEN_API", "https://api.morphscreen.com/v1")
MODEL = os.environ.get("MODEL", "deepseek/deepseek-v4.1-flash")


class Agent(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/api/agent":
            self.send_error(404)
            return
        run = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
        run["forwardedProps"] = {**run.get("forwardedProps", {}), "model": MODEL}
        req = urllib.request.Request(
            f"{API}/ui",
            data=json.dumps(run).encode(),
            headers={"Content-Type": "application/json", "X-MorphScreen-Key": os.environ.get("MORPHSCREEN_KEY", "")},
            method="POST",
        )
        try:
            upstream = urllib.request.urlopen(req)
        except urllib.error.HTTPError as e:
            upstream = e
        with upstream:
            self.send_response(upstream.status)
            self.send_header("Content-Type", upstream.headers.get("Content-Type", "text/event-stream"))
            self.end_headers()
            while chunk := upstream.read1(4096):
                self.wfile.write(chunk)
                self.wfile.flush()


ThreadingHTTPServer(("127.0.0.1", int(os.environ.get("PORT", "3000"))), Agent).serve_forever()
```

## Install the web SDK

```sh
npm install @morphscreen/web
```

> **Before the launch:** The package goes to npm with the public launch. Until then, `/v1/render` draws answers as HTML on your server ([HTML without JavaScript](/docs/integrations/html)), and everything on this page works the same once it's published.
### Draw the conversation

`connectAgent` holds the conversation: it sends what the reader types, draws each answer as it streams, and sends buttons, forms and quiz answers back as the next turn.

```html
<div id="chat"></div>
<form>
  <input name="message" placeholder="Ask anything" aria-label="Your message" required>
  <button>Send</button>
</form>
```

```ts
import { connectAgent, loadCore } from "@morphscreen/web";
import "@morphscreen/web/morphscreen.css";

// morphscreen-agent.wasm from the package, served with your page
const core = await loadCore("/morphscreen-agent.wasm");
const chat = connectAgent(document.querySelector<HTMLElement>("#chat")!, { core, url: "/api/agent" });

const form = document.querySelector("form")!;
form.addEventListener("submit", async (e) => {
  e.preventDefault();
  const input = form.querySelector("input")!;
  const text = input.value;
  input.value = "";
  await chat.send(text);
});
```

Serve `morphscreen-agent.wasm` from the package with your page. Each [integration](/docs/integrations) shows how for its build tool.

That's a working chat. Ask it for a trip, a dashboard or a quiz, and the answer arrives as cards, charts and questions, checked line by line.

## Where next

- [The format](/docs/format): what the model writes, and why half an answer is always valid.
- [Components](/docs/components): all 75, drawn live, with their attributes.
- [Your own components](/docs/format/custom-components): teach the model your product's own cards.
- [Actions and state](/docs/format/actions): what comes back when the reader taps, types and answers.


---

# MorphScreen vs others

> How MorphScreen differs from OpenUI, Thesys C1, A2UI and the Vercel AI SDK's generative UI, and where the measured numbers are.

Generative UI libraries share a goal: a model's answer that the reader can use, not just read. They differ in what the model writes, who checks it, and what happens when it's wrong.

## What MorphScreen does differently

- **The model writes Markdown with a few tags.** Models already write both, so the format needs a short prompt (about 1,400 tokens with the core components, 2,900 with every pack), and half an answer is always a valid start of the whole one. Nothing waits for a closing bracket or a root statement.
- **Every line is checked as it streams.** The core reads each line against the components your app allows, so what reaches your page is already validated, and a mistake is tied to the line it's on.
- **Only broken lines are repaired.** When a line breaks a rule, the API asks the same model to rewrite that line, not the whole answer.
- **Any model.** The model included in every plan, or any model on OpenRouter with your own key.
- **Nothing a model wrote ever runs.** No script, no style, no address you didn't allow (see [Security](/docs/production/security)).

## Against OpenUI, measured

We measure ourselves against OpenUI on the benchmark thesysdev publishes for it: the same 46 briefs, the same models and the same rules for what counts as valid. The [benchmark page](/benchmark) has the method, every raw answer and the rows where OpenUI is ahead with why; [every row](/compare/openui) is on its own page.

## The others

| Library | What the model writes | Measured against MorphScreen |
|---|---|---|
| [OpenUI](https://www.openui.com) | OpenUI Lang, a language of its own | yes: [the benchmark](/benchmark) |
| [A2UI](https://github.com/a2ui-project/a2ui) | JSON messages that describe components | not yet |
| [Vercel AI SDK](https://ai-sdk.dev) | tool calls, which your code turns into components | not yet |
| [Thesys C1](https://www.thesys.dev) | its own format, through its API | not yet |

Comparisons with the last three need runs of their own on the same briefs; they go on this page, with their raw answers, once we have them.


---

# Coding agent setup

> Point Claude Code, Cursor, Codex or any coding agent at MorphScreen's docs, written for agents to read.

Every page of these docs is also plain Markdown, and the whole set is one file. Give your coding agent either, and it can write MorphScreen code from the real reference instead of guessing.

## The docs, for agents

| What | Where |
|---|---|
| An index of every page, with links | [morphscreen.com/llms.txt](/llms.txt) |
| Every page in one file | [morphscreen.com/llms-full.txt](/llms-full.txt) |
| One page | its address with `.md` added, like [/docs/quickstart.md](/docs/quickstart.md) |

Every page also has **Copy Markdown** under its title, for pasting into a chat.

## A rule for your project

Add this to your agent's instructions file (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`):

```markdown
## MorphScreen

This app draws model answers with MorphScreen (@morphscreen/web).
- Docs: https://morphscreen.com/llms.txt (read the page you need as .md).
- Keep the MorphScreen key on the server; the page talks to our own route.
- Components and their attributes: https://morphscreen.com/docs/components.md
- Never render model text as HTML yourself; the SDK or /v1/render draws it.
```

## Asking for UI

The model your app uses is told about the components by the system prompt the API builds. Your coding agent doesn't need to know them to build the app, only to write [your own components](/docs/format/custom-components) or to check an answer by hand.


---

# The format

> What a model writes for MorphScreen: Markdown with a few components written like JSX, designed so half an answer is always a valid start of the whole one.

An answer is Markdown with components written like JSX. Models already write both, so the format needs little teaching, and the prompt that teaches it is short.

```markdown
## Weekend in Lisbon

Two days is enough for the old town and Belém, if you take the trams for the hills.

<Columns>
<Stat label="Budget" value="$330" note="for one, two nights" />
<Stat label="Per day" value="$165" />
</Columns>

<Chart type="bar" title="Where the money goes">
| Item | USD |
|---|---|
| Stay | 180 |
| Food | 90 |
| Trams | 60 |
</Chart>

<FollowUps>
- Where should I stay?
- What should I eat?
</FollowUps>
```
## Components

```markdown
<Name attr="value" other=42 flag>content</Name>
<Name attr="value" />
```

- A component's name starts with a capital letter. `<div>` or `<br>` is text.
- Values are quoted; numbers and `true` or `false` may go without quotes, and a bare attribute (`required`) means `true`.
- A list of values is split by ` | `: `options="S | M | L"`.
- A component with nothing inside closes itself, like `<Stat ... />`.
- An attribute means the same on every component: `tone` is always `neutral`, `info`, `success`, `warning` or `danger`.

Each component says what goes between its tags: Markdown and other components, a Markdown table (a chart's data), a list (follow-up questions), images or nothing. The [component reference](/docs/components) has each one's attributes.

## Markdown

Text between components is Markdown: headings, paragraphs, emphasis, inline code, links, lists, quotes, code blocks, rules and tables. Raw HTML is never drawn as HTML. The few tags models slip in anyway, like `<strong>` and `<br>`, are read as formatting, and the rest shows as written.

## Why it streams well

- **There's no root to forget.** The answer is the root, and a component's place in the tree is where it's written.
- **A value counts only once it's whole.** A component appears when its opening tag is complete, so its attributes never change after it shows. A number or an address is never read half-written.
- **What's finished never changes.** A closed component is final, so the page never draws it twice.

[How streaming works](/docs/format/streaming) has the detail.

## What the core does with it

The core is the same Rust code everywhere: WebAssembly in the browser, inside the API on the server. As the text arrives it builds the tree, checks every line against the components your app allows, and reports each problem on its line. The API repairs those lines with the same model ([Validation and repair](/docs/format/validation)), and the SDK draws the tree.

The full grammar is the [format specification](/docs/reference/specification).


---

# Components and packs

> The 75 components come in a core that every answer has and eight packs an app can choose. Fewer packs, shorter prompt.

The components come in packs. `core` is always there: layout, text blocks, numbers, charts, forms and buttons. Eight more packs add data, commerce, the device, docs, inputs, interaction, media and scheduling.

| Pack | What it adds |
|---|---|
| [Core](/docs/components/core) | Cards, columns, tabs, steps, callouts, stats, badges, progress, charts, forms, buttons, follow-up questions |
| [Data](/docs/components/data) | Key-value facts, timelines, gauges, heatmaps, funnels, sparklines, trees |
| [Commerce](/docs/components/commerce) | Products, plans, carts, ratings, comparisons, prices |
| [Device](/docs/components/device) | Maps, camera, barcode scanning, location, files, contacts, calendar, sharing, voice notes, QR codes |
| [Docs](/docs/components/docs) | Code with a file name, diffs, formulas, file trees, citations |
| [Inputs](/docs/components/inputs) | Star ratings, searchable choices, times, toggle groups, steppers, signatures |
| [Interactive](/docs/components/interactive) | Quizzes, flashcards, polls, checklists, what-if sliders |
| [Media](/docs/components/media) | Video, audio, embeds, carousels |
| [Scheduling](/docs/components/scheduling) | Calendars, events, time slots, agendas, countdowns |

## Choosing packs

Every pack is on unless you name the ones you want. The model is told about only the components it may use, and the core checks the answer against the same list.

```js
{ "model": "deepseek/deepseek-v4.1-flash", "messages": [...], "morphscreen": { "packs": ["data", "interactive"] } }
```

```js
run.forwardedProps = { ...run.forwardedProps, model: MODEL, packs: ["data", "interactive"] };
```

```js
createAnswer(el, { core, packs: ["data", "interactive"] });
```

Give the page the same packs as the API, so the page can read everything the model was allowed to write. `[]` is the core alone.

## Prompt length

| Packs | System prompt |
|---|---|
| Core alone | about 1,400 tokens |
| Every pack | about 2,900 tokens |

Each component adds about 22 tokens. A shorter prompt costs less on every call and leaves the model fewer ways to go wrong; the benchmark measured both ([the benchmark](/benchmark)).

## Names models use on their own

Models sometimes write `<Table>`, `<Column>` or `<Buttons>` without being told. The core reads them as the component they mean and notes it, rather than failing the answer.


---

# Your own components

> Teach the model your product's own components. Describe one once, give it to the API and the page, and say how to draw it.

Next to the built-in components, an app can add its own: a shop's product card, a booking's seat map, a support ticket. It takes three steps, and the same description serves all three: the model learns it from the prompt, the core checks answers against it, and your page draws it.

## Describe it

A component lives in a pack: a name, one line on what it's for, its attributes, and what goes between its tags.

```json
{
  "name": "shop",
  "version": "1.0.0",
  "components": {
    "ProductCard": {
      "about": "a product with its price",
      "attrs": {
        "name": { "type": "string", "required": true },
        "price": { "type": "string", "required": true },
        "stock": ["in", "low", "out"]
      },
      "content": "none"
    }
  }
}
```

Attribute types are `string`, `number`, `boolean`, `url`, `list` (values split by ` | `), or a list of the values allowed, the first being the default. Content is `none`, `text`, `table`, `list`, `images` or `any` (Markdown and other components). One attribute, one meaning: `stock="low"`, not `style="color: orange"`.

A `text` component can take `"actions": true`. The model may then put `Button`s inside it, each with `ask` (the message a tap sends) or `href`, drawn under it as what the reader can do, like "Add to cart".

## Give it to the API

The API puts the pack's components in the system prompt and checks the answer against them. Send it from your server with every call:

```js
{ "model": "deepseek/deepseek-v4.1-flash", "messages": [...], "morphscreen": { "components": [shop] } }
```

```js
run.forwardedProps = { ...run.forwardedProps, model: MODEL, components: [shop] };
```

## Draw it

Give the page the same pack, and a function that draws the component into an element. It gets the component's attributes, and its content as HTML and as text; it may return a cleanup.

```ts
import { createAnswer } from "@morphscreen/web";
import shop from "./shop.json";

createAnswer(el, {
  core,
  custom: [shop],
  components: {
    ProductCard: (el, { attrs }) => {
      el.textContent = `${attrs.name}: ${attrs.price}`;
    },
  },
});
```

With React, pass components:

```tsx
import { Answer, type CustomProps } from "@morphscreen/web/react";
import shop from "./shop.json";

function ProductCard({ attrs }: CustomProps) {
  return (
    <div className="product">
      <strong>{attrs.name}</strong> {attrs.price}
    </div>
  );
}

<Answer core={core} text={text} custom={[shop]} components={{ ProductCard }} />;
```

`connectAgent` takes `custom` and `components` the same way.

## Your styles, untouched

Your component is drawn in a `<div class="ms-custom">` inside the answer. MorphScreen's stylesheet leaves everything in it to yours: it only inherits the answer's font and colour.

## When something's missing

A component your page doesn't draw still shows: its attributes as a list, then its content. Nothing an answer holds is dropped without a word.

## Names

A name defined twice is an error, never an override, so your pack can't replace a built-in component by accident. The one exception: when you leave `packs` out (every pack), your own `Product` or `Map` replaces the pack's. Name the pack outright and the two clash.


---

# The system prompt

> How the model learns the format. The API builds the prompt from your catalog and puts it before your own messages; you can also build it yourself.

The model learns the format from a system prompt built from the catalog: the components your app allows, their attributes, and the rules that keep answers valid. It's the same catalog the core checks answers against, so the two can't disagree.

## Through the API

The API builds the prompt for you. It goes first, and your own messages, system messages included, follow unchanged:

```json
{
  "model": "deepseek/deepseek-v4.1-flash",
  "messages": [
    { "role": "system", "content": "You are Lisbon Trams' trip planner. Answer in British English." },
    { "role": "user", "content": "Plan a weekend for two" }
  ],
  "morphscreen": { "packs": ["data"] }
}
```

Your system message says who the assistant is and what it knows. Ours says how to answer. You don't need to describe the components yourself.

## Building it yourself

To run a model of your own, outside the API, build the same prompt with the core and send it as the first system message.

In the browser or Node, with the web SDK:

```ts
const prompt = core.prompt(["data"], [shop]); // packs, then your own packs
```

On the command line:

```bash
mscore prompt --packs data
```

Then check what comes back with the core yourself: a `Session` from `core.session(packs, custom)` reads the text as it streams and gives you the verdict ([the web SDK reference](/docs/reference/web)). The API does that, and the repair, for you.

## What it costs

With the core alone the prompt is about 1,400 tokens, and with every pack about 2,900: about 22 tokens a component. The prompt's version is a hash recorded with every call, so the dashboard and the benchmark can tell which prompt an answer came from.


---

# Validation and repair

> Every line is checked against your app's components as it streams, and the API asks the same model to rewrite only the lines that break a rule.

A model gets things wrong: an attribute that doesn't exist, a value outside its list, a component it made up. The core catches each one on its line, as the answer streams, and the API repairs only those lines.

## Lenient where the intent is clear

- **Values match without case, and a few synonyms count:** `error` means `danger`, `column` means `bar`. These are reported as notes, not errors.
- **A bad value is fixed at its edge:** the default if there is one, or an optional attribute is dropped. A bad table row drops only that row.
- **An unknown component is dropped** and its content kept as text, so nothing the model said is lost.
- **Names models use on their own** (`<Table>`, `<Column>`, `<Buttons>`) are read as what they mean.

## Strict where it isn't

Each problem is a diagnostic on its line, with a class:

| Class | What it means |
|---|---|
| `hallucinated-component` | a component that isn't in your catalog |
| `signature-mismatch` | an attribute the component doesn't have, or of the wrong kind |
| `required-field` | a required attribute left out |
| `enum-mismatch` | a value outside an attribute's list, with no default to fall back on |
| `malformed-syntax` | a tag that doesn't close, or closes the wrong thing |
| `unreadable-tag` | a line that opens like a component but isn't a tag the core can read |
| `unsafe-url` | an address that could run code, like `javascript:` |

A cut-off answer is reported as truncated, never passed off as whole.

## Repair

When an answer has errors, the API sends the model the broken lines with what's wrong with each and asks for those lines again, with nothing else rewritten. Broken nesting, like a tab closed with its parent's tag, is mended with no model at all.

- It's on by default. `"repair": false` in the options turns it off.
- A blank answer gets one fresh try.
- A repair runs on the same model and key as the answer, and counts as part of the same call.
- It stops after 30 seconds and keeps what it has.

## What you see

**Through `/v1/ui`** (what `connectAgent` reads), a repaired answer replaces the one that streamed, and a `morphscreen.repair` event says what changed. You don't need to do anything.

**Through `/v1/chat/completions`**, the last chunk's `morphscreen` field carries the core's verdict, and when a repair was needed, the repaired text:

```json
{
  "morphscreen": {
    "valid": true,
    "truncated": false,
    "components": 12,
    "diagnostics": [],
    "repair": { "repaired": true, "errors_before": 2, "rounds": 1, "nesting": false, "ms": 1840, "lines": [7, [12, 14]], "text": "...", "valid": true }
  }
}
```

Draw `repair.text` in place of what streamed. Without streaming, the answer you get is already the repaired one.

## On the dashboard

Every call's line shows whether its answer was valid, which components had errors, and what repair did: the [dashboard](/docs/production/dashboard).


---

# Actions and state

> Components never run code. When the reader taps, types or answers, your app gets an action and decides what happens next.

Nothing in an answer runs code. When the reader acts, the SDK hands your app an action, and your app decides what happens: usually the model's next turn.

## Actions

| The reader | The action |
|---|---|
| Taps a `Button` with `ask`, a button outside a form, or a follow-up question | `{ type: "ask", text, node }` |
| Submits a `Form` | `{ type: "submit", node, form, button, fields }` |
| Finishes a `Quiz` | `{ type: "quiz", node, score, total, answers }` |
| Votes in a `Poll` | `{ type: "vote", node, name, choice }` |
| Ticks a `Checklist` item, marks a flashcard known | `{ type: "state", node, name, value }` |
| Taps a `Button` with `href` | nothing: the link opens |
| Switches a tab, opens details, moves a what-if slider | nothing: it all happens on the page |

```ts
createAnswer(el, {
  core,
  onAction: (action) => {
    if (action.type === "ask") send(action.text);
    if (action.type === "submit") send(`Book ${action.fields.flight} for ${action.fields.guests}`);
  },
});
```

With `connectAgent`, actions become the next user message by themselves (`sendActions: false` stops that), in words the core writes the same way everywhere:

```text
I finished the quiz: 1 of 2 right.
1. What absorbs light in a leaf? I answered "B. Chlorophyll" (right).
2. Which gas do plants take in? I answered "Oxygen" (wrong).
```

## Form fields

`fields` is keyed by each field's `name`, or its label as one word when it has none:

| Field | Value |
|---|---|
| Input, TextArea, Select, Radio, Date, Time, Stepper, Combobox, TimeSlots, RatingInput | text |
| Slider | a number |
| Switch | `true` or `false` |
| Checkboxes, and a ToggleGroup that allows several | a list of the chosen options |
| Camera, File | a list of `File`s, the browser's own, for your app to upload |
| Location | `{ lat, lng, accuracy }` in degrees and metres when the reader shared it, or the place they typed |
| Scan | the code, as text; a photo of it, when they took one, as files under `<name>-photo` |

The SDK checks `required` before it sends anything. A photo, a file or a location exists only after the reader acted: nothing is captured until they tap.

## State

What the reader has done is also kept as plain JSON for each component, so it can be saved, restored, or shared with an agent:

| Component | State |
|---|---|
| Quiz | `{ "answers": [index or null per question] }` |
| Flashcards | `{ "known": [card index] }` |
| Poll | `{ "vote": option or null }` |
| Checklist | `{ "done": [item index] }` |
| WhatIf | `{ "values": { slider name: number } }` |
| Form | `{ "fields": { name: value } }` |

`onComponentState(node, state)` tells you when it changes, and `answer.applyState({ [node]: state })` sets it, say from a saved session. With AG-UI the state rides in the shared state's `morphscreen` key, so an agent can read what the reader did and set it too ([AG-UI agents](/docs/agents/ag-ui)).


---

# Pictures, icons and maps

> Answers can show your own pictures, photos found on your own photo key, icons and maps on your own map provider. Nothing loads from a host you didn't choose.

An answer can show pictures and maps, and none of it loads from a host your app didn't choose. We don't supply photos: an answer shows your own pictures, or photos found on your own photo key.

## Your own pictures

An app with pictures of its own (a shop's products, a listing's rooms) sends them with the request, and the model shows them by id:

```json
{
  "images": [
    { "id": "3", "url": "https://cdn.shop.example/mugs/blue.jpg", "alt": "Blue mug", "credit": "Photo: [Shop](https://shop.example)" }
  ]
}
```

The model is told each id and its `alt`, never the address, and writes `![The blue one](img:3)`. The API puts the address in, with the credit under the picture, and allows the picture's host. Up to 200 a request.

## Photos on your own key

With `photos` set to your own Pexels, Unsplash or Openverse key, the model may ask for a photo of a real place, dish, animal, plant or artwork by describing it:

```json
{ "photos": { "pexels": "<your Pexels key>" } }
{ "photos": { "unsplash": { "key": "<access key>", "app": "<your app's name on Unsplash>" } } }
{ "photos": { "openverse": { "client_id": "...", "client_secret": "..." } } }
```

```markdown
![Belém Tower on the Tagus](find)
```

As the answer streams, the API searches that provider on your key and quota and points the picture straight at the provider's address, with its credit. The reader's browser loads it from the provider; we never fetch or keep the photo. Some requests get no photo on purpose and show their description instead: people, things the answer made up ("Customer 9"), and anything no result matches well enough. A wrong photo is worse than none.

Without `photos`, the model isn't told it can ask for any.

## Where pictures may load from

The SDK loads pictures only from the hosts you list. Any other address, a model-written one included, shows the picture's description instead: loading it would tell that host who is reading.

```ts
createAnswer(el, { core, imageHosts: ["cdn.shop.example", "images.pexels.com"] });
```

List your photo provider's image host when you give a photo key: `images.pexels.com`, `images.unsplash.com`, or `live.staticflickr.com` and `upload.wikimedia.org` for Openverse.

## Icons

`Stat` and `Button` take an `icon`: one of 229 Phosphor names. The names models write from other sets (`location`, `MapPin`, `trending_up`) are understood too. The core sends the drawing with the component, so there's no icon font to load. An unknown name shows nothing and never fails the answer.

## Maps

A `Map`'s places are drawn at the zoom that fits them. The map under the pins comes from your own map provider, on your key, straight from the provider:

```ts
createAnswer(el, { core, maps: { provider: "stadia", key: "..." } });
// { provider: "google", key: "...", language: "en-GB", region: "GB" }   Google's Map Tiles API
// { provider: "maptiler", key: "..." }
// { provider: "thunderforest", key: "..." }
// { provider: "tiles", url: "https://tiles.example/{z}/{x}/{y}.png", credit: "© ..." }
```

Each provider's credit shows under the map, as its terms ask. Without a provider a map is its pins on a plain ground, with each place linking to OpenStreetMap, and nothing loads.

For a live map you can pan and zoom, pass MapLibre GL 6.16 or later as `maplibre` too. It starts its worker from `maplibre-gl-worker.mjs` beside its script, so serve that file with your bundle; a page with a content security policy allows it as `worker-src 'self'`, and allows the provider's host for images.


---

# Theming

> Answers look right in your page without touching it. Change their colours, faces and corners with tokens, or a W3C Design Tokens file.

`morphscreen.css`, in the web SDK, styles answers and nothing else. Load it once on the page that shows them.

## In your page

The SDK puts `ms-answer` on the element it draws into, and every rule sits inside it, so the rest of your page looks the same with or without it. Every class an answer uses starts with `ms-` (`ms-card`, `ms-btn`), so Bootstrap's or daisyUI's `.card` and `.btn` never reach an answer, and ours never reach your page. Your own components inside an answer keep your styles.

We check this on every change: 73 answers in pages built with Tailwind and shadcn/ui, Bootstrap and MUI, light and dark, compared element by element with and without the answer.

## Light, dark and mono

Answers follow the reader's system setting. Pin one with `data-theme="light"` or `data-theme="dark"` on `<html>`; `data-theme="mono"` is a greyscale palette.

## Your colours

Every colour is a token starting `--ms-`, so yours and ours never collide. Set them on `:root`:

```css
:root {
  --ms-accent: #2f6fde;
  --ms-ink: #1b1d22;
}
```

Keep text at 4.5:1 against its ground: every token is checked against that in all three palettes.

## Your faces

Answers are set in IBM Plex Sans, with IBM Plex Mono for code, served from the package, never from a font host. To use your app's own:

```css
:root {
  --ms-font: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
  --ms-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
}
```

## A whole theme

`@morphscreen/web/theme` applies a W3C Design Tokens file, light and dark, to every component: colours, faces, sizes and corners ([its reference](/docs/reference/theme)).

## Motion

Components arrive with short morphs: a chart grows as its rows stream in, a quiz choice turns into a check or a cross, numbers count up. With `prefers-reduced-motion: reduce`, nothing moves.


---

# How streaming works

> Why an answer can be drawn line by line without ever redrawing what's done, and what the page shows while a component is still arriving.

The format is built so the core only ever reads the new text, never re-reads what it has already seen, and the page never redraws what's finished.

## One rule: a value counts once it's whole

- A component appears when its opening tag is complete (its `>` arrived), with every attribute final.
- Text streams word by word.
- A table row counts at its line's end.
- A number, a choice from a list or an address is only ever read whole: `max` never shows as "800" on its way to "8000".

## What's done never changes

A closed component is final, so the page never draws it twice. Each part of the answer is known by its place in the tree (`"3"`, `"3.0"`, `"3.0.2"`), never by a position in a list that could shift, because parts only ever arrive after the ones before them.

## While a component arrives

A component still streaming is drawn from its complete lines so far, and the newer lines are patched in: a chart grows as its rows come, a table fills row by row. It becomes interactive when it closes.

## One parser

Reading a whole answer is streaming it in one piece. Our tests check that every split of every recorded answer gives the same tree. The core has also been fuzzed with hundreds of millions of mutated answers, and every crash that turned up was fixed with a test of its own.

## What it costs

Streaming through the core is fast enough not to matter: on our benchmark, Chrome spends 655 ms in all to stream and draw 20 answers, against 5841 ms for OpenUI's renderer, and the first text shows in 73 ms against 150 ms ([the benchmark](/benchmark)).

[The op stream](/docs/reference/ops) is what the core hands a renderer, for drawing answers yourself.


---

# Build agents

> Three ways to get MorphScreen answers into an app with an agent or a chat: the AG-UI endpoint, an AG-UI agent of your own, or the OpenAI-style call you already make.

There are three ways in, depending on where your conversation lives.

| You have | Use | What you get |
|---|---|---|
| A chat with no agent framework yet | `/v1/ui` and `connectAgent` ([Quick start](/docs/quickstart)) | The model run, checks and repairs on our side; the conversation, actions and state on the page; one route on your server |
| An agent that speaks AG-UI (LangGraph, Mastra, CrewAI, Pydantic AI and others) | [AG-UI agents](/docs/agents/ag-ui) | `connectAgent` pointed at your agent, which answers in our format with the prompt from the core |
| Code that already calls OpenAI or OpenRouter | [OpenAI-compatible clients](/docs/agents/openai-compatible) | The same call with a new base address and one header; you draw the text yourself |

## In one turn

1. The reader types, or taps something in the last answer.
2. The page sends it, with the conversation, as an AG-UI run or a chat call.
3. The model answers in our format, with the system prompt built from your catalog.
4. The core reads the answer as it streams: on our server through the API, and on the page in the SDK. Each line is checked, and the page draws each part as soon as it's complete.
5. The reader acts on the answer. Buttons, forms and quiz answers come back as actions, and with `connectAgent` they become the next turn.

## Tools

`/v1/ui` doesn't run tools yet: a run's `tools` must be empty. An agent of your own can use tools as it likes, and `connectAgent`'s `onToolCall` answers tools that run in the page.


---

# AG-UI agents

> Hold a whole conversation with any agent that speaks AG-UI 1.0, with answers drawn as they stream, actions sent back and the reader's state shared with the agent.

`connectAgent` holds a conversation with an agent that speaks [AG-UI](https://github.com/ag-ui-protocol/ag-ui) 1.0 over HTTP and server-sent events: `/v1/ui`, or your own agent on LangGraph, Mastra, CrewAI, Pydantic AI, the Vercel AI SDK or anything else with an AG-UI adapter. The protocol is read by the core, so a stream is read the same way everywhere.

```ts
import { connectAgent, loadCore } from "@morphscreen/web";
import "@morphscreen/web/morphscreen.css";

// morphscreen-agent.wasm from the package, served with your page
const core = await loadCore("/morphscreen-agent.wasm");
const chat = connectAgent(document.querySelector<HTMLElement>("#chat")!, {
  core,
  url: "/api/agent",
  packs: ["interactive"],
  headers: async () => ({ Authorization: `Bearer ${await getToken()}` }),
});

await chat.send("Quiz me on photosynthesis");
```

The AG-UI client adds about 36 KB to the core, so it's a build of its own: `morphscreen-agent.wasm` instead of `morphscreen.wasm`. Pages that only show answers keep the smaller one.

## Your agent answers in our format

An agent of your own needs MorphScreen's system prompt for the components the page will draw: `core.prompt(packs)` in Node or the browser, or `mscore prompt --packs ...` on the command line ([The system prompt](/docs/format/system-prompt)). Give the page the same `packs`.

## Saving the conversation

`chat.messages()` and `chat.state()` are what to save; `chat.load(messages, state)` starts from them again. `chat.stop()` stops a run part way.

## What goes back to the agent

A button, a follow-up, a submitted form, a finished quiz or a vote becomes the next user message, worded the same way on every platform. Photos and files from a form go along as AG-UI content parts.

Everything else the reader does is state: ticks, known cards, slider positions, a vote, quiz answers, what's typed in a form. It lives in the shared state under `morphscreen`, by message id and node id, and goes to the agent with the next run:

```json
{
  "morphscreen": {
    "msg-1": {
      "1.2": { "answers": [1, 0] },
      "1.5": { "done": [0, 1] },
      "1.7": { "fields": { "name": "Ana", "meal": "Fish", "guest": true } }
    }
  }
}
```

It works the other way too. An agent that sends a `STATE_SNAPSHOT` or `STATE_DELTA` touching these keys sets the components: a box ticks, a form fills in. Setting state never sends a message, because the reader didn't act. The rest of the shared state is your agent's own and is kept as it is.

## How strictly a stream is read

Each event is checked against the protocol's schema. A field the schema doesn't describe is removed with a warning; a value it describes but gets wrong stops the stream. Runs, messages, tool calls, steps and reasoning must open and close in order. Older shapes from producers before 1.0 are translated first. The protocol's own conformance streams run in our tests.

A stream that breaks the rules stops as `rejected`. A run the agent says failed (`RUN_ERROR`) is shown as failed. A response that ends mid-run is `truncated`, and the answer it was writing is finished as cut off. Each shows as a short note under the conversation.


---

# LangGraph

> A LangGraph agent that answers in MorphScreen, served over AG-UI with the protocol's own LangGraph adapter, and drawn in the page with connectAgent.

A LangGraph graph answers in our format when its model gets MorphScreen's system prompt, and the protocol's own adapter (`ag-ui-langgraph`) serves it over AG-UI for `connectAgent`. The code below is condensed from the example we run in CI, where a scripted model stands in so it needs no network.

## The agent

```python
import json, os, subprocess
from typing import Any, Optional, TypedDict

from ag_ui_langgraph import LangGraphAgent, add_langgraph_fastapi_endpoint
from fastapi import FastAPI
from langchain_core.messages import SystemMessage
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import END, START, MessagesState, StateGraph

PACKS = "interactive,inputs,data"
# MorphScreen's system prompt for those packs, built by the core once at start.
PROMPT = subprocess.run(["mscore", "prompt", "--packs", PACKS], check=True, capture_output=True, text=True).stdout


class State(MessagesState):
    # What the reader did in earlier answers, by message and node: the page sends it with every run.
    morphscreen: Optional[dict[str, Any]]


class Shared(TypedDict, total=False):
    morphscreen: Optional[dict[str, Any]]


model = ChatOpenAI(model="deepseek/deepseek-v4-flash", base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"], streaming=True)


async def answer(state: State, config):
    prompt = PROMPT
    if state.get("morphscreen"):
        prompt += "\n\nWhat the reader has done in your earlier answers, by message id and node id:\n" + json.dumps(state["morphscreen"])
    reply = await model.ainvoke([SystemMessage(prompt), *state["messages"]], config)
    return {"messages": [reply]}


builder = StateGraph(State, output_schema=Shared)
builder.add_node("answer", answer)
builder.add_edge(START, "answer")
builder.add_edge("answer", END)
graph = builder.compile(checkpointer=MemorySaver())

app = FastAPI()
add_langgraph_fastapi_endpoint(app, LangGraphAgent(name="morphscreen", graph=graph, emit_raw_events=False), "/agent")
```

With `emit_raw_events=False` an answer's stream is just its text, which is what the page reads.

```text
ag-ui-langgraph[fastapi]==0.0.47
ag-ui-protocol==1.0.0
langgraph==1.2.16
langchain-core==1.6.12
langchain-openai==1.7.2
fastapi==0.143.3
uvicorn==0.54.0
```

## The page

```ts
const core = await loadCore("/morphscreen-agent.wasm");
const chat = connectAgent(document.querySelector<HTMLElement>("#chat")!, { core, url: "/agent", packs: ["interactive", "inputs", "data"] });
await chat.send("Quiz me on photosynthesis");
```

## What we check

The check sends a message, ticks a box, answers the quiz, checks that the tick arrives in LangGraph's state, and reloads to see the conversation come back.


---

# OpenAI-compatible clients

> Code that calls OpenAI or OpenRouter switches to MorphScreen with a new base address and one header. Answers come back in our format, checked and repaired.

The API speaks OpenAI's chat completions, OpenRouter's flavour: streaming, usage with cost, fallback models, OpenRouter's provider settings. Code written for OpenAI's SDK or OpenRouter's switches by its base address and one header, and the rest stays as it is.

## On your own OpenRouter key

Any model on OpenRouter runs on your own key. It goes to OpenRouter and nowhere else, never stored or logged.

```ts
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.morphscreen.com/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
  defaultHeaders: { "X-MorphScreen-Key": process.env.MORPHSCREEN_KEY },
});

const stream = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4.6",
  stream: true,
  messages: [{ role: "user", content: "Compare three running shoes under $120" }],
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
```

```python
import os

from openai import OpenAI

client = OpenAI(
    base_url="https://api.morphscreen.com/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
    default_headers={"X-MorphScreen-Key": os.environ["MORPHSCREEN_KEY"]},
)
```

## On the model in your plan

The model included in your plan needs no OpenRouter key: send no `Authorization` header at all. OpenAI's Node SDK always adds one, so turn it off:

```ts
const client = new OpenAI({
  baseURL: "https://api.morphscreen.com/v1",
  apiKey: "unused",
  defaultHeaders: { "X-MorphScreen-Key": process.env.MORPHSCREEN_KEY, Authorization: null },
});
// model: "deepseek/deepseek-v4.1-flash"
```

From Python, call the API without the SDK ([Python](/docs/integrations/python)), since any `Authorization` header is taken as an OpenRouter key.

## OpenRouter's own SDK

```ts
import { OpenRouter } from "@openrouter/sdk";
import { HTTPClient } from "@openrouter/sdk/lib/http.js";

const httpClient = new HTTPClient();
httpClient.addHook("beforeRequest", (req) => {
  const r = new Request(req);
  r.headers.set("X-MorphScreen-Key", process.env.MORPHSCREEN_KEY);
  return r;
});
const openrouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY, serverURL: "https://api.morphscreen.com/v1", httpClient });
```

## What changes

- The answer is in our format, and the API's system prompt goes before your messages ([The system prompt](/docs/format/system-prompt)).
- The last streamed chunk carries the core's verdict, and the repaired text when a repair was needed ([Validation and repair](/docs/format/validation)).
- OpenRouter's errors come back as your SDK's own error classes, with OpenRouter's status: a 402 when your OpenRouter credit runs out, a 429 with its wait.
- Options go in a `morphscreen` field of the request: `packs`, `components`, `images`, `photos`, `repair` ([the reference](/docs/reference/api/chat-completions)).

To draw the text, pass it to the web SDK's `createAnswer` or `<Answer>`, or render it on your server with `/v1/render`.


---

# Going to production

> What to have in place before real readers use it: the key on your server, limits you've planned for, errors you handle, and the dashboard to watch.

## Before you launch

- **The key stays on your server.** Your page talks to your own route, and the route adds `X-MorphScreen-Key`. A key in a page is a key anyone can copy. If one leaks, revoke it on the dashboard and make another.
- **Your server picks the model and the packs.** Don't pass them through from the page as they come, or a reader can choose a model that costs you more.
- **Plan for the limits.** Each plan has calls a month, requests a minute and answers at once ([Limits and errors](/docs/production/limits)). Paid plans carry on past the month as extra calls; the free plan stops.
- **Handle each error by its type.** A 429 says how long to wait. A 402 says what ran out. Show the reader something useful, not a stack trace.
- **Allow what the page loads.** A content security policy needs `'wasm-unsafe-eval'` for the core, and the hosts your pictures, maps and media come from ([Security](/docs/production/security)).
- **Watch the first days.** The dashboard shows every call: how it ended, how long it took, whether the answer was valid, and what repair did.

## What we keep

A line for each call: when, which key, how long, the model, how it ended, whether the answer was valid and what repair did. Never the prompt or the answer, unless you turn on debug logs for a project, which keeps them for 7 days. [Security](/docs/production/security) has the whole list.

## When something's wrong

The [status page](https://status.morphscreen.com) shows whether the API answers, checked every minute, with its uptime and answer times. Write to [support@morphscreen.com](mailto:support@morphscreen.com); [Troubleshooting](/docs/production/troubleshooting) covers the usual problems.


---

# Limits and errors

> Every plan's limits, what happens when one is reached, and every error the API returns with what to do about it.

## The limits

| Limit | Free | Build | Scale |
|---|---|---|---|
| Calls a month | 3,000 | 25,000 | 500,000 |
| Of them on our model | 100 | all | all |
| Calls a day | 100 | no daily limit | no daily limit |
| Extra calls past the month | none: calls stop | up to 25,000 more | up to 500,000 more |
| Requests a minute | 10 | 60 | 300 |
| Answers at once | 2 | 10 | 50 |
| Renders a month, free | 30,000 | 250,000 | 5,000,000 |

Limits are your account's, however many keys and projects it has. A call is one request to `/v1/chat/completions` or `/v1/ui`, its checking and any repair included. A call on the model in your plan may carry up to about 8,000 tokens of conversation. Prices are on the [pricing page](/pricing).

A plan's month counts from the day you moved to it. Extra calls are billed with the next charge, at the price of the plan they were made on.

## Errors

Every error has the same shape. `type` is the reason to act on; `message` says it in words.

```json
{ "error": { "code": 429, "message": "this account's plan allows 60 requests a minute", "type": "rate_limited", "metadata": { "error_type": "rate_limit_exceeded", "reason": "rate_limited" } } }
```

| Status | `type` | What happened | What to do |
|---|---|---|---|
| 400 | `model_needs_your_key` | a model other than the included one, without your OpenRouter key | send `Authorization: Bearer sk-or-...`, or use the included model |
| 400 | `invalid_input` and others | the request can't be run as written | fix the request; `message` says what |
| 401 | `morphscreen_key_required`, `morphscreen_key_invalid` | no MorphScreen key, or one we don't know or that was revoked | check `X-MorphScreen-Key` |
| 401 | `openrouter_key_required`, `openrouter_key_invalid` | OpenRouter turned your key down | check the key at OpenRouter |
| 402 | `plan_quota_reached` | this month's calls are used | wait for the month, or move to a bigger plan |
| 402 | `extra_limit_reached` | a paid plan's month and as many again as extra | wait for the month, or move up |
| 402 | `included_calls_used` | the free plan's calls on our model | send your own OpenRouter key, or pay for a plan |
| 402 | `included_calls_paused` | calls on our model are paused for the free plan | send your own OpenRouter key, or try later |
| 402 | `openrouter_out_of_credit` | your OpenRouter account is out of credit | add credit at OpenRouter |
| 403 | `account_suspended` | the account is suspended | write to support@morphscreen.com |
| 403 | `model_refused` | the model's moderation refused the request | change the request |
| 404 | `model_not_found` and others | no such model, or no such route | check the name |
| 413 | `payload_too_large` | the body is over 1 MB | send less |
| 413 | `conversation_too_long` | more than about 8,000 tokens of conversation on our model | trim the conversation, or use your own key |
| 429 | `rate_limited` | too many requests this minute | wait for `Retry-After` |
| 429 | `too_many_streams` | too many answers at once | wait for one to finish |
| 429 | `daily_limit_reached` | the free plan's calls today | wait for `Retry-After`: midnight UTC |
| 429 | `render_limit_reached` | this month's renders | wait for the month |
| 429 | `openrouter_rate_limited` | OpenRouter's own limit for your key | wait for `Retry-After` |
| 502 | | the model failed or couldn't be reached, after our retries | try again |
| 503 | | accounts can't be read just now | try again shortly |
| 504 | | the model took too long to start | try again, or another model |

A 429 always carries `Retry-After` in seconds. Retry 502, 503 and 504 with a backoff; don't retry the rest unchanged.

## Warnings before the end

At 80% and 100% of a month's calls, the account's address gets a mail saying how many are left and what happens next.


---

# Security

> Nothing a model writes ever runs, nothing loads from a host you didn't choose, and nothing of the conversation is kept. What runs, what loads, what's kept, and the content security policy to use.

A model can be talked into writing anything: a prompt injection in a page it read, or a reader asking it to. So nothing in an answer is trusted.

## Nothing a model wrote runs

The core reads the answer into a tree of the components your catalog knows, and the SDK draws that tree. There's no `eval`, no `new Function` and no script from an answer.

- **Text is text.** Raw HTML is never drawn as HTML; the few tags models write anyway (`<strong>`, `<br>`) are read as formatting, with their attributes dropped.
- **Components never run code.** When the reader acts, your app gets an action and decides what happens ([Actions and state](/docs/format/actions)).
- **A what-if formula** is compiled by the core into a short list of numbers, the sliders' names and a few operators, run by a ten-line stack machine as the sliders move. Nothing else can run.
- **Links and pictures** never go to `javascript:`, `vbscript:` or `file:`, and to `data:` only for an image. The address is read the way a browser reads it, so `java<tab>script:` is caught too.
- **No style attributes.** The core's HTML draws amounts as SVG and classes, so a strict `style-src` holds.

A test fills every attribute of every component with 17 attacks and puts raw `<script>`, `<iframe>`, `<style>` and handlers in the text, and the HTML must come out with none of them. It runs on every change.

## Nothing loads that you didn't choose

- **Pictures** load only from the hosts you list, or as `data:` images. Any other address, a model-written one included, shows the picture's description instead ([Pictures, icons and maps](/docs/format/media)).
- **Map tiles** come only from your own map provider, on your key. Without one, a map is its pins on a plain ground and nothing loads.
- **Video and audio** fetch nothing until the reader presses play.
- **An embed** (YouTube through youtube-nocookie.com, Vimeo, Spotify) is a link until the reader taps it, then loads in a sandboxed frame.
- **The camera, location, signatures and files** start only when the reader uses them, and the browser asks first.
- **The SDK sends nothing of its own:** no analytics, no telemetry. It fetches the core from wherever you say, and `connectAgent` talks only to the address you give it.

## A content security policy

A page that draws answers with the web SDK works under this policy, which we test with every component:

```http
default-src 'self';
script-src 'self' 'wasm-unsafe-eval';
style-src 'self';
img-src 'self' data: <your image hosts> <your map provider>;
media-src <your video and audio hosts>;
font-src 'self';
connect-src 'self';
frame-src https://www.youtube-nocookie.com https://player.vimeo.com https://open.spotify.com;
object-src 'none';
base-uri 'none'
```

`'wasm-unsafe-eval'` lets the core's WebAssembly start; it doesn't allow JavaScript `eval`. A theme applied with `@morphscreen/web/theme` adds a `<style>` element, so allow it with a nonce. A live map with MapLibre needs `worker-src 'self'`, and Google's tiles need `connect-src https://tile.googleapis.com`.

## What we keep

No prompt, no answer, no IP address, no API key.

- **Each call leaves one line:** when, how long, the endpoint, the model asked for and the one that answered, how it ended, whether the answer was valid and repaired, its error classes by component, the system prompt's version, and what the model cost. None of the conversation.
- **Debug logs** are the one exception, and they're opt-in per project: prompts and answers, deleted after 7 days.
- **Your MorphScreen keys** are kept as a <span class="nb">SHA-256</span> hash and their first 12 characters, so a key can be checked and shown as `ms_live_ab12...`, never read back.
- **Your OpenRouter key** goes to OpenRouter and nowhere else: never stored, never logged, and taken out of any error text before it's passed on.
- **The model in your plan** runs on our OpenRouter key, only through providers that keep no prompts.

The [privacy notice](/privacy) and the [sub-processors](/subprocessors) have the rest. Found a problem? See [reporting a security problem](/security).


---

# The dashboard

> Your keys, your usage against each limit, every call with what failed and what repair did, debug logs, billing and your account, at app.morphscreen.com.

The dashboard at [app.morphscreen.com](https://app.morphscreen.com) is where your account lives. Sign in with an email link or GitHub.

## Overview

This month's calls against your plan, with where the month is heading at today's pace, and a meter for each limit with what happens when it's reached. A chart shows calls a day over the last 30 days, split between those on our model and those on your own OpenRouter key.

## Keys

Make a key and copy it: it's shown once, then only its first characters. A project holds up to 20 keys. Revoking a key gives you 8 seconds to undo it, and it keeps working until then; after that it's refused everywhere.

## Calls

The newest 100 calls, each with how it ended, how long it took and how long until the first text, the model asked for and the one that answered, whether the answer was valid, which components had errors, and what repair did. Show only the failed ones to see what needs a look.

## Debug logs

Turn on debug logs for a project to keep its prompts and answers for 7 days, to see exactly what the model wrote. They're off unless you turn them on, and turning them off has an undo.

## Billing

Your plan, and every plan to move to. Paying opens Razorpay's checkout on the same page. An upgrade paid by card starts at once; other changes start when the period ends. Cancel whenever you like, and keep the plan with one click until the period ends ([how billing works](/pricing#billing-title)).

## Account

Your address, how you sign in, and deleting the account: everything it holds goes at once, except the payment records tax law asks us to keep.


---

# Troubleshooting

> The usual problems and their fixes: nothing draws, pictures don't show, a 401 or a 402, a stream that stops, and answers that keep failing.

## Nothing draws

- **The core didn't load.** `loadCore` fetches the `.wasm` file from the address you give it; open that address in the browser. It should be served as `application/wasm`. Each [integration](/docs/integrations) shows where to put it.
- **A content security policy blocks it.** WebAssembly needs `'wasm-unsafe-eval'` in `script-src` ([Security](/docs/production/security)).
- **The stylesheet is missing.** Import `@morphscreen/web/morphscreen.css` once on the page.
- **The packs differ.** Give the page the same `packs` and custom components as the API, or the page can't read what the model was allowed to write.

## A picture shows only its description

That's the SDK refusing a host you didn't list. Add the host to `imageHosts` if you trust it. A picture the model asked for with `find` and that nothing matched shows its description too, on purpose.

## A map is pins on a plain ground

There's no map provider. Pass `maps` with your provider and key ([Pictures, icons and maps](/docs/format/media)).

## 401

`morphscreen_key_invalid` means the key is wrong or revoked; `openrouter_key_invalid` means OpenRouter turned down the key in `Authorization`. Any bearer token is taken as an OpenRouter key, so don't put your MorphScreen key there. With OpenAI's SDK on the included model, turn its `Authorization` header off ([OpenAI-compatible clients](/docs/agents/openai-compatible)).

## 402 or 429

A limit was reached; [Limits and errors](/docs/production/limits) says which one by its `type`, and a 429's `Retry-After` says how long to wait.

## A stream stops part way

A reverse proxy in front of your route may be holding the stream. Turn off buffering for that route (`X-Accel-Buffering: no` for nginx, `flush_interval -1` for Caddy), and don't compress `text/event-stream`. An answer that hit the model's token limit ends as truncated, and the SDK draws it as cut off.

## Answers keep failing

Look at the calls on the dashboard: which components had errors, and what repair did. A small model makes more mistakes; fewer packs make a shorter prompt and fewer ways to slip. Turn on debug logs for a day to see exactly what was written.


---

# Integrations

> The web SDK works in any framework. Each page here is a small app we install, build and run in Chrome every week, so the code works as written.

The web SDK is one npm package: the core as WebAssembly, a renderer for the page, a React component, and a stylesheet. It works with any framework and any package manager. Each integration needs the same three things:

1. **The stylesheet:** import `@morphscreen/web/morphscreen.css` once.
2. **The core, served as a file:** `morphscreen.wasm` (or `morphscreen-agent.wasm` for `connectAgent`) from the package, at an address `loadCore` can fetch. How depends on your build tool, and each page shows it.
3. **The browser only:** the core runs in the browser. On a framework that renders on the server, load it in a client component or after mount.

## Frameworks

- [React](/docs/integrations/react): the `<Answer>` component, with Vite.
- [Next.js](/docs/integrations/nextjs): the App Router, the page rendered on the server and the answer in a client component.
- [Vue and Nuxt](/docs/integrations/vue): a client-only component.
- [Svelte and SvelteKit](/docs/integrations/svelte): `onMount`, with the core imported as a URL.
- [Angular](/docs/integrations/angular): the core as an asset, after the view starts.
- [Plain JavaScript](/docs/integrations/vanilla): `createAnswer` with Vite and no framework.
- [webpack](/docs/integrations/webpack): the core as an asset module.

## Package managers

Every package manager works: npm, pnpm, Yarn (with node_modules or Plug'n'Play) and bun. We install with each of them under Vite every week.

## On your server

Your server keeps the key and talks to MorphScreen: [Node.js](/docs/integrations/node), [Python](/docs/integrations/python), or [HTML with no JavaScript](/docs/integrations/html) for pages drawn on the server.

In these examples a saved answer stands in for your server's stream, so they run anywhere. In your app, the text comes from your server's route ([Quick start](/docs/quickstart)).


---

# React

> Draw an answer with the Answer component in React 18 or later. It reads the text as it grows, so you can pass your streamed text straight in.

```sh
npm install @morphscreen/web
```

`<Answer>` takes the core and the answer's text so far. When `text` grows, only the new part is read, so you can set it on every chunk. Set `done` when the answer is complete.

```tsx
import { useEffect, useState } from "react";
import { createRoot } from "react-dom/client";
import { loadCore, type Core } from "@morphscreen/web";
import { Answer } from "@morphscreen/web/react";
import "@morphscreen/web/morphscreen.css";
import wasm from "@morphscreen/web/morphscreen.wasm?url";
import { SAMPLE } from "./sample";

function App() {
  const [core, setCore] = useState<Core | null>(null);
  const [text, setText] = useState("");
  useEffect(() => {
    loadCore(wasm).then(setCore);
  }, []);
  // Your server's stream goes here; this grows a saved answer piece by piece.
  useEffect(() => {
    if (!core) return;
    let n = 0;
    const t = setInterval(() => {
      n += 24;
      setText(SAMPLE.slice(0, n));
      if (n >= SAMPLE.length) clearInterval(t);
    }, 10);
    return () => clearInterval(t);
  }, [core]);
  const done = text.length >= SAMPLE.length;
  useEffect(() => {
    if (done) document.body.dataset.done = "yes";
  }, [done]);
  return core ? <Answer core={core} text={text} done={done} /> : null;
}

createRoot(document.getElementById("root")!).render(<App />);
```

With Vite, `?url` turns the package's `morphscreen.wasm` into an address it serves with your app.

## Its props

| Prop | What it is |
|---|---|
| `core` | from `loadCore` |
| `text` | the answer so far; or `stream`, an async iterable of chunks |
| `done` | the answer is complete |
| `packs`, `custom`, `components` | the packs and your own components ([Your own components](/docs/format/custom-components)) |
| `onAction` | what the reader did ([Actions and state](/docs/format/actions)) |
| `imageHosts`, `maps`, `maplibre` | where pictures and map tiles load from ([Pictures, icons and maps](/docs/format/media)) |
| `className` | your classes for the answer's element |

For a whole conversation, use `connectAgent` in an effect ([Quick start](/docs/quickstart)), or `<Answer>` once per message.


---

# Next.js

> The App Router with the page rendered on the server and the answer drawn in a client component.

```sh
npm install @morphscreen/web
```

The core runs in the browser, so the answer goes in a client component. The page around it stays a server component.

## Serve the core

Copy `morphscreen.wasm` into `public/` before each build, so it's served at `/morphscreen.wasm`:

```js
// Copies the core out of the package into public/, where the app serves it
// and loadCore("/morphscreen.wasm") fetches it. Run before each build.
import { copyFileSync, mkdirSync } from "node:fs";
import { createRequire } from "node:module";

const require = createRequire(import.meta.url);
mkdirSync("public", { recursive: true });
copyFileSync(require.resolve("@morphscreen/web/morphscreen.wasm"), "public/morphscreen.wasm");
```

```json
{ "scripts": { "build": "node copy-wasm.mjs && next build" } }
```

## The stylesheet

```tsx
import "@morphscreen/web/morphscreen.css";

export const metadata = { title: "MorphScreen with Next.js" };

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

## The answer, in a client component

```tsx
"use client";

import { useEffect, useState } from "react";
import { loadCore, type Core } from "@morphscreen/web";
import { Answer } from "@morphscreen/web/react";
import { SAMPLE } from "./sample";

export function LiveAnswer() {
  const [core, setCore] = useState<Core | null>(null);
  const [text, setText] = useState("");
  useEffect(() => {
    loadCore("/morphscreen.wasm").then(setCore);
  }, []);
  // Your server's stream goes here; this grows a saved answer piece by piece.
  useEffect(() => {
    if (!core) return;
    let n = 0;
    const t = setInterval(() => {
      n += 24;
      setText(SAMPLE.slice(0, n));
      if (n >= SAMPLE.length) clearInterval(t);
    }, 10);
    return () => clearInterval(t);
  }, [core]);
  const done = text.length >= SAMPLE.length;
  useEffect(() => {
    if (done) document.body.dataset.done = "yes";
  }, [done]);
  return core ? <Answer core={core} text={text} done={done} /> : null;
}
```

```tsx
import { LiveAnswer } from "./answer";

// A server component: the page renders on the server, the answer in the browser.
export default function Page() {
  return (
    <main>
      <LiveAnswer />
    </main>
  );
}
```

## Your server route

Your `/api/agent` route can be a Route Handler doing what [the Quick start's server](/docs/quickstart) does: add `X-MorphScreen-Key`, set the model, and return MorphScreen's response body as the response.

```ts
// The page's AG-UI runs go on to MorphScreen with your key, and the events
// stream straight back. The key never reaches the browser, and the server
// picks the model.
export async function POST(req: Request) {
  const run = await req.json();
  run.forwardedProps = { ...run.forwardedProps, model: "deepseek/deepseek-v4.1-flash" };
  const upstream = await fetch("https://api.morphscreen.com/v1/ui", {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-MorphScreen-Key": process.env.MORPHSCREEN_KEY ?? "" },
    body: JSON.stringify(run),
  });
  return new Response(upstream.body, { status: upstream.status, headers: { "Content-Type": upstream.headers.get("content-type") ?? "text/event-stream" } });
}
```


---

# Vue and Nuxt

> A client-only component that draws the answer after it mounts, in Nuxt 4 or any Vue 3 app.

```sh
npm install @morphscreen/web
```

The core runs in the browser. In Nuxt, a component named `*.client.vue` renders only there, and `onMounted` runs after its element exists.

## Serve the core

Copy `morphscreen.wasm` into `public/` before each build:

```js
// Copies the core out of the package into public/, where the app serves it
// and loadCore("/morphscreen.wasm") fetches it. Run before each build.
import { copyFileSync, mkdirSync } from "node:fs";
import { createRequire } from "node:module";

const require = createRequire(import.meta.url);
mkdirSync("public", { recursive: true });
copyFileSync(require.resolve("@morphscreen/web/morphscreen.wasm"), "public/morphscreen.wasm");
```

## The stylesheet

```ts
export default defineNuxtConfig({
  css: ["@morphscreen/web/morphscreen.css"],
  telemetry: false,
});
```

## The answer

```vue
<script setup lang="ts">
import { onMounted, ref } from "vue";
import { createAnswer, loadCore } from "@morphscreen/web";
import { SAMPLE } from "../sample";

const el = ref<HTMLElement | null>(null);

onMounted(async () => {
  const core = await loadCore("/morphscreen.wasm");
  const answer = createAnswer(el.value!, { core });
  // Your server's stream goes here; this feeds a saved answer in pieces.
  for (let i = 0; i < SAMPLE.length; i += 24) {
    answer.push(SAMPLE.slice(i, i + 24));
    await new Promise((r) => setTimeout(r, 10));
  }
  answer.end();
  document.body.dataset.done = "yes";
});
</script>

<template>
  <div ref="el" />
</template>
```

```vue
<template>
  <main>
    <!-- The answer draws in the browser; the page around it renders on the server. -->
    <MorphAnswer />
  </main>
</template>
```

In a Vue app with Vite but no Nuxt, import the core's address the way the [Plain JavaScript](/docs/integrations/vanilla) page does (`@morphscreen/web/morphscreen.wasm?url`) instead of copying the file.


---

# Svelte and SvelteKit

> Draw the answer in onMount, with the core imported as a URL, in SvelteKit 3 or any Svelte 5 app.

```sh
npm install @morphscreen/web
```

`onMount` runs in the browser only, so the core never loads on the server. Vite's `?url` turns the package's `morphscreen.wasm` into an address it serves.

```svelte
<script lang="ts">
  import { onMount } from "svelte";
  import { createAnswer, loadCore } from "@morphscreen/web";
  import "@morphscreen/web/morphscreen.css";
  import wasm from "@morphscreen/web/morphscreen.wasm?url";
  import { SAMPLE } from "../lib/sample";

  let el: HTMLElement;

  // onMount runs in the browser only, so the core never loads on the server.
  onMount(async () => {
    const core = await loadCore(wasm);
    const answer = createAnswer(el, { core });
    // Your server's stream goes here; this feeds a saved answer in pieces.
    for (let i = 0; i < SAMPLE.length; i += 24) {
      answer.push(SAMPLE.slice(i, i + 24));
      await new Promise((r) => setTimeout(r, 10));
    }
    answer.end();
    document.body.dataset.done = "yes";
  });
</script>

<div bind:this={el}></div>
```

```ts
import adapter from "@sveltejs/adapter-static";
import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig } from "vite";

export default defineConfig({ plugins: [sveltekit({ adapter: adapter() })] });
```


---

# Angular

> The core served as an asset and drawn after the view starts, in Angular 22.

```sh
npm install @morphscreen/web
```

## Serve the core and the stylesheet

```json
{
  "styles": ["node_modules/@morphscreen/web/dist/morphscreen.css"],
  "assets": [{ "glob": "morphscreen.wasm", "input": "node_modules/@morphscreen/web/dist", "output": "/" }]
}
```

## The answer

```ts
import { AfterViewInit, Component, ElementRef, viewChild } from "@angular/core";
import { createAnswer, loadCore } from "@morphscreen/web";
import { SAMPLE } from "../sample";

@Component({
  selector: "app-root",
  template: `<div #answer></div>`,
})
export class App implements AfterViewInit {
  readonly answerEl = viewChild.required<ElementRef<HTMLElement>>("answer");

  async ngAfterViewInit() {
    const core = await loadCore("/morphscreen.wasm");
    const answer = createAnswer(this.answerEl().nativeElement, { core });
    // Your server's stream goes here; this feeds a saved answer in pieces.
    for (let i = 0; i < SAMPLE.length; i += 24) {
      answer.push(SAMPLE.slice(i, i + 24));
      await new Promise((r) => setTimeout(r, 10));
    }
    answer.end();
    document.body.dataset["done"] = "yes";
  }
}
```

Angular CLI 22 needs Node.js 22.22.3 or later, or 24.15 or later.


---

# Plain JavaScript

> createAnswer draws into any element, with no framework. Push the text as it arrives and end it when it's done.

```sh
npm install @morphscreen/web
```

```ts
import { createAnswer, loadCore } from "@morphscreen/web";
import "@morphscreen/web/morphscreen.css";
import wasm from "@morphscreen/web/morphscreen.wasm?url";
import { SAMPLE } from "./sample";

const core = await loadCore(wasm);
const answer = createAnswer(document.querySelector<HTMLElement>("#answer")!, { core });

// Your server's stream goes here; this feeds a saved answer in pieces.
for (let i = 0; i < SAMPLE.length; i += 24) {
  answer.push(SAMPLE.slice(i, i + 24));
  await new Promise((r) => setTimeout(r, 10));
}
answer.end();
document.body.dataset.done = "yes";
```

```html
<!doctype html>
<html lang="en">
  <head><meta charset="utf-8"><title>MorphScreen with Vite</title></head>
  <body>
    <div id="answer"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
```

`createAnswer` returns the answer: `push(text)` for each piece, `end()` when it's done, `html()` for the finished answer as HTML, `applyState(states)` to set what the reader did, and `destroy()`. [The web SDK reference](/docs/reference/web) has its options.


---

# webpack

> The core as an asset module and the stylesheet through css-loader, in webpack 5.

```sh
npm install @morphscreen/web
```

An `asset/resource` rule turns the imported `.wasm` into the address of a file webpack emits, which `loadCore` fetches.

```js
import HtmlWebpackPlugin from "html-webpack-plugin";

export default {
  entry: "./src/main.js",
  output: { clean: true },
  module: {
    rules: [
      { test: /\.css$/, use: ["style-loader", "css-loader"] },
      // The core is served as a file of its own, and loadCore fetches it.
      { test: /\.wasm$/, type: "asset/resource" },
    ],
  },
  plugins: [new HtmlWebpackPlugin({ title: "MorphScreen with webpack", templateContent: '<!doctype html><html lang="en"><head><meta charset="utf-8"></head><body><div id="answer"></div></body></html>' })],
};
```

```js
import { createAnswer, loadCore } from "@morphscreen/web";
import "@morphscreen/web/morphscreen.css";
import wasm from "@morphscreen/web/morphscreen.wasm";
import { SAMPLE } from "./sample.js";

const core = await loadCore(wasm);
const answer = createAnswer(document.querySelector("#answer"), { core });

// Your server's stream goes here; this feeds a saved answer in pieces.
for (let i = 0; i < SAMPLE.length; i += 24) {
  answer.push(SAMPLE.slice(i, i + 24));
  await new Promise((r) => setTimeout(r, 10));
}
answer.end();
document.body.dataset.done = "yes";
```


---

# Node.js

> Call MorphScreen from a Node.js server with nothing but fetch: carry a page's AG-UI runs, stream an answer's text, or render a finished answer as HTML.

Node 18 or later has everything this needs. Keep `MORPHSCREEN_KEY` in the server's environment; it never goes to the page.

## A route for the page

The page's `connectAgent` sends its runs to your route, which adds the key and the model and streams the events back:

```js
// Your server's one route for the page: each AG-UI run goes on to MorphScreen
// with your key, and the events stream straight back. The key never reaches
// the browser, and the server, not the page, picks the model.
import { createServer } from "node:http";

const API = process.env.MORPHSCREEN_API ?? "https://api.morphscreen.com/v1";
const MODEL = process.env.MODEL ?? "deepseek/deepseek-v4.1-flash";

createServer(async (req, res) => {
  if (req.method !== "POST" || req.url !== "/api/agent") return res.writeHead(404).end();
  let body = "";
  for await (const chunk of req) body += chunk;
  const run = JSON.parse(body);
  run.forwardedProps = { ...run.forwardedProps, model: MODEL };
  const upstream = await fetch(`${API}/ui`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-MorphScreen-Key": process.env.MORPHSCREEN_KEY },
    body: JSON.stringify(run),
  });
  res.writeHead(upstream.status, { "Content-Type": upstream.headers.get("content-type") ?? "text/event-stream" });
  for await (const chunk of upstream.body) res.write(chunk);
  res.end();
}).listen(process.env.PORT ?? 3000);
```

In Express, Fastify or Hono, the route body is the same: read the run, set `forwardedProps.model`, `fetch` MorphScreen's `/v1/ui`, and pipe the response body back with its status and content type.

## The answer's text, or HTML

For work on the server (a mail, a saved report, a page drawn without JavaScript), stream the answer's text from `/v1/chat/completions`, or render a finished answer with `/v1/render`:

```js
// An answer's text as it streams, and a finished answer as HTML. Run it on
// your server (Node 18 or later): the key stays there.
const API = process.env.MORPHSCREEN_API ?? "https://api.morphscreen.com/v1";
const HEADERS = { "Content-Type": "application/json", "X-MorphScreen-Key": process.env.MORPHSCREEN_KEY };

/** Yields the answer's text, piece by piece, as the model writes it. */
export async function* streamAnswer(messages, model = "deepseek/deepseek-v4.1-flash") {
  const res = await fetch(`${API}/chat/completions`, { method: "POST", headers: HEADERS, body: JSON.stringify({ model, stream: true, messages }) });
  if (!res.ok) throw new Error(`MorphScreen ${res.status}: ${await res.text()}`);
  const decoder = new TextDecoder();
  let buffer = "";
  for await (const chunk of res.body) {
    buffer += decoder.decode(chunk, { stream: true });
    let end;
    while ((end = buffer.indexOf("\n")) >= 0) {
      const line = buffer.slice(0, end).trim();
      buffer = buffer.slice(end + 1);
      if (!line.startsWith("data: ") || line === "data: [DONE]") continue;
      for (const choice of JSON.parse(line.slice(6)).choices ?? []) if (choice.delta?.content) yield choice.delta.content;
    }
  }
}

/** A finished answer drawn by the core as HTML, with its verdict. */
export async function renderHtml(text) {
  const res = await fetch(`${API}/render`, { method: "POST", headers: HEADERS, body: JSON.stringify({ text }) });
  if (!res.ok) throw new Error(`MorphScreen ${res.status}: ${await res.text()}`);
  const { html, morphscreen } = await res.json();
  return { html, verdict: morphscreen };
}
```

```js
import { renderHtml, streamAnswer } from "./morphscreen.mjs";

let text = "";
for await (const piece of streamAnswer([{ role: "user", content: "Make me a sales dashboard" }])) text += piece;
const { html, verdict } = await renderHtml(text);
```

Both are what our tests run against a recorded answer, in Node and in Python.


---

# Python

> Call MorphScreen from Python with only the standard library: carry a page's AG-UI runs, stream an answer's text, or render a finished answer as HTML.

Nothing to install: these use only Python's standard library. Keep `MORPHSCREEN_KEY` in the server's environment; it never goes to the page.

## A route for the page

The page's `connectAgent` sends its runs to your route, which adds the key and the model and streams the events back:

```python
# Your server's one route for the page, with nothing but the standard
# library: each AG-UI run goes on to MorphScreen with your key, and the
# events stream straight back. The key never reaches the browser, and the
# server, not the page, picks the model.
import json
import os
import urllib.error
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

API = os.environ.get("MORPHSCREEN_API", "https://api.morphscreen.com/v1")
MODEL = os.environ.get("MODEL", "deepseek/deepseek-v4.1-flash")


class Agent(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/api/agent":
            self.send_error(404)
            return
        run = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
        run["forwardedProps"] = {**run.get("forwardedProps", {}), "model": MODEL}
        req = urllib.request.Request(
            f"{API}/ui",
            data=json.dumps(run).encode(),
            headers={"Content-Type": "application/json", "X-MorphScreen-Key": os.environ.get("MORPHSCREEN_KEY", "")},
            method="POST",
        )
        try:
            upstream = urllib.request.urlopen(req)
        except urllib.error.HTTPError as e:
            upstream = e
        with upstream:
            self.send_response(upstream.status)
            self.send_header("Content-Type", upstream.headers.get("Content-Type", "text/event-stream"))
            self.end_headers()
            while chunk := upstream.read1(4096):
                self.wfile.write(chunk)
                self.wfile.flush()


ThreadingHTTPServer(("127.0.0.1", int(os.environ.get("PORT", "3000"))), Agent).serve_forever()
```

In FastAPI, Flask or Django the route does the same: read the run, set `forwardedProps["model"]`, POST it to MorphScreen's `/v1/ui`, and stream the response body back with its status and content type, without buffering it.

## The answer's text, or HTML

```python
# An answer's text as it streams, and a finished answer as HTML, with nothing
# but the standard library. Run it on your server: the key stays there.
import json
import os
import urllib.request

API = os.environ.get("MORPHSCREEN_API", "https://api.morphscreen.com/v1")
HEADERS = {"Content-Type": "application/json", "X-MorphScreen-Key": os.environ.get("MORPHSCREEN_KEY", "")}


def stream_answer(messages, model="deepseek/deepseek-v4.1-flash"):
    """Yields the answer's text, piece by piece, as the model writes it."""
    body = json.dumps({"model": model, "stream": True, "messages": messages}).encode()
    req = urllib.request.Request(f"{API}/chat/completions", data=body, headers=HEADERS, method="POST")
    with urllib.request.urlopen(req) as res:
        for line in res:
            line = line.decode().strip()
            if not line.startswith("data: ") or line == "data: [DONE]":
                continue
            for choice in json.loads(line[6:]).get("choices", []):
                text = (choice.get("delta") or {}).get("content")
                if text:
                    yield text


def render_html(text):
    """A finished answer drawn by the core as HTML, with its verdict."""
    req = urllib.request.Request(f"{API}/render", data=json.dumps({"text": text}).encode(), headers=HEADERS, method="POST")
    with urllib.request.urlopen(req) as res:
        out = json.load(res)
    return out["html"], out["morphscreen"]
```

```python
from morphscreen import render_html, stream_answer

text = "".join(stream_answer([{"role": "user", "content": "Make me a sales dashboard"}]))
html, verdict = render_html(text)
```

Both are what our tests run against a recorded answer.

## With OpenAI's SDK

On your own OpenRouter key, OpenAI's Python SDK works with a new `base_url` and the `X-MorphScreen-Key` header ([OpenAI-compatible clients](/docs/agents/openai-compatible)). For the model in your plan, use the functions above: any `Authorization` header is taken as an OpenRouter key.


---

# HTML without JavaScript

> Render a finished answer as HTML on your server with /v1/render. It needs no script, passes a strict content security policy, and works in mail, feeds and pages without JavaScript.

`/v1/render` draws an answer you already have, with no model called. The HTML has no script and no style attributes: tabs switch with radio buttons, details open, selects and date inputs are the browser's own, charts and maps are SVG.

```bash
curl https://api.morphscreen.com/v1/render \
  -H "X-MorphScreen-Key: $MORPHSCREEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "## Budget\n\n<Stat label=\"Per day\" value=\"$165\" />\n"}'
```

```json
{ "html": "<h2>Budget</h2>\n<div class=\"ms-stat\">...</div>", "morphscreen": { "valid": true, "truncated": false, "components": 1, "diagnostics": [] } }
```

Put it in a page with the stylesheets from the web SDK's package (`dist/morphscreen.css` and its `fonts/`, and `dist/morphscreen-page.css` for a page that is just the answer):

```html
<link rel="stylesheet" href="/morphscreen.css">
<link rel="stylesheet" href="/morphscreen-page.css">
<main class="ms-answer"><!-- the html from /v1/render --></main>
```

Every component draws this way; the [component reference](/docs/components) is this HTML. `output: "ops"` or `"tree"` returns the core's op stream or tree instead, for drawing it yourself.

Renders are free up to ten times your plan's calls a month. Pictures load only from your images' and photo provider's hosts, and those you list in `image_hosts`.


---

# All components

> The 75 components a model can use, in 9 packs: what each is for, its attributes, and a live preview drawn by the core.

Every answer can use the `core` pack. The others are added by default; an app that names the packs it wants (`packs` in the API and the SDKs) gets core and those, and the model is told about only those. Fewer packs make a shorter system prompt: core alone is about 1,400 tokens, every pack about 2,900.

| Pack | Components | What it's for |
|---|---|---|
| [Core](/docs/components/core) | 25 | Always included: layout, text blocks, numbers, charts, forms and buttons. |
| [Data](/docs/components/data) | 7 | Ways to show data beyond charts and tables: facts, timelines, gauges, heatmaps, funnels, sparklines and hierarchies. |
| [Commerce](/docs/components/commerce) | 6 | Shopping: products, pricing plans, carts, ratings, comparisons and prices. |
| [Device](/docs/components/device) | 10 | The device's own hardware and apps: maps, camera, scanning, location, files, contacts, the calendar, sharing, voice notes and QR codes. Native on every platform, with a web fallback that needs no JavaScript. |
| [Docs](/docs/components/docs) | 5 | Technical writing: code with a file name, diffs, formulas, file trees and cited sources. |
| [Inputs](/docs/components/inputs) | 6 | More form fields: star ratings, searchable choices, times, toggle groups, steppers and signatures. |
| [Interactive](/docs/components/interactive) | 7 | Things the reader does on the page, kept on their device and reported back: a quiz, flashcards, a poll, a checklist, and what-if sliders. |
| [Media](/docs/components/media) | 4 | Video, audio, embeds from known hosts, and a carousel of images. |
| [Scheduling](/docs/components/scheduling) | 5 | Time: a month calendar, events, time slots to pick, a day's agenda and countdowns. |

## Names models use on their own

A few names models reach for without being told are read as the component they mean, and reported as a note, never taught:

| They write | It's read as |
|---|---|
| `<Table>` | `<Card>`: a section holding a Markdown table |
| `<Column>` | a plain group: one cell of Columns |
| `<Buttons>` | a plain group: a row of buttons |
| `<Text>` | a plain group: what models call a run of text |

## Every component

- **Core:** [Card](/docs/components/core#card), [Columns](/docs/components/core#columns), [Tabs](/docs/components/core#tabs), [Tab](/docs/components/core#tab), [Details](/docs/components/core#details), [Steps](/docs/components/core#steps), [Step](/docs/components/core#step), [Callout](/docs/components/core#callout), [Stat](/docs/components/core#stat), [Badge](/docs/components/core#badge), [Progress](/docs/components/core#progress), [Avatar](/docs/components/core#avatar), [Gallery](/docs/components/core#gallery), [Chart](/docs/components/core#chart), [FollowUps](/docs/components/core#followups), [Form](/docs/components/core#form), [Input](/docs/components/core#input), [TextArea](/docs/components/core#textarea), [Select](/docs/components/core#select), [Date](/docs/components/core#date), [Slider](/docs/components/core#slider), [Checkboxes](/docs/components/core#checkboxes), [Radio](/docs/components/core#radio), [Switch](/docs/components/core#switch), [Button](/docs/components/core#button)
- **Data:** [KeyValue](/docs/components/data#keyvalue), [Timeline](/docs/components/data#timeline), [Gauge](/docs/components/data#gauge), [Heatmap](/docs/components/data#heatmap), [Funnel](/docs/components/data#funnel), [Sparkline](/docs/components/data#sparkline), [Tree](/docs/components/data#tree)
- **Commerce:** [Product](/docs/components/commerce#product), [Plan](/docs/components/commerce#plan), [Cart](/docs/components/commerce#cart), [Rating](/docs/components/commerce#rating), [Compare](/docs/components/commerce#compare), [Price](/docs/components/commerce#price)
- **Device:** [Map](/docs/components/device#map), [Camera](/docs/components/device#camera), [Scan](/docs/components/device#scan), [Location](/docs/components/device#location), [File](/docs/components/device#file), [Contact](/docs/components/device#contact), [AddToCalendar](/docs/components/device#addtocalendar), [Share](/docs/components/device#share), [VoiceNote](/docs/components/device#voicenote), [QR](/docs/components/device#qr)
- **Docs:** [Code](/docs/components/docs#code), [Diff](/docs/components/docs#diff), [Math](/docs/components/docs#math), [FileTree](/docs/components/docs#filetree), [Citation](/docs/components/docs#citation)
- **Inputs:** [RatingInput](/docs/components/inputs#ratinginput), [Combobox](/docs/components/inputs#combobox), [Time](/docs/components/inputs#time), [ToggleGroup](/docs/components/inputs#togglegroup), [Stepper](/docs/components/inputs#stepper), [Signature](/docs/components/inputs#signature)
- **Interactive:** [Quiz](/docs/components/interactive#quiz), [Question](/docs/components/interactive#question), [Flashcards](/docs/components/interactive#flashcards), [Poll](/docs/components/interactive#poll), [Checklist](/docs/components/interactive#checklist), [WhatIf](/docs/components/interactive#whatif), [Result](/docs/components/interactive#result)
- **Media:** [Video](/docs/components/media#video), [Audio](/docs/components/media#audio), [Embed](/docs/components/media#embed), [Carousel](/docs/components/media#carousel)
- **Scheduling:** [Calendar](/docs/components/scheduling#calendar), [Event](/docs/components/scheduling#event), [TimeSlots](/docs/components/scheduling#timeslots), [Agenda](/docs/components/scheduling#agenda), [Countdown](/docs/components/scheduling#countdown)


---

# Core components

> The core pack's 25 components: always included: layout, text blocks, numbers, charts, forms and buttons.

Core comes with every answer, whichever packs an app names.

## Markdown

Text between components is Markdown: headings, lists, tables, emphasis, links, code and images from the hosts an app allows.

```markdown
## A weekend in Lisbon

Lisbon is **compact and hilly**. Most of what you want to see sits between Baixa and Belém, and the trams cover the steep parts.

![Belém Tower on the Tagus](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKAAAAB4CAIAAAD6wG44AAACmklEQVR42u3dQU7bQBQGYDOteopKZdMjVF3CrhKX7C2oqm5gWfUIbOAmXVTqgiCI43nPMy/fv4QQz/jLe7bjSbj4/uPXInXT7ALAAlgAC2ABLIAFMGABLIAFsAAWwAIYsACW+fLeLgjNt69fDn/48/cfwAVdD3+bIK1FZ+ue9kgVPBntsz+JK2UVvKduQikD3l831Biw62DJKr6IIgY8lkp3Y8BatADWn4d9TsAqWAALYAEsgAVwaiJu8/V9TsAqWADr0sP2fMADqUQc0QFr0ZJSfEHr7gAPYRy3qtKy2f7Gq+73Ra99V8F7lnLCJxtUcKyxzyapZmfRy7Isy+3dvZdLTeDbu/t/uowLAj9D/Y8t0wO/Ysl4euA3CRnPCnx8E2Y8H/BaM4fkaYC3UDEeHXi70PjGe43wYt9/jNV92jfXVyPr5g9vN+C4V/RQxofTTB5eq9evxmnXL44k+cQwu4LT5rZvHR8zzZwRtqonGjteQQ11Hd9q7+78ja7aYsLwMlr07gfFnGa4ZZpxI4wFHuryNJR5+0yDhtfO5xZ90Hh6HX2ChteKneAk78S+Txix0zq36CneFu7VDKd4r6Yn8Fxv+m/ZiQkz7WXcavfkCKScmfbaSjvn9Y6D337usq1NLbrMjdhj+uGOk93Srhvd8ZeAbdn6KRVcdQXFi4UyzmRPq+NG95WpDTXZ0wazooLPZ+nTzfXVyJNdVcpHAVvVNq9xo1v7Aq9ZdVzbuCncqY3fZGoKt3YpN4Vb27gp3NrGTeHWPiS/+/Dx08Pjk71TJg+PT58vL31P1rm0a8DFjX1PVnFjFbz4ALgAFsACWAALYAEMWAALYAEsgAWwAAYsgAWwABbAAlgAC2DAAlgAC2ABLIAFMGABLNPkL96PXxmAn95xAAAAAElFTkSuQmCC)

- Day one: Alfama, the castle, a fado dinner
- Day two: Belém, pastries, the river walk
- Day three: Sintra by train (40 minutes from Rossio)

| Neighbourhood | Good for | From the centre |
|---|---|---|
| Alfama | Old streets, fado | 10 min walk |
| Belém | Monuments, pastries | 20 min by tram |
| Príncipe Real | Gardens, shops | 15 min walk |

> The 28 tram is lovely but packed after 10:00. Ride it early.

Book the castle online with `code LISBOA10` for 10% off.
```
## Card

A section, optionally with a header.

Between its tags: Markdown and other components.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |
| `subtitle` | text |  |  |

```markdown
<Card title="Trip budget" subtitle="Three nights, two people">
Flights are booked. What's left is the hotel, food and two day trips, about **€740** in all.
</Card>
```
## Columns

Puts its children side by side, stacking on narrow screens.

Between its tags: Markdown and other components.

```markdown
<Columns>
<Card title="Hotel">
Three nights in Chiado, breakfast included. Check-in from 15:00.
</Card>
<Card title="Flights">
TP 1351 out on Friday 08:40, TP 1358 back on Monday 19:15.
</Card>
<Card title="Getting around">
A Viva Viagem card covers trams, metro and the river ferries.
</Card>
</Columns>
```
## Tabs

One panel per Tab.

Between its tags: only `Tab` components.

```markdown
<Tabs>
<Tab title="Overview">
Three nights, flights booked, hotel to confirm by Thursday.
</Tab>
<Tab title="Food">
- Time Out Market for the first night
- Pastéis de Belém on day two
- A tasca in Alfama for fado
</Tab>
<Tab title="Packing">
Comfortable shoes (the hills are steep), a light jacket for the evenings, sunscreen.
</Tab>
</Tabs>
```
## Tab

A panel inside Tabs.

Between its tags: Markdown and other components. It goes inside `Tabs`.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text | yes |  |

```markdown
<Tabs>
<Tab title="Overview">
Three nights, flights booked, hotel to confirm by Thursday.
</Tab>
<Tab title="Food">
- Time Out Market for the first night
- Pastéis de Belém on day two
- A tasca in Alfama for fado
</Tab>
<Tab title="Packing">
Comfortable shoes (the hills are steep), a light jacket for the evenings, sunscreen.
</Tab>
</Tabs>
```
## Details

A collapsible section, closed until opened (open starts it open).

Between its tags: Markdown and other components.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text | yes |  |
| `open` | true or false |  |  |

```markdown
<Details title="Why the hotel costs more on Saturday">
Weekend rates in Chiado run about 30% higher, and this weekend there's a football match at the Estádio da Luz.
</Details>
<Details title="Cancellation terms" open="true">
Free cancellation until 48 hours before check-in. After that the first night is charged.
</Details>
```
## Steps

An ordered sequence or timeline.

Between its tags: only `Step` components.

```markdown
<Steps>
<Step title="Book flights" status="done" subtitle="Paid on 2 October" />
<Step title="Confirm the hotel" status="current" subtitle="Due Thursday">
Reply to the hotel's email with the arrival time.
</Step>
<Step title="Buy the Sintra train tickets" status="todo" />
</Steps>
```
## Step

One step inside Steps.

Between its tags: Markdown and other components. It goes inside `Steps`.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text | yes |  |
| `status` | one of |  | `done`, `current`, `todo` (default) |
| `subtitle` | text |  |  |

```markdown
<Steps>
<Step title="Book flights" status="done" subtitle="Paid on 2 October" />
<Step title="Confirm the hotel" status="current" subtitle="Due Thursday">
Reply to the hotel's email with the arrival time.
</Step>
<Step title="Buy the Sintra train tickets" status="todo" />
</Steps>
```
## Callout

A highlighted note or alert.

Between its tags: Markdown and other components.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `tone` | one of |  | `neutral`, `info` (default), `success`, `warning`, `danger` |
| `title` | text |  |  |

```markdown
<Callout tone="info" title="Tip">Museums are free on Sunday mornings for residents only, so check the ticket rules.</Callout>

<Callout tone="success" title="Booked">Your table at Taberna Sal Grosso is confirmed for 20:30.</Callout>

<Callout tone="warning" title="Strike on Friday">Metro staff plan a partial strike from 06:30 to 10:30.</Callout>

<Callout tone="danger" title="Passport expires soon">It must be valid for three months after your return date.</Callout>

<Callout tone="neutral">Prices are in euros and include VAT.</Callout>
```
## Stat

One key number, its unit inside value ("3.7 km", "$1,204").

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `value` | text | yes |  |
| `change` | text |  |  |
| `note` | text |  |  |
| `tone` | one of |  | `neutral` (default), `info`, `success`, `warning`, `danger` |
| `icon` | icon name |  |  |

```markdown
<Columns>
<Stat label="Monthly revenue" value="$48,210" change="+12.4%" tone="success" icon="currency-dollar" />
<Stat label="Active users" value="3,904" change="+3.1%" note="vs last month" />
<Stat label="Churn" value="2.8%" change="+0.6 pts" tone="danger" />
</Columns>
```
## Badge

A short status label.

Between its tags: inline text: its label.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `tone` | one of |  | `neutral` (default), `info`, `success`, `warning`, `danger` |

```markdown
Order **#4821** is <Badge tone="success">Shipped</Badge>, invoice <Badge tone="warning">Overdue</Badge>, return window <Badge tone="info">14 days</Badge>, payment <Badge tone="danger">Failed</Badge>, label <Badge>Draft</Badge>.
```
## Progress

A progress bar.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `value` | number | yes |  |
| `max` | number |  | default `100` |
| `label` | text |  |  |
| `tone` | one of |  | `neutral` (default), `info`, `success`, `warning`, `danger` |

```markdown
<Progress label="Course progress" value="7" max="12" />
<Progress label="Storage used" value="91" max="100" tone="danger" />
<Progress label="Fundraising goal" value="64" tone="success" />
```
## Avatar

A person's picture or initials, with their name.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `name` | text | yes |  |
| `src` | address |  |  |
| `subtitle` | text |  |  |

```markdown
<Columns>
<Avatar name="Inês Duarte" subtitle="Product lead" />
<Avatar name="Tomás Ribeiro" subtitle="Engineering" />
<Avatar name="Mia Chen" subtitle="Design" />
</Columns>
```
## Gallery

A grid of images.

Between its tags: Markdown images, one a line.

```markdown
<Gallery>
![Tram 28 climbing through Alfama](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKAAAAB4CAIAAAD6wG44AAACmklEQVR42u3dQU7bQBQGYDOteopKZdMjVF3CrhKX7C2oqm5gWfUIbOAmXVTqgiCI43nPMy/fv4QQz/jLe7bjSbj4/uPXInXT7ALAAlgAC2ABLIAFMGABLIAFsAAWwAIYsACW+fLeLgjNt69fDn/48/cfwAVdD3+bIK1FZ+ue9kgVPBntsz+JK2UVvKduQikD3l831Biw62DJKr6IIgY8lkp3Y8BatADWn4d9TsAqWAALYAEsgAVwaiJu8/V9TsAqWADr0sP2fMADqUQc0QFr0ZJSfEHr7gAPYRy3qtKy2f7Gq+73Ra99V8F7lnLCJxtUcKyxzyapZmfRy7Isy+3dvZdLTeDbu/t/uowLAj9D/Y8t0wO/Ysl4euA3CRnPCnx8E2Y8H/BaM4fkaYC3UDEeHXi70PjGe43wYt9/jNV92jfXVyPr5g9vN+C4V/RQxofTTB5eq9evxmnXL44k+cQwu4LT5rZvHR8zzZwRtqonGjteQQ11Hd9q7+78ja7aYsLwMlr07gfFnGa4ZZpxI4wFHuryNJR5+0yDhtfO5xZ90Hh6HX2ChteKneAk78S+Txix0zq36CneFu7VDKd4r6Yn8Fxv+m/ZiQkz7WXcavfkCKScmfbaSjvn9Y6D337usq1NLbrMjdhj+uGOk93Srhvd8ZeAbdn6KRVcdQXFi4UyzmRPq+NG95WpDTXZ0wazooLPZ+nTzfXVyJNdVcpHAVvVNq9xo1v7Aq9ZdVzbuCncqY3fZGoKt3YpN4Vb27gp3NrGTeHWPiS/+/Dx08Pjk71TJg+PT58vL31P1rm0a8DFjX1PVnFjFbz4ALgAFsACWAALYAEMWAALYAEsgAWwAAYsgAWwABbAAlgAC2DAAlgAC2ABLIAFMGABLNPkL96PXxmAn95xAAAAAElFTkSuQmCC)
![Pastéis de nata fresh from the oven](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKAAAAB4CAIAAAD6wG44AAACmklEQVR42u3dQU7bQBQGYDOteopKZdMjVF3CrhKX7C2oqm5gWfUIbOAmXVTqgiCI43nPMy/fv4QQz/jLe7bjSbj4/uPXInXT7ALAAlgAC2ABLIAFMGABLIAFsAAWwAIYsACW+fLeLgjNt69fDn/48/cfwAVdD3+bIK1FZ+ue9kgVPBntsz+JK2UVvKduQikD3l831Biw62DJKr6IIgY8lkp3Y8BatADWn4d9TsAqWAALYAEsgAVwaiJu8/V9TsAqWADr0sP2fMADqUQc0QFr0ZJSfEHr7gAPYRy3qtKy2f7Gq+73Ra99V8F7lnLCJxtUcKyxzyapZmfRy7Isy+3dvZdLTeDbu/t/uowLAj9D/Y8t0wO/Ysl4euA3CRnPCnx8E2Y8H/BaM4fkaYC3UDEeHXi70PjGe43wYt9/jNV92jfXVyPr5g9vN+C4V/RQxofTTB5eq9evxmnXL44k+cQwu4LT5rZvHR8zzZwRtqonGjteQQ11Hd9q7+78ja7aYsLwMlr07gfFnGa4ZZpxI4wFHuryNJR5+0yDhtfO5xZ90Hh6HX2ChteKneAk78S+Txix0zq36CneFu7VDKd4r6Yn8Fxv+m/ZiQkz7WXcavfkCKScmfbaSjvn9Y6D337usq1NLbrMjdhj+uGOk93Srhvd8ZeAbdn6KRVcdQXFi4UyzmRPq+NG95WpDTXZ0wazooLPZ+nTzfXVyJNdVcpHAVvVNq9xo1v7Aq9ZdVzbuCncqY3fZGoKt3YpN4Vb27gp3NrGTeHWPiS/+/Dx08Pjk71TJg+PT58vL31P1rm0a8DFjX1PVnFjFbz4ALgAFsACWAALYAEMWAALYAEsgAWwAAYsgAWwABbAAlgAC2DAAlgAC2ABLIAFMGABLNPkL96PXxmAn95xAAAAAElFTkSuQmCC)
![The view from Miradouro de Santa Luzia](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKAAAAB4CAIAAAD6wG44AAACmklEQVR42u3dQU7bQBQGYDOteopKZdMjVF3CrhKX7C2oqm5gWfUIbOAmXVTqgiCI43nPMy/fv4QQz/jLe7bjSbj4/uPXInXT7ALAAlgAC2ABLIAFMGABLIAFsAAWwAIYsACW+fLeLgjNt69fDn/48/cfwAVdD3+bIK1FZ+ue9kgVPBntsz+JK2UVvKduQikD3l831Biw62DJKr6IIgY8lkp3Y8BatADWn4d9TsAqWAALYAEsgAVwaiJu8/V9TsAqWADr0sP2fMADqUQc0QFr0ZJSfEHr7gAPYRy3qtKy2f7Gq+73Ra99V8F7lnLCJxtUcKyxzyapZmfRy7Isy+3dvZdLTeDbu/t/uowLAj9D/Y8t0wO/Ysl4euA3CRnPCnx8E2Y8H/BaM4fkaYC3UDEeHXi70PjGe43wYt9/jNV92jfXVyPr5g9vN+C4V/RQxofTTB5eq9evxmnXL44k+cQwu4LT5rZvHR8zzZwRtqonGjteQQ11Hd9q7+78ja7aYsLwMlr07gfFnGa4ZZpxI4wFHuryNJR5+0yDhtfO5xZ90Hh6HX2ChteKneAk78S+Txix0zq36CneFu7VDKd4r6Yn8Fxv+m/ZiQkz7WXcavfkCKScmfbaSjvn9Y6D337usq1NLbrMjdhj+uGOk93Srhvd8ZeAbdn6KRVcdQXFi4UyzmRPq+NG95WpDTXZ0wazooLPZ+nTzfXVyJNdVcpHAVvVNq9xo1v7Aq9ZdVzbuCncqY3fZGoKt3YpN4Vb27gp3NrGTeHWPiS/+/Dx08Pjk71TJg+PT58vL31P1rm0a8DFjX1PVnFjFbz4ALgAFsACWAALYAEMWAALYAEsgAWwAAYsgAWwABbAAlgAC2DAAlgAC2ABLIAFMGABLNPkL96PXxmAn95xAAAAAElFTkSuQmCC)
</Gallery>
```
## Chart

Charts the Markdown table inside: first column labels, every column after it numbers (one series each).

Between its tags: a Markdown table (first column labels, the others series).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `type` | one of |  | `bar` (default), `line`, `area`, `pie`, `donut`, `radar`, `scatter`, `stacked`, `horizontal` |
| `title` | text |  |  |
| `x` | text |  |  |
| `y` | text |  |  |

### bar

```markdown
<Chart type="bar" title="Signups by month" y="Signups">
| Month | Signups |
|---|---|
| Jan | 120 |
| Feb | 180 |
| Mar | 240 |
| Apr | 210 |
| May | 305 |
</Chart>
```
### line

```markdown
<Chart type="line" title="Points by round" x="Round" y="Points">
| Round | Antonelli | Russell | Hamilton |
|---|---|---|---|
| 1 | 25 | 18 | 15 |
| 2 | 43 | 36 | 27 |
| 3 | 68 | 51 | 45 |
| 4 | 93 | 69 | 57 |
| 5 | 111 | 94 | 70 |
</Chart>
```
### area

```markdown
<Chart type="area" title="Visitors this week" y="Visitors">
| Day | Visitors |
|---|---|
| Mon | 1,200 |
| Tue | 1,450 |
| Wed | 1,380 |
| Thu | 1,720 |
| Fri | 1,960 |
</Chart>
```
### stacked

```markdown
<Chart type="stacked" title="Tickets by priority">
| Week | High | Medium | Low |
|---|---|---|---|
| W1 | 12 | 22 | 30 |
| W2 | 9 | 25 | 34 |
| W3 | 14 | 19 | 28 |
| W4 | 7 | 21 | 31 |
</Chart>
```
### horizontal

```markdown
<Chart type="horizontal" title="Course fill rates" y="Fill %">
| Course | Fill % |
|---|---|
| CS 101 Intro to Programming | 98 |
| BIO 150 Genetics | 89 |
| ART 210 Modern Art History | 78 |
| ECO 120 Microeconomics | 71 |
</Chart>
```
### scatter

```markdown
<Chart type="scatter" title="Price against rating" x="Price ($)" y="Rating">
| Price | Rating |
|---|---|
| 49 | 4.1 |
| 79 | 3.6 |
| 129 | 4.8 |
| 199 | 4.4 |
| 249 | 4.6 |
</Chart>
```
### pie

```markdown
<Chart type="pie" title="Traffic sources">
| Source | Visits |
|---|---|
| Search | 5,400 |
| Social | 2,100 |
| Direct | 1,500 |
| Email | 600 |
</Chart>
```
### donut

```markdown
<Chart type="donut" title="Customers by plan">
| Plan | Customers |
|---|---|
| Free | 1,842 |
| Pro | 1,214 |
| Team | 702 |
</Chart>
```
### radar

```markdown
<Chart type="radar" title="Player skills">
| Skill | Alex | Sam |
|---|---|---|
| Speed | 8 | 6 |
| Power | 6 | 9 |
| Accuracy | 9 | 7 |
| Stamina | 7 | 8 |
| Teamwork | 8 | 7 |
</Chart>
```
## FollowUps

Suggested next questions the user can tap.

Between its tags: a Markdown list.

```markdown
<FollowUps>
- What's the cheapest way to get to Sintra?
- Find me a fado house that isn't touristy
- Plan day two around the rain forecast
</FollowUps>
```
## Form

Groups fields; its Button submits them.

Between its tags: Markdown and other components.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `name` | text |  |  |

```markdown
<Card title="Book a demo" subtitle="Tell us about your team">
<Form name="demo-request">
<Input label="Full name" name="name" placeholder="Jane Smith" required="true" />
<Input label="Work email" name="email" type="email" placeholder="jane@company.com" hint="We only use this to reply" required="true" />
<Select label="Team size" name="size" placeholder="Choose a range" options="1-10 people | 11-50 people | 51+ people" />
<Date label="Preferred date" name="date" />
<Slider label="Seats" name="seats" min="1" max="50" value="8" />
<Checkboxes label="Interested in" name="interests" options="Analytics | Billing | Support inbox" value="Analytics" />
<Radio label="Plan" name="plan" options="Cloud, managed by us | Self-hosted in your infra" value="Cloud, managed by us" />
<TextArea label="Anything else?" name="notes" placeholder="Your current tools, deadlines..." rows="3" />
<Switch label="Send me the product newsletter" name="newsletter" />
<Button>Request demo</Button>
<Button variant="tertiary">Cancel</Button>
</Form>
</Card>
```
## Input

A one-line text field.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `type` | one of |  | `text` (default), `email`, `number`, `password`, `url`, `tel`, `search`, `date`, `time`, `datetime-local` |
| `placeholder` | text |  |  |
| `value` | text |  |  |
| `step` | number |  |  |
| `min` | number |  |  |
| `max` | number |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Card title="Book a demo" subtitle="Tell us about your team">
<Form name="demo-request">
<Input label="Full name" name="name" placeholder="Jane Smith" required="true" />
<Input label="Work email" name="email" type="email" placeholder="jane@company.com" hint="We only use this to reply" required="true" />
<Select label="Team size" name="size" placeholder="Choose a range" options="1-10 people | 11-50 people | 51+ people" />
<Date label="Preferred date" name="date" />
<Slider label="Seats" name="seats" min="1" max="50" value="8" />
<Checkboxes label="Interested in" name="interests" options="Analytics | Billing | Support inbox" value="Analytics" />
<Radio label="Plan" name="plan" options="Cloud, managed by us | Self-hosted in your infra" value="Cloud, managed by us" />
<TextArea label="Anything else?" name="notes" placeholder="Your current tools, deadlines..." rows="3" />
<Switch label="Send me the product newsletter" name="newsletter" />
<Button>Request demo</Button>
<Button variant="tertiary">Cancel</Button>
</Form>
</Card>
```
## TextArea

A multi-line text field.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `placeholder` | text |  |  |
| `value` | text |  |  |
| `rows` | number |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Card title="Book a demo" subtitle="Tell us about your team">
<Form name="demo-request">
<Input label="Full name" name="name" placeholder="Jane Smith" required="true" />
<Input label="Work email" name="email" type="email" placeholder="jane@company.com" hint="We only use this to reply" required="true" />
<Select label="Team size" name="size" placeholder="Choose a range" options="1-10 people | 11-50 people | 51+ people" />
<Date label="Preferred date" name="date" />
<Slider label="Seats" name="seats" min="1" max="50" value="8" />
<Checkboxes label="Interested in" name="interests" options="Analytics | Billing | Support inbox" value="Analytics" />
<Radio label="Plan" name="plan" options="Cloud, managed by us | Self-hosted in your infra" value="Cloud, managed by us" />
<TextArea label="Anything else?" name="notes" placeholder="Your current tools, deadlines..." rows="3" />
<Switch label="Send me the product newsletter" name="newsletter" />
<Button>Request demo</Button>
<Button variant="tertiary">Cancel</Button>
</Form>
</Card>
```
## Select

A dropdown.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `options` | values split by ` | ` | yes |  |
| `name` | text |  |  |
| `placeholder` | text |  |  |
| `value` | text |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Card title="Book a demo" subtitle="Tell us about your team">
<Form name="demo-request">
<Input label="Full name" name="name" placeholder="Jane Smith" required="true" />
<Input label="Work email" name="email" type="email" placeholder="jane@company.com" hint="We only use this to reply" required="true" />
<Select label="Team size" name="size" placeholder="Choose a range" options="1-10 people | 11-50 people | 51+ people" />
<Date label="Preferred date" name="date" />
<Slider label="Seats" name="seats" min="1" max="50" value="8" />
<Checkboxes label="Interested in" name="interests" options="Analytics | Billing | Support inbox" value="Analytics" />
<Radio label="Plan" name="plan" options="Cloud, managed by us | Self-hosted in your infra" value="Cloud, managed by us" />
<TextArea label="Anything else?" name="notes" placeholder="Your current tools, deadlines..." rows="3" />
<Switch label="Send me the product newsletter" name="newsletter" />
<Button>Request demo</Button>
<Button variant="tertiary">Cancel</Button>
</Form>
</Card>
```
## Date

A date picker.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `value` | text |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Card title="Book a demo" subtitle="Tell us about your team">
<Form name="demo-request">
<Input label="Full name" name="name" placeholder="Jane Smith" required="true" />
<Input label="Work email" name="email" type="email" placeholder="jane@company.com" hint="We only use this to reply" required="true" />
<Select label="Team size" name="size" placeholder="Choose a range" options="1-10 people | 11-50 people | 51+ people" />
<Date label="Preferred date" name="date" />
<Slider label="Seats" name="seats" min="1" max="50" value="8" />
<Checkboxes label="Interested in" name="interests" options="Analytics | Billing | Support inbox" value="Analytics" />
<Radio label="Plan" name="plan" options="Cloud, managed by us | Self-hosted in your infra" value="Cloud, managed by us" />
<TextArea label="Anything else?" name="notes" placeholder="Your current tools, deadlines..." rows="3" />
<Switch label="Send me the product newsletter" name="newsletter" />
<Button>Request demo</Button>
<Button variant="tertiary">Cancel</Button>
</Form>
</Card>
```
## Slider

Pick a number in a range, shown with its unit ($, %, km).

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `min` | number | yes |  |
| `max` | number | yes |  |
| `step` | number |  |  |
| `value` | number |  |  |
| `name` | text |  |  |
| `unit` | text |  |  |

```markdown
<Card title="Book a demo" subtitle="Tell us about your team">
<Form name="demo-request">
<Input label="Full name" name="name" placeholder="Jane Smith" required="true" />
<Input label="Work email" name="email" type="email" placeholder="jane@company.com" hint="We only use this to reply" required="true" />
<Select label="Team size" name="size" placeholder="Choose a range" options="1-10 people | 11-50 people | 51+ people" />
<Date label="Preferred date" name="date" />
<Slider label="Seats" name="seats" min="1" max="50" value="8" />
<Checkboxes label="Interested in" name="interests" options="Analytics | Billing | Support inbox" value="Analytics" />
<Radio label="Plan" name="plan" options="Cloud, managed by us | Self-hosted in your infra" value="Cloud, managed by us" />
<TextArea label="Anything else?" name="notes" placeholder="Your current tools, deadlines..." rows="3" />
<Switch label="Send me the product newsletter" name="newsletter" />
<Button>Request demo</Button>
<Button variant="tertiary">Cancel</Button>
</Form>
</Card>
```
## Checkboxes

Pick any number of options.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `options` | values split by ` | ` | yes |  |
| `name` | text |  |  |
| `value` | values split by ` | ` |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Card title="Book a demo" subtitle="Tell us about your team">
<Form name="demo-request">
<Input label="Full name" name="name" placeholder="Jane Smith" required="true" />
<Input label="Work email" name="email" type="email" placeholder="jane@company.com" hint="We only use this to reply" required="true" />
<Select label="Team size" name="size" placeholder="Choose a range" options="1-10 people | 11-50 people | 51+ people" />
<Date label="Preferred date" name="date" />
<Slider label="Seats" name="seats" min="1" max="50" value="8" />
<Checkboxes label="Interested in" name="interests" options="Analytics | Billing | Support inbox" value="Analytics" />
<Radio label="Plan" name="plan" options="Cloud, managed by us | Self-hosted in your infra" value="Cloud, managed by us" />
<TextArea label="Anything else?" name="notes" placeholder="Your current tools, deadlines..." rows="3" />
<Switch label="Send me the product newsletter" name="newsletter" />
<Button>Request demo</Button>
<Button variant="tertiary">Cancel</Button>
</Form>
</Card>
```
## Radio

Pick one option.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `options` | values split by ` | ` | yes |  |
| `name` | text |  |  |
| `value` | text |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Card title="Book a demo" subtitle="Tell us about your team">
<Form name="demo-request">
<Input label="Full name" name="name" placeholder="Jane Smith" required="true" />
<Input label="Work email" name="email" type="email" placeholder="jane@company.com" hint="We only use this to reply" required="true" />
<Select label="Team size" name="size" placeholder="Choose a range" options="1-10 people | 11-50 people | 51+ people" />
<Date label="Preferred date" name="date" />
<Slider label="Seats" name="seats" min="1" max="50" value="8" />
<Checkboxes label="Interested in" name="interests" options="Analytics | Billing | Support inbox" value="Analytics" />
<Radio label="Plan" name="plan" options="Cloud, managed by us | Self-hosted in your infra" value="Cloud, managed by us" />
<TextArea label="Anything else?" name="notes" placeholder="Your current tools, deadlines..." rows="3" />
<Switch label="Send me the product newsletter" name="newsletter" />
<Button>Request demo</Button>
<Button variant="tertiary">Cancel</Button>
</Form>
</Card>
```
## Switch

An on/off toggle.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `value` | true or false |  |  |
| `hint` | text |  |  |

```markdown
<Card title="Book a demo" subtitle="Tell us about your team">
<Form name="demo-request">
<Input label="Full name" name="name" placeholder="Jane Smith" required="true" />
<Input label="Work email" name="email" type="email" placeholder="jane@company.com" hint="We only use this to reply" required="true" />
<Select label="Team size" name="size" placeholder="Choose a range" options="1-10 people | 11-50 people | 51+ people" />
<Date label="Preferred date" name="date" />
<Slider label="Seats" name="seats" min="1" max="50" value="8" />
<Checkboxes label="Interested in" name="interests" options="Analytics | Billing | Support inbox" value="Analytics" />
<Radio label="Plan" name="plan" options="Cloud, managed by us | Self-hosted in your infra" value="Cloud, managed by us" />
<TextArea label="Anything else?" name="notes" placeholder="Your current tools, deadlines..." rows="3" />
<Switch label="Send me the product newsletter" name="newsletter" />
<Button>Request demo</Button>
<Button variant="tertiary">Cancel</Button>
</Form>
</Card>
```
## Button

In a Form it submits; elsewhere href opens a link and ask sends a message (the label by default); the label goes between the tags or in label.

Between its tags: inline text: its label.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `variant` | one of |  | `primary` (default), `secondary`, `tertiary`, `danger` |
| `href` | address |  |  |
| `ask` | text |  |  |
| `disabled` | true or false |  |  |
| `size` | one of |  | `medium` (default), `small`, `large` |
| `label` | text |  |  |
| `icon` | icon name |  |  |

```markdown
<Button icon="download-simple">Export CSV</Button>
<Button variant="secondary" icon="share-network">Share report</Button>
<Button variant="tertiary" ask="Compare this with last quarter">Compare with Q2</Button>
<Button variant="danger">Delete project</Button>
<Button size="small" variant="secondary">Small</Button>
<Button size="large">Large</Button>
<Button disabled="true">Not yet</Button>
```


---

# Data components

> The data pack's 7 components: ways to show data beyond charts and tables: facts, timelines, gauges, heatmaps, funnels, sparklines and hierarchies.

Add it with `packs: ["data"]`, or leave `packs` out for every pack.

## KeyValue

Labelled facts, from the Markdown table inside: the label, then the value.

Between its tags: a Markdown table (first column labels, the others series).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<KeyValue title="Server">
| Field | Value |
|---|---|
| Name | api-eu-1 |
| Region | eu-west-1 |
| Uptime | 41 days |
| Version | 2.14.3 |
</KeyValue>
```
## Timeline

Events in order, one per list item, written as "when: what happened".

Between its tags: a Markdown list.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<Timeline title="Company milestones">
- 2019: Founded in a Lisbon flat
- 2021: First 1,000 customers
- 2023: Opened the Berlin office
- 2024: Series B, 120 people
</Timeline>
```
## Gauge

One number on a scale from min to max.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `value` | number | yes |  |
| `min` | number |  |  |
| `max` | number |  |  |
| `unit` | text |  |  |
| `tone` | one of |  | `neutral` (default), `info`, `success`, `warning`, `danger` |

```markdown
<Columns>
<Gauge label="CPU" value="72" unit="%" tone="warning" />
<Gauge label="Air quality (AQI)" value="42" max="300" tone="success" />
<Gauge label="Disk" value="94" unit="%" tone="danger" />
</Columns>
```
## Heatmap

A grid of numbers shaded by size, from the Markdown table inside: the row label, then one column per bucket.

Between its tags: a Markdown table (first column labels, the others series).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<Heatmap title="Commits by time of day">
| Day | Morning | Afternoon | Evening |
|---|---|---|---|
| Mon | 4 | 12 | 3 |
| Tue | 8 | 15 | 1 |
| Wed | 2 | 9 | 7 |
| Thu | 6 | 18 | 5 |
| Fri | 3 | 7 | 0 |
</Heatmap>
```
## Funnel

How many reach each stage, from the Markdown table inside: the stage, then the count.

Between its tags: a Markdown table (first column labels, the others series).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<Funnel title="Signup funnel">
| Step | Users |
|---|---|
| Landing | 12,000 |
| Signup | 3,100 |
| Verified | 2,400 |
| Paid | 410 |
</Funnel>
```
## Sparkline

A number with a small trend line from its recent values.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `values` | values split by ` | ` | yes |  |
| `value` | text |  |  |
| `change` | text |  |  |

```markdown
<Columns>
<Sparkline label="AAPL" value="$187.20" change="+1.4%" values="180 | 182 | 181 | 184 | 183 | 186 | 187" />
<Sparkline label="TSLA" value="$242.10" change="-2.1%" values="255 | 251 | 249 | 250 | 246 | 244 | 242" />
<Sparkline label="NVDA" value="$131.60" change="+0.3%" values="129 | 131 | 130 | 132 | 130 | 131 | 132" />
</Columns>
```
## Tree

A hierarchy, one list item per entry, written as its path with " > " between levels.

Between its tags: a Markdown list.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<Tree title="Organisation">
- Engineering > Platform
- Engineering > Mobile
- Engineering > Mobile > iOS
- Sales > EMEA
- Sales > Americas > US
- Sales > Americas > Brazil
</Tree>
```


---

# Commerce components

> The commerce pack's 6 components: shopping: products, pricing plans, carts, ratings, comparisons and prices.

Add it with `packs: ["commerce"]`, or leave `packs` out for every pack.

## Product

One product with its price; a short description between the tags, then a Button with ask for each thing the reader can do with it (Add to cart, Tell me more); rating is out of 5, count how many rated it. When the reader is choosing what to buy, show each option as one, side by side in Columns.

Between its tags: inline text: its label. It also takes `Button`s, drawn under it as what the reader can do.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `name` | text | yes |  |
| `price` | text |  |  |
| `was` | text |  |  |
| `image` | address |  |  |
| `rating` | number |  |  |
| `count` | number |  |  |
| `badge` | text |  |  |
| `href` | address |  |  |

```markdown
<Columns>
<Product name="Studio Headphones" price="$249" was="$299" rating="4.5" badge="Sale">Closed-back, 30 hours of battery, folds flat.</Product>
<Product name="Travel Earbuds" price="$129" rating="4.1">Small case, noise cancelling, 8 hours a charge.</Product>
</Columns>
```
## Plan

A pricing plan, its features as a Markdown list inside.

Between its tags: a Markdown list.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `name` | text | yes |  |
| `price` | text | yes |  |
| `period` | text |  |  |
| `note` | text |  |  |
| `featured` | true or false |  |  |

```markdown
<Columns>
<Plan name="Starter" price="$0" period="/month">
- 3 projects
- Community support
</Plan>
<Plan name="Team" price="$29" period="/month" featured="true" note="Most popular">
- Unlimited projects
- SSO
- Priority support
</Plan>
<Plan name="Enterprise" price="Custom">
- Audit logs
- 99.99% SLA
- A named contact
</Plan>
</Columns>
```
## Cart

Items and totals, from the Markdown table inside: the item, the quantity, the price.

Between its tags: a Markdown table (first column labels, the others series).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |
| `total` | text |  |  |
| `note` | text |  |  |

```markdown
<Cart title="Your cart" total="$412.00" note="Free shipping over $50">
| Item | Qty | Price |
|---|---|---|
| Studio Headphones | 1 | $249.00 |
| USB-C cable | 2 | $24.00 |
| Hard case | 1 | $139.00 |
</Cart>
```
## Rating

A real star rating out of max, never a made-up one.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `value` | number | yes |  |
| `max` | number |  |  |
| `count` | text |  |  |

```markdown
The Studio Headphones are rated <Rating value="4.6" count="1,203 reviews" /> by buyers, the earbuds <Rating value="3.9" count="88 reviews" />.
```
## Compare

Options side by side, from the Markdown table inside: the feature, then one column per option; yes and no become marks.

Between its tags: a Markdown table (first column labels, the others series).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<Compare title="Phones">
| Feature | Pixel 10 | iPhone 17 | Galaxy S26 |
|---|---|---|---|
| Screen | 6.3" | 6.1" | 6.2" |
| Battery | 4,700 mAh | 3,600 mAh | 4,000 mAh |
| 5G | yes | yes | yes |
| Headphone jack | no | no | no |
| Price | $799 | $829 | $799 |
</Compare>
```
## Price

A price, with the old one struck through.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `value` | text | yes |  |
| `was` | text |  |  |
| `period` | text |  |  |
| `note` | text |  |  |

```markdown
<Price value="$49" was="$79" period="/month" note="First year, then $79" />
```


---

# Device components

> The device pack's 10 components: the device's own hardware and apps: maps, camera, scanning, location, files, contacts, the calendar, sharing, voice notes and QR codes. Native on every platform, with a web fallback that needs no JavaScript.

Add it with `packs: ["device"]`, or leave `packs` out for every pack.

## Map

Places on a map; add one whenever the answer suggests places to go (a trip, places to eat, walks), even when not asked for a map. A Markdown table inside: the place first, then its Lat and Lng (an Address only for a place you can't locate), then anything else; route draws a path through them in order.

Between its tags: a Markdown table (first column labels, the others series).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |
| `route` | true or false |  |  |

```markdown
<Map title="Where to eat">
| Place | Lat | Lng | Note |
|---|---|---|---|
| Time Out Market | 38.7069 | -9.1459 | Food hall |
| Pastéis de Belém | 38.6975 | -9.2032 | Since 1837 |
| Taberna Sal Grosso | 38.7111 | -9.1290 | Book ahead |
</Map>
```
## Camera

A form field that takes a photo with the camera.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `facing` | one of |  | `back` (default), `front` |
| `multiple` | true or false |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="claim">
<Camera label="Photo of the damage" name="photo" hint="Include the whole parcel" required="true" />
<Button>Send claim</Button>
</Form>
```
## Scan

A form field filled by scanning a barcode or QR code.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `kind` | one of |  | `any` (default), `qr`, `barcode` |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="checkin">
<Scan label="Scan your boarding pass" name="pass" kind="barcode" />
<Button>Check in</Button>
</Form>
```
## Location

A form field holding the user's location once they choose to share it.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `precision` | one of |  | `approximate` (default), `precise` |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="pickup">
<Location label="Where should we pick you up?" name="where" precision="precise" required="true" />
<Button>Request a ride</Button>
</Form>
```
## File

A form field for attaching files.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `accept` | values split by ` | ` |  |  |
| `multiple` | true or false |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="apply">
<File label="CV and cover letter" name="docs" accept=".pdf | .docx" multiple="true" />
<Button>Apply</Button>
</Form>
```
## Contact

A form field: a person picked from the user's contacts.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="invite">
<Contact label="Invite a friend" name="friend" />
<Button>Send invite</Button>
</Form>
```
## AddToCalendar

A button that adds an event to the user's calendar; the button's label between the tags.

Between its tags: inline text: its label.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text | yes |  |
| `start` | text | yes |  |
| `end` | text |  |  |
| `where` | text |  |  |
| `note` | text |  |  |

```markdown
<AddToCalendar title="Dinner at Taberna Sal Grosso" start="2026-10-24T19:30" end="2026-10-24T22:00" where="Calçada do Forte 22, Lisbon">Add to calendar</AddToCalendar>
```
## Share

A button that opens the share sheet with this text or link; the button's label between the tags.

Between its tags: inline text: its label.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `text` | text |  |  |
| `href` | address |  |  |

```markdown
<Share text="Three days in Lisbon, the plan" href="https://example.com/trip">Share the plan</Share>
```
## VoiceNote

A form field: the user records a short voice note.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `max` | number |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="update">
<VoiceNote label="Record a voice update" name="note" max="60" />
<Button>Send</Button>
</Form>
```
## QR

A QR code for a link or short text, for another phone to scan.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `value` | text | yes |  |
| `label` | text |  |  |

```markdown
<QR value="WIFI:T:WPA;S:Guest House;P:correct horse battery;;" label="Join the guest Wi-Fi" />
```


---

# Docs components

> The docs pack's 5 components: technical writing: code with a file name, diffs, formulas, file trees and cited sources.

Add it with `packs: ["docs"]`, or leave `packs` out for every pack.

## Code

A fenced code block inside, shown with its file name and highlighted lines.

Between its tags: code, as written.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `file` | text |  |  |
| `highlight` | values split by ` | ` |  |  |

```markdown
<Code file="config.toml" highlight="2">
```toml
[server]
port = 8080
host = "0.0.0.0"
workers = 4
```
</Code>
```
## Diff

A change, from the fenced diff block inside (lines starting with + and -).

Between its tags: code, as written.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `file` | text |  |  |

```markdown
<Diff file="src/rate.ts">
```diff
@@ -1,4 +1,4 @@
-const limit = 10;
+const limit = 100;
 const window = 60;
 export { limit, window };
```
</Diff>
```
## Math

A formula written in TeX.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `tex` | text | yes |  |
| `label` | text |  |  |

```markdown
<Math tex="E_k = \frac{1}{2} m v^2" label="Kinetic energy" />
<Math tex="\sigma = \sqrt{\frac{1}{N} \sum_{i=1}^{N} (x_i - \mu)^2}" label="Standard deviation" />
```
## FileTree

Files and folders, one list item per path, folders ending in /.

Between its tags: a Markdown list.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<FileTree title="Project">
- src/
- src/main.rs
- src/lib.rs
- src/parse/
- src/parse/mod.rs
- Cargo.toml
- README.md
</FileTree>
```
## Citation

A source the answer relies on; what it says between the tags.

Between its tags: inline text: its label.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text | yes |  |
| `href` | address |  |  |
| `source` | text |  |  |
| `date` | text |  |  |

```markdown
<Citation title="Caffeine effects on sleep taken 0, 3, or 6 hours before going to bed" href="https://example.com/study" source="Journal of Clinical Sleep Medicine" date="2013">Caffeine six hours before bed cut total sleep by more than an hour.</Citation>
```


---

# Inputs components

> The inputs pack's 6 components: more form fields: star ratings, searchable choices, times, toggle groups, steppers and signatures.

Add it with `packs: ["inputs"]`, or leave `packs` out for every pack.

## RatingInput

A form field: a star rating out of max.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `max` | number |  |  |
| `value` | number |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="review">
<RatingInput label="How was your stay?" name="stars" value="4" />
<Button>Send review</Button>
</Form>
```
## Combobox

A form field: type to filter the options, or type something new.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `options` | values split by ` | ` | yes |  |
| `name` | text |  |  |
| `placeholder` | text |  |  |
| `value` | text |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="flight">
<Combobox label="From" name="from" options="LIS Lisbon | OPO Porto | MAD Madrid | BCN Barcelona | CDG Paris" placeholder="Type a city or code" />
<Button>Search</Button>
</Form>
```
## Time

A form field: a time of day as HH:MM.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `value` | text |  |  |
| `min` | text |  |  |
| `max` | text |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="alarm">
<Time label="Wake me at" name="alarm" value="06:45" />
<Button>Set</Button>
</Form>
```
## ToggleGroup

A form field: options as a row of toggles, one or several chosen.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `options` | values split by ` | ` | yes |  |
| `name` | text |  |  |
| `value` | values split by ` | ` |  |  |
| `multiple` | true or false |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="classes">
<ToggleGroup label="Which days?" name="days" options="Mon | Tue | Wed | Thu | Fri | Sat" value="Mon | Wed" multiple="true" />
<ToggleGroup label="Level" name="level" options="Beginner | Intermediate | Advanced" value="Intermediate" />
<Button>Save</Button>
</Form>
```
## Stepper

A form field: a whole number with minus and plus.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `value` | number |  |  |
| `min` | number |  |  |
| `max` | number |  |  |
| `step` | number |  |  |
| `unit` | text |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="trip">
<Stepper label="Travellers" name="travellers" value="2" min="1" max="9" unit="people" />
<Stepper label="Nights" name="nights" value="3" min="1" max="30" />
<Button>Find rooms</Button>
</Form>
```
## Signature

A form field: the user signs with a finger or the mouse.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `name` | text |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="lease">
<Signature label="Sign to accept the lease" name="signature" required="true" />
<Button>Sign</Button>
</Form>
```


---

# Interactive components

> The interactive pack's 7 components: things the reader does on the page, kept on their device and reported back: a quiz, flashcards, a poll, a checklist, and what-if sliders.

Add it with `packs: ["interactive"]`, or leave `packs` out for every pack.

## Quiz

Questions with one right answer each: the reader picks, sees right or wrong and why, then a score. End with one when the reader is learning something.

Between its tags: only `Question` components.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<Quiz title="Quick check">
<Question text="What absorbs light in a leaf?" answer="B" explain="Chlorophyll in the chloroplasts absorbs red and blue light.">
- A. Stomata
- B. Chlorophyll
- C. Xylem
</Question>
<Question text="Which gas do plants take in?" answer="Carbon dioxide" explain="CO₂ enters through the stomata.">
- Oxygen
- Carbon dioxide
- Nitrogen
</Question>
</Quiz>
```
## Question

One question inside Quiz; its choices are the Markdown list inside; answer, always given, names the right one (its letter or words).

Between its tags: a Markdown list. It goes inside `Quiz`.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `text` | text | yes |  |
| `answer` | text | yes |  |
| `explain` | text |  |  |

```markdown
<Quiz title="Quick check">
<Question text="What absorbs light in a leaf?" answer="B" explain="Chlorophyll in the chloroplasts absorbs red and blue light.">
- A. Stomata
- B. Chlorophyll
- C. Xylem
</Question>
<Question text="Which gas do plants take in?" answer="Carbon dioxide" explain="CO₂ enters through the stomata.">
- Oxygen
- Carbon dioxide
- Nitrogen
</Question>
</Quiz>
```
## Flashcards

Cards the reader flips, from the Markdown table inside: the front, then the back. For words, terms or facts to remember.

Between its tags: a Markdown table (first column labels, the others series).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<Flashcards title="Key terms">
| Term | Meaning |
|---|---|
| Chlorophyll | The green pigment that absorbs light |
| Stomata | Pores that let gases in and out |
| Glucose | The sugar a plant makes |
| Xylem | Tubes that carry water up from the roots |
</Flashcards>
```
## Poll

A vote with one choice.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `options` | values split by ` | ` | yes |  |
| `name` | text |  |  |

```markdown
<Poll label="Which topic next?" options="Respiration | Transpiration | Cell division" name="next" />
```
## Checklist

Tasks to tick off, one per Markdown list item ([x] marks one done), with progress. For things the reader has to do, pack or buy.

Between its tags: a Markdown list.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |
| `name` | text |  |  |

```markdown
<Checklist title="Revision plan" name="revision">
- [x] Read chapter 4
- [ ] Draw the leaf diagram
- [ ] Do the 2024 past paper
- [ ] Make flashcards for the key terms
</Checklist>
```
## WhatIf

Sliders and the Results they change, worked out as the reader moves them. For an answer that turns on numbers the reader could change.

Between its tags: Markdown and other components.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<WhatIf title="Order total">
<Slider label="Price" min="5" max="100" value="20" />
<Slider label="Quantity" name="qty" min="1" max="10" value="3" />
<Slider label="Discount (%)" min="0" max="50" value="10" />
<Result label="Total" value="price * qty * (1 - discount / 100)" unit="$" decimals="2" />
<Result label="Saved" value="price * qty * discount / 100" unit="$" decimals="2" />
</WhatIf>
```
## Result

A number inside WhatIf; value is a formula of the Sliders' names (+ - * / ^, min, max, round).

Between its tags: nothing: it closes itself (`<Name ... />`). It goes inside `WhatIf`.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `value` | text | yes |  |
| `unit` | text |  |  |
| `decimals` | number |  |  |

```markdown
<WhatIf title="Order total">
<Slider label="Price" min="5" max="100" value="20" />
<Slider label="Quantity" name="qty" min="1" max="10" value="3" />
<Slider label="Discount (%)" min="0" max="50" value="10" />
<Result label="Total" value="price * qty * (1 - discount / 100)" unit="$" decimals="2" />
<Result label="Saved" value="price * qty * discount / 100" unit="$" decimals="2" />
</WhatIf>
```


---

# Media components

> The media pack's 4 components: video, audio, embeds from known hosts, and a carousel of images.

Add it with `packs: ["media"]`, or leave `packs` out for every pack.

## Video

A video file to play.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `src` | address | yes |  |
| `poster` | address |  |  |
| `title` | text |  |  |
| `caption` | text |  |  |

```markdown

```
## Audio

An audio file to play.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `src` | address | yes |  |
| `title` | text |  |  |

```markdown
<Audio src="https://example.com/ep42.mp3" title="Episode 42: Why cities need trams" />
```
## Embed

A YouTube, Vimeo, Spotify or SoundCloud page shown in place; other pages become a link.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `src` | address | yes |  |
| `title` | text |  |  |

```markdown
<Embed src="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="How to fold dumplings" />
```
## Carousel

Images one at a time, from the Markdown images inside. For a set of things to look through: dishes, rooms, products, sights.

Between its tags: Markdown images, one a line.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<Carousel title="The apartment">
![Living room with a grey sofa](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKAAAAB4CAIAAAD6wG44AAACmklEQVR42u3dQU7bQBQGYDOteopKZdMjVF3CrhKX7C2oqm5gWfUIbOAmXVTqgiCI43nPMy/fv4QQz/jLe7bjSbj4/uPXInXT7ALAAlgAC2ABLIAFMGABLIAFsAAWwAIYsACW+fLeLgjNt69fDn/48/cfwAVdD3+bIK1FZ+ue9kgVPBntsz+JK2UVvKduQikD3l831Biw62DJKr6IIgY8lkp3Y8BatADWn4d9TsAqWAALYAEsgAVwaiJu8/V9TsAqWADr0sP2fMADqUQc0QFr0ZJSfEHr7gAPYRy3qtKy2f7Gq+73Ra99V8F7lnLCJxtUcKyxzyapZmfRy7Isy+3dvZdLTeDbu/t/uowLAj9D/Y8t0wO/Ysl4euA3CRnPCnx8E2Y8H/BaM4fkaYC3UDEeHXi70PjGe43wYt9/jNV92jfXVyPr5g9vN+C4V/RQxofTTB5eq9evxmnXL44k+cQwu4LT5rZvHR8zzZwRtqonGjteQQ11Hd9q7+78ja7aYsLwMlr07gfFnGa4ZZpxI4wFHuryNJR5+0yDhtfO5xZ90Hh6HX2ChteKneAk78S+Txix0zq36CneFu7VDKd4r6Yn8Fxv+m/ZiQkz7WXcavfkCKScmfbaSjvn9Y6D337usq1NLbrMjdhj+uGOk93Srhvd8ZeAbdn6KRVcdQXFi4UyzmRPq+NG95WpDTXZ0wazooLPZ+nTzfXVyJNdVcpHAVvVNq9xo1v7Aq9ZdVzbuCncqY3fZGoKt3YpN4Vb27gp3NrGTeHWPiS/+/Dx08Pjk71TJg+PT58vL31P1rm0a8DFjX1PVnFjFbz4ALgAFsACWAALYAEMWAALYAEsgAWwAAYsgAWwABbAAlgAC2DAAlgAC2ABLIAFMGABLNPkL96PXxmAn95xAAAAAElFTkSuQmCC)
![Open kitchen and dining area](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKAAAAB4CAIAAAD6wG44AAACmklEQVR42u3dQU7bQBQGYDOteopKZdMjVF3CrhKX7C2oqm5gWfUIbOAmXVTqgiCI43nPMy/fv4QQz/jLe7bjSbj4/uPXInXT7ALAAlgAC2ABLIAFMGABLIAFsAAWwAIYsACW+fLeLgjNt69fDn/48/cfwAVdD3+bIK1FZ+ue9kgVPBntsz+JK2UVvKduQikD3l831Biw62DJKr6IIgY8lkp3Y8BatADWn4d9TsAqWAALYAEsgAVwaiJu8/V9TsAqWADr0sP2fMADqUQc0QFr0ZJSfEHr7gAPYRy3qtKy2f7Gq+73Ra99V8F7lnLCJxtUcKyxzyapZmfRy7Isy+3dvZdLTeDbu/t/uowLAj9D/Y8t0wO/Ysl4euA3CRnPCnx8E2Y8H/BaM4fkaYC3UDEeHXi70PjGe43wYt9/jNV92jfXVyPr5g9vN+C4V/RQxofTTB5eq9evxmnXL44k+cQwu4LT5rZvHR8zzZwRtqonGjteQQ11Hd9q7+78ja7aYsLwMlr07gfFnGa4ZZpxI4wFHuryNJR5+0yDhtfO5xZ90Hh6HX2ChteKneAk78S+Txix0zq36CneFu7VDKd4r6Yn8Fxv+m/ZiQkz7WXcavfkCKScmfbaSjvn9Y6D337usq1NLbrMjdhj+uGOk93Srhvd8ZeAbdn6KRVcdQXFi4UyzmRPq+NG95WpDTXZ0wazooLPZ+nTzfXVyJNdVcpHAVvVNq9xo1v7Aq9ZdVzbuCncqY3fZGoKt3YpN4Vb27gp3NrGTeHWPiS/+/Dx08Pjk71TJg+PT58vL31P1rm0a8DFjX1PVnFjFbz4ALgAFsACWAALYAEMWAALYAEsgAWwAAYsgAWwABbAAlgAC2DAAlgAC2ABLIAFMGABLNPkL96PXxmAn95xAAAAAElFTkSuQmCC)
![The view from the street](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKAAAAB4CAIAAAD6wG44AAACmklEQVR42u3dQU7bQBQGYDOteopKZdMjVF3CrhKX7C2oqm5gWfUIbOAmXVTqgiCI43nPMy/fv4QQz/jLe7bjSbj4/uPXInXT7ALAAlgAC2ABLIAFMGABLIAFsAAWwAIYsACW+fLeLgjNt69fDn/48/cfwAVdD3+bIK1FZ+ue9kgVPBntsz+JK2UVvKduQikD3l831Biw62DJKr6IIgY8lkp3Y8BatADWn4d9TsAqWAALYAEsgAVwaiJu8/V9TsAqWADr0sP2fMADqUQc0QFr0ZJSfEHr7gAPYRy3qtKy2f7Gq+73Ra99V8F7lnLCJxtUcKyxzyapZmfRy7Isy+3dvZdLTeDbu/t/uowLAj9D/Y8t0wO/Ysl4euA3CRnPCnx8E2Y8H/BaM4fkaYC3UDEeHXi70PjGe43wYt9/jNV92jfXVyPr5g9vN+C4V/RQxofTTB5eq9evxmnXL44k+cQwu4LT5rZvHR8zzZwRtqonGjteQQ11Hd9q7+78ja7aYsLwMlr07gfFnGa4ZZpxI4wFHuryNJR5+0yDhtfO5xZ90Hh6HX2ChteKneAk78S+Txix0zq36CneFu7VDKd4r6Yn8Fxv+m/ZiQkz7WXcavfkCKScmfbaSjvn9Y6D337usq1NLbrMjdhj+uGOk93Srhvd8ZeAbdn6KRVcdQXFi4UyzmRPq+NG95WpDTXZ0wazooLPZ+nTzfXVyJNdVcpHAVvVNq9xo1v7Aq9ZdVzbuCncqY3fZGoKt3YpN4Vb27gp3NrGTeHWPiS/+/Dx08Pjk71TJg+PT58vL31P1rm0a8DFjX1PVnFjFbz4ALgAFsACWAALYAEMWAALYAEsgAWwAAYsgAWwABbAAlgAC2DAAlgAC2ABLIAFMGABLNPkL96PXxmAn95xAAAAAElFTkSuQmCC)
</Carousel>
```


---

# Scheduling components

> The scheduling pack's 5 components: time: a month calendar, events, time slots to pick, a day's agenda and countdowns.

Add it with `packs: ["scheduling"]`, or leave `packs` out for every pack.

## Calendar

A month with marked days, from the Markdown table inside: the date as YYYY-MM-DD, then what's on.

Between its tags: a Markdown table (first column labels, the others series).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `month` | text |  |  |
| `title` | text |  |  |

```markdown
<Calendar month="2026-10" title="October">
| Date | What |
|---|---|
| 2026-10-06 | Sprint planning |
| 2026-10-15 | Design review |
| 2026-10-20 | Launch |
| 2026-10-31 | Quarter closes |
</Calendar>
```
## Event

One event; details between the tags.

Between its tags: inline text: its label.

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text | yes |  |
| `start` | text | yes |  |
| `end` | text |  |  |
| `where` | text |  |  |
| `tone` | one of |  | `neutral` (default), `info`, `success`, `warning`, `danger` |

```markdown
<Event title="Launch party" start="2026-10-20T18:00" end="2026-10-20T21:00" where="Rooftop, 5th floor" tone="info">Bring a guest. Drinks and food from 18:30.</Event>
```
## TimeSlots

A form field: pick one of the times.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `options` | values split by ` | ` | yes |  |
| `name` | text |  |  |
| `value` | text |  |  |
| `hint` | text |  |  |
| `required` | true or false |  |  |

```markdown
<Form name="book">
<TimeSlots label="Pick a time on Thursday" name="slot" options="09:00 | 09:30 | 10:00 | 11:30 | 14:30 | 16:00" required="true" />
<Button>Book</Button>
</Form>
```
## Agenda

A day in time order, from the Markdown table inside: the time, then what.

Between its tags: a Markdown table (first column labels, the others series).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `title` | text |  |  |

```markdown
<Agenda title="Conference, day one">
| Time | Talk |
|---|---|
| 9:00-9:45am | Keynote: the next ten years of the web |
| 10:30-11:15am | Rust on phones |
| 12:30–1:00pm | Lunch |
| 1:30-2:15pm | Designing for streaming UIs |
</Agenda>
```
## Countdown

Time left until a moment, given as YYYY-MM-DDTHH:MM.

Between its tags: nothing: it closes itself (`<Name ... />`).

| Attribute | Type | Required | Values |
|---|---|---|---|
| `label` | text | yes |  |
| `until` | text | yes |  |

```markdown
<Countdown label="Until the year ends" until="2027-01-01T00:00" />
```


---

# The HTTP API

> The base address, the two keys, the four endpoints you call, and where the API's machine-readable description lives.

```text
https://api.morphscreen.com/v1
```

## Keys

| Header | What it is |
|---|---|
| `X-MorphScreen-Key: ms_live_...` | Your MorphScreen key, on every call. The call counts against your plan. Keep it on your server. |
| `Authorization: Bearer sk-or-...` | Your own OpenRouter key, when you want a model other than the one in your plan. It goes to OpenRouter and nowhere else, never stored or logged. Leave it out to use the model in your plan. |

## Endpoints

| Endpoint | What it does |
|---|---|
| [`POST /v1/chat/completions`](/docs/reference/api/chat-completions) | OpenAI's chat completion, answered in our format, checked and repaired; streamed or whole |
| [`POST /v1/ui`](/docs/reference/api/ui) | An AG-UI run, what the web SDK's `connectAgent` reads |
| [`POST /v1/render`](/docs/reference/api/render) | An answer you already have, drawn as HTML (or ops, or the tree) with no model called |
| [`GET /v1/health`](/docs/reference/api/health) | Whether the API is up |

## Options

Each model call takes the same options: in a `morphscreen` field for chat completions, in `forwardedProps` for AG-UI, at the top level for render.

| Option | What it does |
|---|---|
| `packs` | the packs to add to core; every pack when left out, `[]` for core alone |
| `components` | your own packs ([Your own components](/docs/format/custom-components)) |
| `images` | your own pictures, which the model shows by id |
| `photos` | your own Pexels, Unsplash or Openverse key, for photos the model asks for |
| `image_hosts` | more hosts the HTML's pictures may load from |
| `repair` | repair an answer with errors (default `true`) |
| `output` | what comes back: `text` or `html` for chat completions, `agui` or `ops` for AG-UI, `html`, `ops` or `tree` for render |

## The description

The API's OpenAPI 3.1 description is at [`/v1/openapi.json`](https://api.morphscreen.com/v1/openapi.json). Our tests hold the server to it, and these reference pages are generated from it.

[Limits and errors](/docs/production/limits) has every error and what to do about it.


---

# POST /v1/chat/completions

> A chat completion in our format, OpenAI's and OpenRouter's request and response.

## Keys

Your MorphScreen key in `X-MorphScreen-Key`: the call counts against your plan. Your own OpenRouter key in `Authorization: Bearer sk-or-...` when you want a model other than the one in your plan: it runs on that key, and goes to OpenRouter and nowhere else. Leave it out to use the model in your plan.

## Example

Stream an answer on the model included in your plan:
```bash
curl https://api.morphscreen.com/v1/chat/completions \
  -H "X-MorphScreen-Key: $MORPHSCREEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4.1-flash", "stream": true,
       "messages": [{"role": "user", "content": "Plan a weekend in Lisbon"}],
       "morphscreen": {"packs": ["data"]}}'
```

Any other model on OpenRouter runs on your own key, sent as `Authorization: Bearer sk-or-...`. The stream is OpenAI's: `chat.completion.chunk` events whose `delta.content` is the answer in our format, then a last chunk with `finish_reason` and a `morphscreen` field holding the core's verdict (and the repaired text, when a repair was needed), then `data: [DONE]`.

## Request

### ChatCompletionRequest

OpenAI's chat completion request. Every field not listed here (temperature, max_tokens, models, provider, reasoning...) goes to the model as you set it. DeepSeek V4 Flash answers with reasoning off unless you set `reasoning`.

| Field | Type | Required | What it is |
|---|---|---|---|
| `model` | string | yes | An OpenRouter model name, like <span class="nb">deepseek/deepseek-v4.1-flash</span>. |
| `messages` | list of object | yes |  |
| `stream` | boolean |  |  Default `false`. |
| `stream_options` | object |  |  |
| `n` | `1` |  |  |
| `morphscreen` | object |  | output: text (the answer in our format, the default) or html (drawn by the core; not streamed). |

### Message

A chat message, as OpenAI and OpenRouter take it.

| Field | Type | Required | What it is |
|---|---|---|---|
| `role` | `system`, `developer`, `user`, `assistant`, `tool` | yes |  |
| `content` | string or array or null |  |  |

### stream_options


| Field | Type | Required | What it is |
|---|---|---|---|
| `include_usage` | boolean |  |  |

### Options

output: text (the answer in our format, the default) or html (drawn by the core; not streamed).

| Field | Type | Required | What it is |
|---|---|---|---|
| `packs` | list of string |  | The core's packs to add: data, commerce, scheduling, media, docs, inputs, device, interactive, or all. Left out, every pack ("all"); [] for the core alone, a prompt about half as long. At most 16. |
| `components` | list of object |  | Your own packs, in the shape of <span class="nb">spec/packs</span>/*.json; 256 KB at most. At most 16. |
| `image_hosts` | list of string |  | Hosts the HTML's pictures may load from, besides the app's images' hosts and its photo provider's. At most 16. |
| `images` | list of object |  | Your own pictures, which the model shows by id. At most 200. |
| `photos` | one of the shapes below |  | The app's own photo key, for one provider: with it the model may ask for photos, searched there on the app's quota, each loading from the provider's own address with its credit. Without one (or false) the model isn't asked for photos. |
| `output` | string |  | What comes back; each endpoint has its own choices. |
| `repair` | boolean |  | Repair an answer with errors, and give a blank one a fresh try. Default `true`. |

### AppImage

One of your own pictures. The model shows it as ![alt](img:ID) and the API puts its URL and credit in; its host is allowed with it.

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Letters, digits, '-', '_' or '.'. |
| `url` | string | yes | Where it loads from, http(s). |
| `alt` | string |  | What it shows, told to the model. |
| `credit` | string |  | Shown under it, as written (Markdown links allowed). |

## Responses

| Status | What comes back |
|---|---|
| 200 | The answer whole, or with stream true as <span class="nb">server-sent</span> events: chat.completion.chunk after chunk, the last with finish_reason and morphscreen (and the repaired text when a repair was needed), a usage chunk when asked, then `data: [DONE]`. |
| 400 | The request can't be run as written; model_needs_your_key: a model other than the included one, asked for without your own OpenRouter key. |
| 401 | No key, or one turned down: your MorphScreen key (morphscreen_key_required, morphscreen_key_invalid) or your OpenRouter key (openrouter_key_required, openrouter_key_invalid). |
| 402 | This month's calls on your plan are used (plan_quota_reached), a paid plan's month and as many again as extra (extra_limit_reached), the free plan's calls with the model included (included_calls_used, or included_calls_paused while our credit is low), or the OpenRouter account is out of credit (openrouter_out_of_credit). |
| 403 | The account is suspended (account_suspended), or the model's moderation refused the request (model_refused). |
| 404 | No such model. |
| 413 | The body is over 1 MB (payload_too_large), or a call with the model included has more than about 8,000 tokens of conversation (conversation_too_long). |
| 429 | A limit reached, with <span class="nb">Retry-After</span> saying how long to wait: requests a minute (rate_limited), answers at once (too_many_streams), the free tier's day (daily_limit_reached), renders this month (render_limit_reached), or OpenRouter's own (openrouter_rate_limited). |
| 502 | The model failed or couldn't be reached, after the retries. |
| 503 | Accounts can't be read just now; try again. |
| 504 | The model took too long to start. |

Errors come back as `{"error": {"code", "message", "type", "metadata": {"error_type", "reason"}}}`: `type` is the reason to act on (`rate_limited`, `plan_quota_reached`...). [Limits and errors](/docs/production/limits) says what to do about each.


---

# POST /v1/ui

> An AG-UI run (protocol 1.0), what the MorphScreen SDKs read.

## Keys

Your MorphScreen key in `X-MorphScreen-Key`: the call counts against your plan. Your own OpenRouter key in `Authorization: Bearer sk-or-...` when you want a model other than the one in your plan: it runs on that key, and goes to OpenRouter and nowhere else. Leave it out to use the model in your plan.

## Example

An AG-UI run, which `connectAgent` sends for you; the model and the options go in `forwardedProps`:
```bash
curl -N https://api.morphscreen.com/v1/ui \
  -H "X-MorphScreen-Key: $MORPHSCREEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threadId": "t1", "runId": "r1", "tools": [], "context": [], "state": {},
       "messages": [{"id": "m1", "role": "user", "content": "Quiz me on photosynthesis"}],
       "forwardedProps": {"model": "deepseek/deepseek-v4.1-flash", "packs": ["interactive"]}}'
```

## Request

### RunAgentInput

AG-UI's RunAgentInput (protocol 1.0). Tools aren't supported yet: `tools` must be empty.

| Field | Type | Required | What it is |
|---|---|---|---|
| `threadId` | string |  |  |
| `runId` | string |  |  |
| `messages` | list of object |  |  |
| `tools` | list of any |  |  At most 0. |
| `state` | any |  |  |
| `context` | list of any |  |  |
| `forwardedProps` | object | yes | The model and the options. output: agui (AG-UI events, the default) or ops (the core's op stream). |

### forwardedProps

The model and the options. output: agui (AG-UI events, the default) or ops (the core's op stream).

| Field | Type | Required | What it is |
|---|---|---|---|
| `model` | string | yes |  |
| `packs` | list of string |  |  |
| `components` | list of object |  |  |
| `image_hosts` | list of string |  |  |
| `images` | list of object |  |  At most 200. |
| `photos` | one of the shapes below |  | The app's own photo key, for one provider: with it the model may ask for photos, searched there on the app's quota, each loading from the provider's own address with its credit. Without one (or false) the model isn't asked for photos. |
| `output` | `agui`, `ops` |  |  |
| `repair` | boolean |  |  |

### AppImage

One of your own pictures. The model shows it as ![alt](img:ID) and the API puts its URL and credit in; its host is allowed with it.

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Letters, digits, '-', '_' or '.'. |
| `url` | string | yes | Where it loads from, http(s). |
| `alt` | string |  | What it shows, told to the model. |
| `credit` | string |  | Shown under it, as written (Markdown links allowed). |

## Responses

| Status | What comes back |
|---|---|
| 200 | <span class="nb">Server-sent</span> events: <span class="nb">AG-UI</span> events (output agui), or the core's ops (output ops). |
| 400 | The request can't be run as written; model_needs_your_key: a model other than the included one, asked for without your own OpenRouter key. |
| 401 | No key, or one turned down: your MorphScreen key (morphscreen_key_required, morphscreen_key_invalid) or your OpenRouter key (openrouter_key_required, openrouter_key_invalid). |
| 402 | This month's calls on your plan are used (plan_quota_reached), a paid plan's month and as many again as extra (extra_limit_reached), the free plan's calls with the model included (included_calls_used, or included_calls_paused while our credit is low), or the OpenRouter account is out of credit (openrouter_out_of_credit). |
| 403 | The account is suspended (account_suspended), or the model's moderation refused the request (model_refused). |
| 404 | No such model. |
| 413 | The body is over 1 MB (payload_too_large), or a call with the model included has more than about 8,000 tokens of conversation (conversation_too_long). |
| 429 | A limit reached, with <span class="nb">Retry-After</span> saying how long to wait: requests a minute (rate_limited), answers at once (too_many_streams), the free tier's day (daily_limit_reached), renders this month (render_limit_reached), or OpenRouter's own (openrouter_rate_limited). |
| 502 | The model failed or couldn't be reached, after the retries. |
| 503 | Accounts can't be read just now; try again. |
| 504 | The model took too long to start. |

Errors come back as `{"error": {"code", "message", "type", "metadata": {"error_type", "reason"}}}`: `type` is the reason to act on (`rate_limited`, `plan_quota_reached`...). [Limits and errors](/docs/production/limits) says what to do about each.


---

# POST /v1/render

> An answer you already have, drawn again with no model.

## Keys

Your MorphScreen key in `X-MorphScreen-Key`: the call counts against your plan.

## Example

Draw an answer you already have as HTML, with no model called:
```bash
curl https://api.morphscreen.com/v1/render \
  -H "X-MorphScreen-Key: $MORPHSCREEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "## Budget\n\n<Stat label=\"Per day\" value=\"$165\" />\n"}'
```

The HTML needs no JavaScript and no style attributes, so it passes a strict content security policy. Load `morphscreen.css` from the web SDK on the page that shows it ([HTML without JavaScript](/docs/integrations/html)).

## Request

### RenderRequest

An answer you already have, in our format, with the options. output: html (the default), ops or tree. Free, counted, within a fair-use limit.

| Field | Type | Required | What it is |
|---|---|---|---|
| `text` | string | yes |  |
| `packs` | list of string |  |  |
| `components` | list of object |  |  |
| `image_hosts` | list of string |  |  |
| `images` | list of object |  |  At most 200. |
| `photos` | one of the shapes below |  | The app's own photo key, for one provider: with it the model may ask for photos, searched there on the app's quota, each loading from the provider's own address with its credit. Without one (or false) the model isn't asked for photos. |
| `output` | `html`, `ops`, `tree` |  |  |

### AppImage

One of your own pictures. The model shows it as ![alt](img:ID) and the API puts its URL and credit in; its host is allowed with it.

| Field | Type | Required | What it is |
|---|---|---|---|
| `id` | string | yes | Letters, digits, '-', '_' or '.'. |
| `url` | string | yes | Where it loads from, http(s). |
| `alt` | string |  | What it shows, told to the model. |
| `credit` | string |  | Shown under it, as written (Markdown links allowed). |

## Responses

| Status | What comes back |
|---|---|
| 200 | The answer as HTML, ops or the tree, with the core's verdict. |
| 400 | The request can't be run as written; model_needs_your_key: a model other than the included one, asked for without your own OpenRouter key. |
| 401 | No key, or one turned down: your MorphScreen key (morphscreen_key_required, morphscreen_key_invalid) or your OpenRouter key (openrouter_key_required, openrouter_key_invalid). |
| 403 | The account is suspended (account_suspended), or the model's moderation refused the request (model_refused). |
| 413 | The body is over 1 MB (payload_too_large), or a call with the model included has more than about 8,000 tokens of conversation (conversation_too_long). |
| 429 | A limit reached, with <span class="nb">Retry-After</span> saying how long to wait: requests a minute (rate_limited), answers at once (too_many_streams), the free tier's day (daily_limit_reached), renders this month (render_limit_reached), or OpenRouter's own (openrouter_rate_limited). |
| 503 | Accounts can't be read just now; try again. |

Errors come back as `{"error": {"code", "message", "type", "metadata": {"error_type", "reason"}}}`: `type` is the reason to act on (`rate_limited`, `plan_quota_reached`...). [Limits and errors](/docs/production/limits) says what to do about each.


---

# GET /v1/health

> Whether the API is up.

## Keys

None.

## Example

```bash
curl https://api.morphscreen.com/v1/health
```

## Responses

| Status | What comes back |
|---|---|
| 200 | ok |

Errors come back as `{"error": {"code", "message", "type", "metadata": {"error_type", "reason"}}}`: `type` is the reason to act on (`rate_limited`, `plan_quota_reached`...). [Limits and errors](/docs/production/limits) says what to do about each.


---

# "@morphscreen/web"

> The web SDK's functions and types: loadCore, createAnswer and its options, the Answer it returns, the Core and its sessions, and the actions.

```ts
import { createAnswer, connectAgent, loadCore } from "@morphscreen/web";
import "@morphscreen/web/morphscreen.css";
```

## loadCore

```ts
loadCore(src: string | URL | ArrayBuffer | Uint8Array | Response): Promise<Core>
```

Loads the core from `morphscreen.wasm`, or `morphscreen-agent.wasm` for `connectAgent`, and starts the answer faces loading alongside. Load it once and share it.

## createAnswer

```ts
createAnswer(el: HTMLElement, options: AnswerOptions): Answer
```

Draws an answer into `el`, which gets the class `ms-answer`.

| Option | Type | What it does |
|---|---|---|
| `core` | `Core` | from `loadCore` |
| `packs` | `string[]` | packs beyond core; every one when left out, `[]` for core alone |
| `custom` | `Pack[]` | your own packs |
| `components` | `Record<string, Mount>` | how to draw your own components: `(el, { attrs, html, text }) => cleanup?` |
| `onAction` | `(action: Action) => void` | the reader asked, submitted, finished a quiz, voted or changed state |
| `onComponentState` | `(node, state) => void` | an interactive component's state changed because the reader acted |
| `imageHosts` | `string[]` | hosts pictures may load from; any other shows its description |
| `maps` | `MapTiles` | your map provider and key |
| `maplibre` | module, or a function that loads it | MapLibre GL 6.16 or later, for live maps |
| `onOps` | `(ops: Op[]) => void` | every op, for logging or a renderer of your own |

## Answer

| Method | What it does |
|---|---|
| `push(text)` | the next piece of the model's text |
| `end(truncated?)` | the answer is over; `true` if it hit the token limit |
| `html()` | the finished answer as HTML, what a server would send |
| `applyState(states)` | sets interactive components' state, by node id |
| `destroy()` | stops and clears it |

## Action

```ts
type Action =
  | { type: "ask"; text: string; node: string }
  | { type: "submit"; node: string; form: string; button: string; fields: Record<string, FieldValue> }
  | { type: "quiz"; node: string; score: number; total: number; answers: { question: string; choice: string; right: boolean | null }[] }
  | { type: "vote"; node: string; name: string; choice: string }
  | { type: "state"; node: string; name: string; value: unknown };

type FieldValue = string | number | boolean | string[] | File[] | { lat: number; lng: number; accuracy: number };
```

[Actions and state](/docs/format/actions) says when each is sent.

## Core

| Method | What it does |
|---|---|
| `prompt(packs?, custom?)` | the system prompt for that catalog |
| `session(packs?, custom?)` | a `Session` that reads one answer |
| `actionMessage(action)` | the user message an action starts, worded as the API words it |

## Session

For reading an answer yourself, without drawing it:

| Method | What it does |
|---|---|
| `push(text)` | feeds the next piece; returns the ops it produced |
| `finish(truncated?)` | the answer is over; returns the last ops |
| `html()`, `tree()` | the answer as HTML, or as its tree |
| `verdict()` | the core's verdict: valid, truncated, the component count and the diagnostics |
| `allowImages(hosts)` | where the HTML's pictures may load from |

## Other exports

- `connectAgent(el, options)`: a conversation with an AG-UI agent ([its reference](/docs/reference/agent)).
- `allowedImage(src, { imageHosts })`: whether a picture's address may load.
- `enhanceCharts(root)`: makes the charts under `root` respond (tooltips, legend items that switch a series off), for HTML from the server; returns a function that undoes it.

The package also has `@morphscreen/web/react` ([React](/docs/reference/react)) and `@morphscreen/web/theme` ([theme](/docs/reference/theme)).


---

# "@morphscreen/web/react"

> The Answer component for React 18 and later, and the props for your own components.

```tsx
import { Answer, type CustomProps } from "@morphscreen/web/react";

<Answer core={core} text={text} done={done} onAction={send} />;
```

## Answer

| Prop | Type | What it is |
|---|---|---|
| `core` | `Core` | from `loadCore` |
| `text` | `string` | the answer so far; when it grows, only the new part is read |
| `stream` | `AsyncIterable<string>` | or the chunks as they arrive |
| `done` | `boolean` | the answer is complete |
| `packs` | `string[]` | packs beyond core |
| `custom` | `Pack[]` | your own packs |
| `components` | `Record<string, ComponentType<CustomProps>>` | React components for your own components, by name |
| `onAction` | `(action: Action) => void` | what the reader did |
| `imageHosts` | `string[]` | hosts pictures may load from |
| `maps` | `MapTiles` | your map provider and key |
| `maplibre` | module | MapLibre GL, for live maps |
| `className` | `string` | your classes for the answer's element, which keeps `ms-answer` too |

## CustomProps

```ts
type CustomProps = { attrs: Attrs; html: string; text: string };
```

`attrs` are the component's attributes as the model wrote them, and `html` and `text` its content. [React](/docs/integrations/react) has a whole example.


---

# connectAgent

> A whole conversation with an AG-UI agent, drawn as it streams, with the reader's actions sent back and the state shared.

```ts
connectAgent(el: HTMLElement, options: AgentOptions): Conversation
```

It needs the core from `morphscreen-agent.wasm`. Every option of [`createAnswer`](/docs/reference/web#createanswer) applies to each answer, except `onOps`.

## AgentOptions

| Option | Type | What it does |
|---|---|---|
| `url` | `string` | the agent's endpoint: a run's input is POSTed, its events read back |
| `headers` | object, or a function returning one | request headers, like your own auth, for each run |
| `threadId` | `string` | the conversation's id; a new one when left out |
| `tools`, `context`, `forwardedProps` | | sent with every run, as AG-UI defines them |
| `onToolCall` | `(call) => result` | answers a tool of yours the agent called; the conversation then goes on |
| `onUpdate` | `(update) => void` | every update from the core: steps, custom events, warnings |
| `onState` | `(state) => void` | the shared state changed, by the agent or the reader |
| `sendActions` | `boolean` | send the reader's actions on as user messages (default `true`) |

## Conversation

| Member | What it does |
|---|---|
| `send(content, id?)` | the reader says something (text, or AG-UI content parts); runs the agent |
| `run()` | runs the agent on the conversation as it is |
| `stop()` | stops the run in progress, which ends as truncated |
| `messages()`, `state()` | what to save |
| `load(messages, state?)` | starts from a saved conversation |
| `setState(state)` | sets the shared state |
| `threadId`, `running` | the conversation's id, and whether a run is going |
| `destroy()` | stops and clears it |

[AG-UI agents](/docs/agents/ag-ui) has the guide.


---

# "@morphscreen/web/theme"

> Apply a W3C Design Tokens file to every component, light, dark and mono, and check its contrast before you ship it.

```ts
import { applyTheme } from "@morphscreen/web/theme";
import tokens from "./brand.tokens.json";

applyTheme(tokens);                         // every answer on the page
applyTheme(tokens, { scope: "#support" });  // only answers inside #support
```

A theme is a [W3C Design Tokens](https://www.designtokens.org) file: the colours of each role in light, dark and mono, the faces, the type steps and the corners. A file that leaves a role out is an error, so a theme is always complete. The page's `data-theme` still picks the mode. Applying again with the same scope replaces the earlier theme.

## Functions

| Function | What it does |
|---|---|
| `applyTheme(tokens, { scope?, document? })` | puts the theme on the page after the SDK's stylesheet, as a `<style>` element, and returns it; throws `ThemeError`, naming the token, when the file is incomplete or a value is the wrong type |
| `readTheme(file)` | the theme in a tokens file |
| `writeTheme(theme, description?)` | the theme as a tokens file |
| `themeCss(theme, root?)` | the theme as CSS custom properties, to ship in your own stylesheet |
| `checkTheme(theme)` | every text colour against every ground it's drawn on, in each mode, at 4.5:1; what fails |

Under a content security policy, `applyTheme`'s `<style>` element needs a nonce. To avoid that, write `themeCss(theme)` into your own stylesheet at build time.


---

# The op stream

> What the core hands a renderer as an answer streams: one JSON operation per line, for drawing answers on a platform of your own.

The SDKs never parse the format: they apply the core's operations. `output: "ops"` on `/v1/ui` and `/v1/render` gives you the same operations, for drawing answers yourself, without the core.

The core turns chunks of model text into a stream of operations, one JSON
object per line (served as SSE `data:` lines by the API). Every renderer, on
every platform, only applies ops; none of them parses the format.

## Nodes

The document is a tree. A node's id is its position: the indexes from the
root joined with dots (`"3"`, `"3.0"`, `"3.0.2"`). Ids never shift, because
nodes only ever arrive after the ones before them.

| Node type | What it is | Holds |
|---|---|---|
| A component name (`Card`, `Chart`, `Camera`, a customer's own) | a component, aliases already resolved | children, spans, or data, by its content kind |
| `p` | paragraph | spans |
| `h` | heading; `attrs.level` 1 to 6 | spans |
| `ul`, `ol` | list | `li` children |
| `li` | list item; `attrs.task` is `"open"` or `"done"` for task items | spans |
| `table` | table | `row` children |
| `row` | table row; `attrs.head` is true for the header row | `cell` children |
| `cell` | table cell; `attrs.align` is `"right"` when its column is numeric | spans |
| `code` | fenced code; `attrs.lang` when given | spans (one text span) |
| `quote` | block quote | spans |
| `hr` | thematic break | nothing |

## Ops

| Op | Fields | Meaning |
|---|---|---|
| `open` | `id`, `type`, `attrs` (left out when empty) | A node starts; its parent is its id up to the last dot. A component's attributes are final when it opens (the tag was complete). Attribute values are strings, or `true` for a bare attribute. |
| `spans` | `id`, `spans` | The whole inline content of an open leaf so far (a string when it's plain text). Replaces the previous `spans` of that node. Sent at most once per chunk of input, and before the node closes. |
| `node` | `id`, `type`, `attrs`, `spans`, `data` (each left out when empty) | A leaf that opened and finished within one chunk: `open`, `spans` and `close` in one op. |
| `close` | `id`, optional `data` | The node is final and never changes again. Components with table, list or image content carry their parsed content in `data`. |
| `diag` | `line`, `cls`, `detail`, `severity` | A problem (`error`) or a coercion the core made (`note`), tied to the line, for repair. |
| `end` | `complete`, `truncated` | The stream is over. Anything still open was closed first, with a diagnostic. |

`data` by content kind:

- `table` (Chart, Map): `{"columns": [...], "rows": [[...], ...]}`, cells as
  the model wrote them (renderers parse numbers for charts).
- `list` (FollowUps): `{"items": [spans, ...]}`.
- `images` (Gallery): `{"images": [{"src": "...", "alt": "...", "credit": [spans]}]}`
  (`credit` only when the image has one).
- A Question (interactive pack): `{"items": [spans, ...], "answer": index or null}`;
  the core matches `answer` to a choice by its letter, number or words.
- A Checklist: `{"checks": [{"done": true or false, "c": [spans]}]}` (`[x]` marks done).
- A What-if Result: `{"formula": [tokens], "value": number or null}`: the
  formula in postfix tokens (numbers, the Sliders' names, `+ - * / ^ %`,
  `neg`, `min`, `max`, `round`, `floor`, `ceil`, `abs`, `sqrt`) and its value
  at the Sliders' starting values. A Slider's name is its `name`, or its
  label as one word ("Unit price ($)" is `unit_price`). Renderers run the
  tokens on a stack as the Sliders move; nothing else runs.

## Spans

Inline content is an array of spans:

| Span | Fields |
|---|---|
| `{"t": "text", "v": "..."}` | plain text |
| `{"t": "strong" \| "em" \| "s" \| "u" \| "small" \| "sub" \| "sup" \| "mark" \| "kbd", "c": [spans]}` | formatting |
| `{"t": "code", "v": "..."}` | inline code |
| `{"t": "link", "href": "...", "c": [spans]}` | link |
| `{"t": "img", "src": "...", "alt": "...", "credit": [spans]}` | inline image; `credit` is its title, parsed, when it has one |
| `{"t": "br"}` | line break |
| `{"t": "el", "type": "Badge", "attrs": {...}, "c": [spans]}` | a component inside a sentence or a table cell |

The core strips emojis (keeping ©, ® and ™), reads the HTML models slip in as
formatting, and keeps a dash between words from starting a line, so every
renderer shows the same text.

## Example

```
{"op":"open","id":"0","type":"h","attrs":{"level":"1"}}
{"op":"spans","id":"0","spans":[{"t":"text","v":"Revenue overview"}]}
{"op":"close","id":"0"}
{"op":"open","id":"1","type":"Card","attrs":{"title":"Weekly revenue"}}
{"op":"open","id":"1.0","type":"Chart","attrs":{"type":"line","x":"Week","y":"USD"}}
{"op":"close","id":"1.0","data":{"columns":["Week","Revenue"],"rows":[["W1","24100"],["W2","30800"]]}}
{"op":"close","id":"1"}
{"op":"end","complete":true,"truncated":false}
```


## Actions

Components never run code. When the user acts, the renderer sends an action,
and the API turns it into the model's next turn.

| User does | Action | Next model turn |
|---|---|---|
| Taps a Button with `ask`, or one with no `href` outside a Form | `{"type": "ask", "text": ask or the label, "node": id}` | a user message with that text |
| Taps a FollowUps item | `{"type": "ask", "text": the item, "node": id}` | a user message with that text |
| Taps a Button with `href` | nothing is sent; the link opens | none |
| Submits a Form (any Button inside it) | `{"type": "submit", "node": form id, "form": its name, "button": the label, "fields": {...}}` | a user message listing each field's label and value, with photos and files attached |
| Switches a Tab, opens Details | nothing; local state | none |
| Answers the last question of a Quiz | `{"type": "quiz", "node": id, "score": n, "total": n, "answers": [{"question", "choice", "right": true, false or null}]}` | a user message with the score and each answer |
| Votes in a Poll | `{"type": "vote", "node": id, "name": its name, "choice": the option}` | a user message with the vote |
| Ticks a Checklist item, marks a Flashcard known | `{"type": "state", "node": id, "name": the Checklist's name or "known", "value": what's ticked or known}` | none: it's component state (below) |
| Moves a What-if Slider | nothing; the Results are worked out on the device | none |

`fields` is keyed by each field's `name` (or its label as a slug when it has
none):

| Field | Value |
|---|---|
| Input, TextArea, Select, Radio, Date, Scan | a string |
| Slider | a number |
| Switch | `true` or `false` |
| Checkboxes | an array of the chosen options |
| Camera, File | an array of the platform's file objects (`File` on the web) |
| Location | `{"lat", "lng", "accuracy"}` in degrees and meters |

Photos and files come to the app in the action as the platform's own file
objects (a `File` on the web), for the app to upload where it likes; with
AG-UI they go to the agent as content parts. The renderer checks `required`
before sending. Device values exist only after the user acted: a tap took
the photo, a tap shared the location.

## Component state

What the reader has done to the interactive components and forms is also
kept as plain JSON per node, the same shape on every platform, so it can be
saved, restored and shared with an agent. With AG-UI it is the shared
state's `morphscreen` key, by message id and node id, sent with every run;
an agent that sets it sets the components, and that sends no action.

| Component | State |
|---|---|
| Quiz | `{"answers": [index or null per question]}` |
| Flashcards | `{"known": [card index]}` |
| Poll | `{"vote": option or null}` |
| Checklist | `{"done": [item index]}` |
| WhatIf | `{"values": {slider name: number}}` |
| Form | `{"fields": {name: value}}`, typed as above; uploads and locations stay on the device |

The words of an action's user message come from the core
(`morphscreen_core::action::message`), so every SDK and the API send the
same turn. docs/agui.md has the rest.


---

# Format specification

> The format in full, as the core implements it: the catalog, the document, components, content kinds, streaming, validation, the op stream and actions.

A response is Markdown with a small set of components written like JSX. Models
already write both, so the format needs little teaching, and a half-written
response is always a valid prefix of a finished one.

The catalog is the only definition of the components. The system prompt, the
validator and the renderers all read it, so they always agree.

## Catalog: packs and custom components

A catalog is built from packs (`spec/packs/<name>.json`) and an app's own
components, in that order:

- `core` is always included: layout, text blocks, numbers, charts, forms and
  buttons. The API and the SDKs add every other pack unless an app names the
  ones it wants (`all` names every pack; `[]` is core alone, for a prompt
  about half as long: 1,400 tokens against 2,900, about 22 a component).
- An app's own components use the same JSON as a pack, or come from a JSON
  Schema of their props (Zod 4: `z.toJSONSchema`). Strings, numbers,
  booleans, string enums, URLs and arrays of strings map to attributes; other
  shapes are rejected, since a model can't write them in an attribute.
- A name defined twice is an error, never an override, so an app can't
  replace a built-in component by accident. The one exception: a pack that
  comes in only through the default (`all`) gives way to the app's own, so
  an app's own `Product` or `Map` replaces the pack's; a pack the app names
  outright still clashes. Definitions are checked when the
  catalog is built: names, content kinds, attribute types, enum defaults,
  parents, alias targets, and that `tone` uses the shared values.
- Each renderer draws the components it knows. An app registers renderers
  for its own; a component with none shows its attributes as a list and then
  its content, so nothing the model wrote is lost.

## Document

- The document is the root. There is no `root` statement to forget and no
  names to wire up: a component's place in the tree is where it's written.
- Text between components is Markdown.
- Anything the model writes before or after the UI (a sentence of intro, for
  example) is just Markdown and renders as text.

### Markdown subset

CommonMark plus GFM tables, limited to: ATX headings (`#` to `######`),
paragraphs, emphasis and strong, inline code, links, images, unordered and
ordered lists, block quotes, fenced code, thematic breaks and tables.

Images:

- `![what it shows](find)` asks for a photo, when the app gave the API its
  own Pexels, Unsplash or Openverse key. The API searches that provider for
  what the alt text names and rewrites the image to the provider's address
  before the answer reaches the app. People and the answer's own made-up
  things (an app's dashboard, a listing's rooms) get none. A request
  nothing answers keeps `find`, and renderers show its description in a
  tile.
- `![what it shows](img:ID)` shows one of the app's own pictures, given
  with the request; the API puts its address in.
- An image's title is its credit line, as inline Markdown with links:
  `![Belém Tower](https://images.pexels.com/... "[Author](page), [Pexels License](license), via Pexels")`.
  Renderers show it under the image.
- Renderers load images only from the hosts the app allows. Any other address, model-written URLs included, shows the
  description (an avatar its initials): loading it would tell that host who
  is reading, and a URL can carry what the page holds.
- Link and image addresses may hold balanced parentheses
  (`https://en.wikipedia.org/wiki/Mercury_(planet)`), as in CommonMark.

Raw HTML is never rendered as HTML, but models write some anyway (`<strong>`
and `<br>` in about one answer in ten), so it is read as formatting:

- `<br>` is a line break, `<p>` and `<div>` are paragraph breaks (line breaks
  inside a table cell), `<h1>` to `<h6>` are headings.
- `<strong>`/`<b>`, `<em>`/`<i>`, `<u>`, `<s>`/`<del>`, `<code>`, `<small>`,
  `<sub>`, `<sup>`, `<mark>` and `<kbd>` keep their meaning. Their attributes
  are dropped and unclosed ones are closed where the text ends.
- `<span>`, `<font>`, `<a>` and other layout tags are dropped; their text stays.
- Anything else, and anything inside code, is text.

## Components

```
<Name attr="value" other=42 flag>content</Name>
<Name attr="value" />
```

- A component name starts with an uppercase letter. `<div>` or `<br>` is text.
- Attribute values are quoted strings. Numbers and `true`/`false` may be
  unquoted; JSX-style `{value}` is accepted and unwrapped. A bare attribute
  (`required`) means `true`.
- List attributes separate values with ` | `: `options="S | M | L"`.
- Components whose content is `none` are void, like HTML's `<br>`: they never
  need closing, and a stray `</Input>` is ignored.
- A line that opens with a known component but isn't a tag the core can read
  (`<Stat label! value!>`, the prompt's signature copied in; `subtitle "Eno"`
  without its `=`; a value with no name) shows as text, and is an
  `unreadable-tag` error on its own line, not only the stray closing tags
  it leaves behind.
- Only the attributes listed in the catalog exist. `!` in the prompt marks a
  required attribute; an enum lists every allowed value, the first being the
  default.
- An attribute name means the same thing on every component, with the same
  values: `tone` is always `neutral`, `info`, `success`, `warning` or `danger`.
  (In v0.1 Stat's tones lacked `info` and Callout's lacked `neutral`; models
  wrote the missing one in 8 of 10 answers.)

### Aliases

Some names models write on their own for something that exists: `<Table>` (a
section holding a table), `<Column>` (one cell of Columns) and `<Buttons>` (a
row of buttons). The catalog lists them under `aliases`; they are read as the
component they mean and reported as a note, never taught in the prompt.

### Content kinds

| Kind | Between the tags |
|---|---|
| `any` | Markdown and components |
| `text` | inline text (a label) |
| `table` | a Markdown table: first column labels, other columns series; the separator row may be left out |
| `images` | Markdown images, one item a line; words after an image on its line are its caption |
| `list` | a Markdown list |
| `only:<Tag>` | only those components (`Tabs` holds `Tab`s) |
| `none` | nothing (void) |

A component with a `parent` (like `Tab`) is only valid inside that parent; a
`Result` may sit anywhere inside its `WhatIf` (in a `Columns`, say). A `text`
component marked `"actions": true` (`Product`) also takes `Button`s inside,
drawn under it as what the reader can do with it ("Add to cart"); nothing else
goes inside it.

### Inline components

Any component may sit inside a Markdown table cell (models put badges,
avatars and buttons in cells), and `Badge` and `Button` may also appear inside
a sentence. They render in place without breaking the table.

### Emojis

Renderers strip emojis from everything a model writes (©, ® and ™ stay), and
the prompt asks for none.

## Device pack

`spec/packs/device.json` reaches the device's own hardware and apps. Each
component is native on every platform, and a web page without JavaScript gets
a fallback that still works:

| Component | iOS (SwiftUI) | Android (Compose) | Web with the DOM renderer | Web without JavaScript |
|---|---|---|---|---|
| `Map` | MapKit, markers, route; addresses geocoded on device | MapLibre on the app's own map provider | the app's own map provider's tiles, live with MapLibre | numbered pins on a plain schematic, no tiles; every place links to OpenStreetMap |
| `Camera` | camera capture, or the photo library | CameraX / `TakePicture` | `capture` file input | `<input type="file" accept="image/*" capture>` |
| `Scan` | VisionKit `DataScannerViewController` | ML Kit barcode scanning | `BarcodeDetector`, else typing | type the code or photograph it |
| `Location` | `LocationButton` (one-time permission) | fused location provider | Geolocation API | a city or address field |
| `File` | `fileImporter` | `OpenDocument` | file input | file input, `accept` from the list |

Rules that hold on every platform:

- The model only asks. Nothing is captured, read or sent until the user acts:
  a tap opens the camera or shares the location, and values leave the device
  only when the user submits the form they belong to.
- The operating system's own permission prompts apply; a renderer never works
  around a refused permission, it falls back to the typed field.
- `Location` defaults to approximate. Precise location needs `precision="precise"`
  and the platform's precise-location permission.
- Device components are form fields: their values are submitted with the
  form, photos and files as multipart uploads, a location as coordinates.

## Streaming

The format is designed so the core only ever reads the new text and never
re-reads what it has already processed.

**A value is committed only once it is complete.** This one rule replaces the
per-component patches OpenUI needed (`step` arriving last, cut-short URLs,
truncated `$state` defaults, `max` arriving as "800" before "8000"):

- A component appears when its opening tag is complete (`>` received), with
  every attribute final.
- Text streams word by word.
- A table row counts at its newline. A chart draws when its closing tag
  arrives and shows a placeholder of the same size until then.
- Numbers, enum values and URLs are only ever read in full.

**Finished nodes never change.** A closed component is final, so renderers
never redraw it. Nodes are identified by their position in the document, never
by an array index that can shift.

**One parser.** Parsing a whole response is streaming it in one chunk; the
test suite checks that every split of every recording gives the same tree.

## Validation and repair

Lenient where the intent is clear, strict where it isn't:

- Enum values match without case, and a few common synonyms are accepted
  (`error` means `danger`, `column` means `bar`). These are reported as notes.
- An invalid value is resolved at its edge (OpenUI's #729 rule): use the
  default if there is one; otherwise drop an optional attribute, or invalidate
  the component if the attribute is required. A bad table row drops only that
  row.
- An unknown component is dropped and its content kept as text.
- Every problem is reported as a diagnostic tied to its line, so a repair pass
  can rewrite just that line. Truncation is reported, never silent.

## Output: the op stream (v1)

The core turns chunks of model text into a stream of operations, one JSON
object per line (served as SSE `data:` lines by the API). Every renderer, on
every platform, only applies ops; none of them parses the format.

### Nodes

The document is a tree. A node's id is its position: the indexes from the
root joined with dots (`"3"`, `"3.0"`, `"3.0.2"`). Ids never shift, because
nodes only ever arrive after the ones before them.

| Node type | What it is | Holds |
|---|---|---|
| A component name (`Card`, `Chart`, `Camera`, a customer's own) | a component, aliases already resolved | children, spans, or data, by its content kind |
| `p` | paragraph | spans |
| `h` | heading; `attrs.level` 1 to 6 | spans |
| `ul`, `ol` | list | `li` children |
| `li` | list item; `attrs.task` is `"open"` or `"done"` for task items | spans |
| `table` | table | `row` children |
| `row` | table row; `attrs.head` is true for the header row | `cell` children |
| `cell` | table cell; `attrs.align` is `"right"` when its column is numeric | spans |
| `code` | fenced code; `attrs.lang` when given | spans (one text span) |
| `quote` | block quote | spans |
| `hr` | thematic break | nothing |

### Ops

| Op | Fields | Meaning |
|---|---|---|
| `open` | `id`, `type`, `attrs` (left out when empty) | A node starts; its parent is its id up to the last dot. A component's attributes are final when it opens (the tag was complete). Attribute values are strings, or `true` for a bare attribute. |
| `spans` | `id`, `spans` | The whole inline content of an open leaf so far (a string when it's plain text). Replaces the previous `spans` of that node. Sent at most once per chunk of input, and before the node closes. |
| `node` | `id`, `type`, `attrs`, `spans`, `data` (each left out when empty) | A leaf that opened and finished within one chunk: `open`, `spans` and `close` in one op. |
| `close` | `id`, optional `data` | The node is final and never changes again. Components with table, list or image content carry their parsed content in `data`. |
| `diag` | `line`, `cls`, `detail`, `severity` | A problem (`error`) or a coercion the core made (`note`), tied to the line, for repair. |
| `end` | `complete`, `truncated` | The stream is over. Anything still open was closed first, with a diagnostic. |

`data` by content kind:

- `table` (Chart, Map): `{"columns": [...], "rows": [[...], ...]}`, cells as
  the model wrote them (renderers parse numbers for charts).
- `list` (FollowUps): `{"items": [spans, ...]}`.
- `images` (Gallery): `{"images": [{"src": "...", "alt": "...", "credit": [spans]}]}`
  (`credit` only when the image has one).
- A Question (interactive pack): `{"items": [spans, ...], "answer": index or null}`;
  the core matches `answer` to a choice by its letter, number or words.
- A Checklist: `{"checks": [{"done": true or false, "c": [spans]}]}` (`[x]` marks done).
- A What-if Result: `{"formula": [tokens], "value": number or null}`: the
  formula in postfix tokens (numbers, the Sliders' names, `+ - * / ^ %`,
  `neg`, `min`, `max`, `round`, `floor`, `ceil`, `abs`, `sqrt`) and its value
  at the Sliders' starting values. A Slider's name is its `name`, or its
  label as one word ("Unit price ($)" is `unit_price`). Renderers run the
  tokens on a stack as the Sliders move; nothing else runs.

### Spans

Inline content is an array of spans:

| Span | Fields |
|---|---|
| `{"t": "text", "v": "..."}` | plain text |
| `{"t": "strong" \| "em" \| "s" \| "u" \| "small" \| "sub" \| "sup" \| "mark" \| "kbd", "c": [spans]}` | formatting |
| `{"t": "code", "v": "..."}` | inline code |
| `{"t": "link", "href": "...", "c": [spans]}` | link |
| `{"t": "img", "src": "...", "alt": "...", "credit": [spans]}` | inline image; `credit` is its title, parsed, when it has one |
| `{"t": "br"}` | line break |
| `{"t": "el", "type": "Badge", "attrs": {...}, "c": [spans]}` | a component inside a sentence or a table cell |

The core strips emojis (keeping ©, ® and ™), reads the HTML models slip in as
formatting, and keeps a dash between words from starting a line, so every
renderer shows the same text.

### Example

```
{"op":"open","id":"0","type":"h","attrs":{"level":"1"}}
{"op":"spans","id":"0","spans":[{"t":"text","v":"Revenue overview"}]}
{"op":"close","id":"0"}
{"op":"open","id":"1","type":"Card","attrs":{"title":"Weekly revenue"}}
{"op":"open","id":"1.0","type":"Chart","attrs":{"type":"line","x":"Week","y":"USD"}}
{"op":"close","id":"1.0","data":{"columns":["Week","Revenue"],"rows":[["W1","24100"],["W2","30800"]]}}
{"op":"close","id":"1"}
{"op":"end","complete":true,"truncated":false}
```

## Actions: what the app sends back (v1)

Components never run code. When the user acts, the renderer sends an action,
and the API turns it into the model's next turn.

| User does | Action | Next model turn |
|---|---|---|
| Taps a Button with `ask`, or one with no `href` outside a Form | `{"type": "ask", "text": ask or the label, "node": id}` | a user message with that text |
| Taps a FollowUps item | `{"type": "ask", "text": the item, "node": id}` | a user message with that text |
| Taps a Button with `href` | nothing is sent; the link opens | none |
| Submits a Form (any Button inside it) | `{"type": "submit", "node": form id, "form": its name, "button": the label, "fields": {...}}` | a user message listing each field's label and value, with photos and files attached |
| Switches a Tab, opens Details | nothing; local state | none |
| Answers the last question of a Quiz | `{"type": "quiz", "node": id, "score": n, "total": n, "answers": [{"question", "choice", "right": true, false or null}]}` | a user message with the score and each answer |
| Votes in a Poll | `{"type": "vote", "node": id, "name": its name, "choice": the option}` | a user message with the vote |
| Ticks a Checklist item, marks a Flashcard known | `{"type": "state", "node": id, "name": the Checklist's name or "known", "value": what's ticked or known}` | none: it's component state (below) |
| Moves a What-if Slider | nothing; the Results are worked out on the device | none |

`fields` is keyed by each field's `name` (or its label as a slug when it has
none):

| Field | Value |
|---|---|
| Input, TextArea, Select, Radio, Date, Scan | a string |
| Slider | a number |
| Switch | `true` or `false` |
| Checkboxes | an array of the chosen options |
| Camera, File | an array of the platform's file objects (`File` on the web) |
| Location | `{"lat", "lng", "accuracy"}` in degrees and meters |

Photos and files come to the app in the action as the platform's own file
objects (a `File` on the web), for the app to upload where it likes; with
AG-UI they go to the agent as content parts. The renderer checks `required`
before sending. Device values exist only after the user acted: a tap took
the photo, a tap shared the location.

### Component state

What the reader has done to the interactive components and forms is also
kept as plain JSON per node, the same shape on every platform, so it can be
saved, restored and shared with an agent. With AG-UI it is the shared
state's `morphscreen` key, by message id and node id, sent with every run;
an agent that sets it sets the components, and that sends no action.

| Component | State |
|---|---|
| Quiz | `{"answers": [index or null per question]}` |
| Flashcards | `{"known": [card index]}` |
| Poll | `{"vote": option or null}` |
| Checklist | `{"done": [item index]}` |
| WhatIf | `{"values": {slider name: number}}` |
| Form | `{"fields": {name: value}}`, typed as above; uploads and locations stay on the device |

The words of an action's user message come from the core
(`morphscreen_core::action::message`), so every SDK and the API send the
same turn. docs/agui.md has the rest.

## Versioning

Every pack carries a version, and a built catalog has a hash of everything in
it. The prompt's hash is recorded with every benchmark run, so results are
tied to the exact prompt the model saw.


---

# Versions and deprecation

> How the API and the web SDK are versioned during the public beta, what counts as a breaking change, and how much notice you get.

## The API

The API is `v1`, in its address. Within `v1`:

- **We add, we don't take away.** New endpoints, new optional fields and new values in a response can arrive at any time; your code should ignore what it doesn't know.
- **A breaking change gets notice.** Removing or renaming a field, changing its type, or changing what a status means waits at least 90 days after a mail to every account and a note on this page, with the old behaviour working until then.
- **A breaking change that can't wait** (a security fix) is mailed the same day, with what to change.

The API's [OpenAPI description](https://api.morphscreen.com/v1/openapi.json) is the contract, and our tests hold the server to it.

## The web SDK

`@morphscreen/web` follows semantic versions. Before 1.0 it's published under npm's `beta` tag, and a minor version (0.2 after 0.1) may break things, each written in the package's changelog. From 1.0, only a major version breaks anything.

The SDK and the API agree on the format: a newer API never sends what an SDK from the same major version can't read.

## The format

Every pack has a version, and a catalog has a hash of everything in it. A component or attribute is added in a minor version; one is removed only with the same notice as an API change. A model that writes something removed sees it reported, never a silent change.

## Deprecated

Nothing yet.