sygnal 7.0.0 → 7.2.0-preview.0

package/dist/sandbox.esm.js

@@ -0,0 +1,1406 @@
+import { defineWidget } from 'sygnal';
+
+/*
+ * sygnal/sandbox: what the page and the guest kernel agree on (research: dev-plans/research/sandbox).
+ *
+ * The protocol is internal and versioned: a kernel built from another Sygnal version is refused
+ * at boot ('protocol'), never half understood. It is the part a native or edge host would
+ * reimplement:
+ *
+ *   page → guest  (QuickJS entries on the kernel's `__sandbox`):
+ *     dispatch(id, type, initJson) → 1 when prevented   fire(timerId)   resolve(fetchId, ok, json)
+ *     props(json)   start(exportName)   flush()          v (the protocol number)
+ *   guest → page  (host functions on `__host`, each checked):
+ *     render(json)  {v, tree, types, f?}: tree = [node], node = {i, t, a, s?, v?, k?, c} | {i, x} | id
+ *                   (an id alone: an unchanged subtree), types = DOM event types to forward,
+ *                   f = the id the guest moved focus to
+ *     emit(json)    {type, data}          log(level, text)
+ *     timer(id, ms) (ms < 0: setImmediate) clearTimer(id)   fetch(id, url, initJson)
+ *   page ↔ worker (postMessage; `isolation: 'worker'`):
+ *     → init {v, kernel, source, props, limits, fetch}  event {id, type, init}  props {p}  ping  fetched {id, ok, res|error}
+ *     ← ready {v, wasmMs, bootMs}  render {json}  emit {e}  log {l, x}  fetch {id, url, init}  pong  error {reason, message}
+ */
+const PROTOCOL = 1;
+class SandboxError extends Error {
+    constructor(reason, message) {
+        super(message);
+        this.name = 'SandboxError';
+        this.reason = reason;
+    }
+}
+// README §8: an instance per sandbox capped at 64 MB, heap 32 MB, stack 256 KB, boot 1 s, 100 ms per entry, CPU 50 %
+const DEFAULT_LIMITS = {
+    memoryBytes: 32 << 20, // QuickJS's heap (the kernel alone takes ~4 MB)
+    // QuickJS's own stack check must fire before the host engine's: at 512 KB a guest recursion
+    // overflows V8's native stack first, a host RangeError unwinds the WASM mid-call, and freeing
+    // that runtime aborts the whole module (README §5, finding 3). 384 KB and below are caught.
+    stackBytes: 256 << 10,
+    // the instance's whole linear memory (heap, ArrayBuffers, C stack): setMemoryLimit() doesn't
+    // count ArrayBuffer storage (README finding 1), a capped WebAssembly.Memory does
+    maxWasmBytes: 64 << 20,
+    bootMs: 1000, // kernel + component + first render
+    callMs: 100, // one event, timer or fetch reply, with the flush it causes
+    cpuShare: 0.5, // guest time per rolling second
+    hardMs: 1000, // worker: the watchdog terminates a worker silent this long
+    maxTimers: 64,
+    minTimerMs: 4,
+    maxFetches: 4, // in flight
+    maxMessageBytes: 1 << 20,
+    maxLogs: 100,
+};
+/** above this, a guest recursion can overflow the host's stack before QuickJS's check (a crash) */
+const MAX_STACK_BYTES = 384 << 10;
+function limitsOf(l) {
+    const out = { ...DEFAULT_LIMITS };
+    for (const k of Object.keys(l || {})) {
+        if (!(k in DEFAULT_LIMITS))
+            continue;
+        const v = Number(l[k]);
+        if (!(v > 0))
+            throw new TypeError(`sygnal/sandbox: limits.${k} must be a positive number`);
+        out[k] = v;
+    }
+    if (out.stackBytes > MAX_STACK_BYTES)
+        throw new RangeError(`sygnal/sandbox: limits.stackBytes over ${MAX_STACK_BYTES} can crash the WASM module instead of throwing in the guest`);
+    return out;
+}
+/** an allowlist entry is a URL prefix: same origin, path under its path */
+function allowed(u, allow) {
+    if (u.username || u.password)
+        return false;
+    return allow.some((a) => {
+        if (a instanceof RegExp)
+            return a.test(u.href);
+        const p = new URL(a);
+        return u.origin === p.origin && u.pathname.startsWith(p.pathname);
+    });
+}
+/**
+ * The request the page makes for a guest (both tiers): the allowlist, the methods, accept /
+ * content-type headers only, `credentials: 'omit'` (never the user's cookies), `redirect: 'error'`
+ * (a redirect could leave the allowlist), the response size capped. Resolves with a plain
+ * {status, headers, body} or rejects with the reason.
+ */
+async function capFetch(f, url, init, maxBytes, signal) {
+    if (!f)
+        throw new Error('no fetch capability');
+    let u;
+    try {
+        u = f.base ? new URL(url, f.base) : new URL(url);
+    }
+    catch {
+        throw new Error(`bad URL ${String(url).slice(0, 80)}`);
+    }
+    if (!allowed(u, f.allow || []))
+        throw new Error(`${u.origin}${u.pathname} is not allowed`);
+    const method = String(init?.method || 'GET').toUpperCase();
+    if (!(f.methods || ['GET']).map((m) => m.toUpperCase()).includes(method))
+        throw new Error(`method ${method} is not allowed`);
+    const headers = {};
+    for (const [k, v] of Object.entries(init?.headers || {}))
+        if (/^(accept|content-type)$/i.test(k))
+            headers[k] = String(v);
+    const body = typeof init?.body == 'string' && method !== 'GET' && method !== 'HEAD' ? init.body : undefined;
+    const r = await (f.impl || globalThis.fetch)(u.href, { method, headers, body, credentials: 'omit', redirect: 'error', signal });
+    const text = await r.text();
+    if (text.length > (f.maxBodyBytes || maxBytes))
+        throw new Error('response too large');
+    return { status: r.status, headers: { 'content-type': r.headers.get('content-type') || '' }, body: text };
+}
+
+/*
+ * The QuickJS WASM module: `quickjs-emscripten-core` + `@jitl/quickjs-wasmfile-release-sync`,
+ * optional peer dependencies (D209), loaded on first use. Stock packages only (README §9 Q6):
+ * a quickjs-ng variant can be passed as `variant`.
+ */
+let compiled = null;
+let shared = null;
+const isNode$1 = () => typeof globalThis.process == 'object' && !!globalThis.process.versions?.node && typeof globalThis.window == 'undefined';
+/**
+ * A QuickJS module. By default a fresh instance whose own `WebAssembly.Memory` is capped at
+ * `maxWasmBytes` (64 MB): QuickJS's `setMemoryLimit()` doesn't count ArrayBuffer storage, so
+ * without the cap a guest can grow the instance to 2 GB (README finding 1). Instances share
+ * one compiled `WebAssembly.Module` (compiled once per page).
+ */
+async function loadQuickJS(opts = {}) {
+    if (opts.shared && !opts.wasm && !opts.variant && shared)
+        return shared;
+    const p = load(opts);
+    if (opts.shared && !opts.wasm && !opts.variant)
+        shared = p;
+    return p;
+}
+async function load({ maxWasmBytes = 64 << 20, shared: sh, variant, wasm }) {
+    let core, base;
+    try {
+        core = await import('quickjs-emscripten-core');
+        base = variant || (await import('@jitl/quickjs-wasmfile-release-sync')).default;
+    }
+    catch (e) {
+        throw new Error("sygnal/sandbox needs quickjs-emscripten-core and @jitl/quickjs-wasmfile-release-sync (optional peer dependencies): npm install quickjs-emscripten-core @jitl/quickjs-wasmfile-release-sync (" + (e?.message || e) + ')');
+    }
+    const custom = {};
+    if (wasm)
+        custom.wasmModule = wasm instanceof WebAssembly.Module ? wasm : await WebAssembly.compile(wasm);
+    else if (!variant && isNode$1())
+        custom.wasmModule = await (compiled ?? (compiled = nodeWasm()));
+    // a browser without `wasm` lets the variant fetch its .wasm itself (the bundler emits the file)
+    if (!sh)
+        custom.wasmMemory = new WebAssembly.Memory({ initial: 256, maximum: Math.max(256, Math.ceil(maxWasmBytes / 65536)) });
+    return core.newQuickJSWASMModuleFromVariant(Object.keys(custom).length ? core.newVariant(base, custom) : base);
+}
+async function nodeWasm() {
+    const [{ readFile }, { createRequire }] = await Promise.all([nodeImport('node:fs/promises'), nodeImport('node:module')]);
+    // next to sygnal (a peer), else from the app's root
+    let file;
+    try {
+        file = createRequire(import.meta.url).resolve('@jitl/quickjs-wasmfile-release-sync/wasm');
+    }
+    catch {
+        file = createRequire(globalThis.process.cwd() + '/').resolve('@jitl/quickjs-wasmfile-release-sync/wasm');
+    }
+    return WebAssembly.compile(await readFile(file));
+}
+// Node built-ins by a name bundlers don't follow (a browser bundle never loads them)
+const nodeImport = (name) => import(/* @vite-ignore */ /* webpackIgnore: true */ name);
+/**
+ * Modules a guest crashed: the host's stack overflowed or the WASM trapped in the middle of a
+ * QuickJS call, so its C state was unwound without cleanup. createSandbox refuses them.
+ */
+const poisoned = new WeakSet();
+const checkModule = (QJS) => {
+    if (!QJS || typeof QJS.newRuntime != 'function')
+        throw new TypeError('sygnal/sandbox: quickjs must be a module from loadQuickJS()');
+    if (poisoned.has(QJS))
+        throw new SandboxError('crash', 'this QuickJS module crashed earlier; load a fresh one');
+};
+
+/*
+ * The page's side of the tree: mirrors the guest's serialized host tree into the real DOM through
+ * a sanitizer, and forwards DOM events back.
+ *
+ * Everything that arrives is untrusted (the guest can send any JSON). The mirror:
+ *   - creates only allowlisted tags and attributes (no on*, srcdoc, formaction, <script>,
+ *     <iframe>, <style>, <svg>, …); unknown tags are dropped, never rendered;
+ *   - checks URLs: <a href> only http(s)/mailto (clicks never navigate by themselves: see
+ *     bindEvents), <img src> only data:image/* or an allowlisted origin (an image is a request);
+ *   - filters inline style (no url(), image-set(), expression(), escapes; plain names only);
+ *   - prefixes ids (and for / aria-* references to them) so the guest can't clobber the page's
+ *     ids or `window.<id>`; `name` only on form fields; classes are kept (the page's design system
+ *     styles the guest) unless `classPrefix` is set;
+ *   - limits nodes, depth and text so a huge tree can't stall the page;
+ *   - confines layout: the root has `contain: content` (a containing block for position: fixed,
+ *     paint clipped), `isolation: isolate` and `overflow: hidden` (no overlaying the page).
+ * A violation is recorded (violations[]) and the offending part dropped; a malformed tree (a
+ * cycle, a node inside itself) throws, and the sandbox is killed.
+ */
+const TAGS = new Set(('div span p a button input textarea select option optgroup label ul ol li h1 h2 h3 h4 h5 h6 strong em b i u s small ' +
+    'code pre kbd br hr img table caption thead tbody tfoot tr td th colgroup col form fieldset legend section article header ' +
+    'footer nav main aside figure figcaption details summary progress meter time abbr blockquote q cite dl dt dd mark sub sup output').split(' '));
+const ATTRS = /^(class|title|role|tabindex|lang|dir|hidden|alt|width|height|colspan|rowspan|scope|open|value|placeholder|checked|selected|disabled|readonly|required|multiple|min|max|step|minlength|maxlength|pattern|size|rows|cols|wrap|autocomplete|spellcheck|start|reversed|datetime|high|low|optimum|label|draggable)$|^aria-[a-z-]+$|^data-[a-z0-9-]+$/;
+// no password or file inputs (phishing, file exfiltration)
+const INPUT_TYPES = /^(text|search|email|url|tel|number|range|date|time|datetime-local|month|week|color|checkbox|radio|button|submit|reset|hidden)$/;
+const ID_REFS = /^(for|aria-labelledby|aria-describedby|aria-controls|aria-owns|aria-activedescendant|list)$/;
+const SAFE_HREF = /^(https?:|mailto:)/i;
+const BAD_STYLE = /url\s*\(|image-set|expression|javascript:|\\|@|<|behavior|binding/i;
+const FIELD = /^(input|textarea|select|button|output|fieldset)$/;
+const CLASS_TOKEN = /^[A-Za-z0-9_-]+$/;
+const DEFAULT_POLICY = { maxNodes: 5000, maxDepth: 128, maxText: 1 << 20, imageOrigins: [], classPrefix: '' };
+/** one element's attributes and inline style through the allowlist (the mirror and SSR share it) */
+function sanitize(tag, n, prefix, policy, violate) {
+    const attrs = new Map();
+    const a = n.a && typeof n.a == 'object' ? n.a : {};
+    for (const k0 of Object.keys(a)) {
+        const k = String(k0).toLowerCase(), v = String(a[k0]);
+        if (k === 'id')
+            attrs.set('id', prefix + v);
+        else if (ID_REFS.test(k))
+            attrs.set(k, v.split(/\s+/).filter(Boolean).map((x) => prefix + x).join(' '));
+        else if (k === 'name') {
+            if (FIELD.test(tag))
+                attrs.set(k, v);
+            else
+                violate(`name on <${tag}>`);
+        }
+        else if (k === 'type') {
+            if (tag !== 'input' || INPUT_TYPES.test(v))
+                attrs.set(k, v);
+            else
+                violate(`input type ${v}`);
+        }
+        else if (k === 'href') {
+            if (tag === 'a' && SAFE_HREF.test(v.trim()))
+                attrs.set(k, v);
+            else
+                violate(`href ${v.slice(0, 40)}`);
+        }
+        else if (k === 'src') {
+            if (tag === 'img' && imageOk(v, policy))
+                attrs.set(k, v);
+            else
+                violate(`src ${v.slice(0, 40)}`);
+        }
+        else if (k === 'style')
+            violate('style attribute'); // inline style arrives as n.s, filtered below
+        else if (k === 'class' && policy.classPrefix)
+            attrs.set(k, v.split(/\s+/).filter((c) => CLASS_TOKEN.test(c)).map((c) => policy.classPrefix + c).join(' '));
+        else if (ATTRS.test(k))
+            attrs.set(k, v);
+        else
+            violate(`attribute ${k}`);
+    }
+    if (tag === 'a' && attrs.has('href')) {
+        attrs.set('rel', 'noopener noreferrer');
+        attrs.set('target', '_blank');
+    }
+    const css = [];
+    const s = n.s && typeof n.s == 'object' ? n.s : {};
+    for (const k of Object.keys(s)) {
+        const name = String(k).replace(/[A-Z]/g, (c) => '-' + c.toLowerCase()), v = String(s[k]);
+        if (!/^-?[a-z][a-z-]*$/.test(name) || BAD_STYLE.test(v)) {
+            violate(`style ${name}`);
+            continue;
+        }
+        css.push(`${name}: ${v}`);
+    }
+    return { attrs, css: css.join('; ') };
+}
+function imageOk(v, policy) {
+    if (/^data:image\/(png|gif|jpeg|webp);base64,/i.test(v))
+        return true;
+    try {
+        return policy.imageOrigins.includes(new URL(v).origin);
+    }
+    catch {
+        return false;
+    }
+}
+const VOID = new Set(['br', 'hr', 'img', 'input', 'col']);
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+/**
+ * A render message's tree as HTML (SSR, edge, multi-tenant): the same allowlist and limits as the
+ * mirror. A full tree only (no bare ids).
+ */
+function treeToHTML(tree, opts = {}) {
+    const policy = { ...DEFAULT_POLICY, ...opts.policy }, prefix = opts.prefix ?? policy.idPrefix ?? 'sbx-';
+    const violations = [], violate = (w) => { if (violations.length < 100)
+        violations.push(w); };
+    let count = 0, text = 0;
+    const out = (n, depth) => {
+        if (depth > policy.maxDepth || ++count > policy.maxNodes)
+            throw new Error('sandbox tree: over the limits');
+        if (!n || typeof n != 'object')
+            throw new Error('sandbox tree: malformed node (SSR needs a full tree)');
+        if (typeof n.x == 'string') {
+            if ((text += n.x.length) > policy.maxText)
+                throw new Error('sandbox tree: too much text');
+            return esc(n.x);
+        }
+        const tag = String(n.t);
+        if (!TAGS.has(tag)) {
+            violate(`tag <${tag}>`);
+            return '';
+        }
+        const { attrs, css } = sanitize(tag, n, prefix, policy, violate);
+        if ('v' in n && tag === 'input')
+            attrs.set('value', String(n.v));
+        if (n.k && (tag === 'input' || tag === 'option'))
+            attrs.set(tag === 'option' ? 'selected' : 'checked', '');
+        if (css)
+            attrs.set('style', css);
+        const open = `<${tag}${[...attrs].map(([k, v]) => ` ${k}="${esc(v)}"`).join('')}>`;
+        if (VOID.has(tag))
+            return open;
+        const inner = tag === 'textarea' ? esc(n.v ?? '') : (Array.isArray(n.c) ? n.c : []).map((c) => out(c, depth + 1)).join('');
+        return `${open}${inner}</${tag}>`;
+    };
+    return { html: (Array.isArray(tree) ? tree : []).map((n) => out(n, 0)).join(''), violations };
+}
+let roots = 0;
+function createMirror(container, opts = {}) {
+    const policy = { ...DEFAULT_POLICY, ...opts.policy };
+    const doc = container.ownerDocument;
+    const prefix = policy.idPrefix ?? `sbx${++roots}-`;
+    const root = doc.createElement('div');
+    root.setAttribute('data-sandbox-root', '');
+    root.style.cssText = 'contain: content; isolation: isolate; position: relative; overflow: hidden';
+    container.appendChild(root);
+    const nodes = new Map(); // guest id → real node
+    const idOf = new WeakMap(); // real node → guest id
+    const violations = [];
+    const violate = (what) => { if (violations.length < 100)
+        violations.push(what); };
+    let count = 0, text = 0, alive = new Set();
+    const keepSubtree = (n) => {
+        const i = idOf.get(n);
+        if (i !== undefined)
+            alive.add(i);
+        n.childNodes.forEach(keepSubtree);
+    };
+    function build(n, depth) {
+        if (depth > policy.maxDepth)
+            throw new Error('sandbox tree: too deep');
+        if (++count > policy.maxNodes)
+            throw new Error('sandbox tree: too many nodes');
+        if (typeof n == 'number') {
+            const real = nodes.get(n);
+            if (!real)
+                return null; // dropped by the sanitizer when it was sent
+            keepSubtree(real);
+            return real;
+        }
+        if (!n || typeof n != 'object' || typeof n.i != 'number')
+            throw new Error('sandbox tree: malformed node');
+        alive.add(n.i);
+        if (typeof n.x == 'string') {
+            if ((text += n.x.length) > policy.maxText)
+                throw new Error('sandbox tree: too much text');
+            let t = nodes.get(n.i);
+            if (!t || t.nodeType !== 3) {
+                t = doc.createTextNode(n.x);
+                nodes.set(n.i, t);
+                idOf.set(t, n.i);
+            }
+            else if (t.data !== n.x)
+                t.data = n.x;
+            return t;
+        }
+        const tag = String(n.t);
+        if (!TAGS.has(tag)) {
+            violate(`tag <${tag}>`);
+            return null;
+        }
+        let el = nodes.get(n.i);
+        if (!el || el.localName !== tag) {
+            el = doc.createElement(tag);
+            nodes.set(n.i, el);
+            idOf.set(el, n.i);
+        }
+        const { attrs: want, css } = sanitize(tag, n, prefix, policy, violate);
+        for (const a of [...el.attributes])
+            if (a.name !== 'style' && !want.has(a.name))
+                el.removeAttribute(a.name);
+        for (const [k, v] of want)
+            if (el.getAttribute(k) !== v)
+                el.setAttribute(k, v);
+        if ((el.getAttribute('style') || '') !== css)
+            css ? el.setAttribute('style', css) : el.removeAttribute('style');
+        // field state the guest controls
+        const f = el;
+        if ('v' in n && f.value !== String(n.v))
+            f.value = String(n.v);
+        if ('k' in n && (tag === 'input' || tag === 'option'))
+            tag === 'option' ? (f.selected = !!n.k) : (f.checked = !!n.k);
+        const kids = [];
+        for (const c of Array.isArray(n.c) ? n.c : []) {
+            const r = build(c, depth + 1);
+            if (r)
+                kids.push(r);
+        }
+        for (let i = 0; i < kids.length; i++) {
+            if (kids[i].contains(el))
+                throw new Error('sandbox tree: a node inside itself');
+            if (el.childNodes[i] !== kids[i])
+                el.insertBefore(kids[i], el.childNodes[i] || null);
+        }
+        while (el.childNodes.length > kids.length)
+            el.removeChild(el.lastChild);
+        return el;
+    }
+    return {
+        root, violations, prefix,
+        /** apply one render's tree; throws on a malformed one */
+        apply(tree) {
+            count = 0;
+            text = 0;
+            alive = new Set();
+            const top = [];
+            for (const n of Array.isArray(tree) ? tree : []) {
+                const r = build(n, 0);
+                if (r)
+                    top.push(r);
+            }
+            for (let i = 0; i < top.length; i++) {
+                if (root.childNodes[i] !== top[i])
+                    root.insertBefore(top[i], root.childNodes[i] || null);
+            }
+            while (root.childNodes.length > top.length)
+                root.removeChild(root.lastChild);
+            for (const k of [...nodes.keys()])
+                if (!alive.has(k))
+                    nodes.delete(k);
+        },
+        /**
+         * The guest moved focus (README §9 Q5): only with the focus capability, and only while the
+         * page's focus is already inside the box. A guest can manage focus in its own dialog, never
+         * take it from the page.
+         */
+        focus(id) {
+            const el = nodes.get(id);
+            if (!opts.focus)
+                return void violate('focus (no focus capability)');
+            if (!el || el.nodeType !== 1 || !root.contains(doc.activeElement) || doc.activeElement === el)
+                return;
+            el.focus?.();
+        },
+        /** the guest id of a real node, or of its nearest mirrored ancestor inside the root */
+        idFor(target) {
+            for (let n = target; n && n !== root; n = n.parentNode) {
+                const i = idOf.get(n);
+                if (i !== undefined)
+                    return i;
+            }
+            return undefined;
+        },
+        clear() { root.remove(); nodes.clear(); },
+    };
+}
+const FORWARD = /^(click|dblclick|input|change|submit|keydown|keyup|focus|blur|focusin|focusout|pointerdown|pointerup|mouseenter|mouseleave)$/;
+const NO_BUBBLE = /^(focus|blur|mouseenter|mouseleave)$/;
+const STOP = ('click dblclick auxclick contextmenu mousedown mouseup mouseover mouseout pointerdown pointerup pointerover pointerout ' +
+    'input change submit reset keydown keyup keypress beforeinput focusin focusout touchstart touchend wheel select').split(' ');
+const KEYS = ['key', 'code', 'shiftKey', 'ctrlKey', 'altKey', 'metaKey', 'button', 'clientX', 'clientY'];
+/**
+ * DOM events → the guest: one listener at the mirror's root per type the guest listens for
+ * (delegation, as the DOM driver does), with the event's plain fields and the target's value /
+ * checked. `dispatch` returns whether the guest prevented the default (in-thread: synchronous;
+ * a worker answers too late, so only declared keys are prevented). A form submit and a link
+ * click never act on the page by themselves: an unprevented link click goes to `navigate(href)`.
+ */
+function bindEvents(mirror, dispatch, navigate) {
+    const root = mirror.root, on = new Map();
+    const add = (key, l, capture = false) => {
+        on.set(key, [l, capture]);
+        root.addEventListener(key.replace(/^\$/, ''), l, capture);
+    };
+    function onEvent(e) {
+        const id = mirror.idFor(e.target);
+        if (id === undefined)
+            return;
+        const t = e.target, init = {};
+        for (const k of KEYS)
+            if (e[k] !== undefined)
+                init[k] = e[k];
+        if (t && /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName)) {
+            init.value = t.value;
+            if (t.type === 'checkbox' || t.type === 'radio')
+                init.checked = t.checked;
+        }
+        if (dispatch(id, e.type, init))
+            e.preventDefault();
+    }
+    add('$submit', (e) => e.preventDefault());
+    // The guest's elements are not the host app's: its delegated intents (DOM.select('.danger'),
+    // bubbling at the app root) must never see a sandboxed element's events, or a guest could render
+    // a class the host listens to and have the user trigger a host action. The page's own capture
+    // listeners still see them.
+    for (const t of STOP)
+        add('$' + t, (e) => e.stopPropagation());
+    const link = (e) => {
+        const a = e.target?.closest?.('a[href]');
+        if (!a || !root.contains(a))
+            return;
+        const was = e.defaultPrevented;
+        e.preventDefault();
+        if (!was)
+            navigate?.(a.getAttribute('href'));
+    };
+    add('$click', link);
+    return {
+        listen(types) {
+            for (const t of types)
+                if (!on.has(t) && FORWARD.test(t))
+                    add(t, onEvent, NO_BUBBLE.test(t));
+            // the link check runs after the guest's own click (whose preventDefault it honours): last
+            if (types.includes('click')) {
+                root.removeEventListener('click', link);
+                root.addEventListener('click', link);
+            }
+        },
+        detach() {
+            for (const [t, [l, c]] of on)
+                root.removeEventListener(t.replace(/^\$/, ''), l, c);
+            root.removeEventListener('click', link);
+            on.clear();
+        },
+    };
+}
+
+/*
+ * The in-thread engine: one guest in its own QuickJS runtime and context. Used directly for
+ * `isolation: 'thread'`, and inside the Worker for `isolation: 'worker'` (no container there:
+ * renders go out as JSON).
+ *
+ * Isolation comes from QuickJS: the guest's globals are QuickJS's own (no window, document,
+ * fetch, storage; the Function constructor reaches only the guest global). Its only way out is
+ * the `__host` functions below, each of which checks its arguments. Every entry (boot, an event,
+ * a timer, a fetch reply) runs under a deadline (the interrupt handler) with the runtime's
+ * memory and stack limits, and a CPU share over a rolling second. A guest that trips a limit is
+ * killed: there is no safe way to resume a context interrupted half way through a flush.
+ *
+ * The deadline stops accidents, not hostile code: QuickJS polls the interrupt handler once per
+ * 10,000 ticks and never inside a builtin (README finding 2). The Worker's watchdog is the hard stop.
+ */
+const ENTRIES = ['dispatch', 'fire', 'resolve', 'props', 'start', 'flush'];
+function createEngine(QJS, opts) {
+    checkModule(QJS);
+    const limits = opts.limits;
+    const now = () => performance.now();
+    const stats = { bootMs: 0, calls: 0, guestMs: 0, renders: 0, lastCallMs: 0 };
+    let deadline = Infinity;
+    const rt = QJS.newRuntime();
+    rt.setMemoryLimit(limits.memoryBytes);
+    rt.setMaxStackSize(limits.stackBytes);
+    rt.setInterruptHandler(() => now() > deadline);
+    const ctx = rt.newContext();
+    let dead = false, crashed = false, logs = 0, immediates = 0;
+    // renders are deltas against the previous one (unchanged subtrees are bare ids): all are applied, in order
+    const renders = [], emits = [];
+    const timers = new Map(), fetches = new Map();
+    const mirror = opts.container ? createMirror(opts.container, { policy: opts.policy, focus: !!opts.focus }) : null;
+    // a DOM event goes into the guest synchronously, so its preventDefault() reaches the page's event
+    const events = mirror && bindEvents(mirror, (id, type, init) => !!enter('dispatch', [id, type, JSON.stringify(init)]), (href) => opts.navigate?.(href));
+    // --- the bridge: the only functions the guest can reach --------------------------------------
+    const str = (h, max = limits.maxMessageBytes) => {
+        if (ctx.typeof(h) !== 'string')
+            throw new SandboxError('protocol', 'expected a string');
+        const s = ctx.getString(h);
+        if (s.length > max)
+            throw new SandboxError('protocol', `message over ${max} bytes`);
+        return s;
+    };
+    const num = (h) => {
+        const n = ctx.typeof(h) === 'number' ? ctx.getNumber(h) : NaN;
+        if (!Number.isFinite(n))
+            throw new SandboxError('protocol', 'expected a number');
+        return n;
+    };
+    const host = ctx.newObject();
+    const fn = (name, f) => {
+        const h = ctx.newFunction(name, (...a) => {
+            try {
+                return f(...a);
+            }
+            catch (e) {
+                // a protocol violation kills; anything else is thrown into the guest
+                if (e instanceof SandboxError)
+                    queueMicrotask(() => kill(e.reason, e.message));
+                return { error: ctx.newError(String(e?.message || e)) };
+            }
+        });
+        ctx.setProp(host, name, h);
+        h.dispose();
+    };
+    fn('render', (h) => {
+        if (renders.length >= 4)
+            throw new SandboxError('protocol', 'too many renders in one call');
+        renders.push(str(h));
+        stats.renders++;
+    });
+    fn('emit', (h) => {
+        // delivered when the guest call returns, after its render (never into a running guest call)
+        if (emits.length >= 64)
+            throw new SandboxError('protocol', 'too many EVENTS in one call');
+        const ev = JSON.parse(str(h, 64 << 10));
+        if (!ev || typeof ev != 'object' || typeof ev.type != 'string')
+            throw new SandboxError('protocol', 'an event needs a string type');
+        emits.push(ev);
+    });
+    fn('log', (lv, h) => {
+        if (++logs > limits.maxLogs)
+            return;
+        const level = str(lv, 16), text = str(h, 4096);
+        if (opts.log)
+            opts.log(level, text);
+        else
+            console[level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'log']('[sandbox]', text);
+    });
+    fn('timer', (idH, msH) => {
+        const id = num(idH), raw = num(msH);
+        // < 0: setImmediate (the core's macrotask hop), counted apart from the component's timers
+        if (raw < 0) {
+            if (immediates >= 16)
+                throw new Error('sandbox: too many setImmediate');
+            immediates++;
+            timers.set(id, setTimeout(() => { immediates--; timers.delete(id); enter('fire', [id]); }, 0));
+            return;
+        }
+        const ms = Math.max(limits.minTimerMs, Math.min(raw, 2 ** 31 - 1));
+        if (timers.size - immediates >= limits.maxTimers)
+            throw new Error(`sandbox: more than ${limits.maxTimers} timers`);
+        timers.set(id, setTimeout(() => { timers.delete(id); enter('fire', [id]); }, ms));
+    });
+    fn('clearTimer', (idH) => {
+        const id = num(idH);
+        clearTimeout(timers.get(id));
+        timers.delete(id);
+    });
+    fn('fetch', (idH, urlH, initH) => {
+        const id = num(idH), url = str(urlH, 4096), init = JSON.parse(str(initH, 256 << 10));
+        const done = (ok, payload) => { fetches.delete(id); if (!dead)
+            enter('resolve', [id, ok ? 1 : 0, payload]); };
+        if (fetches.size >= limits.maxFetches)
+            return void queueMicrotask(() => done(false, 'sandbox fetch denied: too many requests in flight'));
+        const ac = new AbortController();
+        fetches.set(id, ac);
+        capFetch(opts.fetch, url, init, limits.maxMessageBytes, ac.signal)
+            .then((res) => done(true, JSON.stringify(res)), (e) => done(false, `sandbox fetch denied: ${String(e?.message || e)}`));
+    });
+    ctx.setProp(ctx.global, '__host', host);
+    host.dispose();
+    // --- entering the guest -----------------------------------------------------------------------
+    let windowStart = now(), windowMs = 0;
+    const entries = {};
+    function enter(name, args, budget = limits.callMs) {
+        if (dead)
+            return;
+        const t0 = now();
+        deadline = t0 + budget;
+        let out;
+        try {
+            const hs = args.map((a) => (typeof a == 'number' ? ctx.newNumber(a) : ctx.newString(String(a))));
+            const r = ctx.callFunction(entries[name], ctx.undefined, ...hs);
+            hs.forEach((h) => h.dispose());
+            out = settle(r);
+            // the promise jobs (the core's flush is a microtask) run under the same deadline
+            settle(rt.executePendingJobs(10000));
+            if (rt.hasPendingJob())
+                throw new SandboxError('timeout', 'endless promise jobs');
+            // then the tree, once
+            settle(ctx.callFunction(entries.flush, ctx.undefined));
+        }
+        catch (e) {
+            deadline = Infinity;
+            kill(e.reason || classify(e), e.message || String(e));
+            return;
+        }
+        deadline = Infinity;
+        const ms = now() - t0;
+        stats.calls++;
+        stats.guestMs += ms;
+        stats.lastCallMs = ms;
+        if (t0 - windowStart > 1000) {
+            windowStart = t0;
+            windowMs = 0;
+        }
+        if ((windowMs += ms) > limits.cpuShare * 1000) {
+            kill('cpu', `over ${limits.cpuShare * 100}% CPU`);
+            return;
+        }
+        deliver();
+        return out;
+    }
+    function settle(r) {
+        if (r.error) {
+            const e = ctx.dump(r.error);
+            r.error.dispose();
+            const err = new Error(typeof e == 'object' && e ? `${e.name}: ${e.message}` : String(e));
+            err.guest = true;
+            throw err;
+        }
+        const v = ctx.typeof(r.value) === 'number' ? ctx.getNumber(r.value) : undefined;
+        r.value.dispose?.();
+        return v;
+    }
+    function classify(e) {
+        // not the guest's own exception: the host's stack or the WASM gave out mid-call (finding 3)
+        if (!e.guest) {
+            poisoned.add(QJS);
+            crashed = true;
+            return 'crash';
+        }
+        if (/out of memory|stack overflow/i.test(e.message))
+            return 'memory';
+        if (/interrupted/i.test(e.message)) {
+            // near the memory limit every allocation collects the whole heap: that thrash ends as a timeout
+            try {
+                const h = rt.computeMemoryUsage(), m = ctx.dump(h);
+                h.dispose();
+                if (m.memory_used_size > 0.9 * limits.memoryBytes)
+                    return 'memory';
+            }
+            catch { }
+            return 'timeout';
+        }
+        return 'error';
+    }
+    function deliver() {
+        while (renders.length && !dead) {
+            const json = renders.shift();
+            if (!mirror) {
+                opts.onRender?.(json);
+                continue;
+            }
+            try {
+                applyRender(mirror, events, json);
+            }
+            catch (e) {
+                kill('protocol', e.message);
+            }
+        }
+        while (emits.length && !dead)
+            opts.onEmit?.(emits.shift());
+    }
+    // --- lifecycle --------------------------------------------------------------------------------
+    function kill(reason, message) {
+        if (dead)
+            return;
+        dead = true;
+        cleanup();
+        opts.onError?.(new SandboxError(reason, message));
+    }
+    function cleanup() {
+        for (const t of timers.values())
+            clearTimeout(t);
+        for (const ac of fetches.values())
+            ac.abort();
+        timers.clear();
+        fetches.clear();
+        if (mirror) {
+            events.detach();
+            mirror.clear();
+        }
+        // a crashed runtime is leaked: freeing it asserts (an abort that would end the whole module)
+        if (crashed)
+            return;
+        for (const k in entries)
+            entries[k]?.alive && entries[k].dispose();
+        try {
+            ctx.dispose();
+            rt.dispose();
+        }
+        catch {
+            poisoned.add(QJS);
+        }
+    }
+    const t0 = now();
+    deadline = t0 + limits.bootMs;
+    try {
+        settle(ctx.evalCode(opts.kernel, 'sygnal-sandbox-kernel.js'));
+        const sbx = ctx.getProp(ctx.global, '__sandbox');
+        const v = ctx.typeof(sbx) === 'object' ? ctx.getProp(sbx, 'v') : null;
+        const version = v && ctx.typeof(v) === 'number' ? ctx.getNumber(v) : 0;
+        v?.dispose();
+        if (version !== PROTOCOL) {
+            sbx.dispose();
+            throw new SandboxError('protocol', version
+                ? `the kernel speaks protocol ${version}, this sygnal/sandbox ${PROTOCOL}: rebuild it from the installed sygnal`
+                : 'not a sandbox kernel: import it from sygnal/sandbox/kernel?raw through sygnal/vite, or build it with buildSandboxKernel()');
+        }
+        // the kernel's own functions, taken before the component runs (it could replace __sandbox)
+        for (const k of ENTRIES)
+            entries[k] = ctx.getProp(sbx, k);
+        sbx.dispose();
+        settle(ctx.evalCode(opts.source, 'component.js'));
+        deadline = Infinity;
+        if (opts.props !== undefined)
+            enter('props', [JSON.stringify(opts.props)], limits.bootMs);
+        enter('start', [opts.exportName || ''], Math.max(1, limits.bootMs - (now() - t0)));
+    }
+    catch (e) {
+        deadline = Infinity;
+        kill(e.reason || classify(e), e.message);
+    }
+    stats.bootMs = now() - t0;
+    return {
+        stats,
+        get dead() { return dead; },
+        get violations() { return mirror ? mirror.violations : []; },
+        root: mirror ? mirror.root : null,
+        setProps(p) { enter('props', [JSON.stringify(p ?? null)]); },
+        /** an event as if it came from the element with that guest id (tests, benchmarks, the worker) */
+        dispatch(id, type, init = {}) { return enter('dispatch', [id, type, JSON.stringify(init)]); },
+        memory() {
+            if (dead)
+                return null;
+            const h = rt.computeMemoryUsage(), m = ctx.dump(h);
+            h.dispose();
+            return m;
+        },
+        dispose() { if (!dead) {
+            dead = true;
+            cleanup();
+        } },
+    };
+}
+/** one render message onto a mirror (both tiers); throws on a malformed one */
+function applyRender(mirror, events, json) {
+    const msg = JSON.parse(json);
+    if (!msg || typeof msg != 'object' || msg.v !== PROTOCOL)
+        throw new Error('sandbox render: wrong protocol');
+    mirror.apply(msg.tree);
+    events.listen(Array.isArray(msg.types) ? msg.types.map(String) : []);
+    if (typeof msg.f == 'number')
+        mirror.focus(msg.f);
+}
+
+/*
+ * `isolation: 'worker'` (the default, README §9 Q7): QuickJS in a Worker (a browser Worker or
+ * Node's worker_threads), for code that may be hostile. The page keeps the DOM mirror, the fetch
+ * policy and the emits check; the worker runs the engine without a container (worker-entry.ts).
+ * Against the in-thread tier:
+ *   + a hard stop: a watchdog pings the worker and terminate()s it when it doesn't answer in
+ *     `limits.hardMs` (an in-thread deadline can't stop a loop over slow builtins, finding 2);
+ *   + a guest never stalls the page's main thread;
+ *   - events are asynchronous: the guest's preventDefault() can't reach the DOM event (submit and
+ *     link clicks are always prevented; keys the guest handles are declared up front: `preventKeys`);
+ *   - one more hop per event, and a worker per sandbox.
+ */
+const isNode = () => typeof globalThis.process == 'object' && !!globalThis.process.versions?.node && typeof globalThis.Worker == 'undefined';
+/** the worker script that ships with sygnal/sandbox: worker_threads in Node, a module Worker in a browser */
+async function defaultWorker() {
+    if (isNode()) {
+        const [{ Worker }, { fileURLToPath }] = await Promise.all([nodeImport('node:worker_threads'), nodeImport('node:url')]);
+        // the CommonJS build, next to this file (a string the bundlers don't take for an asset)
+        const file = fileURLToPath(import.meta.url.replace(/[^/]*$/, 'sandbox-worker.cjs.js'));
+        const w = new Worker(file);
+        w.unref();
+        return w;
+    }
+    // the pattern Vite and webpack bundle as a worker (with its imports: quickjs and the variant's .wasm)
+    return new Worker(new URL('./sandbox-worker.esm.js', import.meta.url), { type: 'module' });
+}
+function createWorkerEngine(opts) {
+    const limits = opts.limits;
+    const mirror = createMirror(opts.container, { policy: opts.policy, focus: !!opts.focus });
+    const preventKeys = new Set(opts.preventKeys || []);
+    const stats = { readyMs: 0, wasmMs: 0, bootMs: 0, renders: 0 };
+    const queue = [];
+    let w = null, dead = false;
+    let lastPong = performance.now() + limits.bootMs + 2000;
+    const t0 = performance.now();
+    const post = (m) => { if (dead)
+        return; w ? w.postMessage(m) : queue.push(m); };
+    const events = bindEvents(mirror, (id, type, init) => {
+        post({ t: 'event', id, type, init });
+        return /^key/.test(type) && preventKeys.has(init.key);
+    }, (href) => opts.navigate?.(href));
+    let resolveReady, rejectReady;
+    const ready = new Promise((ok, fail) => { resolveReady = ok; rejectReady = fail; });
+    ready.catch(() => { });
+    const watchdog = setInterval(() => {
+        if (performance.now() - lastPong > limits.hardMs)
+            return kill('timeout', `the worker didn't answer in ${limits.hardMs} ms; terminated`);
+        if (w)
+            w.postMessage({ t: 'ping' });
+    }, Math.max(25, limits.hardMs / 4));
+    watchdog.unref?.();
+    async function onMessage(m) {
+        if (dead || !m || typeof m != 'object')
+            return;
+        if (m.t === 'pong')
+            lastPong = performance.now();
+        else if (m.t === 'render') {
+            lastPong = performance.now();
+            try {
+                applyRender(mirror, events, String(m.json));
+                stats.renders++;
+            }
+            catch (e) {
+                kill('protocol', e.message);
+            }
+        }
+        else if (m.t === 'emit')
+            opts.onEmit?.(m.e);
+        else if (m.t === 'log')
+            opts.log ? opts.log(String(m.l), String(m.x).slice(0, 4096)) : console.log('[sandbox]', String(m.x).slice(0, 4096));
+        else if (m.t === 'ready') {
+            if (m.v !== PROTOCOL)
+                return kill('protocol', `the worker speaks protocol ${m.v}, the page ${PROTOCOL}`);
+            lastPong = performance.now();
+            stats.readyMs = performance.now() - t0;
+            stats.wasmMs = +m.wasmMs || 0;
+            stats.bootMs = +m.bootMs || 0;
+            resolveReady();
+        }
+        else if (m.t === 'error')
+            kill(m.reason, String(m.message));
+        else if (m.t === 'fetch') {
+            // the page checks again: the worker's own check ran in a thread the guest shares
+            let res;
+            try {
+                res = { ok: true, res: await capFetch(opts.fetch, String(m.url), m.init || {}, limits.maxMessageBytes) };
+            }
+            catch (e) {
+                res = { ok: false, error: String(e?.message || e) };
+            }
+            post({ t: 'fetched', id: m.id, ...res });
+        }
+    }
+    Promise.resolve()
+        .then(() => (opts.worker || defaultWorker)())
+        .then((worker) => {
+        if (dead)
+            return worker.terminate();
+        w = worker;
+        if (w.on)
+            w.on('message', onMessage);
+        else
+            w.addEventListener('message', (e) => onMessage(e.data));
+        const f = opts.fetch;
+        w.postMessage({
+            t: 'init', v: PROTOCOL, kernel: opts.kernel, source: opts.source, exportName: opts.exportName, props: opts.props, limits, wasm: opts.wasm,
+            fetch: f && { allow: f.allow, methods: f.methods, base: f.base, maxBodyBytes: f.maxBodyBytes },
+        });
+        for (const m of queue.splice(0))
+            w.postMessage(m);
+    })
+        .catch((e) => kill('error', `the worker didn't start: ${e?.message || e}`));
+    function kill(reason, message) {
+        if (dead)
+            return;
+        cleanup();
+        const err = new SandboxError(reason, message);
+        rejectReady(err);
+        opts.onError?.(err);
+    }
+    function cleanup() {
+        dead = true;
+        clearInterval(watchdog);
+        w?.terminate();
+        events.detach();
+        mirror.clear();
+    }
+    return {
+        stats, ready, root: mirror.root,
+        get dead() { return dead; },
+        get violations() { return mirror.violations; },
+        setProps(p) { post({ t: 'props', p: p ?? null }); },
+        dispatch(id, type, init = {}) { post({ t: 'event', id, type, init }); return undefined; },
+        memory() { return null; },
+        dispose() { if (!dead) {
+            cleanup();
+            rejectReady(new SandboxError('error', 'disposed'));
+        } },
+    };
+}
+
+/*
+ * createSandbox(): one untrusted Sygnal component, rendered into the page's real DOM, behind one
+ * API for both tiers (README §8, §9 Q7):
+ *
+ *   isolation: 'worker' (default)  QuickJS in a Worker with a watchdog: for code that may be
+ *                                  hostile (plugins, a marketplace, other tenants)
+ *   isolation: 'thread'            QuickJS on the page's thread with a capped instance: for
+ *                                  model-written code (accidents, prompt injection), not hostile
+ *                                  code: synchronous events (preventDefault works), but a loop over
+ *                                  slow builtins can overrun the deadline by seconds
+ *
+ * The guest's EVENTS reach `onEmit` only when their type is declared in `emits` and the data
+ * passes that type's Standard Schema (README §9 Q3); anything else is dropped (SYG692 in dev).
+ */
+const diag = (code, message, fix, data) => {
+    try {
+        globalThis.__SYGNAL_DIAGNOSTICS__?.report?.(code, { message, fix, severity: 'warn', data });
+    }
+    catch (e) {
+        setTimeout(() => { throw e; });
+    }
+};
+/** the page's gate for the guest's EVENTS: declared types only, data through the type's schema, in order */
+function emitGate(emits, deliver, reject) {
+    let chain = null, warnedNone = false;
+    const declared = emits ? Object.keys(emits) : [];
+    const drop = (type, reason, why, issues) => {
+        diag('SYG692', `sygnal/sandbox: dropped the guest's '${type}' event: ${why}`, "Declare each event type the page accepts in emits, with a Standard Schema for its data: emits={{ ANSWER: schema }}", issues);
+        reject?.({ type, reason, declared, issues: Array.isArray(issues)
+                ? issues.map((i) => ({ path: (i?.path || []).map((p) => (p && typeof p == 'object' ? p.key : p)), message: String(i?.message ?? i) }))
+                : [] });
+    };
+    const check = (ev) => {
+        if (!emits) {
+            if (!warnedNone) {
+                warnedNone = true;
+                drop(ev.type, 'none', 'no emits declared');
+            }
+            return null;
+        }
+        const schema = Object.prototype.hasOwnProperty.call(emits, ev.type) ? emits[ev.type] : undefined;
+        if (!schema) {
+            drop(ev.type, 'undeclared', 'not declared in emits');
+            return null;
+        }
+        const done = (r) => {
+            if (r && r.issues) {
+                drop(ev.type, 'invalid', 'invalid data: ' + r.issues.map((i) => i.message).join('; '), r.issues);
+                return null;
+            }
+            return { type: ev.type, data: r ? r.value : undefined };
+        };
+        try {
+            const r = schema['~standard'].validate(ev.data);
+            return r && typeof r.then == 'function' ? r.then(done, (e) => { drop(ev.type, 'threw', 'its schema threw: ' + (e?.message || e)); return null; }) : done(r);
+        }
+        catch (e) {
+            drop(ev.type, 'threw', 'its schema threw: ' + (e?.message || e));
+            return null;
+        }
+    };
+    return (ev) => {
+        if (!ev || typeof ev.type != 'string')
+            return;
+        const r = check(ev);
+        if (!chain && !(r && typeof r.then == 'function')) {
+            if (r)
+                deliver(r);
+            return;
+        }
+        // an async schema: keep the guest's order
+        const prev = chain || Promise.resolve();
+        const next = prev.then(() => r).then((x) => { if (x)
+            deliver(x); });
+        chain = next;
+        next.then(() => { if (chain === next)
+            chain = null; });
+    };
+}
+function createSandbox(opts) {
+    if (!opts || typeof opts.kernel != 'string' || !opts.kernel)
+        throw new TypeError("sygnal/sandbox: `kernel` is required (import kernel from 'sygnal/sandbox/kernel?raw' with sygnal/vite, or buildSandboxKernel())");
+    if (typeof opts.source != 'string')
+        throw new TypeError('sygnal/sandbox: `source` must be the component compiled to a CommonJS string');
+    const isolation = opts.isolation ?? 'worker';
+    if (isolation !== 'worker' && isolation !== 'thread')
+        throw new TypeError(`sygnal/sandbox: isolation must be 'worker' or 'thread', got ${JSON.stringify(isolation)}`);
+    const limits = limitsOf(opts.limits);
+    if (!opts.container || typeof opts.container.appendChild != 'function')
+        throw new TypeError('sygnal/sandbox: `container` must be an element (renderToHTML renders without one)');
+    const caps = opts.capabilities || {};
+    const gate = emitGate(opts.emits, (ev) => opts.onEmit?.(ev), opts.onReject && ((r) => opts.onReject(r)));
+    let dead = false, failure = null;
+    const onError = (e) => {
+        if (dead)
+            return;
+        dead = true;
+        failure = e;
+        opts.onError?.(e);
+    };
+    const common = {
+        kernel: opts.kernel, source: opts.source, exportName: opts.exportName, props: opts.props, limits,
+        container: opts.container, policy: opts.policy, fetch: caps.fetch, focus: !!caps.focus, navigate: caps.navigate, log: caps.log,
+        onEmit: gate, onError,
+    };
+    if (isolation === 'worker') {
+        const w = createWorkerEngine({ ...common, worker: opts.worker, preventKeys: opts.preventKeys, wasm: opts.wasm });
+        return w;
+    }
+    // thread: an engine now (a module given) or once a fresh capped instance is loaded
+    let e = null, props = opts.props, disposed = false;
+    const boot = (QJS) => {
+        if (disposed)
+            return;
+        e = createEngine(QJS, { ...common, props });
+        if (failure)
+            throw failure;
+    };
+    let ready;
+    try {
+        ready = opts.quickjs ? (boot(opts.quickjs), Promise.resolve()) : loadQuickJS({ maxWasmBytes: limits.maxWasmBytes }).then(boot);
+    }
+    catch (err) {
+        ready = Promise.reject(err);
+    }
+    ready = ready.catch((err) => {
+        const se = err instanceof SandboxError ? err : new SandboxError('error', String(err?.message || err));
+        onError(se);
+        throw failure || se;
+    });
+    ready.catch(() => { });
+    return {
+        ready,
+        get dead() { return dead || disposed || !!e?.dead; },
+        get violations() { return e ? e.violations : []; },
+        get stats() { return e ? e.stats : {}; },
+        setProps(p) { if (e)
+            e.setProps(p);
+        else
+            props = p; },
+        dispose() { disposed = true; e?.dispose(); },
+        memory() { return e ? e.memory() : null; },
+        dispatch(id, type, init) { return e ? e.dispatch(id, type, init) : undefined; },
+    };
+}
+
+/*
+ * <Sandboxed>: a sandboxed component as a JSX tag of the host app, on defineWidget (PLAN-5 W-1).
+ * The host's intent reads the guest's accepted EVENTS as `emit` DOM events on the tag:
+ *
+ *   import kernel from 'sygnal/sandbox/kernel?raw'
+ *   // view:   <Sandboxed className="card" kernel={kernel} source={compiled} emits={{ ANSWER: AnswerSchema }}
+ *   //                    input={{ bill: state.bill }} capabilities={{ fetch: { allow: ['https://api.example.com/v1/'] } }} />
+ *   // intent: ANSWER: DOM.select('.card').events('emit').detail().filter(e => e.type === 'ANSWER').map(e => e.data),
+ *   //         FAILED: DOM.select('.card').events('sandboxerror').detail()
+ *
+ * `input` goes to the guest's PROPS (JSON); a new `source` replaces the sandbox. `sandboxed(defaults)`
+ * makes a tag with props preset (`kernel`, `worker`, `limits`, …).
+ */
+function sandboxed(defaults = {}) {
+    // a prop left undefined keeps its default
+    const merged = (p) => {
+        const o = { ...defaults };
+        for (const k of Object.keys(p))
+            if (p[k] !== undefined)
+                o[k] = p[k];
+        o.capabilities = { ...defaults.capabilities, ...p.capabilities };
+        return o;
+    };
+    const start = (el, props, dispatch) => createSandbox({
+        ...merged(props),
+        container: el,
+        onEmit: (ev) => dispatch('emit', ev),
+        onError: (e) => dispatch('sandboxerror', { reason: e.reason, message: e.message }),
+        props: props.input ?? null,
+    });
+    return defineWidget({
+        tag: 'div',
+        events: ['emit', 'sandboxerror'],
+        mount(el, props, dispatch) {
+            return { sb: start(el, props, dispatch), source: props.source, kernel: merged(props).kernel, input: props.input, dispatch };
+        },
+        update(w, props, el) {
+            if (props.source !== w.source || merged(props).kernel !== w.kernel) {
+                w.sb.dispose();
+                w.sb = start(el, props, w.dispatch);
+                w.source = props.source;
+                w.kernel = merged(props).kernel;
+                w.input = props.input;
+            }
+            else if (props.input !== w.input) {
+                w.input = props.input;
+                w.sb.setProps(props.input ?? null);
+            }
+        },
+        unmount(w) { w.sb.dispose(); },
+    });
+}
+// pure: an app that never renders the tag drops it (and defineWidget's registration with it)
+const Sandboxed = /*#__PURE__*/ sandboxed();
+
+/*
+ * SSR of an untrusted component (edge, multi-tenant): a fresh runtime per call, its first render
+ * printed through the mirror's allowlist (treeToHTML). No DOM anywhere. By default each call gets
+ * its own capped instance too, so tenants share nothing; pass `quickjs` to reuse one module (a
+ * crash then poisons it for every tenant on it: check `poisoned`). This runs on the caller's
+ * thread with the in-thread deadline: for code that may be hostile, call it in a Worker or a
+ * process you can kill.
+ */
+async function renderToHTML(opts) {
+    const limits = limitsOf(opts.limits);
+    const QJS = opts.quickjs || await loadQuickJS({ maxWasmBytes: limits.maxWasmBytes });
+    const t0 = performance.now();
+    let json = null, error = null;
+    const sb = createEngine(QJS, {
+        kernel: opts.kernel, source: opts.source, exportName: opts.exportName, props: opts.props, limits,
+        log: opts.log || (() => { }),
+        onRender: (j) => { json ?? (json = j); },
+        onError: (e) => { error = e; },
+    });
+    sb.dispose();
+    if (error)
+        throw error;
+    if (!json)
+        throw new Error('sygnal/sandbox: the component rendered nothing');
+    return { ...treeToHTML(JSON.parse(json).tree, { policy: opts.policy }), ms: performance.now() - t0 };
+}
+
+/*
+ * generatedRuntime(): the runtime of model-generated parts (experimental, outside semver; research:
+ * dev-plans/research/compose-sandbox). sygnal/ai's `compose.generated(runtime, { data, emits })`
+ * builds the catalog part, the prompt rules and the repair loop on it; this side owns everything
+ * that touches the code: compile, the check before mount, the box, its failures.
+ *
+ *   import kernel from 'sygnal/sandbox/kernel?raw'
+ *   const runtime = generatedRuntime({ kernel, compile: sucraseCompiler(() => import('sucrase')) })
+ *
+ * `runtime.Box` is a widget tag: <Box code emits input isolation maxCode limits policy capabilities checks />.
+ * - `code` is the model's source (an ES module with JSX). It is compiled on the page (`compile`:
+ *   trusted code reading untrusted text) and checked before it mounts: over `maxCode`, a syntax
+ *   error, a JSX event handler (`onClick={…}`: dropped in a Sygnal view, silent) and the app's own
+ *   `check` (sygnal-check, where it can run) fail the part with reason 'compile' and no box boots.
+ *   The kernel checks the wiring at boot (an intent action with no model entry, SYG101: silent
+ *   otherwise): reason 'check'. A new `code` replaces the box in the same element.
+ * - `emits` is required (`{ TYPE: StandardSchema }`): the guest's events go through createSandbox's
+ *   gate; an accepted one is an `emit` event `{ type, data }` (the schema's output), a dropped one a
+ *   `sandboxreject` event `{ type, reason, issues, declared }`.
+ * - Failures are `sandboxerror` events `{ reason, message }`: compile, check, runtime (the guest's
+ *   console.error: the core's SYG406 for a view that throws, SYG216 for a reducer), empty (nothing
+ *   drawn 250 ms after ready), and the sandbox's own (timeout, memory, cpu, protocol, error, crash).
+ *   Ready is `sandboxready` `{ tier, readyMs, bootMs }`.
+ * - Defaults: `isolation: 'worker'`, no capabilities, GENERATED_LIMITS (smaller than a plugin's:
+ *   a part is a card, not an app).
+ */
+/** a generated part's limits: 16 MB heap in a 48 MB instance, boot 500 ms, 50 ms per event */
+const GENERATED_LIMITS = Object.freeze({
+    memoryBytes: 16 << 20, maxWasmBytes: 48 << 20, stackBytes: 256 << 10, bootMs: 500, callMs: 50, hardMs: 1000,
+});
+/** how long a booted box may take to draw before it counts as empty (the core's first render can trail ready) */
+const EMPTY_GRACE_MS = 250;
+const HANDLER = /<[A-Za-z][\w.]*\b[^<>]*?\s(on[A-Z][A-Za-z]*)\s*=\s*\{/;
+const isSchema = (s) => !!s && typeof s == 'object' && typeof s['~standard']?.validate == 'function';
+const msg = (e) => String(e?.message ?? e);
+/** the page's check before mount, with no parser: JSX event handlers, which a Sygnal view drops silently */
+function lintGenerated(code) {
+    const m = HANDLER.exec(code);
+    if (!m)
+        return [];
+    const line = code.slice(0, m.index).split('\n').length;
+    return [`line ${line}: JSX event handlers (${m[1]}) don't run in a Sygnal view; read the event in intent: DOM.select('.cls').events('${m[1].slice(2).toLowerCase()}')`];
+}
+/**
+ * sucraseCompiler(load): `compile` with sucrase (the app's own dependency: sygnal never imports it).
+ * `load` is the module or `() => import('sucrase')`, so the compiler loads with the first part.
+ */
+function sucraseCompiler(load) {
+    let mod = null;
+    return async (code) => {
+        const s = await (mod ?? (mod = Promise.resolve(typeof load == 'function' ? load() : load)));
+        const transform = s.transform || s.default?.transform;
+        return transform(code, { transforms: ['jsx', 'imports'], jsxPragma: '__h', jsxFragmentPragma: '__frag', production: true }).code;
+    };
+}
+function generatedRuntime(o) {
+    if (!o || typeof o.kernel != 'string' || !o.kernel)
+        throw new TypeError("sygnal/sandbox generatedRuntime: `kernel` is required (import kernel from 'sygnal/sandbox/kernel?raw')");
+    if (typeof o.compile != 'function')
+        throw new TypeError("sygnal/sandbox generatedRuntime: `compile` is required, e.g. sucraseCompiler(load), where load is the app's own dynamic import of sucrase");
+    const limits = limitsOf({ ...GENERATED_LIMITS, ...o.limits });
+    const stats = { mounted: 0, live: 0, compiles: 0, compileMs: 0 };
+    /** compile and check: `{ ok, source }`, or `{ ok: false, error }` with what a repair turn needs */
+    async function compile(code, checks = true) {
+        const t0 = performance.now();
+        stats.compiles++;
+        try {
+            const source = await o.compile(code);
+            if (checks) {
+                const issues = [...lintGenerated(code), ...((o.check && (await o.check(code))) || [])];
+                if (issues.length)
+                    return { ok: false, error: issues.join('\n') };
+            }
+            return { ok: true, source };
+        }
+        catch (e) {
+            // a compiler's first lines name line:column
+            return { ok: false, error: msg(e).split('\n').slice(0, 4).join('\n') };
+        }
+        finally {
+            stats.compileMs += performance.now() - t0;
+        }
+    }
+    function start(el, props, dispatch, w) {
+        const gen = w.gen = (w.gen || 0) + 1;
+        w.code = props.code;
+        w.failed = false;
+        w.sb = null;
+        const live = () => w.gen === gen && !w.gone;
+        const fail = (reason, message, stop = false) => {
+            if (w.failed || !live())
+                return;
+            w.failed = true;
+            if (stop)
+                w.sb?.dispose();
+            dispatch('sandboxerror', { reason, message });
+        };
+        const code = String(props.code ?? '');
+        // over the limit is a failure the repair loop hears about, never silently cut code
+        if (props.maxCode && code.length > props.maxCode)
+            return fail('compile', `the code is over the limit of ${props.maxCode} characters; write a shorter part`);
+        api.compile(code, props.checks !== false).then((c) => {
+            if (!live())
+                return;
+            if (!c.ok)
+                return fail('compile', c.error);
+            const lim = props.limits ? limitsOf({ ...limits, ...props.limits }) : limits;
+            const t0 = performance.now();
+            stats.mounted++;
+            stats.live++;
+            let counted = true;
+            const done = () => { if (counted) {
+                counted = false;
+                stats.live--;
+            } };
+            let sb;
+            try {
+                sb = w.sb = createSandbox({
+                    kernel: o.kernel, source: c.source, container: el, isolation: props.isolation ?? 'worker', emits: props.emits, props: props.input ?? null,
+                    limits: lim, policy: props.policy, quickjs: o.quickjs, worker: o.worker, wasm: o.wasm,
+                    capabilities: {
+                        ...props.capabilities,
+                        log: (level, text) => {
+                            if (live()) {
+                                if (level == 'error')
+                                    fail('runtime', text);
+                                else if (level == 'warn' && /^\[Sygnal SYG101\]/.test(text))
+                                    fail('check', text.replace(/^\[Sygnal (SYG\d+)\]\s*/, '$1: '), true);
+                            }
+                            o.log?.(level, text);
+                        },
+                    },
+                    onEmit: (ev) => { if (live())
+                        dispatch('emit', ev); },
+                    onReject: (r) => { if (live())
+                        dispatch('sandboxreject', r); },
+                    onError: (e) => { done(); fail(e.reason, e.message); },
+                });
+            }
+            catch (e) {
+                done();
+                return fail('error', msg(e));
+            }
+            const dispose = sb.dispose.bind(sb);
+            sb.dispose = () => { done(); dispose(); };
+            sb.ready.then(() => {
+                if (w.failed || !live())
+                    return;
+                const s = { tier: props.isolation ?? 'worker', readyMs: performance.now() - t0, bootMs: sb.stats.bootMs || 0 };
+                // drawn: text or a control below the root (a view that returns null leaves an empty root)
+                const drawn = () => { const r = el.querySelector('[data-sandbox-root]'); return !!r && ((r.textContent || '').trim() !== '' || !!r.querySelector('input, select, textarea, img, progress, meter, svg')); };
+                // a view stopped by the boot deadline: the core's error boundary catches QuickJS's
+                // 'interrupted' and the deadline stops its log too, so the box lives on, empty
+                if (s.bootMs >= lim.bootMs * 0.9 && !drawn())
+                    return fail('timeout', `the component ran into the ${lim.bootMs} ms boot deadline (an endless loop?)`, true);
+                if (drawn())
+                    return dispatch('sandboxready', s);
+                // the first render can trail ready (the core's macrotask hop is a host timer): look again
+                setTimeout(() => {
+                    if (w.failed || !live())
+                        return;
+                    drawn() ? dispatch('sandboxready', s) : fail('empty', 'the component rendered nothing', true);
+                }, EMPTY_GRACE_MS);
+            }, () => { });
+        });
+    }
+    const Box = defineWidget({
+        tag: 'div',
+        events: ['emit', 'sandboxready', 'sandboxerror', 'sandboxreject'],
+        ownProps: ['code', 'maxCode', 'emits', 'input', 'isolation', 'limits', 'policy', 'capabilities', 'checks'],
+        mount(el, props, dispatch) {
+            if (!props.emits || typeof props.emits != 'object' || !Object.values(props.emits).every(isSchema)) {
+                throw new TypeError('sygnal/sandbox generated Box: `emits` is required: { TYPE: a Standard Schema } for every event the code may send');
+            }
+            const w = { el, dispatch, inputJson: JSON.stringify(props.input ?? null) };
+            start(el, props, dispatch, w);
+            return w;
+        },
+        update(w, props) {
+            if (props.code !== w.code) {
+                // a repaired or edited part: a new box in the same element
+                w.sb?.dispose();
+                w.inputJson = JSON.stringify(props.input ?? null);
+                return start(w.el, props, w.dispatch, w);
+            }
+            // a host render passes a new input object each time: only a changed value crosses the bridge
+            const json = JSON.stringify(props.input ?? null);
+            if (json !== w.inputJson) {
+                w.inputJson = json;
+                w.sb?.setProps(props.input ?? null);
+            }
+        },
+        unmount(w) { w.gone = true; w.sb?.dispose(); },
+    });
+    // the Box compiles through api.compile, so a wrapper (a cache, a test's spy) sees every mount
+    const api = { Box, compile, limits, stats, kernel: o.kernel };
+    return api;
+}
+
+export { DEFAULT_LIMITS, DEFAULT_POLICY, GENERATED_LIMITS, PROTOCOL, SandboxError, Sandboxed, createSandbox, emitGate, generatedRuntime, lintGenerated, loadQuickJS, poisoned, renderToHTML, sandboxed, sanitize, sucraseCompiler, treeToHTML };
+//# sourceMappingURL=sandbox.esm.js.map