Skip to content

Composing UI with a Model

Some pages are better arranged by the user than by you: a dashboard, a workspace, a “show me what matters this morning” screen. With sygnal/ai the user describes the page in words (“urgent tickets first, then the pending orders”), and a model builds it from parts your app prepared: real Sygnal components with their own data, wording and actions.

The model only chooses. It picks parts, arranges them, and picks their params from the lists you declared. It never writes markup, state paths or action names, so every label, number and button on the composed page is the app’s own, and every part is wired into app state the way you wired it.

One declaration, the catalog, works with two kinds of model:

  • a decision model (TypeSafe Jev, Ollama’s nimble) through decide(): it answers multiple-choice questions (“is the revenue chart asked for?”, “which comes first?”) with probabilities, and code turns the answers into the layout;
  • a chat LLM through the chat driver: it fills a JSON Schema of the catalog in one structured-output request, streamed as a preview.

Choosing the backend is the only difference. The app code, the rendering and the tests are the same.

Reach for it when the set of useful views is larger than the screens you want to design, and every view is made of parts you can build ahead of time. If the user needs text the app doesn’t have (a summary, an answer), that’s a chat; if the app needs one typed answer about some state, that’s a decision.

defineCatalog() declares the parts a model may place. Each part is a component plus a description, which is all a model ever sees of it. This catalog is the one every demo on this page composes from:

catalog.jsx
import { defineCatalog } from 'sygnal/ai'
const KPIS = { revenue: ['Revenue', '$48.2k', '+6%'], signups: ['Signups', '312', '+12%'] }
const SERIES = { year: [31, 34, 33, 38, 41, 40, 44, 43, 46, 45, 47, 48], quarter: [45, 47, 48], month: [44, 46, 45, 47, 49, 48] }
const ORDERS = [
{ id: 'A-1041', customer: 'Northwind', amount: '$1,200', status: 'paid' },
{ id: 'A-1042', customer: 'Globex', amount: '$640', status: 'pending' },
{ id: 'A-1043', customer: 'Initech', amount: '$2,310', status: 'pending' },
{ id: 'A-1044', customer: 'Umbrella', amount: '$90', status: 'refunded' },
]
export const TICKETS = [
{ id: 1, title: 'Checkout fails on Safari', priority: 'high' },
{ id: 2, title: 'Invoice PDF is blank', priority: 'high' },
{ id: 3, title: 'Typo on the pricing page', priority: 'low' },
]
export const TASKS = [
{ id: 1, text: 'Reply to Globex', done: false },
{ id: 2, text: 'Review the Q3 numbers', done: true },
]
export function Kpi({ metric }) {
const [label, value, delta] = KPIS[metric]
return <section className="card kpi"><h3>{label}</h3><b>{value}</b> <span className="muted">{delta}</span></section>
}
export function RevenueChart({ range }) {
const values = SERIES[range]
const points = values.map((v, i) => `${(i / (values.length - 1)) * 200},${60 - (v - 28) * 2.5}`).join(' ')
return (
<section className="card">
<h3>Revenue, last {range}</h3>
<svg viewBox="0 0 200 60" role="img" aria-label={`Revenue over the last ${range}`}><polyline points={points} /></svg>
</section>
)
}
export function OrdersTable({ status }) {
const rows = ORDERS.filter((o) => status === 'any' || o.status === status)
return (
<section className="card">
<h3>{status === 'any' ? 'Recent orders' : `Orders: ${status}`}</h3>
<ul>{rows.map((o) => <li>{o.id} · {o.customer} · {o.amount}</li>)}</ul>
</section>
)
}
// a part that talks to its host: "Add to my tasks" goes to the PARENT sink
export function TicketList({ priority }) {
const shown = TICKETS.filter((t) => priority === 'any' || t.priority === priority)
return (
<section className="card">
<h3>{priority === 'high' ? 'Urgent tickets' : 'Open tickets'}</h3>
<ul>{shown.map((t) => <li>{t.title} <button type="button" className="take" data={{ id: t.id }}>Add to my tasks</button></li>)}</ul>
</section>
)
}
TicketList.intent = ({ DOM }) => ({ TAKE: DOM.click('.take').data('id', Number) })
TicketList.model = { TAKE: { PARENT: (state, id) => TICKETS.find((t) => t.id === id) } }
// a part with state: the catalog gives it the lens `state: 'tasks'`, so it edits the app's tasks
export function Checklist({ state }) {
return (
<section className="card">
<h3>Today</h3>
<ul>{state.map((task) => <li><label><input type="checkbox" className="toggle" checked={task.done} data={{ id: task.id }} /> {task.text}</label></li>)}</ul>
</section>
)
}
Checklist.intent = ({ DOM }) => ({ TOGGLE: DOM.change('.toggle').data('id', Number) })
Checklist.model = { TOGGLE: (tasks, id) => tasks.map((t) => (t.id === id ? { ...t, done: !t.done } : t)) }
export function Weather() {
return <section className="card"><h3>Weather</h3><b>27°C</b> <span className="muted">sunny in Lisbon</span></section>
}
export const catalog = defineCatalog({
parts: {
revenue: { component: Kpi, props: { metric: 'revenue' }, description: "Revenue (KPI card: this month's revenue total as one number)" },
signups: { component: Kpi, props: { metric: 'signups' }, description: 'Signups (KPI card: new signups this week)' },
revenueChart: {
component: RevenueChart,
description: 'Revenue chart (line chart of the revenue trend over time)',
params: {
range: {
label: 'time range', default: 'year',
options: { year: 'the last 12 months (this year)', quarter: 'the last 3 months (this quarter)', month: 'the last 30 days (this month)' },
},
},
},
orders: {
component: OrdersTable,
description: 'Orders (table of the most recent orders: customer, amount, status)',
params: { status: { label: 'order status', default: 'any', options: { any: 'orders of every status', paid: 'paid orders', pending: 'pending orders (not paid yet)', refunded: 'refunded orders' } } },
},
tickets: {
component: TicketList,
description: 'Tickets (list of open support tickets, by priority)',
params: { priority: { label: 'priority', default: 'any', options: { any: 'every open ticket', high: 'only high-priority (urgent) tickets' } } },
},
tasks: { component: Checklist, state: 'tasks', description: "Tasks (checklist of the user's tasks for today)" },
weather: { component: Weather, description: "Weather (today's weather forecast for the office city)" },
},
})

(This block is a module the demos on this page import, ./catalog.jsx.)

