arul28/ade/ade-scene

ADE scenes

Emit a fenced code block with language scene containing plain HTML. ADE renders it in a sandboxed frame with its own origin and its own Content-Security-Policy, inline in your reply, on the reply's own text column and in ADE's font and colors. You write real HTML, CSS and JavaScript — there is no schema and no component list to stay inside.

A scene shows, and it can ask: a button or a small form in it puts a ready reply in the user's prompt box (see "Asking"). The user can add to it, and sends it themselves. That reply is a chat message, never a permission. ADE has native surfaces for approvals, and a scene never stands in for one.

ade scene guide prints the short version of this file: when to draw, how a scene must look, charts, asking. Run it before you write a scene. This file is the full reference.

Decide first: does this reply need one?

Most replies need no scene. Add one only when a picture makes the answer clearly faster to read than prose would, and only one per reply.

Good: several PRs and their check states; status across lanes or chats (use live data); a count or metric that changed; CI stages and where it failed; a comparison of many items; a trend or distribution; anything a reader would want to hover, zoom or click through.

Bad: one number or one fact (say it), a short answer, a paragraph (write it), a list a bullet list handles, a yes/no question (ask it in a sentence), or a wall of text in a box (that is just text, further away). When unsure, skip it.

Scenes cost the reader nothing to wait for: the reply streams on while the scene draws, and a preview takes a second or two.

Always draw one when the user asks for a visual. Ask with a scene (see "Asking") for a larger decision only; a small question stays plain text.

How a scene must look

The scene sits in your reply, on the chat's own background.

• No background on html, body or the outermost element. No outer card, no

border around the whole scene, no title banner.

• No side padding on the outermost element: its left edge lines up with your

reply text. Use a fluid width, never a fixed one.

• A box that needs its own background (a panel, a mock of a screen) gets

background: var(--surface), a 1px solid var(--border) border, a 10px radius and at least 14px of padding, so content never touches its edge.

• Colors come from the variables only. Never a hex color for text or a

surface: the user may be on a light theme.

• Let content set the height. No 100vh, no height: 100% on html or

body. Give a chart a fixed pixel height.

The loop: write, preview, fix, then reply

1. Write the scene to a file (/tmp/<name>.html), body only or a whole fence.
2. ade scene preview /tmp/<name>.html --text. It renders the scene exactly as

the chat will, in a hidden window, and prints a screenshot path and every problem: script errors, blocked requests, a scene that never settles, and source mistakes the policy turns into blanks.

1. Open the screenshot and look at it: ok only means nothing threw. Check

the layout (columns lined up, nothing cut off or overlapping, text readable). Fix and preview again until it is right. Check --theme light if colors matter; --width 980 for wide panes.

1. Put the fence in your reply.

Do not skip the preview for anything non-trivial: a scene that throws is a blank box in the user's transcript.

The block

The first line may carry a title and the live data the scene wants. Everything after it is your markup.

<!-- @scene title="Merged pull requests" --> <style> .n { font-size: 48px; font-weight: 600; letter-spacing: -.03em; } .row { display: grid; grid-template-columns: 64px 1fr auto; gap: 14px; padding: 8px 0; border-bottom: 1px solid var(--border); opacity: 0; } .row:hover { background: var(--surface); } </style>

<div class="n" id="count">0</div> <a class="row" data-row href="ade://pr/acme/app/1237"><span>#1237</span><span>Persistent director</span><span>passed</span></a>

<script> ade.countUp("#count", 3); document.querySelectorAll("[data-row]").forEach(function (row, i) { ade.animate(row, [{ opacity: 0, transform: "translateY(8px)" }, { opacity: 1, transform: "none" }], { duration: 460, delay: 200 + i * 110 }); }); ade.ready(); </script>

No padding is added around your markup: content starts on the reply's left edge. Draw your own card (background: var(--surface); border: 1px solid var(--border); border-radius: 10px) when you want one.

Asking

Give the user buttons or a small form when the choice is clearer seen than described: a few options with a picture or a table next to them, several settings at once. A click writes a reply into the user's prompt box. Nothing is sent: the user can add detail, change it, pick another option, and then send. Their message is your answer, so read it as written.

