/render

ao render

Show a self-contained HTML page inline in the current **chat** session's thread, above your final reply. Use it when a chart, table, diagram, image collage, or mockup says more than prose.

In a chat session, the `html_preview` and `html_render` tools do the same as `ao render --check` and `ao render`. They work without shell access to the daemon, so use them when you have them. The rules below apply to both.

ao render "$TMPDIR/turns-by-day.html" --title "Turns by day" --height 420

Rules

• Call it before your final reply. The reader already sees the page, so the

reply must not announce it, say where it is, or restate it. Add only what the page does not say.

• One self-contained HTML file: inline `<style>` and `<script>`, at most 1 MiB.

Remote `https://` resources (a CDN chart library, for example) load as they are. Relative URLs do not resolve. Web workers do not run, and a page can reach no address on this computer or its local network.

• To show a local image, write its absolute path: `src="/abs/shot.png"`, CSS

`url(/abs/bg.webp)`, or a JS string. `ao render` puts the image into the page. PNG, JPEG, GIF, WebP, AVIF, SVG, BMP, and ICO files work, each up to 10 MiB. Remote http(s) URLs load as they are.

• Write the file outside the repository (for example under `$TMPDIR`) so it does

not appear in the diff. AO stores its own copy.

• AO measures the page when you publish it, so the frame opens at the right

height. `--height` (80-2000) is used only when the desktop app is not running. The frame then fits the page's real height.

• Chat sessions only. In a terminal session, open the file with `ao preview`.
• Do not use a built-in visualize skill, for example the Codex visualize skill, or a

`visualize{...}` line. AO does not show them. Only `ao render` or the `html_render` tool shows a page in the thread.

Check before you publish

Run `ao render --check <file>` first. It loads the page in the AO desktop app the way readers see it and writes a PNG. It prints the page's content height and its console messages. Read the PNG. Fix every `console.error` line. Use `--width 390` to check a phone layout. The check loads only public addresses. A request to this computer or to your local network fails. The check needs the desktop app. Without it, publish without a check.

ao render or the Browser panel

Use `ao render` when the page is the answer: a chart, table, diagram, or mockup that you make from data you already have. The page stays in the thread.

Use `ao preview` and `ao browser` when the page is the work: an app that runs, a page that needs a server or a login, or a page that you must click through. The Browser panel shows the live page, and the next preview replaces it.

If the user must still read the page after the dev server stops, use `ao render`.

ao render or a session artifact

Use `ao render` (or `html_render`) when the page answers a question in the thread. Write a session artifact when the user asks for something to keep, for example a report, a dashboard, or a document. Write it to the artifact directory that your prompt names, and attach it with `ao report --artifact <path>`. In a chat session, an HTML file from the artifact directory that you attach with `--artifact` also shows in the thread.

To keep a rendered page as an artifact as well, add `--artifact` to `ao render` (or set `artifact: true` in `html_render`). Do this only when the user asks to keep the page.

Layout

• The frame is borderless on the thread background, as wide as the reply column,

and its left edge lines up with your text.

• Use a fluid width with no outer padding, card, border, or banner title. The

page is part of your reply.

• When the reader expands the page, it opens in a dialog up to 1024 px wide that fits

its height. Use a fluid width so the page can use that width. AO centers a top-level block that has a maximum width.

• Give charts fixed pixel heights. Do not size `html` or `body` with `100vh` or

`height: 100%`: the frame grows to fit the page, and viewport heights make it grow again.

• Scripts run in a sandbox with no access to AO, cookies, or storage. Links open

in the user's browser.

Theme

AO injects its active theme as CSS custom properties on `:root`. They follow light/dark mode live:

`--background` (identical to the thread), `--foreground`, `--muted`, `--muted-foreground`, `--card`, `--card-foreground`, `--popover`, `--border`, `--border-strong`, `--primary`, `--primary-foreground`, `--accent`, `--accent-foreground`, `--success`, `--warning`, `--destructive`, `--code`, `--link`, `--chart-1` … `--chart-6` (categorical series), `--radius`, `--font-sans`, `--font-mono`.

The base stylesheet sets the page background, text color, and font from these, sets `body` margin to 0, and hides the page scrollbar in the thread. Use the variables rather than hard-coded colors so the page reads correctly in both themes.