sygnal 7.1.0 → 7.2.0-preview.1

package/src/sandbox/kernel.ts

@@ -0,0 +1,180 @@
+/*
+ * The guest kernel: runs INSIDE the QuickJS context, next to the untrusted component.
+ *
+ * Built as dist/sandbox-kernel.esm.js with 'sygnal' and 'sygnal/host' external; sygnal/vite
+ * (`sygnal/sandbox/kernel?raw`) or buildSandboxKernel() bundles it with the app's installed
+ * sygnal, xstream and snabbdom into one script (D209: never shipped prebuilt), after the
+ * platform prelude (build.ts PLATFORM: timers, console, microtasks; the core's modules read
+ * setTimeout when they load). Nothing here is a security boundary: the component runs in the
+ * same context and can tamper with all of it. The boundary is the bridge (`__host`), which the
+ * page checks (engine.ts, mirror.ts). The kernel only makes the guest side convenient:
+ *
+ *   - the component renders through the real core into a sygnal/host tree (HostDocument);
+ *   - after each entry the tree goes out as JSON (ids from nodeId; a subtree whose revision didn't
+ *     move goes out as its bare id), with the event types the app listens for;
+ *   - events come in as {id, type, init}: the kernel finds the host element, syncs value/checked
+ *     as a browser would have, dispatches a HostEvent and returns whether it was prevented;
+ *   - drivers: DOM (host tree), STATE (the core's own), EVENTS (a bus; each event also goes to the
+ *     page), PROPS (from the page), HTTP (makeFetchDriver over the page's checked fetch).
+ */
+import {run, xs, createElement, makeFetchDriver, ABORT, classes, set, toggle, event, debounce, throttle, delay, dropRepeats, sampleCombine, Collection, Switchable} from '../index'
+import {HostDocument, HostEvent, makeHostDriver, nodeId} from '../host'
+
+const PROTOCOL = 1
+const G: any = globalThis
+const H: any = G.__host
+const timers: Map<number, () => void> = G.__sandboxTimers
+
+// --- the tree going out --------------------------------------------------------------------------
+const doc: any = new HostDocument()
+const byId = new Map<number, any>()   // id → host node (events look elements up)
+const sent = new Map<number, number>() // id → revision last sent
+// {i, t, a, s, v, k, c} for an element, {i, x} for a text, a bare id for an unchanged subtree
+function ser(n: any, out: Map<number, any>): any {
+  const i = nodeId(n)
+  out.set(i, n)
+  if (sent.get(i) === n.revision) { mark(n, out); return i }
+  sent.set(i, n.revision)
+  if (n.nodeType === 3) return {i, x: String(n.textContent)}
+  const a: any = {}
+  for (const [k, v] of n.attributes) a[k] = v
+  const s: any = {}
+  for (const k of Object.keys(n.style)) s[k] = String(n.style[k])
+  const o: any = {i, t: n.localName, a, c: n.childNodes.map((c: any) => ser(c, out))}
+  if (Object.keys(s).length) o.s = s
+  if (/^(input|textarea|select)$/.test(n.localName)) { o.v = n.value; o.k = n.checked }
+  if (n.localName === 'option' && n.selected) o.k = true
+  return o
+}
+// an unchanged subtree's nodes stay addressable
+function mark(n: any, out: Map<number, any>) { if (n.childNodes) for (const c of n.childNodes) { out.set(nodeId(c), c); mark(c, out) } }
+
+let dirty = false, lastMsg = '', focused: any = null
+function flushTree() {
+  dirty = false
+  const out = new Map<number, any>()
+  const tree = doc.body.childNodes.map((c: any) => ser(c, out))
+  byId.clear()
+  for (const [k, v] of out) byId.set(k, v)
+  for (const k of [...sent.keys()]) if (!out.has(k)) sent.delete(k)
+  // the event types to listen for at the sandbox root (delegated, as the DOM driver does)
+  const types = [...new Set([...doc.delegates].map((d: any) => d.type))]
+  const msg: any = {v: PROTOCOL, tree, types}
+  // focus the guest moved (autoFocus, an ELEMENT focus command); the page applies it only with
+  // the focus capability and while focus is inside the box
+  const active = doc.activeElement
+  if (active && active !== focused && byId.has(nodeId(active))) msg.f = nodeId(active)
+  focused = active
+  const json = JSON.stringify(msg)
+  // nothing moved (a change that patched back to what was sent): no message
+  if (json !== lastMsg || tree.some((n: any) => typeof n != 'number')) H.render(lastMsg = json)
+}
+// one render per guest entry: the page calls __sandbox.flush() once the entry's promise jobs ran
+// (a checkbox click changes the tree twice, its checked state, then the patch: one message)
+doc.onChange = () => { dirty = true }
+
+// --- events coming in ----------------------------------------------------------------------------
+const EVENT_FIELDS = /^(key|code|shiftKey|ctrlKey|altKey|metaKey|button|clientX|clientY|deltaX|deltaY|detail)$/
+const props$: any = xs.createWithMemory()
+const fetches = new Map<number, {ok: (v: any) => void; fail: (e: any) => void}>()
+let app: any
+
+G.__sandbox = {
+  v: PROTOCOL,
+  // returns 1 when the guest prevented the default action
+  dispatch(id: number, type: string, initJson: string) {
+    const el = byId.get(id)
+    if (!el || el.nodeType !== 1) return 0
+    const init = JSON.parse(initJson || '{}')
+    if ('value' in init) el.value = init.value
+    if ('checked' in init) el.checked = !!init.checked
+    if (type === 'focus' || type === 'focusin') doc.activeElement = focused = el
+    const e: any = new HostEvent(type, {bubbles: !/^(focus|blur|mouseenter|mouseleave)$/.test(type)})
+    for (const k in init) if (EVENT_FIELDS.test(k)) e[k] = init[k]
+    return el.dispatchEvent(e) ? 0 : 1
+  },
+  flush() { if (dirty || doc.activeElement !== focused) flushTree(); return 0 },
+  fire(id: number) { const f = timers.get(id); timers.delete(id); if (f) f() },
+  resolve(id: number, ok: number, payload: string) {
+    const p = fetches.get(id)
+    fetches.delete(id)
+    if (p) ok ? p.ok(JSON.parse(payload)) : p.fail(new Error(payload))
+  },
+  props(json: string) { props$.shamefullySendNext(JSON.parse(json)) },
+  start(exportName: string) {
+    const mod = G.module.exports
+    const App = exportName ? mod[exportName] : (mod.default || Object.values(mod).find((v) => typeof v == 'function'))
+    if (typeof App != 'function') throw new Error('sandbox: the source exports no component')
+    // a root without state never renders (SYG204); generated code often has none
+    if (App.initialState === undefined) App.initialState = {}
+    wiringCheck(App)
+    app = run(App, {
+      DOM: makeHostDriver(doc, {onError: (e: any) => console.error('patch', String(e?.message || e))}),
+      EVENTS: eventsDriver,
+      PROPS: () => ({stream: props$, get: (k?: string) => props$.map((p: any) => (k ? p?.[k] : p))}),
+      HTTP: makeFetchDriver({fetch: pageFetch as any}),
+    } as any, {useDefaultDrivers: false} as any)
+    return 1
+  },
+  dispose() { app && app.dispose() },
+}
+
+// sygnal-check's SYG101 at boot, on the actions the intent really returns: an action with no model
+// entry does nothing and throws nothing (the core's own check is in the dev build only). Model-written
+// code gets this wrong silently, so the kernel says so; a page may treat the line as a failure
+// (compose.generated does). Behavior actions ('page.COMPOSE') belong to `uses`: not checked.
+function wiringCheck(App: any) {
+  const intent = App.intent, model = App.model
+  if (typeof intent != 'function' || (model != null && typeof model != 'object')) return
+  App.intent = function (this: any, ...args: any[]) {
+    const out = intent.apply(this, args)
+    if (out && typeof out == 'object') {
+      for (const k of Object.keys(out)) {
+        if (k.includes('.') || (model && Object.prototype.hasOwnProperty.call(model, k))) continue
+        console.warn(`[Sygnal SYG101] intent action '${k}' has no model entry, so it never does anything; add '${k}' to model or remove it from intent`)
+      }
+    }
+    return out
+  }
+}
+
+// --- drivers -------------------------------------------------------------------------------------
+// HTTP: the core's own makeFetchDriver over a Response-shaped capability; the page checks the URL
+let fetchSeq = 0
+const pageFetch = (url: string, init: any = {}) => new Promise((ok, fail) => {
+  const id = ++fetchSeq
+  fetches.set(id, {ok, fail})
+  H.fetch(id, String(url), JSON.stringify({method: init.method || 'GET', headers: init.headers || {}, body: typeof init.body == 'string' ? init.body : undefined}))
+}).then((r: any) => ({
+  ok: r.status >= 200 && r.status < 300, status: r.status, statusText: '',
+  headers: {get: (k: string) => r.headers[String(k).toLowerCase()] ?? null},
+  json: async () => JSON.parse(r.body), text: async () => r.body,
+}))
+
+// EVENTS: an in-guest bus (eventBusDriver needs EventTarget); each event also goes to the page,
+// which only delivers the types declared in `emits`, validated by their schemas
+function eventsDriver(out$: any) {
+  const bus: any = xs.create()
+  out$.addListener({
+    next: (ev: any) => {
+      bus.shamefullySendNext(ev)
+      try { H.emit(JSON.stringify({type: String(ev?.type), data: ev?.data})) } catch (e) { console.error('EVENTS: data must be JSON', String(e)) }
+    },
+    error: () => {}, complete: () => {},
+  })
+  return {select: (type?: string | string[]) => bus.filter((ev: any) => !type || ev.type === type || (Array.isArray(type) && type.includes(ev.type))).map((ev: any) => ev.data ?? null)}
+}
+
+// what a component may import: `require('sygnal')` (a compiled `import {ABORT} from 'sygnal'`)
+function Fragment() {}
+;(Fragment as any).__sygnalFragment = true
+const SYGNAL = Object.freeze({xs, createElement, Fragment, ABORT, classes, set, toggle, event, debounce, throttle, delay, dropRepeats, sampleCombine, Collection, Switchable})
+G.require = (name: string) => {
+  if (name === 'sygnal' || name === 'sygnal/jsx') return SYGNAL
+  throw new Error(`sandbox: '${name}' can't be imported here`)
+}
+// the JSX a host compiles guest code to: __h(tag, props, ...children), __frag
+G.__h = createElement
+G.__frag = Fragment
+G.module = {exports: {}}
+G.exports = G.module.exports