A button: data-reply holds the reply it writes (without a value, the button's own label is used).

<button data-reply="Use option A: one table per tenant">Option A</button>
<button data-reply="Use option B: a shared table">Option B</button>

A form: every named field becomes a - Label: value line under the form's data-reply text.

<form data-reply="Release settings">
  <label>Channel <select name="channel"><option>beta</option><option>stable</option></select></label>
  <label>Rollout % <input name="rollout" type="number" value="25" min="5" max="100"></label>
  <label><input type="checkbox" name="targets" value="mac" checked> mac</label>
  <label><input type="checkbox" name="targets" value="ios"> ios</label>
  <button>Use these</button>
</form>

From script: ade.reply(text) returns a promise that resolves when the text is in the prompt box.

• A reply works only in answer to the user's click or key press in the scene.

A timer, a load handler or a loop cannot write to the prompt box.

• The picked button is marked, and picking another one swaps the reply. Write

each data-reply as a full sentence that reads well as the user's message.

• Once the user sends a message after the scene, the scene is answered:

every reply control is disabled, the options their message names stay marked, ade.answered holds their message, and ade.on("answered", fn) fires, so you can redraw.

• button, input, select and textarea already look like ADE. Add layout,

not a restyle.

• Say the question in your reply text too. The terminal and the phone show the

scene's title only, and the user can always answer by typing.

• Do not ask for a secret in a scene, and do not present a button as an

approval of a tool call or a command. It writes words, nothing else.

• ade scene preview cannot click, so check the layout there and keep the

reply logic to data-reply.

What the frame gives you

window.ade is injected before your code runs:

CSS variables, already set on :root and kept current when the theme changes: --bg, --surface, --border, --fg, --fg-muted, --accent, --success, --warning, --danger, --chart-1 … --chart-6 (series colors for charts), --font-sans, --font-mono, --font-size. Use them and the scene looks like the rest of ADE in every theme, light ones included. --font-sans is ADE's Geist and --font-mono its JetBrains Mono.

Charts

Use ade.chart for a chart. Do not hand-draw axes in SVG: the helper picks round gridlines, spaces the labels, adds a legend and a hover tip, follows the theme, and refits when the reader resizes the chat.

<div id="runs"></div>
<script>
  ade.chart("#runs", {
    type: "bar",                       // "bar" | "line" | "area" | "donut" | "spark"
    labels: ["Mon", "Tue", "Wed"],
    series: [
      { name: "Build", values: [4.1, 4.0, 4.3] },
      { name: "Tests", values: [6.2, 5.9, 6.1] },
    ],
    stacked: true,                     // bars only
    suffix: "m",                       // or prefix: "$", or format: function (v) { return ... }
    height: 200,
  });
  ade.ready();
</script>

• One series: pass values: [...] instead of series.
• donut: labels and values, one slice each. The total sits in the

middle (total: "text" replaces it).

• spark: a small inline line for next to a number. Put it in a <span>;

width and height are in px (96 × 24 by default).

• bar, area and donut take values of zero or more. line also draws

negative values.

• A series may set its own color; use var(--success) or var(--danger)

only when the color means good or bad. Leave it out otherwise.

• ade.chart returns { update(options), destroy() }. With live data, create

the chart once and call update from ade.on("data", ...).

• Give the chart's container no fixed width. Put two charts side by side with

a CSS grid.

3D

Use 3D only when depth is the point: a molecule, a mechanical part, a 3D layout, a surface plot, a spatial dataset. A bar chart is never better in 3D.

Use three.js through ade.three.view. The global THREE is there as soon as a scene mentions it (THREE.OrbitControls included); do not import it.

<div id="model"></div>
<script>
  var view = ade.three.view("#model", { height: 320 });
  var cube = new THREE.Mesh(
    new THREE.BoxGeometry(1, 1, 1),
    ade.three.paint(new THREE.MeshStandardMaterial(), "accent"),
  );
  view.scene.add(cube);
  view.fit();                                                   // frame it
  view.onFrame(function (dt) { cube.rotation.y += dt * 0.6; }); // optional
  ade.ready();
</script>