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) throughdecide(): 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.
The catalog
Section titled “The catalog”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:
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 sinkexport 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 tasksexport 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; }| Field | What it does |
|---|---|
component | The 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.) |
description | All a model sees of the part: “Noun (what it shows)” (below) |
props | Fixed props, or (params, state) => props |
params | The inputs a model gives, passed as props (below) |
state | How 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 |
local | State kept in the composition instead (local: { text: '' }), per placed part |
in | Where it may go: 'page' (the default), a container, or 'container:slot' |
group | Alternatives: parts in one group are offered as one choice, and the first one in a layout wins |
maxUses | How often one identity may appear (default 1) |
required, pin, companions | Always on the page (never offered to the model); pinned to 'start' or 'end'; parts added right after it |
Params
Section titled “Params”Params are the only inputs a model gives, and each kind says what a model may write:
| Param | Both backends? | Example |
|---|---|---|
{ options, default } | yes: a decision model picks one option, with “not stated” meaning the default; an LLM fills an enum | range: { 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 covers | limit: { 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-only | title: { type: 'text', maxLength: 40, required: true } |
{ from: (state) => records } | yes: one node per record the request names, found by name and aliases | below |
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)} />.
Containers
Section titled “Containers”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 }:slotsmaps each slot to its rendered parts,childrenlists them in order with their slot. control(name, value)returns data attributes to spread on an element: a click on it setsui[name] = valuefor this container (the behavior’sCONTROLaction), 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 theirinallows (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 and limits
Section titled “Guidance and limits”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.
Writing descriptions a model picks well
Section titled “Writing descriptions a model picks well”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
nimblewith 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
binsname the vague words they cover (“a few (top 3)”).
Composing a page
Section titled “Composing a page”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.
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/iconst 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 namefunction 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, … keysfunction 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 partsfunction 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.
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 DashboardA 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.
The slice
Section titled “The slice”state.page (the key you gave in uses):
| Field | |
|---|---|
prompt | The request |
status | idle, composing (a request is out), preview (a partial layout shows), done, unavailable (nothing in the catalog fits), error |
layout | The last finished layout: plain JSON, { root: 'page', nodes }. Kept on an error and when nothing fits |
preview | The layout being built; catalog.render shows it instead while it is set |
queued | With busy: 'queue': the composition waiting for the one in flight, { prompt, fresh? }, else null |
decisions | What the backend explains: a decision model’s answers per step, or an LLM’s plan (asked_for) and what its repair step fixed |
error | Why the last composition failed |
ui, local | Container 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'witherrorset. 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).
Actions
Section titled “Actions”The behavior’s actions are the host’s, under the slice’s key:
| Action | Data |
|---|---|
page.COMPOSE | A 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_LAYOUT | A layout to show without a model: restore, undo, your own edits. null clears |
page.REMOVE | A node key: that part and anything inside it go |
page.CONTROL | { key, name, value }: a container control (what control() clicks send) |
page.DONE | Sent when a composition finishes, with the layout. A host entry 'page.DONE' runs after the behavior’s |
A page that recomposes itself
Section titled “A page that recomposes itself”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.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 }) },}busy | A 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.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.
Follow-up edits
Section titled “Follow-up edits”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:
preview | While 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() | |
|---|---|---|
| Request | Call 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 goes | One 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 |
| Calls | 1 or 2 | 1 (streamed: the preview applies each finished operation) |
| Exact edits, measured | Jev: 66/66 on the tuning set, 43/48 held out, every key kept; nimble: weaker, 18/22 and 8/16 | qwen3:8b: 9/10 and 18/21, every key kept, no invalid reply, about 1.4 s; container edits 9/10 (2/10 without wrap) |
decisions | The answers of edit and where | ops: 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.
profile: 'small'
Section titled “profile: 'small'”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
Section titled “catalog.render”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).
Rendering with <Composed>
Section titled “Rendering with <Composed>”<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>fromis a key (default'page') or a path, such as['boards', 0, 'page'].localparts write their state there.scope,frozenandanswerare props, as they are options ofcatalog.render.card={part}renders anask_usertool part’s card, asaskCard()does. Withcard,fromis 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 /> | |
|---|---|---|
| Reads | Whatever slice you pass, including one the view computes | The host’s own state at from |
A container view or part props() throws | The composition becomes an empty .compose-error element (SYG406) | The host’s onError renders in place of the composition (SYG408) |
| Misuse | A missing slice renders nothing | No 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.
Parts are real components
Section titled “Parts are real components”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.
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 PlannerPersisting 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'] })Backends
Section titled “Backends”compose.decisions()
Section titled “compose.decisions()”compose.decisions({ model: 'jev-latest' }) // POST /api/decide, your server's routecompose.decisions({ url: 'http://localhost:11434/v1/systemone', model: 'nimble', rowMean: 0.5 }) // a local OllamaIt 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 suitsnimble);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 withprofile: 'small');trueorfalseto choose;maxParts: the most parts one composition picks (the catalog’slimits.maxParts, 12; 8 withprofile: 'small');maxOptions: the most options one question may have (255; 25 whenurllooks like Ollama): a larger choice is split into several questions;maxQuestions,maxPromptTokens,split: passed to everydecide()request (Large question sets). A step with more than 64 questions, such asprofile: 'small'’s layout step for 6 or more elements, goes as parallel requests read as one;profile: 'small': for a small local model such asnimble(profile: 'small');timeoutMs: the most one step may take (300000;0for no limit): thenstatusis'error'and the page stays.
compose.llm()
Section titled “compose.llm()”compose.llm({ model: 'gpt-5-mini' }) // the LLM sink: one structured-output request, streamedIt 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).
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 LlmDashboardChoosing one
Section titled “Choosing one”Measured on the research catalogs (exact layouts; the case sets differ by column):
| Jev (TypeSafe) | nimble (Ollama) | qwen3:8b + schema (Ollama) | |
|---|---|---|---|
| Backend | compose.decisions() | compose.decisions() | compose.llm() |
| Flat dashboard (11 prompts) | 9/11 | 9/11 | 11/11 |
| Rows, sections, tabs, repeats (5 catalogs) | 191/210 | 38/68 | 15/15 |
| Enum params | 57/60 | 19/20 | 20/20 |
| Parts from records | 57/60 | 18/20 | — |
| Free-text params | keeps the default | keeps the default | yes |
| 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.
nimbleis 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).
Keys stay on the server
Section titled “Keys stay on the server”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/decideimport { 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.
Compose from an agent
Section titled “Compose from an agent”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? }):promptis what the page should show, or how to change it, in the user’s words. Like anypage.COMPOSE, it edits the current page unlessfreshis true. - The tool’s result waits for the composition (
until), so itsstatealready shows the new page.compose.summary(slice)is{ status, page, error? }, withpagethe 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 sameLLMsink 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.
Generated parts (experimental)
Section titled “Generated parts (experimental)”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 yourfrom; - 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:
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.partis in a catalog only when you put it there. It works withcompose.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 } }.codeis aformat: 'code'text param and comes last in the schema, so it streams last.gen.instructionsis 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 }, wheredatais the schema’s output (a zod object strips the keys it doesn’t declare). The model never names one of your actions. Treatemitsas user input: a part written under prompt injection can send a valid event the user didn’t mean, so confirm anything destructive. readspicks keys fromdata. A name you didn’t declare reads nothing. The box gets the values as JSON onPROPS, and again only when their JSON changes.
Defaults
Section titled “Defaults”| option | default | |
|---|---|---|
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 |
maxUses | 3 | generated parts per page. The model’s output time dominates: about 4–9 s per part at 100 tokens/s |
maxCode | 4000 | characters. The schema caps code at maxCode + 1, so code compose had to cut fails as “too long” instead of mounting truncated |
maxAttempts | 2 | repair turns per part (gen.repair({ maxAttempts })) |
check | true | the check before mount |
capabilities | none | no fetch, no navigation. Pass capabilities: { fetch: { allow: [...] } } to grant one |
| limits | GENERATED_LIMITS | heap 16 MB in a 48 MB instance, boot 500 ms, 50 ms per event, watchdog 1 s |
Failures and repair
Section titled “Failures and repair”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.
| reason | what happened | what the model reads |
|---|---|---|
compile | a syntax error, code over maxCode, a JSX event handler, or your check | compile: Unexpected token (12:55), line 7: JSX event handlers (onClick) don't run … |
check | an intent action with no model entry (checked in the box at boot) | check: SYG101: intent action 'PICK' has no model entry … |
error | the module threw while loading, such as an import | error: sandbox: 'date-fns' can't be imported here |
runtime | the view or a reducer threw | runtime: view threw (SYG406): ReferenceError: 'document' is not defined |
empty | it booted and drew nothing | empty: the component rendered nothing |
timeout, memory, cpu, crash | the sandbox stopped it | timeout: the worker didn't answer in 1000 ms; terminated |
| rejected | it 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.
Compiling and checking in the browser
Section titled “Compiling and checking in the browser”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 generated card in a chat
Section titled “A generated card in a chat”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.
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.
Testing generated parts
Section titled “Testing generated parts”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.
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 requestawait 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'.
Testing
Section titled “Testing”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).
composeWiththrows when the backend can’t reachtree(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 innchunks, 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'), ort.fail(backend.sink, 500, 'page.FAILED'). - A layout is plain JSON:
t.state.page.layout.nodesholds the keys and params to assert on.
Cards in a chat
Section titled “Cards in a chat”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.
Related
Section titled “Related”- AI Decisions:
decide(), the questions, and the server route that keeps the key - AI Chat: the chat driver, transports and structured output
- Agents: the
chatbehavior and theagentstatic - Cards in a Chat:
chat({ ask }), client tools and composed cards - Parent-Child Communication:
PARENTandCHILD.select - Persistence:
persist()