sygnal 7.0.0 → 7.2.0-preview.0

package/dist/agent-ui.esm.js

@@ -0,0 +1,582 @@
+import { run } from 'sygnal';
+import { isCheckable, isTextField, labelTarget, computeStyle, isInteractive, nodeId, optionValue, HostDocument, makeHostDriver, activate, chooseOption, pressKey, typeText, fill, doubleClick } from 'sygnal/host';
+
+const BLOCK = /^(root|div|section|header|footer|main|nav|article|aside|ul|ol|li|form|fieldset|h[1-6]|p|pre|table|tr|td|th|details|summary|dialog|blockquote|figure|figcaption|dl|dt|dd|hr|br|menu|search|label)$/;
+const NATIVE = /^(input|textarea|select|button|a|summary|option)$/;
+const LANDMARKS = { nav: 'navigation', main: 'main', aside: 'complementary', search: 'search', dialog: 'dialog' };
+function roleOf(el) {
+    const r = el.getAttribute('role');
+    if (r)
+        return r.split(/\s+/)[0];
+    const t = el.localName;
+    // a target's own field tags (registerFieldTags)
+    if (t != 'input' && t != 'textarea' && isCheckable(el))
+        return 'checkbox';
+    if (t != 'input' && t != 'textarea' && isTextField(el))
+        return 'textbox';
+    if (t == 'a')
+        return el.hasAttribute('href') ? 'link' : null;
+    if (t == 'button' || t == 'summary')
+        return 'button';
+    if (t == 'input') {
+        const ty = el.type || 'text';
+        if (/^(button|submit|reset|image)$/.test(ty))
+            return 'button';
+        if (ty == 'checkbox' || ty == 'radio')
+            return ty;
+        if (ty == 'range')
+            return 'slider';
+        if (ty == 'number')
+            return 'spinbutton';
+        if (ty == 'search')
+            return 'searchbox';
+        if (ty == 'hidden' || ty == 'file')
+            return null;
+        return 'textbox';
+    }
+    if (t == 'textarea')
+        return 'textbox';
+    if (t == 'select')
+        return el.multiple ? 'listbox' : 'combobox';
+    if (t == 'option')
+        return 'option';
+    if (/^h[1-6]$/.test(t))
+        return 'heading';
+    if (t == 'ul' || t == 'ol' || t == 'menu')
+        return 'list';
+    if (t == 'li')
+        return 'listitem';
+    if (t == 'img')
+        return el.getAttribute('alt') === '' ? null : 'img';
+    if (t == 'table')
+        return 'table';
+    if (t == 'tr')
+        return 'row';
+    if (t == 'td')
+        return 'cell';
+    if (t == 'th')
+        return 'columnheader';
+    if (t == 'progress')
+        return 'progressbar';
+    if (t == 'fieldset' || t == 'details')
+        return 'group';
+    if (t == 'form')
+        return el.getAttribute('aria-label') || el.getAttribute('name') ? 'form' : null;
+    if (t == 'section')
+        return el.getAttribute('aria-label') ? 'region' : null;
+    return LANDMARKS[t] || null;
+}
+const squash = (s) => s.replace(/\s+/g, ' ').trim();
+/** visible text, without hidden subtrees */
+function textOf(n, rules, skip) {
+    if (n.nodeType === 3)
+        return n.data;
+    const el = n;
+    if (el === skip || computeStyle(el, rules).display == 'none' || el.getAttribute('aria-hidden') == 'true')
+        return '';
+    if (el.localName == 'input' || el.localName == 'select' || el.localName == 'textarea')
+        return '';
+    return el.childNodes.map(c => textOf(c, rules, skip)).join(BLOCK.test(el.localName) ? ' ' : '');
+}
+/** the accessible name: aria-label, aria-labelledby, a label, contents, alt / value / placeholder / title */
+function nameOf(el, rules = []) {
+    const a = el.getAttribute('aria-label');
+    if (a)
+        return squash(a);
+    const by = el.getAttribute('aria-labelledby');
+    if (by)
+        return squash(by.split(/\s+/).map(id => { const t = el.ownerDocument.getElementById(id); return t ? textOf(t, rules) : ''; }).join(' '));
+    const t = el.localName;
+    if (t == 'input' || t == 'textarea' || t == 'select') {
+        const id = el.id;
+        const lab = (id && el.ownerDocument.querySelector(`label[for="${id}"]`)) || el.closest('label');
+        // (a label names its control even when it's visually hidden, as the browser's accessible name)
+        const l = lab ? squash(textOf(lab, [], el)) : '';
+        if (l)
+            return l;
+        if (t == 'input' && /^(button|submit|reset)$/.test(el.type))
+            return el.getAttribute('value') || (el.type == 'reset' ? 'Reset' : 'Submit');
+        return squash(el.placeholder || el.title || '');
+    }
+    if (t == 'img')
+        return squash(el.getAttribute('alt') || el.title || '');
+    return squash(textOf(el, rules)) || squash(el.title || '');
+}
+const CONTENT_NAMED = /^(button|link|heading|checkbox|radio|switch|textbox|searchbox|combobox|listbox|slider|spinbutton|option|img|columnheader|cell|tab|menuitem|treeitem|tooltip|progressbar)$/;
+const labelOnly = (el, rules) => {
+    const a = el.getAttribute('aria-label');
+    if (a)
+        return squash(a);
+    const by = el.getAttribute('aria-labelledby');
+    if (by)
+        return squash(by.split(/\s+/).map(id => { const t = el.ownerDocument.getElementById(id); return t ? textOf(t, rules) : ''; }).join(' '));
+    return squash(el.title || '');
+};
+/** the host tree as agent nodes (generic containers flattened, their text merged into text nodes) */
+function snapshotTree(doc, options = {}) {
+    const rules = options.rules || [];
+    // labels that name a control are read as that control's name, not again as text
+    const naming = new Set();
+    for (const l of doc.body.querySelectorAll('label')) {
+        const t = labelTarget(l);
+        if (t && t.localName != 'button')
+            naming.add(l);
+    }
+    const kids = (el) => {
+        const out = [];
+        let text = '';
+        const flushText = () => { const t = squash(text); if (t)
+            out.push({ role: 'text', text: t }); text = ''; };
+        // a flex container's children are separate items (a column's lines, a row's gap): their text doesn't run together
+        const visit = (n, inFlex = false) => {
+            if (n.nodeType === 3) {
+                text += n.data;
+                return;
+            }
+            const c = n;
+            const st = computeStyle(c, rules);
+            if (st.display == 'none' || c.getAttribute('aria-hidden') == 'true')
+                return;
+            const node = nodeFor(c);
+            if (node) {
+                flushText();
+                out.push(node);
+                return;
+            }
+            if (naming.has(c)) {
+                // the label's own text names its control; any other content stays
+                for (const x of c.childNodes)
+                    if (x.nodeType === 1)
+                        visit(x);
+                return;
+            }
+            const block = inFlex || BLOCK.test(c.localName);
+            const flex = /flex$/.test(st.display || '');
+            if (block)
+                flushText();
+            for (const x of c.childNodes)
+                visit(x, flex);
+            if (block)
+                flushText();
+        };
+        for (const c of el.childNodes)
+            visit(c, /flex$/.test(computeStyle(el, rules).display || ''));
+        flushText();
+        return out;
+    };
+    const nodeFor = (el) => {
+        const role = roleOf(el);
+        const interactive = isInteractive(el, rules);
+        const listened = NATIVE.test(el.localName) ? [] : el.ownerDocument.listenedTypes(el).filter(t => !/^(focus|blur|focusin|focusout)$/.test(t));
+        if (!role && !(interactive && listened.length))
+            return null;
+        const node = { role: role || 'generic' };
+        // a role-less element the app listens to is one control (its contents its name), unless
+        // interactive elements are inside it: a scene-graph group with a click intent (canvas-three F1)
+        // keeps its children
+        const leaf = /^(textbox|searchbox|checkbox|radio|switch|slider|spinbutton|combobox|listbox|button|link|img|heading|option|progressbar)$/.test(node.role) || !role && !el.querySelectorAll('*').some(d => isInteractive(d, rules));
+        // a name from contents only for the roles that take one (ARIA "name from content"); a
+        // landmark, list or group (or such a container) is named by aria-label / aria-labelledby / title only
+        const name = !role && leaf || CONTENT_NAMED.test(node.role) ? nameOf(el, rules) : labelOnly(el, rules);
+        if (name)
+            node.name = name;
+        if (interactive)
+            node.ref = 'e' + nodeId(el);
+        if (listened.length)
+            node.on = listened;
+        const states = [];
+        if (/^(checkbox|radio|switch)$/.test(node.role)) {
+            if (isCheckable(el) ? el.checked : el.getAttribute('aria-checked') == 'true')
+                states.push('checked');
+        }
+        if (el.disabled || el.getAttribute('aria-disabled') == 'true')
+            states.push('disabled');
+        for (const s of ['expanded', 'pressed', 'selected']) {
+            const v = el.getAttribute('aria-' + s);
+            if (v)
+                states.push(v == 'true' ? s : `${s}=${v}`);
+        }
+        if (node.role == 'option' && el.selected)
+            states.push('selected');
+        if (el.required)
+            states.push('required');
+        if (node.role == 'heading')
+            states.push('level=' + (+(el.getAttribute('aria-level') || el.localName.slice(1)) || 2));
+        if (el.ownerDocument.activeElement === el)
+            states.push('focused');
+        if (states.length)
+            node.states = states;
+        if (isTextField(el))
+            node.value = el.type == 'password' ? '•'.repeat([...el.value].length) : el.value;
+        if (el.localName == 'select') {
+            const o = el.options.find(x => optionValue(x) == el.value);
+            if (o)
+                node.value = squash(o.textContent);
+            node.children = el.options.map(x => ({ role: 'option', name: squash(x.textContent), ...(x === o ? { states: ['selected'] } : {}) }));
+            return node;
+        }
+        if (!leaf) {
+            const c = kids(el);
+            if (c.length)
+                node.children = c;
+        }
+        return node;
+    };
+    return kids(doc.body);
+}
+const q = (s) => JSON.stringify(s);
+/** agent nodes as the YAML-like text */
+function formatSnapshot(nodes, indent = '') {
+    const lines = [];
+    for (const n of nodes) {
+        if (n.role == 'text') {
+            lines.push(`${indent}- text: ${n.text}`);
+            continue;
+        }
+        let line = `${indent}- ${n.role}`;
+        if (n.name)
+            line += ' ' + q(n.name);
+        for (const s of n.states || [])
+            line += ` [${s}]`;
+        if (n.ref)
+            line += ` [ref=${n.ref}]`;
+        if (n.on?.length)
+            line += ` [on=${n.on.join(',')}]`;
+        if (n.value !== undefined && n.value !== '')
+            line += ': ' + q(n.value);
+        if (n.children?.length)
+            lines.push(line + ':', formatSnapshot(n.children, indent + '  '));
+        else
+            lines.push(line);
+    }
+    return lines.join('\n');
+}
+
+/**
+ * sygnal/agent-ui: a minimal Model Context Protocol server (tools only), as sygnal-check's
+ * (sygnal-check/src/mcp.js) and sygnal/vite's dev endpoint (src/vite/mcp.ts): hand-rolled, no
+ * dependency, both protocol eras answered per request.
+ *
+ * - legacy, the `initialize` revisions (2024-11-05 … 2025-11-25): initialize, ping, tools/list,
+ *   tools/call; JSON-RPC batches answered. tools.listChanged is true: the tool set can change
+ *   when extra tools (sygnal/ai agentTools) do, and notifications/tools/list_changed is sent.
+ * - modern, the stateless 2026-07-28 revision (`_meta['io.modelcontextprotocol/protocolVersion']`
+ *   with client capabilities): server/discover, tools/list, tools/call; results carry
+ *   `resultType: 'complete'` and the server info in `_meta`.
+ * Transport: newline-delimited JSON over any stream pair with `on('data')` and `write()` (Node's
+ * stdin / stdout); messages are handled one at a time, in order.
+ */
+const MODERN_VERSIONS = ['2026-07-28'];
+const LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+const SUPPORTED = [...MODERN_VERSIONS, ...LEGACY_VERSIONS];
+const META = 'io.modelcontextprotocol/';
+const isObj = (v) => !!v && typeof v == 'object' && !Array.isArray(v);
+function createMcpHandler(spec) {
+    const serverInfo = { name: spec.name, version: spec.version };
+    const result = (id, value) => ({ jsonrpc: '2.0', id, result: value });
+    const error = (id, code, message, data) => ({ jsonrpc: '2.0', id, error: { code, message, ...(data !== undefined ? { data } : {}) } });
+    async function route(id, method, params, modern) {
+        if (modern && (method == 'initialize' || method == 'ping'))
+            return error(id, -32601, `Method not found: ${method} is not in 2026-07-28`);
+        switch (method) {
+            case 'initialize':
+                return result(id, {
+                    protocolVersion: LEGACY_VERSIONS.includes(params.protocolVersion) ? params.protocolVersion : LEGACY_VERSIONS[0],
+                    capabilities: { tools: { listChanged: true } },
+                    serverInfo,
+                    ...(spec.instructions ? { instructions: spec.instructions } : {}),
+                });
+            case 'server/discover':
+                if (!modern)
+                    return error(id, -32602, 'Invalid params: server/discover is a 2026-07-28 request');
+                return result(id, { supportedVersions: SUPPORTED, capabilities: { tools: {} }, ...(spec.instructions ? { instructions: spec.instructions } : {}) });
+            case 'ping':
+                return result(id, {});
+            case 'tools/list':
+                return result(id, { tools: spec.tools() });
+            case 'tools/call': {
+                const name = params.name;
+                if (!spec.tools().some(t => t.name == name))
+                    return error(id, -32602, `Unknown tool: ${name}`);
+                try {
+                    const r = await spec.call(name, isObj(params.arguments) ? params.arguments : {});
+                    return result(id, { content: [{ type: 'text', text: r.text }], ...(r.value ? { structuredContent: r.value } : {}), isError: !!r.isError });
+                }
+                catch (e) {
+                    return result(id, { content: [{ type: 'text', text: `${name} failed: ${e?.message || e}` }], isError: true });
+                }
+            }
+            default:
+                return error(id, -32601, `Method not found: ${method}`);
+        }
+    }
+    /** one message → its response (null for a notification); never throws */
+    async function handle(msg, inBatch = false) {
+        try {
+            if (!isObj(msg) || msg.jsonrpc !== '2.0' || typeof msg.method != 'string') {
+                return isObj(msg) && 'id' in msg && !('result' in msg || 'error' in msg) ? error(msg.id ?? null, -32600, 'Invalid Request') : null;
+            }
+            if (!('id' in msg) || msg.id === null)
+                return null;
+            const { id, method } = msg;
+            const params = isObj(msg.params) ? msg.params : {};
+            const meta = isObj(params._meta) ? params._meta : {};
+            let modern = false;
+            if (META + 'protocolVersion' in meta) {
+                const v = meta[META + 'protocolVersion'];
+                if (!SUPPORTED.includes(v))
+                    return error(id, -32022, 'Unsupported protocol version', { supported: SUPPORTED, requested: v });
+                if (MODERN_VERSIONS.includes(v)) {
+                    if (!isObj(meta[META + 'clientCapabilities']))
+                        return error(id, -32602, `Invalid params: _meta["${META}clientCapabilities"] is required`);
+                    if (inBatch)
+                        return error(id, -32600, 'Invalid Request: 2026-07-28 messages are sent one per line, not in a batch');
+                    modern = true;
+                }
+            }
+            const out = await route(id, method, params, modern);
+            if (modern && isObj(out.result))
+                out.result = { resultType: 'complete', ...out.result, _meta: { ...(out.result._meta || {}), [META + 'serverInfo']: serverInfo } };
+            return out;
+        }
+        catch (e) {
+            return error(isObj(msg) ? msg.id ?? null : null, -32603, `Internal error: ${e?.message || e}`);
+        }
+    }
+    return { handle };
+}
+/** serve over a newline-delimited JSON stream pair (default: process.stdin / process.stdout) */
+function serveMcpStream(spec, input, output) {
+    const proc = globalThis.process;
+    input || (input = proc?.stdin);
+    output || (output = proc?.stdout);
+    const { handle } = createMcpHandler(spec);
+    const send = (m) => { if (m && !(Array.isArray(m) && !m.length))
+        output.write(JSON.stringify(m) + '\n'); };
+    let buf = '', queue = Promise.resolve(), end;
+    const done = new Promise(r => end = r);
+    const line = (l) => {
+        if (!l.trim())
+            return;
+        queue = queue.then(async () => {
+            let msg;
+            try {
+                msg = JSON.parse(l);
+            }
+            catch {
+                return send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+            }
+            if (Array.isArray(msg))
+                send((await Promise.all(msg.map(m => handle(m, true)))).filter(Boolean));
+            else
+                send(await handle(msg));
+        });
+    };
+    const onData = (chunk) => {
+        buf += String(chunk);
+        let i;
+        while ((i = buf.indexOf('\n')) >= 0) {
+            line(buf.slice(0, i));
+            buf = buf.slice(i + 1);
+        }
+    };
+    const onEnd = () => { if (buf)
+        line(buf); buf = ''; queue.then(end); };
+    input.setEncoding?.('utf8');
+    input.on('data', onData);
+    input.on('end', onEnd);
+    input.resume?.();
+    return {
+        listChanged: () => send({ jsonrpc: '2.0', method: 'notifications/tools/list_changed' }),
+        stop: () => { input.off?.('data', onData); input.off?.('end', onEnd); end(); },
+        done,
+    };
+}
+
+/*
+ * 'sygnal/agent-ui': a Sygnal app rendered for an LLM agent. The app renders into a sygnal/host
+ * tree; this target's "screen" is an accessibility snapshot (roles, names, states, values, refs:
+ * the format browser agents read), and its "input" is tool calls: ui_click, ui_type, ui_press,
+ * ui_select, ui_check, which become the same DOM events a user's input makes. The app's views,
+ * intents and models don't change: an agent operates the app the way a person does, without a
+ * browser, deterministically, and in a test.
+ *
+ *   const {app, ui} = runAgentUI(App)
+ *   ui.snapshot()                                   // what the agent sees
+ *   await ui.call('ui_click', { ref: 'e12' })       // → { ok: true, snapshot }
+ *   serveMcp(ui, { name: 'my-app' })                // the same tools over MCP (stdio)
+ *
+ * With sygnal/ai: `agentTools(app)` (the semantic tools of the app's `agent` declarations) can be
+ * served alongside (`serveMcp(ui, { tools: agentTools(app) })`); `ui.chatTools()` gives the tools
+ * in the chat driver's format. Separate entry: './index' and './host' become the external
+ * 'sygnal' and 'sygnal/host'.
+ */
+const REF = { type: 'string', description: 'The element\'s ref from the snapshot, like "e12"' };
+const TOOLS = [
+    { name: 'ui_snapshot', description: 'Read the app\'s current screen: an accessibility snapshot with a ref on each element you can act on. [on=…] lists events the app handles on that element.', inputSchema: { type: 'object', properties: {}, additionalProperties: false }, annotations: { readOnlyHint: true } },
+    { name: 'ui_click', description: 'Click an element (a button, link, checkbox, or an element with [on=click]). double: true for a double click ([on=dblclick]).', inputSchema: { type: 'object', properties: { ref: REF, double: { type: 'boolean', description: 'A double click' } }, required: ['ref'], additionalProperties: false }, annotations: {} },
+    { name: 'ui_type', description: 'Type into a text field. Replaces its value unless append is true; submit: true presses Enter afterwards (submits its form).', inputSchema: { type: 'object', properties: { ref: REF, text: { type: 'string' }, append: { type: 'boolean' }, submit: { type: 'boolean' } }, required: ['ref', 'text'], additionalProperties: false }, annotations: {} },
+    { name: 'ui_press', description: 'Press a key ("Enter", "Escape", "Tab", "ArrowDown", "a", modifiers as "Control+s") on an element, or on the focused element / the whole app without a ref.', inputSchema: { type: 'object', properties: { key: { type: 'string' }, ref: REF }, required: ['key'], additionalProperties: false }, annotations: {} },
+    { name: 'ui_select', description: 'Choose an option of a combobox (<select>) by its label or value.', inputSchema: { type: 'object', properties: { ref: REF, option: { type: 'string' } }, required: ['ref', 'option'], additionalProperties: false }, annotations: {} },
+    { name: 'ui_check', description: 'Set a checkbox or radio to checked (true) or unchecked (false); does nothing when it already is.', inputSchema: { type: 'object', properties: { ref: REF, checked: { type: 'boolean' } }, required: ['ref', 'checked'], additionalProperties: false }, annotations: {} },
+];
+function createAgentUI(options = {}) {
+    const doc = options.document || new HostDocument();
+    const rules = options.styles || [];
+    const ua = { onNavigate: options.onNavigate };
+    const quiet = options.quietMs ?? 20, maxWait = options.maxWaitMs ?? 2000;
+    const listeners = new Set();
+    let changes = 0, runtime = null;
+    doc.onChange = () => { changes++; for (const l of [...listeners])
+        l(); };
+    const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+    const find = (ref) => {
+        const id = typeof ref == 'string' && /^e(\d+)$/.exec(ref.trim());
+        if (!id)
+            return null;
+        return [doc.body, ...doc.body.querySelectorAll('*')].find(el => nodeId(el) == +id[1]) || null;
+    };
+    const target = (ref) => {
+        const el = find(ref);
+        if (!el)
+            throw new Error(`no element with ref ${JSON.stringify(ref)}: take a new ui_snapshot (refs of elements that left the screen are gone)`);
+        if (!el.isConnected)
+            throw new Error(`ref ${ref} is no longer on the screen`);
+        if (!isInteractive(el, rules) && !/^(input|textarea|select)$/.test(el.localName) && !isTextField(el) && !isCheckable(el))
+            throw new Error(`ref ${ref} is not interactive (no ref in the snapshot)`);
+        if (el.disabled)
+            throw new Error(`ref ${ref} is disabled`);
+        return el;
+    };
+    const parseKey = (k) => {
+        const parts = k.split('+').filter(Boolean);
+        const key = parts.pop() || k;
+        const m = new Set(parts.map(p => p.toLowerCase()));
+        return { key: key == 'Space' ? ' ' : key, init: { ctrlKey: m.has('control') || m.has('ctrl'), shiftKey: m.has('shift'), altKey: m.has('alt'), metaKey: m.has('meta') || m.has('cmd') } };
+    };
+    const ui = {
+        doc,
+        driver: makeHostDriver(doc),
+        tree: () => snapshotTree(doc, { rules }),
+        snapshot: () => formatSnapshot(ui.tree()) || '(the screen is empty)',
+        element: find,
+        tools: () => TOOLS.map(t => ({ ...t })),
+        chatTools: () => Object.fromEntries(TOOLS.map(t => [t.name, { description: t.description, inputSchema: t.inputSchema }])),
+        attach(app) { runtime = app?.__runtime || app || null; },
+        subscribe(l) { listeners.add(l); return () => { listeners.delete(l); }; },
+        async settle() {
+            const end = Date.now() + maxWait;
+            for (;;) {
+                const n = changes;
+                if (runtime?.flushed)
+                    await runtime.flushed();
+                await sleep(quiet);
+                if (changes === n || Date.now() > end)
+                    return;
+            }
+        },
+        async call(name, args = {}) {
+            try {
+                switch (name) {
+                    case 'ui_snapshot': break;
+                    case 'ui_click': {
+                        const el = target(args.ref);
+                        args.double ? doubleClick(el, ua) : (el.focus(), activate(el, ua));
+                        break;
+                    }
+                    case 'ui_type': {
+                        const el = target(args.ref);
+                        if (typeof args.text != 'string')
+                            throw new Error('text must be a string');
+                        if (!isTextField(el))
+                            throw new Error(`ref ${args.ref} is not a text field`);
+                        args.append ? typeText(el, args.text, ua) : fill(el, args.text);
+                        if (args.submit)
+                            pressKey(el, 'Enter', {}, ua);
+                        break;
+                    }
+                    case 'ui_press': {
+                        if (typeof args.key != 'string' || !args.key)
+                            throw new Error('key must be a key name, like "Enter"');
+                        const el = args.ref != null ? target(args.ref) : doc.activeElement || doc.body;
+                        if (args.ref != null)
+                            el.focus();
+                        const { key, init } = parseKey(args.key);
+                        pressKey(el, key, init, ua);
+                        break;
+                    }
+                    case 'ui_select': {
+                        const el = target(args.ref);
+                        if (el.localName != 'select')
+                            throw new Error(`ref ${args.ref} is not a combobox`);
+                        el.focus();
+                        if (!chooseOption(el, String(args.option)))
+                            throw new Error(`no option ${JSON.stringify(args.option)}; options: ${el.options.map(o => JSON.stringify(o.textContent.trim())).join(', ')}`);
+                        break;
+                    }
+                    case 'ui_check': {
+                        const el = target(args.ref);
+                        if (!isCheckable(el))
+                            throw new Error(`ref ${args.ref} is not a checkbox, switch or radio`);
+                        if (el.checked !== !!args.checked) {
+                            el.focus();
+                            activate(el, ua);
+                        }
+                        break;
+                    }
+                    default:
+                        throw new Error(`unknown tool ${name}`);
+                }
+            }
+            catch (e) {
+                await ui.settle();
+                return { ok: false, error: e?.message || String(e), snapshot: ui.snapshot() };
+            }
+            await ui.settle();
+            return { ok: true, snapshot: ui.snapshot() };
+        },
+    };
+    return ui;
+}
+/** run an app for an agent: `{ app, ui }`, the ui attached to the app's flushes */
+function runAgentUI(App, options = {}) {
+    const ui = createAgentUI(options);
+    const app = run(App, { ...options.drivers, DOM: ui.driver }, options.runOptions);
+    ui.attach(app);
+    return { app, ui };
+}
+const INSTRUCTIONS = 'This server is an app\'s user interface. Call ui_snapshot to see the screen, then act on elements by their ref (ui_click, ui_type, ui_press, ui_select, ui_check); every action answers with the new snapshot. Refs change when elements are re-created: use the latest snapshot.';
+/** the agent UI's tools (and any extra tools) as an MCP server on a stream pair (default stdio) */
+function serveMcp(ui, options = {}) {
+    const extra = options.tools;
+    const server = serveMcpStream({
+        name: options.name || 'sygnal-agent-ui',
+        version: options.version || '0.0.0',
+        instructions: options.instructions ?? INSTRUCTIONS,
+        tools: () => [...ui.tools(), ...(extra ? extra.list().map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema, annotations: t.annotations })) : [])],
+        async call(name, args) {
+            if (name.startsWith('ui_')) {
+                const r = await ui.call(name, args);
+                return r.ok ? { text: r.snapshot, value: r } : { text: `Error: ${r.error}\n\n${r.snapshot ?? ''}`, value: r, isError: true };
+            }
+            const r = await extra.call(name, args);
+            await ui.settle();
+            return { text: JSON.stringify(r), value: r && typeof r == 'object' ? r : { result: r }, isError: r?.ok === false };
+        },
+    }, options.input, options.output);
+    // only a change of the tool set is announced (agentTools' listener also fires for context changes)
+    let names = extra ? extra.list().map(t => t.name).join() : '';
+    const off = extra?.subscribe?.(() => {
+        const now = extra.list().map(t => t.name).join();
+        if (now !== names) {
+            names = now;
+            server.listChanged();
+        }
+    });
+    const stop = server.stop;
+    server.stop = () => { off?.(); stop(); };
+    return server;
+}
+
+export { createAgentUI, createMcpHandler, formatSnapshot, nameOf, roleOf, runAgentUI, serveMcp, serveMcpStream, snapshotTree };
+//# sourceMappingURL=agent-ui.esm.js.map