.composer { display: grid; gap: 0.6rem; }
.composer .ask { display: flex; gap: 0.5rem; }
.composer .ask input { flex: 1; }
.composer .chips { display: flex; flex-wrap: wrap; gap: 0.4rem; }
.composer .chip { font-size: 0.8rem; }
.composer .status { margin: 0; font-size: 0.85rem; opacity: 0.8; }
.compose-page { display: grid; gap: 0.6rem; }
.compose-row { display: grid; grid-auto-flow: column; grid-auto-columns: 1fr; gap: 0.6rem; }
.canvas.preview { opacity: 0.6; }
.card { border: 1px solid #8884; border-radius: 6px; padding: 0.5rem 0.75rem; }
.card h3 { margin: 0 0 0.3rem; font-size: 0.9rem; }
.card ul { margin: 0; padding-left: 1.1rem; }
.card svg { width: 100%; height: 60px; }
.card polyline { fill: none; stroke: currentColor; stroke-width: 2; }
.muted { opacity: 0.7; font-size: 0.85em; }
.explain { font-size: 0.8rem; }
.explain ul { margin: 0.2rem 0 0.5rem; padding-left: 1.1rem; }
FieldWhat it does
componentThe Sygnal component. It renders as a child of the host, so lenses, CHILD.select, EVENTS, context and drivers work as for any child. (render, a view function, works for a part with no state of its own. It is called inline, so its elements are in the host’s own DOM scope: the host’s intent and a form() behavior on the host hear them. Its root element gets the node key, as a component does, unless the view gives one.)
descriptionAll a model sees of the part: “Noun (what it shows)” (below)
propsFixed props, or (params, state) => props
paramsThe inputs a model gives, passed as props (below)
stateHow the part reaches app state: a key of the host’s state ('tasks'), a lens, or (node) => lens for a record part. Without it the part sees the host’s state, as any child does
localState kept in the composition instead (local: { text: '' }), per placed part
inWhere it may go: 'page' (the default), a container, or 'container:slot'
groupAlternatives: parts in one group are offered as one choice, and the first one in a layout wins
maxUsesHow often one identity may appear (default 1)
required, pin, companionsAlways on the page (never offered to the model); pinned to 'start' or 'end'; parts added right after it

Params are the only inputs a model gives, and each kind says what a model may write:

ParamBoth backends?Example
{ options, default }yes: a decision model picks one option, with “not stated” meaning the default; an LLM fills an enumrange: { default: 'year', options: { year: 'the last 12 months (this year)', quarter: '…' } }
{ type: 'number', bins }yes: an LLM writes a number; a decision model picks a bin, which names the vague words it coverslimit: { type: 'number', default: 5, min: 1, max: 8, bins: { 3: 'a few (top 3)', 8: 'all of them' } }
{ type: 'text' }, { type: 'list' }LLM only: a decision model keeps the default, and a required one with no default makes the part LLM-onlytitle: { type: 'text', maxLength: 40, required: true }
{ from: (state) => records }yes: one node per record the request names, found by name and aliasesbelow

A record param turns one part into a part per record: “Northwind and Globex” places the customer card twice, once per customer. The record’s value becomes part of the node key (customer:7), and byId() from sygnal gives each card a lens to its own record, so what it edits lands in app state:

import { byId } from 'sygnal'
const customer = {
component: CustomerCard,
description: "Customer (card: one customer's plan, contact and notes)",
maxUses: 4,
params: {
id: { label: 'customer', from: (state) => state.customers.map((c) => ({ value: c.id, name: c.name, aliases: c.aliases })) },
},
state: (node) => byId('customers', node.params.id),
}

byId(field, id) is a { get, set } lens to the element of state[field] whose id is id (a third argument names another key). It works for any child: <TodoItem state={byId('todos', 3)} />.

A container is a view function with named slots; parts go into a slot when their in names it. The model never chooses a container: a container appears when parts land in its slots, and the built-in row appears when the request asks for things side by side.

const catalog = defineCatalog({
parts: {
orders: { component: OrdersTable, description: 'Orders (table of recent orders)', in: ['page', 'tabs:billing'] },
invoices: { component: Invoices, description: 'Invoices (list of unpaid invoices)', in: 'tabs:billing' },
tasks: { component: Checklist, state: 'tasks', description: "Tasks (the user's checklist)", in: ['page', 'tabs:overview'] },
},
containers: {
tabs: {
slots: { overview: 'Overview tab: the summary', billing: 'Billing tab: money (orders, invoices, payments)' },
minSlots: 2,
render: ({ children, ui, control }) => (
<div className="tabs">
<div role="tablist">
{children.map((c, i) => <button type="button" role="tab" aria-selected={String(i === (ui.tab ?? 0))} {...control('tab', i)}>{c.slot}</button>)}
</div>
{children.map((c, i) => <div role="tabpanel" hidden={i !== (ui.tab ?? 0)}>{c.vnode}</div>)}
</div>
),
},
},
})
  • The view gets { key, node, params, slots, children, ui, control, frozen }: slots maps each slot to its rendered parts, children lists them in order with their slot.
  • control(name, value) returns data attributes to spread on an element: a click on it sets ui[name] = value for this container (the behavior’s CONTROL action), so the open tab is state too.
  • minSlots: with fewer filled slots the container is unwrapped and its parts go where it was.
  • maxUses: how many of it one layout may hold (default: no limit), as with parts. The ones after the limit are unwrapped, and their parts move to the first place their in allows (the first such container). compose.llm() tells the model the limit and repairs a reply that goes over it. compose.decisions() places parts into one container of each kind, so its layouts never repeat a container.
  • A container is a view, never a component with a model (SYG161): its parts must stay the host’s children.

in is the most valuable field a catalog has: with it, a decision model placed parts right in 37 of 37 cases, against 25 of 37 when it chose a parent among every slot.

  • guidance: a sentence the order questions and the LLM prompt quote, for what the request doesn’t say: guidance: 'Summaries before details.'
  • limits: { maxParts: 12, maxDepth: 4 } by default.
  • examples: few-shot cases for an LLM ({ prompt, tree }), written by you.
  • rows: false: no built-in row.

Fixed structure belongs in data (required, pin, companions, in, guidance), not in a question to the model.

Most of the measured errors are part selection, not arrangement: from the right parts, Jev arranged 62–63 of 65 layouts right. Selection depends mostly on the descriptions:

  • “Noun (what it shows)”, leading with the word a user says: “Revenue chart (line chart of the revenue trend over time)”. The demo app’s catalog went from 5 to 7 of 11 prompts right on nimble with this form alone.
  • Don’t let descriptions overlap. Don’t mention another part’s content: “monthly revenue” on both the KPI and the chart pulled in the KPI whenever the chart was asked for.
  • Alternatives go in a group (cards per project or a project list), never in two similar descriptions.
  • Each option says what it shows (“the last 3 months (this quarter)”), and a number’s bins name the vague words they cover (“a few (top 3)”).

The compose behavior holds a composition in a slice of the host’s state, and catalog.render() renders it in the host’s view:

import { compose } from 'sygnal/ai'
import { catalog } from './catalog.jsx'
function Dashboard({ state }) {
return (
<div>
<form className="ask">
<input className="prompt" aria-label="The page you want" value={state.page.prompt} />
<button type="submit">Compose</button>
</form>
<div className="canvas">{catalog.render(state.page, state)}</div>
</div>
)
}
Dashboard.uses = {
page: compose(catalog, { backend: compose.decisions({ model: 'jev-latest' }), form: '.ask', prompt: '.prompt' }),
}

form and prompt are selectors: typing in the prompt field sets state.page.prompt, and submitting the form composes.

In this demo, the demo server below stands in for both kinds of model. They only match words, which is enough to show the wiring: the decision route answers each question decide() sends, by name, and the chat route writes the layout JSON a chat model would. For a follow-up edit both read the change into the same list of removes, moves, adds and setting changes, then answer it in their backend’s encoding (the edit questions, or the operations). A real model reads the descriptions instead.

Demo server
import { encodeOpenResponses } from 'sygnal/ai'
// how a request names each part, and each param value (a real model reads the descriptions)
const PARTS = {
revenue: /revenue(?! (chart|trend))/i,
signups: /sign-?ups?/i,
revenueChart: /chart|trend/i,
orders: /orders?\b/i,
tickets: /tickets?|support/i,
tasks: /tasks?|to-?dos?/i,
weather: /weather|forecast/i,
}
const PARAMS = {
revenueChart: { range: { quarter: /quarter/i, month: /month/i } },
orders: { status: { pending: /pending|unpaid/i, paid: /\bpaid/i, refunded: /refund/i } },
tickets: { priority: { high: /urgent|high/i } },
}
const SIDE = /side by side|beside|next to|in a row/i
const at = (text, id) => text.search(PARTS[id])
const clause = (text, id) => text.split(/,|\bthen\b/i).find((c) => PARTS[id].test(c)) ?? ''
const valueOf = (text, id, name) => Object.keys(PARAMS[id][name]).find((v) => PARAMS[id][name][v].test(text))
const sure = (choice, keys, p = 0.92) => ({
type: 'choice', choice, confidence: p,
probabilities: Object.fromEntries(keys.map((k) => [k, k === choice ? p : (1 - p) / (keys.length - 1)])),
})
// a decision model: one answer per question, by the question's name
function answer(name, question, text) {
const keys = Object.keys(question.criteria ?? {})
let m
if (name === 'row') return { type: 'noul', noul: SIDE.test(text) ? 0.91 : 0.04 }
if ((m = name.match(/^use_(\w+)$/))) return sure(at(text, m[1]) >= 0 ? 'use' : 'omit', keys)
if ((m = name.match(/^param_(\w+?)__(\w+)$/))) return sure(valueOf(text, m[1], m[2]) ?? 'not_stated', keys)
if ((m = name.match(/^beside_(\w+)$/))) {
const c = clause(text, m[1])
return sure((SIDE.test(c) && keys.find((k) => k !== 'none' && k !== m[1] && PARTS[k]?.test(c))) || 'none', keys)
}
if ((m = name.match(/^(?:first|left)_(\w+)_vs_(\w+)$/))) return sure(at(text, m[1]) <= at(text, m[2]) ? m[1] : m[2], keys)
if (question.type === 'noul') return { type: 'noul', noul: 0.05 }
return sure(keys[0], keys)
}
// a follow-up, read into what it changes (each node key here is its part id)
const named = (text) => Object.keys(PARTS).filter((id) => at(text, id) >= 0).sort((a, b) => at(text, a) - at(text, b))
const paramsIn = (text, id) => Object.fromEntries(Object.keys(PARAMS[id] ?? {}).map((n) => [n, valueOf(text, id, n)]).filter(([, v]) => v))
function changes(text, onPage) {
const out = { remove: [], move: [], add: [], set: [], replace: null }
if (/\bonly\b/i.test(text)) out.remove = onPage.filter((id) => !named(text).includes(id))
for (const c of text.split(/,|\bthen\b|\band (?=remove|move|add|show|put)/i)) {
let m
if ((m = c.match(/^(.*)\binstead of\b(.*)$/i))) { out.replace = { to: named(m[1])[0], from: named(m[2])[0] }; continue }
if (/\b(remove|drop|hide|without)\b/i.test(c)) { out.remove.push(...named(c).filter((id) => onPage.includes(id))); continue }
const ref = c.match(/\b(above|below|under|beside|next to)\s/i)
const anchor = ref ? named(c.slice(ref.index))[0] : null
const where = /\b(top|first)\b/i.test(c) ? 'top' : /\b(bottom|last)\b/i.test(c) ? 'bottom'
: anchor ? `${/above/i.test(ref[1]) ? 'above' : /below|under/i.test(ref[1]) ? 'below' : 'beside'}:${anchor}` : null
for (const id of named(c).filter((x) => x !== anchor)) {
const params = paramsIn(c, id)
if (!onPage.includes(id)) out.add.push({ id, params, where })
else {
if (where) out.move.push({ id, where })
if (Object.keys(params).length) out.set.push({ id, params })
}
}
}
return out
}
// a decision model, editing: the edit questions (remove_, set_, add_, moved_, where_ and the gates)
function editAnswer(name, question, ch) {
const keys = Object.keys(question.criteria ?? {})
const yes = (b) => ({ type: 'noul', noul: b ? 0.93 : 0.04 })
const part = (k) => k.replace(/_\d+$/, '')
let m
if ((m = name.match(/^remove_(\w+)$/))) return yes(ch.remove.includes(part(m[1])) || ch.replace?.from === part(m[1]))
if (name === 'swap') return yes(!!ch.replace)
if (name === 'placed') return yes(ch.move.length > 0)
if (name === 'change') return yes(ch.set.length > 0)
if ((m = name.match(/^set_(\w+?)__(\w+)$/))) {
const v = ch.set.find((s) => s.id === part(m[1]))?.params[m[2]]
return sure(keys.includes(v) ? v : 'keep', keys)
}
if ((m = name.match(/^add_(\w+)$/))) return sure(ch.add.some((a) => a.id === m[1]) || ch.replace?.to === m[1] ? 'use' : 'omit', keys)
if ((m = name.match(/^moved_(\d)$/))) return sure(ch.move[m[1] - 1]?.id ?? 'none', keys)
if ((m = name.match(/^where_(\w+)$/))) {
const w = [...ch.move, ...ch.add].find((x) => x.id === part(m[1]))?.where
return sure(keys.includes(w) ? w : 'not_stated', keys)
}
return null // the params of an added part: as for a new page
}
// a chat model, editing: the operations, on the page's n1, n2, … keys
function ops(text) {
const nodes = Object.fromEntries([...text.matchAll(/^\s*n(\d+): (\w+)(.*)$/gm)].map(([, n, part, rest]) => [part, { key: `n${n}`, rest }]))
const ch = changes(text.split('\nChange: ')[1], Object.keys(nodes))
const place = (w) => {
const [dir, id] = (w ?? 'bottom').split(':')
return id ? `${dir === 'beside' ? 'right of' : dir} ${nodes[id].key}` : dir
}
const changed = (s) => Object.entries(s.params).some(([k, v]) => !nodes[s.id].rest.includes(`${k}="${v}"`))
return [
...ch.remove.map((id) => ({ op: 'remove', node: nodes[id].key })),
...(nodes[ch.replace?.from] && ch.replace.to ? [{ op: 'replace', node: nodes[ch.replace.from].key, part: ch.replace.to }] : []),
...ch.set.filter(changed).map((s) => ({ op: 'setParams', node: nodes[s.id].key, params: s.params })),
...ch.move.map((mv) => ({ op: 'move', node: nodes[mv.id].key, where: place(mv.where) })),
...ch.add.map((a) => ({ op: 'add', part: a.id, params: a.params, where: place(a.where) })),
]
}
// a chat model: the layout JSON, in the order the request names the parts
function layout(text) {
const node = (id) => {
const params = paramsIn(text, id)
return Object.keys(params).length ? { part: id, params } : { part: id }
}
const parts = named(text)
const row = parts.filter((id) => SIDE.test(clause(text, id)))
const children = parts.flatMap((id) => !row.includes(id) || row.length < 2 ? [node(id)] : id === row[0] ? [{ part: 'row', children: row.map(node) }] : [])
return JSON.stringify({ asked_for: parts.map((id) => text.match(PARTS[id])[0]), children })
}
export default {
'POST /api/decide': ({ json }) => {
const text = json.state.user_request
// an edit's questions come with the current page
const onPage = Object.keys(json.questions).filter((n) => n.startsWith('remove_')).map((n) => n.slice(7).replace(/_\d+$/, ''))
const ch = json.state.current_page && changes(text, onPage)
const reply = (name, q) => (ch && editAnswer(name, q, ch)) ?? answer(name, q, text)
return { delayMs: 350, json: { model: json.model, answers: Object.fromEntries(Object.entries(json.questions).map(([name, q]) => [name, reply(name, q)])) } }
},
'POST /v1/responses': ({ json }) => {
const text = String(json.input.at(-1).content)
// an edit sends the current page and the change
const reply = text.startsWith('Current page:') ? JSON.stringify({ ops: ops(text) }) : layout(text)
return { delayMs: 300, chunkMs: 90, sse: encodeOpenResponses(reply.match(/[\s\S]{1,16}/g)) }
},
}

The demo composes its first prompt on load. The first row of chips starts a new page (fresh: true); the second row changes the page that is there (follow-up edits), and so does the field. Try your own with the words the stand-in knows (revenue, signups, chart, orders, tickets, tasks, weather; “side by side”; quarter, month, pending, urgent; top, bottom, above, below, beside, remove, instead of). Under the page, the model’s answers: every question of each step, with the probability of the answer it chose.

Dashboard.jsx
import { compose } from 'sygnal/ai'
import { catalog, TASKS } from './catalog.jsx'
const EXAMPLES = [
'Revenue and signups side by side, then the revenue chart for the quarter',
'Urgent tickets first, then the pending orders',
'The weather and my tasks',
'The stock price of Apple',
]
const FOLLOW_UPS = [
'Move the chart to the top',
'Show the chart for the month',
'Add my tasks beside the chart',
'The orders instead of the chart',
'Remove the signups',
]
const STATUS = {
idle: () => 'Describe the page you want.',
composing: () => 'Composing…',
preview: () => 'Arranging the parts…',
done: () => 'Done.',
unavailable: () => 'Nothing in the catalog fits that request.',
error: (page) => `The model failed: ${page.error}`,
}
const pct = (p) => `${Math.round((p ?? 1) * 100)}%`
const answerLine = ([name, a]) => (
<li><code>{name}</code>: {a.type === 'noul' ? pct(a.noul) : <>{a.choice} <span className="muted">{pct(a.probabilities?.[a.choice])}</span></>}</li>
)
function Dashboard({ state }) {
const page = state.page
const busy = page.status === 'composing' || page.status === 'preview'
return (
<div className="composer">
<form className="ask">
<input className="prompt" aria-label="The page you want" value={page.prompt} />
<button type="submit" disabled={busy}>Compose</button>
</form>
<div className="chips">
{EXAMPLES.map((p) => <button type="button" className="chip" data={{ prompt: p }} disabled={busy}>{p}</button>)}
</div>
<div className="chips">
{FOLLOW_UPS.map((p) => <button type="button" className="chip follow-up" data={{ prompt: p }} disabled={busy || !page.layout}>{p}</button>)}
</div>
<p className="status" aria-live="polite">{STATUS[page.status](page)}</p>
<div className={page.preview ? 'canvas preview' : 'canvas'}>{catalog.render(page, state)}</div>
{page.decisions && (
<details className="explain" open>
<summary>The model's answers</summary>
{Object.entries(page.decisions).map(([step, answers]) => (
<>
<b>{step}</b>
<ul>{Object.entries(answers).map(answerLine)}</ul>
</>
))}
</details>
)}
</div>
)
}
Dashboard.initialState = { tasks: TASKS }
Dashboard.uses = {
page: compose(catalog, { backend: compose.decisions({ model: 'jev-latest' }), form: '.ask', prompt: '.prompt' }),
}
Dashboard.intent = ({ DOM }) => ({
EXAMPLE: DOM.click('.chip:not(.follow-up)').data('prompt'),
FOLLOW_UP: DOM.click('.follow-up').data('prompt'),
})
Dashboard.model = {
// the demo composes on load only to have something to show
BOOTSTRAP: { EFFECT: (state, data, next) => next('page.COMPOSE', EXAMPLES[0]) },
// a new page: start over
EXAMPLE: { EFFECT: (state, prompt, next) => next('page.COMPOSE', { prompt, fresh: true }) },
// a change to the page that is there
FOLLOW_UP: { EFFECT: (state, prompt, next) => next('page.COMPOSE', prompt) },
}
export default Dashboard

A decision model composes in at most two decide() calls (watch the demo server’s notes): a select step (which parts, which params, “side by side?”), then, when there is something to arrange, a layout step (which comes first, what goes beside what). After the select step the chosen parts show as a preview while the layout step runs.

state.page (the key you gave in uses):

Field
promptThe request
statusidle, composing (a request is out), preview (a partial layout shows), done, unavailable (nothing in the catalog fits), error
layoutThe last finished layout: plain JSON, { root: 'page', nodes }. Kept on an error and when nothing fits
previewThe layout being built; catalog.render shows it instead while it is set
queuedWith busy: 'queue': the composition waiting for the one in flight, { prompt, fresh? }, else null
decisionsWhat the backend explains: a decision model’s answers per step, or an LLM’s plan (asked_for) and what its repair step fixed
errorWhy the last composition failed
ui, localContainer state (the open tab) and local parts’ state, per node

The layout’s node keys are identities: the part id (orders), part:value for a record (customer:7), ~2 for a repeat, row and row~2 for rows. A part that stays in a new composition keeps its key, so its instance and its state.

  • Nothing fits (“The stock price of Apple”): status: 'unavailable', and the page keeps its layout.
  • Errors: a failed request, or a reply the backend can’t turn into a valid layout, is status: 'error' with error set. The page keeps its layout: a model’s mistake never becomes an invalid page.
  • A new prompt while one is composing aborts the old one’s step in flight (busy: 'queue' makes it wait instead: A page that recomposes itself).

The behavior’s actions are the host’s, under the slice’s key:

ActionData
page.COMPOSEA prompt, { prompt, fresh: true } (start over), or nothing (the form’s submit: the slice’s prompt). From code: next('page.COMPOSE', 'Show my tasks'), as the demo’s chips do
page.SET_LAYOUTA layout to show without a model: restore, undo, your own edits. null clears
page.REMOVEA node key: that part and anything inside it go
page.CONTROL{ key, name, value }: a container control (what control() clicks send)
page.DONESent when a composition finishes, with the layout. A host entry 'page.DONE' runs after the behavior’s

A page that composes on its own, from a STATE.watch on what it shows, can ask for compositions faster than a model writes them: a fresh layout of nine parts takes a local 8B model 15 to 20 seconds. By default each new page.COMPOSE aborts the one in flight, so while the changes keep coming, none finishes. busy: 'queue' keeps one in flight and runs the latest after it:

Board.jsx
Board.uses = {
page: compose(catalog, { backend: compose.llm({ model: 'qwen3:8b' }), busy: 'queue' }),
}
Board.intent = ({ STATE }) => ({
// compose again when what needs attention changes, not on every number that moves
ARRANGE: STATE.watch((s) => signature(s), { immediate: true }),
})
Board.model = {
ARRANGE: { EFFECT: (state, _, next) => next('page.COMPOSE', { prompt: brief(state), fresh: true }) },
}
busyA page.COMPOSE while a composition is in flight
'abort' (default)Starts at once; the one in flight is aborted (the request lane’s latest)
'queue'Waits in queued; a newer one replaces it. When the one in flight ends, it lands first (status: 'done', page.DONE runs), then the waiting one starts on the layout page.DONE’s entries left. One that fails while another waits is replaced by it (in the same action). A request aborted with no reply (by another compose use of the component in the same key, or by your { abort }) ends as an error, or, when one waits, lets it start once the request’s timeoutMs ends

With 'queue', at most one request is out per slice, and the page always ends on the latest request. page.SET_LAYOUT ends both (a layout of your own wins). To correct the model’s layout as it lands (hold it to the user’s pins), write it in a page.DONE entry’s STATE rather than through page.SET_LAYOUT, which would also drop the one waiting:

Board.jsx
Board.model = {
'page.DONE': (state, layout) => {
const fixed = enforcePins(catalog, state, layout)
return fixed ? { ...state, page: { ...state.page, layout: catalog.finish(fixed, state) } } : state
},
}

A burst of changes that should count as one (a slider dragged, several fields typed) is the intent’s to collapse: STATE.watch(signature).compose(debounce(500)) (debounce from 'sygnal') sends one page.COMPOSE after the burst. An aborted request costs the model little: Ollama stops generating within about 100 ms of the abort, streamed or not, and drops one still waiting in its queue.

When the page already has parts, page.COMPOSE is an edit of it, with either backend: “move the orders to the top”, “show the chart for the month”, “the orders instead of the chart”. { prompt, fresh: true } starts over instead (a new page, keys still reused by identity), as the demo’s first row of chips does.

While a fresh composition streams over a page, the preview holds only the parts the model has finished so far. compose(catalog, { preview }) says what shows meanwhile:

previewWhile a fresh composition streams over a page
'merge' (default)The finished parts where the new layout puts them; the page’s other parts stay mounted until the reply, in the container they were in, after the finished ones, in their old order. A part the new layout drops goes when the reply arrives
'replace'Only the finished parts: the others are unmounted until they stream in again
'keep'The page as it is; status stays 'composing' until the reply

A first composition, with no page yet, always shows its preview. An edit’s preview is the whole page with the finished operations applied ('keep' hides that too).

An edit can do any of these, several at once:

  • remove a part (“drop the weather”; “only my tasks” removes the rest);
  • change a setting: a param option (“for the month”, “only the pending orders”);
  • add a part, with its params;
  • move a part to the top or the bottom, above, below or beside another part, or into a container’s slot;
  • swap one part for another (“the orders instead of the chart”);
  • group parts in a new container (“put the dates and amount in a Trip section”), take a part out of one, or ungroup one (“remove the sections but keep their fields”).

What stays the same:

  • Parts the edit doesn’t touch keep their key, so their instance and their state, in their place and row.
  • A setting change keeps the key: the part re-renders with the new props instead of being replaced. (A record param is the exception: another record is another node.)
  • A replacement takes the old part’s place, unless the request says where.
  • The part a place is relative to (“below the chart”) never moves.
  • An edit that changes nothing, or asks for nothing in the catalog, is status: 'unavailable', and the page stays.

The backends edit in their own way:

compose.decisions()compose.llm()
RequestCall 1 asks, per part on the page, “remove it?” and “change its setting?”, per part not on it “add it?”, and which parts move. Call 2, only when something moves or is added, asks where each one goesOne request with the page (one node per line) and the change; the model writes operations: add, remove, move, replace, setParams, placed by top, bottom, above n2, left of n3; with containers in the catalog also wrap (parts into a new container), unwrap, and into n1
Calls1 or 21 (streamed: the preview applies each finished operation)
Exact edits, measuredJev: 66/66 on the tuning set, 43/48 held out, every key kept; nimble: weaker, 18/22 and 8/16qwen3:8b: 9/10 and 18/21, every key kept, no invalid reply, about 1.4 s; container edits 9/10 (2/10 without wrap)
decisionsThe answers of edit and whereops: the operations as applied, with layout keys

The demos above and below edit: in the first, compose a page, then try the second row of chips.

With compose.llm(), an edit can group parts when the catalog has a container other than a row: {"op":"wrap","nodes":["n2","n3"],"part":"section","params":{"title":"Trip"}} puts those parts, in that order, into a new section where the first one was, and the parts keep their keys (the container’s maxUses holds). unwrap puts a container’s parts in its place, into n1 is the end of container n1 (into n1:side names a slot), and above / below a part inside a container stay inside it. compose.llm({ containers: false }) leaves these out.

A reply that runs away is stopped. Asked for something it couldn’t express, qwen3:8b once repeated add dates top, add amount top, … without end. So every list in the reply’s schema has a maxItems (an edit’s operations: one per node on the page plus the catalog’s limits.maxParts), and a streamed reply that repeats an operation exactly more often than it can mean anything (an add more times than the part’s maxUses, so “two notes at the bottom” is fine; any other operation twice), or runs past that, is stopped there: the request is aborted, the operations before it are applied, and decisions.repairs has { kind: 'stopped' } (SYG687). A composition with a list (the page, a container’s slot) of more than twice the parts its schema allows is stopped the same way, and a reply cut at the output-token limit (maxTokens) is read up to where it stopped. A step that takes longer than timeoutMs (300 s by default, both backends) ends as status: 'error', with the page kept.

A small local decision model such as Ollama’s nimble tends to pick the first of two options, whatever they say. compose.decisions({ profile: 'small' }) corrects for it: it asks each “which comes first” question in both orders, and when the answers come out about even, it follows the order in which the request names the parts. On the demo app’s catalog it took nimble from 7/11 to 8/11 flat dashboards, and its side-by-side prompts from 1/4 to 3/4. It costs more questions in the same calls, so leave it off for Jev. It also picks at most 8 parts per composition (maxParts), and narrows a catalog of more than 30 parts by category first (prefilter).

compose.decisions({ url: 'http://localhost:11434/v1/systemone', model: 'nimble', rowMean: 0.5, profile: 'small' })

catalog.render(slice, state) returns the composition as vnodes for the host’s view: slice.preview ?? slice.layout, each part a child of the host keyed by its node key (a render part’s root element too), and containers through their views. Each part gets its params (defaults filled) as props, its lens, and the prop node (its key).

It renders anything with a layout, so a layout you keep elsewhere renders the same way: catalog.render({ layout: state.saved }, state).

<Composed> is the same render as a tag. It names where the composition is in the host’s state instead of taking the slice:

import { Composed } from 'sygnal/ai'
// the same parts, keys and instances as {catalog.render(state.page, state)}
<div className="canvas"><Composed catalog={catalog} from="page" /></div>
  • from is a key (default 'page') or a path, such as ['boards', 0, 'page']. local parts write their state there.
  • scope, frozen and answer are props, as they are options of catalog.render.
  • card={part} renders an ask_user tool part’s card, as askCard() does. With card, from is the chat’s key (default 'assistant').

The parts are still the host’s children, so CHILD.select, lenses and keys work the same. The forms differ in three ways:

catalog.render(slice, state)<Composed catalog from />
ReadsWhatever slice you pass, including one the view computesThe host’s own state at from
A container view or part props() throwsThe composition becomes an empty .compose-error element (SYG406)The host’s onError renders in place of the composition (SYG408)
MisuseA missing slice renders nothingNo catalog, or nothing composed at from: SYG451 in development, renders nothing

Use <Composed> when the composition is a slice of the host’s state, as the compose behavior keeps it, and you want the host’s onError to show a failure. Use catalog.render() for a layout the view computes or keeps outside state. The Planner demo below uses <Composed>. An app that never renders the tag ships none of it.

Composed parts are the host’s children. A part with a lens edits app state, a part’s PARENT value reaches the host through CHILD.select, and context and drivers work as for any child.

In this demo the checklist edits state.tasks (the summary line outside the composition reads it), and the ticket list’s “Add to my tasks” goes to the host, which adds a task the checklist then shows. Tick a task, then “Move my tasks to the top”: the edit moves the checklist out of the row and keeps its node key (tasks), so it is the same instance, with the same ticks. “Only my tasks” removes the tickets and leaves the checklist as it is.

Planner.jsx
import { ABORT } from 'sygnal'
import { compose, Composed } from 'sygnal/ai'
import { catalog, TASKS, TicketList } from './catalog.jsx'
const PROMPTS = ['My tasks beside the urgent tickets', 'Move my tasks to the top', 'Only my tasks']
function Planner({ state }) {
const done = state.tasks.filter((t) => t.done).length
return (
<div className="composer">
<p className="summary">{done} of {state.tasks.length} tasks done</p>
<div className="chips">{PROMPTS.map((p) => <button type="button" className="chip" data={{ prompt: p }}>{p}</button>)}</div>
<div className="canvas"><Composed catalog={catalog} from="page" /></div>
</div>
)
}
Planner.initialState = { tasks: TASKS }
Planner.uses = { page: compose(catalog, { backend: compose.decisions({ model: 'jev-latest' }) }) }
Planner.intent = ({ DOM, CHILD }) => ({
EXAMPLE: DOM.click('.chip').data('prompt'),
TAKE: CHILD.select(TicketList),
})
Planner.model = {
BOOTSTRAP: { EFFECT: (state, data, next) => next('page.COMPOSE', PROMPTS[0]) },
// the first prompt starts over; the others edit the page
EXAMPLE: { EFFECT: (state, prompt, next) => next('page.COMPOSE', prompt === PROMPTS[0] ? { prompt, fresh: true } : prompt) },
TAKE: (state, ticket) => (state.tasks.some((t) => t.text === ticket.title)
? ABORT
: { ...state, tasks: [...state.tasks, { id: state.tasks.length + 1, text: ticket.title, done: false }] }),
}
export default Planner

Persisting a page. The layout is plain state, so persist() keeps it across reloads with no model call: pick the slice and the state the parts use.

import { persist } from 'sygnal'
Planner.persist = persist({ key: 'planner', pick: ['page', 'tasks'] })
compose.decisions({ model: 'jev-latest' }) // POST /api/decide, your server's route
compose.decisions({ url: 'http://localhost:11434/v1/systemone', model: 'nimble', rowMean: 0.5 }) // a local Ollama

It sends decide() requests on the HTTP sink (the fetch driver): one when nothing fits or a single part is asked for, otherwise two. The model writes no text; code reads the probabilities, so the layout follows the answers it was most sure of. Options:

  • url: the decision endpoint, '/api/decide' by default;
  • model: required (SYG681 without one);
  • rowMean: how sure “side by side” answers must be to make a row (0.25, measured on Jev; 0.5 suits nimble);
  • prefilter: one more call first, to narrow a large catalog by the parts’ category (about half the tokens, the same accuracy on Jev). 'auto' by default: on when the catalog has categories and more than 60 parts (30 with profile: 'small'); true or false to choose;
  • maxParts: the most parts one composition picks (the catalog’s limits.maxParts, 12; 8 with profile: 'small');
  • maxOptions: the most options one question may have (255; 25 when url looks like Ollama): a larger choice is split into several questions;
  • maxQuestions, maxPromptTokens, split: passed to every decide() request (Large question sets). A step with more than 64 questions, such as profile: 'small'’s layout step for 6 or more elements, goes as parallel requests read as one;
  • profile: 'small': for a small local model such as nimble (profile: 'small');
  • timeoutMs: the most one step may take (300000; 0 for no limit): then status is 'error' and the page stays.
compose.llm({ model: 'gpt-5-mini' }) // the LLM sink: one structured-output request, streamed

It sends one chat request on the LLM sink (makeChatDriver(), any transport): a system prompt with the catalog as text and its guidance, and a JSON Schema of the catalog as the structured output. The model writes a short plan (asked_for: what the request asks for), then the layout tree. Parts are closed objects with enum params, so a schema the provider enforces keeps it to the catalog. While it streams, the complete parts so far show as the preview. The reply goes through a repair step (unknown parts dropped, duplicates removed, bad params set to their default); a reply still invalid after it is status: 'error' (SYG683), never a layout.

Options: model, sink ('LLM'), stream (true), plan (true; false when the catalog has examples), instructions (more rules, or a function of the system prompt), examples, timeoutMs (300000: a step that takes longer is status: 'error', the page kept; 0 for no limit), maxTokens (no default: the most tokens the model may write, sent as the transport’s max_tokens / max_output_tokens), and transport options such as body: { temperature: 0 }, sent on the request as is.

This demo is the first one with compose.llm(): its stand-in model streams the layout JSON from the demo server’s 'POST /v1/responses' route, so the page fills in part by part. The second row of chips edits the page: the stand-in streams operations, and the preview applies each one as it completes. Under the page, the model’s plan, or the operations of an edit as applied (with the layout’s keys).

LlmDashboard.jsx
import { compose } from 'sygnal/ai'
import { catalog, TASKS } from './catalog.jsx'
const PROMPTS = ['Signups and revenue side by side, then the monthly revenue chart and the paid orders', 'The weather, then urgent tickets']
const FOLLOW_UPS = ['Move the paid orders to the top', 'Show the chart for the quarter', 'Add the weather beside the signups', 'Remove the revenue']
const opText = (o) => [o.op, o.node, o.part !== o.node && o.part, o.params && JSON.stringify(o.params), o.where].filter(Boolean).join(' ')
function LlmDashboard({ state }) {
const page = state.page
const busy = page.status === 'composing' || page.status === 'preview'
return (
<div className="composer">
<div className="chips">{PROMPTS.map((p) => <button type="button" className="chip" data={{ prompt: p }} disabled={busy}>{p}</button>)}</div>
<div className="chips">{FOLLOW_UPS.map((p) => <button type="button" className="chip follow-up" data={{ prompt: p }} disabled={busy || !page.layout}>{p}</button>)}</div>
<p className="status" aria-live="polite">{page.status === 'preview' ? 'Writing the layout…' : page.status}</p>
<div className={page.preview ? 'canvas preview' : 'canvas'}>{catalog.render(page, state)}</div>
{page.decisions?.asked_for && <p className="explain">Plan: {page.decisions.asked_for.join(' · ')}</p>}
{page.decisions?.ops && <p className="explain">Operations: {page.decisions.ops.map(opText).join(' · ')}</p>}
</div>
)
}
LlmDashboard.initialState = { tasks: TASKS }
LlmDashboard.uses = { page: compose(catalog, { backend: compose.llm() }) }
LlmDashboard.intent = ({ DOM }) => ({
EXAMPLE: DOM.click('.chip:not(.follow-up)').data('prompt'),
FOLLOW_UP: DOM.click('.follow-up').data('prompt'),
})
LlmDashboard.model = {
BOOTSTRAP: { EFFECT: (state, data, next) => next('page.COMPOSE', PROMPTS[0]) },
EXAMPLE: { EFFECT: (state, prompt, next) => next('page.COMPOSE', { prompt, fresh: true }) },
FOLLOW_UP: { EFFECT: (state, prompt, next) => next('page.COMPOSE', prompt) },
}
export default LlmDashboard

Measured on the research catalogs (exact layouts; the case sets differ by column):

Jev (TypeSafe)nimble (Ollama)qwen3:8b + schema (Ollama)
Backendcompose.decisions()compose.decisions()compose.llm()
Flat dashboard (11 prompts)9/119/1111/11
Rows, sections, tabs, repeats (5 catalogs)191/21038/6815/15
Enum params57/6019/2020/20
Parts from records57/6018/20—
Free-text paramskeeps the defaultkeeps the defaultyes
Time per composition~0.35 s, 2 calls~3 s~3.4 s, 1 call
  • Jev is the production default: fast, cheap, and strong on structure, params and records.
  • nimble is fine on your machine for small catalogs (about 10 parts or fewer), and weak on nesting.
  • An LLM with a schema the provider enforces is the most accurate local option and the only one that fills free text, about ten times slower than Jev.

Switching is one line: the catalog, the host and the tests stay the same. A backend sends on one sink, so a page that switches between kinds at run time uses one host per kind (the examples/ai-compose app shows both in a Switchable).

compose.decisions() posts to /api/decide by default, so the server route from AI Decisions serves it unchanged: it adds the key, fixes the model, requires a session and limits the size of the request. For Jev, point it at TypeSafe’s endpoint:

// server: POST /api/decide
import { currentUser } from './auth.js' // your session check
const MODELS = new Set(['jev-latest'])
const DECIDE_URL = 'https://api.typesafe.ai/v1/systemone'
export async function POST(req) {
if (!(await currentUser(req))) return new Response('Sign in first', { status: 401 })
const body = await req.text()
const { model } = JSON.parse(body)
if (!MODELS.has(model) || body.length > 512_000) return new Response('Bad request', { status: 400 })
const res = await fetch(DECIDE_URL, {
method: 'POST',
headers: { 'content-type': 'application/json', authorization: `Bearer ${process.env.TYPESAFE_API_KEY}` },
body,
})
return new Response(res.body, { status: res.status, headers: { 'content-type': 'application/json' } })
}

A composition’s requests are larger than a single decision (every part’s description is in its questions), so allow more than a triage route would. compose.llm() goes through your chat driver’s transport, which ships behind your own route the same way.

A chat assistant can arrange the page too. compose.action('page') is the agent action for the behavior’s page.COMPOSE, and compose.summary(slice) is what the assistant reads of the page:

import { chat, compose } from 'sygnal/ai'
import { catalog } from './catalog.jsx'
function Workspace({ state }) {
const a = state.assistant
return (
<main>
<div className="canvas">{catalog.render(state.page, state)}</div>
<form className="ask">
<input className="prompt" aria-label="Ask the assistant" value={a.prompt} />
<button type="submit">Send</button>
</form>
</main>
)
}
Workspace.uses = {
page: compose(catalog, { backend: compose.decisions({ model: 'jev-latest' }) }),
assistant: chat({ form: '.ask', prompt: '.prompt', instructions: 'You arrange the workspace with the tools.' }),
}
Workspace.agent = {
name: 'app',
description: 'The workspace page',
read: (state) => ({ page: compose.summary(state.page) }),
actions: { ...compose.action('page') },
}
  • The model gets the tool app_page_compose({ prompt, fresh? }): prompt is what the page should show, or how to change it, in the user’s words. Like any page.COMPOSE, it edits the current page unless fresh is true.
  • The tool’s result waits for the composition (until), so its state already shows the new page. compose.summary(slice) is { status, page, error? }, with page the layout as a tree: the assistant can tell the user what it placed, or that nothing fit.
  • compose.action(key, { description, timeout }) takes another slice key, its own tool description, and a timeout (60 s by default; past it the result says the composition is still pending).
  • With compose.llm(), the composition’s request goes on the same LLM sink as the chat’s, in its own lane with its own reply actions, so neither aborts the other.

The chat behavior and the call rules are in Agents.

Sometimes no prepared part shows what the user asks for. A generated part lets the model write that one part’s component as code, which runs in sygnal/sandbox. The rule “the model only chooses” is relaxed inside the box only:

  • the code reads only the data keys you declare in data, computed from your state by your from;
  • it can only send the event types you declare in emits, and the page checks each one against its Standard Schema before your intent sees it;
  • it runs in QuickJS in a Worker, with no document, window, fetch, storage or imports other than 'sygnal'.

generatedRuntime() from sygnal/sandbox owns the code: it compiles it, checks it and runs it. compose.generated(runtime, { data, emits }) from sygnal/ai turns that into a catalog part, the prompt rules and a repair loop:

Dashboard.jsx
import { compose, defineCatalog } from 'sygnal/ai'
import { generatedRuntime, sucraseCompiler } from 'sygnal/sandbox'
import kernel from 'sygnal/sandbox/kernel?raw'
import { z } from 'zod'
import { Revenue } from './Revenue.jsx'
const runtime = generatedRuntime({ kernel, compile: sucraseCompiler(() => import('sucrase')) })
const gen = compose.generated(runtime, {
data: {
orders: { description: 'the recent orders', shape: '[{ id: number, customer: number, total: number, status: "paid" | "pending" }]', from: (state) => state.orders },
},
emits: {
OPEN_CUSTOMER: { description: 'the user picked a customer', schema: z.object({ id: z.number().int() }) },
},
})
const catalog = defineCatalog({
parts: {
revenue: { component: Revenue, description: 'Revenue (KPI card: the total this month)' },
custom: gen.part,
},
})
export function Dashboard({ state }) {
return <main>{catalog.render(state.page, state)}</main>
}
Dashboard.initialState = { orders: [], openCustomer: null }
Dashboard.uses = {
page: compose(catalog, { backend: compose.llm({ instructions: gen.instructions }) }),
fix: gen.repair(),
}
Dashboard.intent = ({ CHILD }) => ({
OPEN_CUSTOMER: gen.events(CHILD, 'OPEN_CUSTOMER'),
})
Dashboard.model = {
OPEN_CUSTOMER: (state, { id }) => ({ ...state, openCustomer: id }),
}
  • Opt in per catalog. gen.part is in a catalog only when you put it there. It works with compose.llm() only, because a decision model can’t write code.
  • The model writes one node per generated part in the same structured reply as the rest of the page: { part: 'custom', params: { title, reads, code } }. code is a format: 'code' text param and comes last in the schema, so it streams last. gen.instructions is the rules the model needs: the component shape, what isn’t there, each data key’s shape and each event’s JSON Schema (from zod 4’s Standard JSON Schema). The prompt holds shapes, never your data.
  • Partial code never mounts. While the reply streams, the preview shows a node only once its JSON object closes, so a part’s box boots with its final code. It keeps its node key from the preview to the final layout, so it mounts once.
  • Events are your actions. gen.events(CHILD, type) is a stream of { node, ...data }, where data is the schema’s output (a zod object strips the keys it doesn’t declare). The model never names one of your actions. Treat emits as user input: a part written under prompt injection can send a valid event the user didn’t mean, so confirm anything destructive.
  • reads picks keys from data. A name you didn’t declare reads nothing. The box gets the values as JSON on PROPS, and again only when their JSON changes.
optiondefault
isolation'worker'QuickJS in a Worker with a watchdog. 'thread' runs on the page’s thread: synchronous events, but a loop over slow builtins can overrun the deadline
maxUses3generated parts per page. The model’s output time dominates: about 4–9 s per part at 100 tokens/s
maxCode4000characters. The schema caps code at maxCode + 1, so code compose had to cut fails as “too long” instead of mounting truncated
maxAttempts2repair turns per part (gen.repair({ maxAttempts }))
checktruethe check before mount
capabilitiesnoneno fetch, no navigation. Pass capabilities: { fetch: { allow: [...] } } to grant one
limitsGENERATED_LIMITSheap 16 MB in a 48 MB instance, boot 500 ms, 50 ms per event, watchdog 1 s

A part that fails reports it to gen.repair(), which sends the model one small request: the failing code and one line that names the error, never the page or the other parts. The reply’s code is an overlay keyed by the failing code’s hash. The layout keeps the model’s original code, so a layout that arrives after the fix, a follow-up edit, or a restored page all get the fix. While it waits, the part shows “Fixing this part…”. A part still failing after maxAttempts repairs shows fallback (“This part couldn’t be built.”) in its own place, and the rest of the page is unaffected.

reasonwhat happenedwhat the model reads
compilea syntax error, code over maxCode, a JSX event handler, or your checkcompile: Unexpected token (12:55), line 7: JSX event handlers (onClick) don't run …
checkan intent action with no model entry (checked in the box at boot)check: SYG101: intent action 'PICK' has no model entry …
errorthe module threw while loading, such as an importerror: sandbox: 'date-fns' can't be imported here
runtimethe view or a reducer threwruntime: view threw (SYG406): ReferenceError: 'document' is not defined
emptyit booted and drew nothingempty: the component rendered nothing
timeout, memory, cpu, crashthe sandbox stopped ittimeout: the worker didn't answer in 1000 ms; terminated
rejectedit sent an undeclared type or invalid data (the part keeps working)the app dropped an event OPEN_CUSTOMER: invalid (id: …)

t.state.fix (the repair slice) holds the overlay (patches), each chain’s status (repairing, patched, fixed, gave-up) and a log. It is plain JSON: persist it with the page if a reload shouldn’t repair again.

compile turns the model’s module into the CommonJS the kernel runs. Sygnal doesn’t ship a compiler: sucraseCompiler(load) wraps sucrase, which your app installs and imports itself. Pass a dynamic import, () => import('sucrase'), and the compiler loads with the first generated part, outside your main chunk. Sucrase is small and fast, it only parses and prints (trusted code reading untrusted text), and its errors carry line:column for the repair request. compile can be any function, sync or async, such as esbuild-wasm or the TypeScript compiler.

The check before mount has two parts, and neither loads anything on the page:

  • On the page, lintGenerated(code) finds JSX event handlers (onClick={…}). A Sygnal view drops them silently, and they are the most common React habit.
  • In the box, the kernel checks the wiring when the component boots. An intent action with no model entry (SYG101) never does anything and never throws, so a loop that only listens for errors would never repair it. The kernel compares the actions intent really returns with the model’s keys, so it needs no parser.

sygnal-check’s full rules are an opt-in for where Node runs, such as a server that composes, or your tests: pass check: (code) => messages to generatedRuntime, and each message fails the part with reason compile. sygnal-check isn’t loaded in the browser.

A render_component card is the one-part case: a catalog with one part, gen.card(type), used as the chat’s direct ask catalog. The model’s ask_user input is the card with its code, and the code’s type event, validated, is the call’s output.

Assistant.jsx
import { chat, compose, defineCatalog, askCard } from 'sygnal/ai'
import { generatedRuntime, sucraseCompiler } from 'sygnal/sandbox'
import kernel from 'sygnal/sandbox/kernel?raw'
import { z } from 'zod'
const gen = compose.generated(generatedRuntime({ kernel, compile: sucraseCompiler(() => import('sucrase')) }), {
data: { plans: { description: 'the pricing plans', shape: '[{ id: "free" | "team", name: string, price: number }]', from: (state) => state.plans } },
emits: { PICK_PLAN: { description: 'the plan the user picked (the answer)', schema: z.object({ id: z.enum(['free', 'team']) }) } },
})
const cards = defineCatalog({ parts: { card: gen.card('PICK_PLAN') }, rows: false })
export function Assistant({ state }) {
return (
<div className="chat">
{state.assistant.messages.flatMap((m) => m.parts.map((p) => (p.type === 'tool-ask_user' ? askCard(cards, state, p) : null)))}
</div>
)
}
Assistant.initialState = { plans: [{ id: 'free', name: 'Free', price: 0 }, { id: 'team', name: 'Team', price: 12 }] }
Assistant.uses = {
assistant: chat({ ask: { catalog: cards, direct: true, instructions: gen.instructions } }),
fix: gen.repair(),
}

The answer is { part: 'card', answer: { id: 'team' } }, as for any card. A card whose code fails goes through the same repair loop.

The model is scripted, as for any composition: answer the compose request with a reply that holds the code, and answer a repair request on its own key.

Dashboard.test.js
const t = renderComponent(Dashboard, { dom: 'real' })
t.simulateAction('page.COMPOSE', 'refunds by customer')
await t.respond('LLM', JSON.stringify({ asked_for: ['refunds'], children: [{ part: 'custom', params: { title: 'Refunds', reads: ['orders'], code } }] }), 'page.REPLY')
const fix = t.requests('LLM').find((r) => String(r.key).startsWith('fix:')) // a failing part's repair request
await t.respond('LLM', JSON.stringify({ code: fixedCode }), 'fix.REPLY')

The box needs the real DOM (dom: 'real'). In Node, pass worker a worker_threads Worker of sygnal/sandbox/worker, or use isolation: 'thread'.

Tests never call a model. composeWith(t, catalog, tree) answers the pending composition so that it becomes tree, whichever backend is pending: it builds each step’s reply with the backend’s own fake() (the decide() answers, or the LLM’s JSON) and sends it as the model would. So one test runs against both backends:

import { describe, it, expect } from 'vitest'
import { renderComponent } from 'sygnal'
import { compose, composeWith } from 'sygnal/ai'
import { catalog } from './catalog.jsx'
import { makeDashboard } from './Dashboard.jsx'
describe.each([
['decisions', compose.decisions({ model: 'jev-latest' })],
['llm', compose.llm()],
])('compose.%s()', (name, backend) => {
it('puts revenue and signups in a row, then the chart for the quarter', async () => {
const t = renderComponent(makeDashboard(backend))
t.simulateAction('page.COMPOSE', 'Revenue and signups side by side, then the revenue chart for the quarter')
await composeWith(t, catalog, [
{ part: 'row', children: [{ part: 'revenue' }, { part: 'signups' }] },
{ part: 'revenueChart', params: { range: 'quarter' } },
])
await t.waitForState((s) => s.page.status === 'done')
expect(t.query('.compose-row')).toBeTruthy()
expect(t.html()).toContain('Revenue, last quarter')
t.dispose()
})
it('keeps the page when nothing fits', async () => {
const t = renderComponent(makeDashboard(backend))
t.simulateAction('page.SET_LAYOUT', { root: 'page', nodes: { page: { part: 'page', slots: { default: ['weather'] } }, weather: { part: 'weather' } } })
t.simulateAction('page.COMPOSE', 'The stock price of Apple')
await composeWith(t, catalog, [])
await t.waitForState((s) => s.page.status === 'unavailable')
expect(t.html()).toContain('27°C')
t.dispose()
})
})

Here makeDashboard(backend) returns the first demo’s component with that backend in its uses (and without its BOOTSTRAP entry: the demo composes on load only to have something to show).

  • composeWith throws when the backend can’t reach tree (a record the prompt doesn’t name, for a decision model), so a test can’t pass by accident.
  • { stream: n } streams an LLM reply in n chunks, through the preview.
  • To test the preview or a failure, answer one step yourself: t.respond('HTTP', backend.fake({ catalog, state: t.state, pending: t.state.page.pending, target }), 'page.REPLY'), or t.fail(backend.sink, 500, 'page.FAILED').
  • A layout is plain JSON: t.state.page.layout.nodes holds the keys and params to assert on.

The same catalogs build the cards an assistant asks the user with: chat({ ask: { catalog } }) gives the model an ask_user tool, the app composes a card from prepared parts, and the user’s click is the tool’s result. Cards in a Chat documents it, with a demo.