package/src/sandbox/mirror.ts

@@ -0,0 +1,269 @@
+/*
+ * 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_-]+$/
+
+export interface MirrorPolicy {
+  maxNodes: number
+  maxDepth: number
+  maxText: number
+  /** origins `<img src>` may load from (an image is a request: an exfiltration channel) */
+  imageOrigins: string[]
+  /** prefix every guest class ('sbx-' → `class="sbx-card"`): the page's CSS no longer applies */
+  classPrefix: string
+  /** the prefix of guest ids (default: a per-sandbox 'sbxN-') */
+  idPrefix?: string
+}
+export const DEFAULT_POLICY: MirrorPolicy = {maxNodes: 5000, maxDepth: 128, maxText: 1 << 20, imageOrigins: [], classPrefix: ''}
+
+type Violate = (what: string) => void
+
+/** one element's attributes and inline style through the allowlist (the mirror and SSR share it) */
+export function sanitize(tag: string, n: any, prefix: string, policy: MirrorPolicy, violate: Violate): {attrs: Map<string, string>; css: string} {
+  const attrs = new Map<string, string>()
+  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: string[] = []
+  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: string, policy: MirrorPolicy) {
+  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: unknown) => String(s).replace(/[&<>"']/g, (c) => ({'&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;'} as any)[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).
+ */
+export function treeToHTML(tree: unknown, opts: {policy?: Partial<MirrorPolicy>; prefix?: string} = {}): {html: string; violations: string[]} {
+  const policy = {...DEFAULT_POLICY, ...opts.policy}, prefix = opts.prefix ?? policy.idPrefix ?? 'sbx-'
+  const violations: string[] = [], violate = (w: string) => { if (violations.length < 100) violations.push(w) }
+  let count = 0, text = 0
+  const out = (n: any, depth: number): string => {
+    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: any) => 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
+
+export function createMirror(container: Element, opts: {policy?: Partial<MirrorPolicy>; focus?: boolean} = {}) {
+  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<number, Node>()   // guest id → real node
+  const idOf = new WeakMap<Node, number>() // real node → guest id
+  const violations: string[] = []
+  const violate = (what: string) => { if (violations.length < 100) violations.push(what) }
+  let count = 0, text = 0, alive = new Set<number>()
+
+  const keepSubtree = (n: Node) => {
+    const i = idOf.get(n)
+    if (i !== undefined) alive.add(i)
+    n.childNodes.forEach(keepSubtree)
+  }
+
+  function build(n: any, depth: number): Node | null {
+    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) as Text | undefined
+      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) as HTMLElement | undefined
+    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 as any
+    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: Node[] = []
+    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: unknown) {
+      count = 0; text = 0; alive = new Set()
+      const top: Node[] = []
+      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: number) {
+      const el = nodes.get(id) as HTMLElement | undefined
+      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: any): number | undefined {
+      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() },
+  }
+}
+export type Mirror = ReturnType<typeof createMirror>
+
+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)`.
+ */
+export function bindEvents(mirror: Mirror, dispatch: (id: number, type: string, init: any) => boolean, navigate?: (href: string) => void) {
+  const root = mirror.root, on = new Map<string, [EventListener, boolean]>()
+  const add = (key: string, l: EventListener, capture = false) => {
+    on.set(key, [l, capture])
+    root.addEventListener(key.replace(/^\$/, ''), l, capture)
+  }
+  function onEvent(e: any) {
+    const id = mirror.idFor(e.target)
+    if (id === undefined) return
+    const t = e.target, init: any = {}
+    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: any) => {
+    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: string[]) {
+      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()
+    },
+  }
+}
+export type EventBinding = ReturnType<typeof bindEvents>

package/src/sandbox/protocol.ts

@@ -0,0 +1,128 @@
+/*
+ * 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}
+ */
+export const PROTOCOL = 1
+
+/** Why a sandbox was killed (`SandboxError.reason`) */
+export type SandboxReason = 'timeout' | 'memory' | 'cpu' | 'protocol' | 'error' | 'crash'
+
+export class SandboxError extends Error {
+  reason: SandboxReason
+  constructor(reason: SandboxReason, message: string) {
+    super(message)
+    this.name = 'SandboxError'
+    this.reason = reason
+  }
+}
+
+export interface SandboxLimits {
+  memoryBytes: number
+  stackBytes: number
+  maxWasmBytes: number
+  bootMs: number
+  callMs: number
+  cpuShare: number
+  hardMs: number
+  maxTimers: number
+  minTimerMs: number
+  maxFetches: number
+  maxMessageBytes: number
+  maxLogs: number
+}
+
+// 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 %
+export const DEFAULT_LIMITS: SandboxLimits = {
+  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) */
+export const MAX_STACK_BYTES = 384 << 10
+
+export function limitsOf(l?: Partial<SandboxLimits>): SandboxLimits {
+  const out = {...DEFAULT_LIMITS}
+  for (const k of Object.keys(l || {}) as (keyof SandboxLimits)[]) {
+    if (!(k in DEFAULT_LIMITS)) continue
+    const v = Number((l as any)[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
+}
+
+export interface FetchCapability {
+  /** URL prefixes ('https://api.example.com/v1/': same origin, a path under it) or RegExps on the href */
+  allow: (string | RegExp)[]
+  /** default ['GET'] */
+  methods?: string[]
+  /** resolves relative URLs */
+  base?: string
+  /** default: globalThis.fetch */
+  impl?: (url: string, init: RequestInit) => Promise<Response>
+  /** default: limits.maxMessageBytes */
+  maxBodyBytes?: number
+}
+
+/** an allowlist entry is a URL prefix: same origin, path under its path */
+export function allowed(u: URL, allow: (string | RegExp)[]): boolean {
+  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.
+ */
+export async function capFetch(f: FetchCapability | undefined, url: string, init: any, maxBytes: number, signal?: AbortSignal) {
+  if (!f) throw new Error('no fetch capability')
+  let u: URL
+  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: Record<string, string> = {}
+  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}
+}

package/src/sandbox/quickjs.ts

@@ -0,0 +1,74 @@
+/*
+ * 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`.
+ */
+import {SandboxError} from './protocol'
+
+let compiled: Promise<WebAssembly.Module> | null = null
+let shared: Promise<any> | null = null
+
+export interface LoadQuickJSOptions {
+  /** the whole linear memory of a fresh instance capped at this (heap, ArrayBuffers, C stack) */
+  maxWasmBytes?: number
+  /** a shared module (one per page) instead of a fresh instance: no ArrayBuffer cap, and one crash poisons it for everyone */
+  shared?: boolean
+  /** another variant (default '@jitl/quickjs-wasmfile-release-sync') */
+  variant?: any
+  /** the .wasm bytes or a compiled WebAssembly.Module (default: the variant's own file) */
+  wasm?: ArrayBuffer | Uint8Array | WebAssembly.Module
+}
+
+const isNode = () => typeof (globalThis as any).process == 'object' && !!(globalThis as any).process.versions?.node && typeof (globalThis as any).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).
+ */
+export async function loadQuickJS(opts: LoadQuickJSOptions = {}): Promise<any> {
+  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}: LoadQuickJSOptions): Promise<any> {
+  let core: any, base: any
+  try {
+    core = await import('quickjs-emscripten-core')
+    base = variant || (await import('@jitl/quickjs-wasmfile-release-sync')).default
+  } catch (e: any) {
+    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: any = {}
+  if (wasm) custom.wasmModule = wasm instanceof WebAssembly.Module ? wasm : await WebAssembly.compile(wasm as any)
+  else if (!variant && isNode()) custom.wasmModule = await (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(): Promise<WebAssembly.Module> {
+  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: string
+  try { file = createRequire(import.meta.url).resolve('@jitl/quickjs-wasmfile-release-sync/wasm') } catch {
+    file = createRequire((globalThis as any).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)
+export const nodeImport = (name: string): Promise<any> => 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.
+ */
+export const poisoned = new WeakSet<object>()
+export const checkModule = (QJS: any) => {
+  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')
+}