sygnal 7.0.0 → 7.2.0-preview.0

package/dist/astro/index.cjs.js

@@ -4,6 +4,8 @@ var fs = require('node:fs');
 var path = require('node:path');
 var node_module = require('node:module');
 var node_url = require('node:url');
+var magicString = require('magic-string');
+var node_stream = require('node:stream');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 /**
@@ -892,6 +894,922 @@ function printGraphUrl(server, available = true) {
     };
 }
 
+/**
+ * CV-2: compiled views, tier A (dev-plans/research/compile-wasm/compiled-views-plan.md). Rewrites a
+ * module's JSX before the JSX transform: an HTML element (not a form field, custom element or SVG
+ * tag) with plain attributes becomes a call to the pragma's `__cv.e(sel, data, children, key)`,
+ * its data made by the pragma's own sanitizeData (`__cv.sd`): once at module load (hoisted) when
+ * every attribute is static, else per render. Everything else (components, markers, fragments,
+ * fields, spreads, refs, ...) is left as JSX for the JSX transform; their children may still
+ * compile. The output vnodes are the ones the pragma would make (test/cv-compile.test.js).
+ *
+ * CV-1 (`ssr`, server builds): the outermost compiled element stays a vnode (`__cvs.r`: the
+ * root's `data-sygnal-ssr` stamp and the SSR walk need one) whose inside is HTML parts made by
+ * ssr.ts (`__cvs.f`, `__cvs.s`): open tags and static subtrees serialized by its own vnodeToHtml
+ * (cached per escaping mode), text escaped by its escapeHtml, anything not compiled (components,
+ * markers, fields, ...) kept as a vnode at the child path the JSX runtime's tree would give it.
+ * The HTML is renderToString's (test/cv-ssr.test.js).
+ *
+ * `parse` is Vite 8's parseAst (ESTree + JSX, UTF-16 offsets). The source map maps each rewritten
+ * JSX expression to its start (magic-string).
+ */
+// the named export: magic-string's CJS build has no plain default for the plugin's CJS output
+// HTML elements the compiler takes. Not here: the form fields (input, textarea, select, option:
+// the controlled-input module re-syncs them; the pragma never makes them plain), SVG and MathML
+// (the pragma sets the namespace), hyphenated custom elements, and any other lowercase tag (a host
+// renderer's own tags go through the pragma, which knows its run-time tag lists)
+const HTML = new Set(('a abbr address article aside audio b bdi bdo blockquote br button canvas caption cite code col colgroup ' +
+    'data datalist dd del details dfn dialog div dl dt em fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 header hgroup hr i ' +
+    'iframe img ins kbd label legend li main map mark menu meter nav noscript object ol optgroup output p picture pre progress q rp rt ' +
+    'ruby s samp search section small source span strong sub summary sup table tbody td template tfoot th thead time tr track u ul var ' +
+    'video wbr').split(' '));
+// attributes the pragma gives run-time behaviour (hooks) or that change what the element is
+const BAIL_ATTR = /^(ref|autoFocus|autoSelect|hook|children|key)$/;
+// in server builds also: the SSR serializer gives these their own content
+const SSR_BAIL_ATTR = /^(innerHTML|textContent)$/;
+// an HTML entity: JSX decodes them, the parser keeps them raw (the pragma path decodes through the JSX transform)
+const ENTITY = /&(#\d+|#x[\da-f]+|[a-z][a-z\d]*);/i;
+function compileViews(code, id, parse, opts = {}) {
+    const ssr = !!opts.ssr, blocks = !ssr && !!opts.blocks;
+    let nblocks = 0;
+    if (!/<[a-z]/.test(code))
+        return null;
+    let ast;
+    try {
+        ast = parse(code, { lang: /\.tsx$/.test(id) ? 'tsx' : /\.ts$/.test(id) ? 'ts' : 'jsx' });
+    }
+    catch {
+        return null;
+    }
+    const hoisted = [];
+    let compiled = 0;
+    // CV-3: the JSX a component (a capitalized function) returns directly: its view's root
+    const roots = new Set();
+    if (blocks) {
+        const un = (n) => n?.type == 'ParenthesizedExpression' ? un(n.expression) : n;
+        const fnRoots = (f) => {
+            if (!f)
+                return;
+            if (f.expression) {
+                roots.add(un(f.body));
+                return;
+            }
+            for (const st of f.body?.body || [])
+                if (st.type == 'ReturnStatement')
+                    roots.add(un(st.argument));
+        };
+        const scan = (n) => {
+            if (!n || typeof n != 'object')
+                return;
+            if (n.type == 'FunctionDeclaration' && /^[A-Z]/.test(n.id?.name || ''))
+                fnRoots(n);
+            if (n.type == 'VariableDeclarator' && /^[A-Z]/.test(n.id?.name || '') && /Function/.test(n.init?.type || ''))
+                fnRoots(n.init);
+            for (const k in n) {
+                if (k == 'start' || k == 'end' || k == 'loc')
+                    continue;
+                const v = n[k];
+                if (Array.isArray(v))
+                    v.forEach(scan);
+                else if (v && typeof v == 'object' && typeof v.type == 'string')
+                    scan(v);
+            }
+        };
+        scan(ast);
+    }
+    const src = (s, e, subs) => {
+        let out = '', at = s;
+        for (const [a, b, t] of subs.sort((x, y) => x[0] - y[0])) {
+            out += code.slice(at, a) + t;
+            at = b;
+        }
+        return out + code.slice(at, e);
+    };
+    // every maximal JSX node under `node`, rewritten (a JSX node in expression position)
+    const subsIn = (node, subs = []) => {
+        if (!node || typeof node != 'object')
+            return subs;
+        if (node.type == 'JSXElement' || node.type == 'JSXFragment') {
+            subs.push([node.start, node.end, jsx(node)]);
+            return subs;
+        }
+        for (const k in node) {
+            if (k == 'start' || k == 'end' || k == 'loc' || k == 'range')
+                continue;
+            const v = node[k];
+            if (Array.isArray(v))
+                for (const c of v)
+                    subsIn(c, subs);
+            else if (v && typeof v == 'object' && typeof v.type == 'string')
+                subsIn(v, subs);
+        }
+        return subs;
+    };
+    const expr = (e) => src(e.start, e.end, subsIn(e));
+    const tag = (el) => el.openingElement.name.type == 'JSXIdentifier' ? el.openingElement.name.name : null;
+    const compilable = (el) => {
+        const t = tag(el);
+        if (!t || !HTML.has(t))
+            return false;
+        for (const a of el.openingElement.attributes) {
+            if (a.type != 'JSXAttribute' || a.name.type != 'JSXIdentifier')
+                return false;
+            if (BAIL_ATTR.test(a.name.name) && a.name.name != 'key' || ssr && SSR_BAIL_ATTR.test(a.name.name))
+                return false;
+            const v = a.value;
+            if (v && v.type == 'Literal' && ENTITY.test(String(v.value)))
+                return false;
+            if (v && v.type != 'Literal' && !(v.type == 'JSXExpressionContainer' && v.expression.type != 'JSXEmptyExpression'))
+                return false;
+        }
+        for (const c of el.children)
+            if (c.type == 'JSXText' && ENTITY.test(c.value) || c.type == 'JSXSpreadChild')
+                return false;
+        return true;
+    };
+    // no expression anywhere below (attributes, children): its HTML never changes (CV-1)
+    const isStatic = (el) => compilable(el)
+        && el.openingElement.attributes.every((a) => !a.value || a.value.type == 'Literal')
+        && el.children.every((c) => c.type == 'JSXText' || c.type == 'JSXElement' && isStatic(c));
+    // a JSX node in expression position: compiled, or JSX whose children may compile
+    // (`vnodes`: inside a static SSR subtree's vnode factory, every element is a client one)
+    let vnodes = 0;
+    const jsx = (node) => node.type == 'JSXElement' && compilable(node)
+        ? (ssr && !vnodes ? ssrRoot(node) : blocks && !vnodes && roots.has(node) && blockable(node) ? block(node) : element(node)) : jsxSource(node);
+    const jsxSource = (node) => {
+        const subs = [];
+        const open = node.openingElement;
+        if (open)
+            for (const a of open.attributes) {
+                const v = a.type == 'JSXSpreadAttribute' ? a.argument : a.value?.type == 'JSXExpressionContainer' ? a.value.expression : null;
+                if (v)
+                    subsIn(v, subs);
+            }
+        for (const c of node.children) {
+            if (c.type == 'JSXElement')
+                subs.push([c.start, c.end, compilable(c) ? '{' + jsx(c) + '}' : jsxSource(c)]);
+            else if (c.type == 'JSXFragment')
+                subs.push([c.start, c.end, jsxSource(c)]);
+            else if (c.type == 'JSXExpressionContainer')
+                subsIn(c.expression, subs);
+        }
+        return src(node.start, node.end, subs);
+    };
+    // the element's data expression and key (a static one hoisted; see __cv in src/pragma/index.ts)
+    const dataOf = (el) => {
+        let key = 'undefined', dynamic = false;
+        const names = [], vals = [];
+        for (const a of el.openingElement.attributes) {
+            const name = a.name.name, v = a.value;
+            const val = !v ? 'true' : v.type == 'Literal' ? JSON.stringify(v.value) : (dynamic = name != 'key' || dynamic, '(' + expr(v.expression) + ')');
+            if (name == 'key')
+                key = val;
+            // a duplicate keeps its first place and takes the last value, as in an object literal
+            else {
+                const i = names.indexOf(name);
+                if (i >= 0)
+                    vals[i] = val;
+                else
+                    names.push(name), vals.push(val);
+            }
+        }
+        // static: made once at load by the pragma's sanitizeData; dynamic: the keys routed once at
+        // load by the pragma's route(), the data made per render from the values (__cv.d)
+        const data = !dynamic ? hoist('__cv.sd({' + names.map((n, i) => JSON.stringify(n) + ': ' + vals[i]).join(', ') + '})')
+            : `__cv.d(${hoist('__cv.r(' + JSON.stringify(names) + ')')}, [${vals.join(', ')}])`;
+        return [data, key, dynamic];
+    };
+    const childArg = (kids) => kids.length == 0 ? 'undefined' : kids.length == 1 ? kids[0] : '[' + kids.join(', ') + ']';
+    const element = (el) => {
+        compiled++;
+        const [data, key] = dataOf(el);
+        const c = childArg(children(el.children, false));
+        return `__cv.e(${JSON.stringify(tag(el))}, ${data}, ${c}${key == 'undefined' ? '' : ', ' + key})`;
+    };
+    // CV-1: the outermost compiled element in server code: a vnode with HTML parts inside
+    const ssrRoot = (el) => {
+        compiled++;
+        const [data, key] = dataOf(el);
+        return `__cvs.r(${JSON.stringify(tag(el))}, ${data}, ${childArg(children(el.children, true))}${key == 'undefined' ? '' : ', ' + key})`;
+    };
+    // CV-1: a compiled element inside one: a static one's HTML made once (per escaping mode), else
+    // its open tag (static: once) and its children's parts
+    const ssrInner = (el) => {
+        compiled++;
+        if (isStatic(el)) {
+            vnodes++;
+            const v = element(el);
+            vnodes--;
+            return `__cvs.s(${hoist('__cvs.S(() => ' + v + ')')})`;
+        }
+        const [data, , dynamic] = dataOf(el), t = JSON.stringify(tag(el));
+        const open = dynamic ? `__cvs.od(${t}, ${data})` : hoist(`__cvs.O(${t}, ${data})`);
+        return `__cvs.f(${open}, ${childArg(children(el.children, true))})`;
+    };
+    // CV-1: JSX in a direct value position of a compiled element's child expression (the expression,
+    // a ?: branch, either side of && || ??, an array element, a .map() arrow's expression body) can
+    // only become that element's child, so a compilable one is an HTML chunk; anything else (JSX in a
+    // variable, a call's argument, a component prop) stays a vnode
+    // (client builds with blocks: a .map() row there is a block, `row`: inside a .map() body)
+    const direct = (n, subs, row = false) => {
+        if (!n)
+            return;
+        const t = n.type;
+        if (t == 'JSXElement' && compilable(n))
+            subs.push([n.start, n.end, ssr ? ssrInner(n) : row && blockable(n) ? block(n) : jsx(n)]);
+        else if (t == 'ParenthesizedExpression')
+            direct(n.expression, subs, row);
+        else if (t == 'ConditionalExpression') {
+            subsIn(n.test, subs);
+            direct(n.consequent, subs, row);
+            direct(n.alternate, subs, row);
+        }
+        else if (t == 'LogicalExpression') {
+            direct(n.left, subs, row);
+            direct(n.right, subs, row);
+        }
+        else if (t == 'ArrayExpression') {
+            for (const e of n.elements)
+                e && (e.type == 'SpreadElement' ? subsIn(e, subs) : direct(e, subs, row));
+        }
+        else if (t == 'CallExpression' && n.callee.type == 'MemberExpression' && !n.callee.computed && n.callee.property.name == 'map'
+            && n.arguments.length == 1 && n.arguments[0].type == 'ArrowFunctionExpression' && n.arguments[0].expression) {
+            subsIn(n.callee, subs);
+            for (const p of n.arguments[0].params)
+                subsIn(p, subs);
+            direct(n.arguments[0].body, subs, true);
+        }
+        else
+            subsIn(n, subs);
+    };
+    // CV-3: a block: compilable all the way down, at least two elements, children only text, text
+    // holes (an expression with no JSX in it; not `children` / `slots`, which are vnodes) and such
+    // elements
+    const SLOTISH = /^(children|slots)$|\.(children|slots)$/;
+    const hasJsx = (n) => {
+        if (!n || typeof n != 'object')
+            return false;
+        if (n.type == 'JSXElement' || n.type == 'JSXFragment')
+            return true;
+        for (const k in n) {
+            if (k == 'start' || k == 'end' || k == 'loc')
+                continue;
+            const v = n[k];
+            if (Array.isArray(v) ? v.some(hasJsx) : v && typeof v == 'object' && typeof v.type == 'string' && hasJsx(v))
+                return true;
+        }
+        return false;
+    };
+    const blockable = (el, top = true) => {
+        if (!compilable(el))
+            return false;
+        let n = 0;
+        const ok = (e) => {
+            if (!compilable(e))
+                return false;
+            n++;
+            for (const c of e.children) {
+                if (c.type == 'JSXElement') {
+                    if (!ok(c))
+                        return false;
+                }
+                else if (c.type == 'JSXExpressionContainer') {
+                    if (c.expression.type == 'JSXEmptyExpression')
+                        continue;
+                    if (hasJsx(c.expression) || SLOTISH.test(code.slice(c.expression.start, c.expression.end).trim()))
+                        return false;
+                }
+                else if (c.type != 'JSXText')
+                    return false;
+            }
+            return true;
+        };
+        return ok(el) && (!top || n >= 2);
+    };
+    const block = (el) => {
+        compiled++;
+        nblocks++;
+        const vals = [], kinds = [];
+        const hole = (k, v) => (kinds.push(k), vals.push(v), `h(${vals.length - 1})`);
+        const [rootData, key] = dataOf(el);
+        hole('r', rootData);
+        const bel = (e, root) => {
+            let d;
+            if (root)
+                d = 'h(0)';
+            else {
+                const [data, , dynamic] = dataOf(e);
+                d = dynamic ? hole('d', data) : data;
+            }
+            const kids = [];
+            for (const c of e.children) {
+                if (c.type == 'JSXText') {
+                    const t = cleanText(c.value);
+                    if (t)
+                        kids.push(JSON.stringify(t));
+                }
+                else if (c.type == 'JSXExpressionContainer') {
+                    if (c.expression.type != 'JSXEmptyExpression')
+                        kids.push(hole('t', '(' + expr(c.expression) + ')'));
+                }
+                else
+                    kids.push(bel(c, false));
+            }
+            return `__cv.e(${JSON.stringify(tag(e))}, ${d}, ${childArg(kids)})`;
+        };
+        const body = bel(el, true);
+        const def = hoist(`__cvb.b((h) => ${body}, ${JSON.stringify(kinds.join(''))})`);
+        return `__cvb.B(${def}, [${vals.join(', ')}]${key == 'undefined' ? '' : ', ' + key})`;
+    };
+    const hoist = (obj) => {
+        const i = hoisted.indexOf(obj);
+        if (i >= 0)
+            return '$cv' + i;
+        hoisted.push(obj);
+        return '$cv' + (hoisted.length - 1);
+    };
+    // the children as the JSX transform passes them: JSX text cleaned as the JSX spec does (lines
+    // trimmed, empty lines dropped, joined by a space), empty expressions dropped
+    const children = (list, html) => {
+        const out = [];
+        for (const c of list) {
+            if (c.type == 'JSXText') {
+                const t = cleanText(c.value);
+                if (t)
+                    out.push(JSON.stringify(t));
+            }
+            else if (c.type == 'JSXExpressionContainer') {
+                const e = c.expression;
+                if (e.type == 'JSXEmptyExpression')
+                    continue;
+                if ((html || blocks) && !vnodes) {
+                    const subs = [];
+                    direct(e, subs);
+                    out.push('(' + src(e.start, e.end, subs) + ')');
+                }
+                else
+                    out.push('(' + expr(e) + ')');
+            }
+            else if (html && !vnodes && c.type == 'JSXElement' && compilable(c))
+                out.push(ssrInner(c));
+            else
+                out.push(jsx(c));
+        }
+        return out;
+    };
+    const subs = subsIn(ast);
+    if (!compiled)
+        return null;
+    const ms = new magicString.MagicString(code);
+    for (const [a, b, t] of subs)
+        ms.overwrite(a, b, t);
+    ms.prepend(`import { __cv${ssr ? ', __cvs' : ''}${nblocks ? ', __cvb' : ''} } from 'sygnal';\n` + hoisted.map((h, i) => `const $cv${i} = ${h};\n`).join(''));
+    return { code: ms.toString(), map: ms.generateMap({ hires: 'boundary', source: id, includeContent: true }) };
+}
+// JSX text as oxc's JSX transform cleans it (the transform the plugin configures): split on line
+// breaks, trim spaces and tabs at each line's edges (not the first line's start nor the last's
+// end), drop empty lines, join with ' '; tabs inside a line stay (Babel would make them spaces)
+function cleanText(value) {
+    const lines = value.split(/\r\n|\n|\r/);
+    let last = 0;
+    for (let i = 0; i < lines.length; i++)
+        if (/[^ \t]/.test(lines[i]))
+            last = i;
+    let str = '';
+    for (let i = 0; i < lines.length; i++) {
+        let line = lines[i];
+        if (i !== 0)
+            line = line.replace(/^[ \t]+/, '');
+        if (i !== lines.length - 1)
+            line = line.replace(/[ \t]+$/, '');
+        if (line) {
+            if (i !== last)
+                line += ' ';
+            str += line;
+        }
+    }
+    return str;
+}
+
+/*
+ * 'sygnal/api' (dev preview; index.ts adds contractFetch: this module imports no diagnostics, so
+ * sygnal/vite can bundle it without a second copy of their state; research: dev-plans/research/fullstack-contracts/): typed clients
+ * for an API whose contract the server already has. A client turns a call into plain data the
+ * existing drivers understand, so effects stay data and replies come back as actions:
+ *
+ * - a GET endpoint → a FetchRequest (`resources`, the query cache, retry, `latest`), tagged
+ *   `api:<id>` so `invalidates: [api.x]` / `{ invalidate: [api.x] }`-style tags can name it;
+ * - any other method → a FetchRequest with a JSON body (reply actions);
+ * - a stream (an oRPC event iterator, or `.sse(path)`) → an SseConnection for `connections`.
+ *
+ * Adapters (one per contract source), all over plain JSON on the wire:
+ * - orpcClient(contract, options): an oRPC contract router served by oRPC's OpenAPIHandler
+ *   (compact input: path params from `{name}` / `{+name}`, the rest in the query for GET with
+ *   bracket notation, else the JSON body). The RPCHandler protocol ({ json, meta }) is not
+ *   supported: its rich serialisation is what the network-calls research ruled out.
+ * - openApiClient<paths>(options): openapi-typescript's `paths` (types only); input is
+ *   openapi-fetch's `{ params: { path, query }, body }`; query arrays repeat the key (form,
+ *   explode), objects use deepObject brackets.
+ * - honoClient<ExtractSchema<typeof app>>(options): Hono routes (types only); input is hc's
+ *   `{ param, query, json }`.
+ *
+ * Each endpoint is a function `(input?, options?) => request` with `id`, `kind`, `method`,
+ * `path` and `match(request)` (renderComponent's t.respond / t.fail take an endpoint as target).
+ * Requests carry `endpoint: id` (an app key: not sent). `options` are the request's own fields
+ * (ok, error, key, latest, cache, retry, ...); `invalidates` takes endpoints or tags.
+ *
+ * Version skew (D: contract hash): contractHash(contract) is a stable hash of the contract (an
+ * oRPC router: ids, routes, JSON Schemas of input/output, error codes; anything else: its
+ * stable JSON). The app sends it in a header of its choice (`headers` option); on the server,
+ * contractSkew(request, { hash, header }) answers a different one with 409 CONTRACT_SKEW (the
+ * oRPC error shape). isContractSkew(failure) tells a reducer; contractFetch() wraps fetch for the
+ * drivers and reports SYG690 once (and calls onSkew) when a reply says the contract changed.
+ */
+// ── oRPC (OpenAPIHandler) ──────────────────────────────────────────────
+const isProcedure = (x) => !!x && typeof x == 'object' && '~orpc' in x && x['~orpc'] && 'route' in x['~orpc'];
+/** the yields schema of an oRPC eventIterator() output schema, or undefined */
+const eventYields = (schema) => {
+    const std = schema?.['~standard'];
+    if (!std)
+        return undefined;
+    const s = Object.getOwnPropertySymbols(std).find(s => s.description === 'ORPC_EVENT_ITERATOR_DETAILS');
+    return s ? std[s].yields ?? {} : undefined;
+};
+/** every procedure of an oRPC contract router: [keys, procedure] */
+const procedures = (router, keys = [], out = [], seen = new Set()) => {
+    if (isProcedure(router))
+        out.push([keys, router]);
+    // a router is plain nested objects: not a schema (a contract module may export those too), no cycles
+    else if (router && typeof router == 'object' && !router['~standard'] && !seen.has(router)) {
+        seen.add(router);
+        Object.keys(router).forEach(k => procedures(router[k], [...keys, k], out, seen));
+    }
+    return out;
+};
+const orpcRoute = (keys, p) => {
+    const def = p['~orpc'];
+    const method = String(def.route.method || 'POST').toUpperCase();
+    const path = def.route.path || '/' + keys.map(encodeURIComponent).join('/');
+    // a manifest (a contract without its schemas, or a server function) says `stream` and `kind`
+    const yields = def.stream ? def.outputSchema || {} : eventYields(def.outputSchema);
+    const kind = yields ? 'stream' : def.kind || (method == 'GET' ? 'query' : 'mutation');
+    return { id: keys.join('.'), def, method, path, yields, kind };
+};
+// ── contract hash and skew ─────────────────────────────────────────────
+const stable = (v) => {
+    if (Array.isArray(v))
+        return '[' + v.map(stable).join(',') + ']';
+    if (v && typeof v == 'object')
+        return '{' + Object.keys(v).sort().map(k => JSON.stringify(k) + ':' + stable(v[k])).join(',') + '}';
+    return JSON.stringify(v) ?? 'null';
+};
+// cyrb53: a fast, well-distributed 53-bit string hash (not cryptographic: this only detects change)
+const cyrb53 = (s) => {
+    let h1 = 0xdeadbeef, h2 = 0x41c6ce57;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        h1 = Math.imul(h1 ^ c, 2654435761);
+        h2 = Math.imul(h2 ^ c, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+};
+/** a schema's JSON Schema (Standard JSON Schema), else its vendor: what the hash can see of it */
+const schemaShape = (s, io) => {
+    const std = s?.['~standard'];
+    if (!std)
+        return null;
+    try {
+        if (std.jsonSchema?.[io])
+            return std.jsonSchema[io]({ target: 'draft-2020-12', libraryOptions: { unrepresentable: 'any' } });
+    }
+    catch (_) { /* a schema it can't represent: the vendor below */ }
+    return std.vendor || 'schema';
+};
+function contractHash(contract) {
+    // a manifest made at build time (sygnal/vite's api.contracts) carries its hash
+    if (contract && typeof contract['~hash'] == 'string')
+        return contract['~hash'];
+    const ps = procedures(contract);
+    if (!ps.length)
+        return cyrb53(stable(contract));
+    const shape = ps.map(([keys, p]) => {
+        const r = orpcRoute(keys, p);
+        return [r.id, r.method, r.path, r.kind, schemaShape(r.def.inputSchema, 'input'),
+            r.yields ? schemaShape(r.yields, 'output') : schemaShape(r.def.outputSchema, 'output'),
+            Object.keys(r.def.errorMap || {}).sort()];
+    }).sort((a, b) => (a[0] < b[0] ? -1 : 1));
+    return cyrb53(stable(shape));
+}
+// ── build time: a contract without its schemas ─────────────────────────
+/**
+ * sygnal/vite's `api.contracts`: what a client needs of a contract (routes, kinds, error codes and
+ * statuses) and its hash, so the client bundle has no schema library. Plain JSON (`~hash` aside).
+ */
+function contractManifest(contract) {
+    const count = procedures(contract).length;
+    if (!count)
+        return { manifest: undefined, hash: '', count };
+    const walk = (node, keys) => {
+        if (isProcedure(node)) {
+            const r = orpcRoute(keys, node);
+            const errorMap = {};
+            Object.keys(r.def.errorMap || {}).forEach(c => { errorMap[c] = { status: r.def.errorMap[c]?.status }; });
+            const route = { method: r.method, path: r.path };
+            if (r.def.route.inputStructure)
+                route.inputStructure = r.def.route.inputStructure;
+            return { '~orpc': { route, kind: r.kind, stream: r.kind == 'stream', manifest: true, errorMap } };
+        }
+        const out = {};
+        Object.keys(node || {}).forEach(k => { if (procedures(node[k]).length)
+            out[k] = walk(node[k], [...keys, k]); });
+        return out;
+    };
+    return { manifest: walk(contract, []), hash: contractHash(contract), count };
+}
+// ── function-first: *.server.ts modules ────────────────────────────────
+/*
+ * A `*.server.ts` file exports query(input, fn), mutation(input, fn) and stream(input, fn). Its
+ * path and export names are the contract: `src/quotes.server.ts` → `export const list` is
+ * `quotes.list`, POST /quotes/list (a stream: GET, read as server-sent events). sygnal/vite
+ * (`api: { functions: true }`) replaces the file in the client by stubs that build the requests,
+ * so nothing of it but its export names, kinds and error codes reaches the bundle; on the
+ * server, serverFunctions(import.meta.glob(...), { os }) makes the oRPC router to mount.
+ * Input is always validated (a Standard Schema, or none: then only an empty input passes), the
+ * wire is plain JSON (oRPC's OpenAPIHandler), and only module exports are functions (no closures
+ * over component scope, no ids made from a closure).
+ */
+const FN = '~sygnal';
+/** `src/admin/users.server.ts` (or `/src/...`, `../src/...`) → `admin/users` */
+const fnNamespace = (file, dir = 'src') => {
+    let f = file.split('?')[0].replace(/\\/g, '/').replace(/^(\.{1,2}\/)+|^\/+/, '');
+    const d = dir.replace(/^\.?\/+|\/+$/g, '');
+    if (d && f.startsWith(d + '/'))
+        f = f.slice(d.length + 1);
+    return f.replace(/\.server\.[cm]?[jt]sx?$/, '');
+};
+const fnSpec = (id, kind, errors, schemas) => ({ '~orpc': {
+        route: { method: kind == 'stream' ? 'GET' : 'POST', path: '/' + id.split('.').map(encodeURIComponent).join('/') },
+        kind, stream: kind == 'stream', manifest: !schemas, errorMap: errors,
+        inputSchema: schemas?.input, outputSchema: schemas?.output,
+    } });
+/** each file's server functions: its namespace, its own contract tree (for the hash), [name, meta] */
+function fnFiles(modules, dir = 'src') {
+    return Object.keys(modules).sort().map(file => {
+        const ns = fnNamespace(file, dir);
+        const keys = ns.split('/');
+        const tree = {};
+        let node = tree;
+        keys.forEach(k => { node = node[k] = {}; });
+        const fns = [];
+        Object.keys(modules[file] || {}).forEach(name => {
+            const meta = modules[file][name]?.[FN];
+            if (!meta)
+                return;
+            const id = [...keys, name].join('.');
+            node[name] = Object.assign(fnSpec(id, meta.kind, meta.errors, meta), { [FN]: meta });
+            fns.push([name, meta]);
+        });
+        return { file, ns, keys, tree, fns, hash: contractHash(tree) };
+    });
+}
+
+/**
+ * sygnal/vite's `api` option (sygnal/api, dev preview; research: dev-plans/research/fullstack-contracts/):
+ *
+ * - `handler`: in dev, requests under `prefix` go to that module's default export, a Fetch handler
+ *   (Request → Response): the same module a production server mounts. The plugin only bridges
+ *   Node's request to it; the server is the app's own (oRPC), never one of Sygnal's.
+ * - `contracts`: in client code (dev and build, never Vitest) each listed contract module is
+ *   replaced by what orpcClient needs of it (routes, kinds, error codes and statuses) with its
+ *   contractHash computed at build time, so the bundle has no schema library. The module is
+ *   evaluated on the server side (the dev server's SSR loader; for `vite build` a temporary one).
+ *   An export that is no contract is left out, so a client import of a schema from it fails
+ *   loudly (keep the module out of `contracts` to validate on the client).
+ * - `functions`: `*.server.ts` files under `dir` (function-first). In client code a file becomes
+ *   stubs: `export const list = __serverFunction('quotes.list', { kind, errors }, client)`, plus
+ *   the file's contract hash in the stub header. Nothing else of the file (its imports, secrets,
+ *   handler bodies) is in the client graph. In server code and under Vitest the file keeps its
+ *   code and each export gets its id appended, so tests can call it as an endpoint.
+ */
+// @ts-ignore
+const SERVER_FILE = /\.server\.[cm]?[jt]sx?$/;
+// set while the temporary build-time server loads the config: its own sygnal() then adds no api plugin
+const NESTED = '__SYGNAL_API_EVAL__';
+const g = globalThis;
+const nodeProcess$1 = g.process;
+function apiPlugin(o) {
+    if (g[NESTED])
+        return null;
+    const prefix = (o.prefix ?? '/api').replace(/\/+$/, '');
+    const fo = o.functions === true ? {} : o.functions || null;
+    const dir = (fo && fo.dir) || 'src';
+    const header = (fo && fo.header) || 'x-api-functions';
+    let root = nodeProcess$1.cwd();
+    let isVitest = false;
+    let config;
+    let dev;
+    let temp;
+    const rel = (file) => path.relative(root, file).split(path.sep).join('/');
+    const contractFiles = () => new Set((o.contracts || []).map((f) => path.resolve(root, f)));
+    const isFnFile = (file) => {
+        if (!fo || !SERVER_FILE.test(file) || file.includes('/node_modules/'))
+            return false;
+        const r = rel(file);
+        return !r.startsWith('..') && (r + '/').startsWith(dir.replace(/^\.?\/+|\/+$/g, '') + '/');
+    };
+    // evaluates a module on the server side: the dev server's SSR loader, or (vite build) a temporary one
+    async function load(file) {
+        if (dev)
+            return dev.ssrLoadModule(file);
+        temp ?? (temp = (async () => {
+            const vite = await import(/* @vite-ignore */ projectVite(root));
+            g[NESTED] = true;
+            try {
+                return await vite.createServer({
+                    root, mode: config?.mode, configFile: config?.configFile ?? false, logLevel: 'warn', appType: 'custom',
+                    server: { middlewareMode: true, hmr: false, ws: false, watch: null },
+                    optimizeDeps: { noDiscovery: true, include: [] },
+                });
+            }
+            finally {
+                delete g[NESTED];
+            }
+        })());
+        return (await temp).ssrLoadModule(file);
+    }
+    const exportLine = (name, value) => (name === 'default' ? `export default ${value};` : `export const ${name} = ${value};`);
+    return {
+        name: 'vite-plugin-sygnal:api',
+        config() {
+            isVitest = !!nodeProcess$1?.env?.VITEST;
+        },
+        configResolved(c) {
+            config = c;
+            root = c.root;
+        },
+        configureServer(server) {
+            dev = server;
+            if (!o.handler || isVitest)
+                return;
+            const handlerFile = path.resolve(root, o.handler);
+            server.middlewares.use(async (req, res, next) => {
+                const url = req.url || '';
+                if (!(url === prefix || url.startsWith(prefix + '/') || url.startsWith(prefix + '?')))
+                    return next();
+                try {
+                    const mod = await server.ssrLoadModule(handlerFile);
+                    const handle = typeof mod.default === 'function' ? mod.default : mod.default?.fetch ?? mod.fetch;
+                    if (typeof handle !== 'function')
+                        throw new Error(`[sygnal] api.handler (${o.handler}) must export default a Fetch handler: (request: Request) => Response`);
+                    const ctl = new AbortController();
+                    res.on('close', () => ctl.abort());
+                    const body = req.method === 'GET' || req.method === 'HEAD' ? undefined : node_stream.Readable.toWeb(req);
+                    const request = new Request(new URL(url, 'http://' + (req.headers.host || 'localhost')), {
+                        method: req.method, headers: req.headers, body, signal: ctl.signal, ...(body && { duplex: 'half' }),
+                    });
+                    const response = await handle(request);
+                    res.writeHead(response.status, Object.fromEntries(response.headers));
+                    if (!response.body)
+                        return void res.end();
+                    node_stream.Readable.fromWeb(response.body).pipe(res);
+                }
+                catch (e) {
+                    next(e);
+                }
+            });
+        },
+        async transform(code, id, opts) {
+            const file = id.split('?')[0];
+            if (id.startsWith('\0'))
+                return null;
+            const client = !opts?.ssr && !isVitest;
+            if (client && o.contracts && contractFiles().has(file)) {
+                const mod = await load(file);
+                const out = [];
+                Object.keys(mod).forEach((name) => {
+                    const { manifest, hash, count } = contractManifest(mod[name]);
+                    if (!count)
+                        return;
+                    out.push(exportLine(name, `Object.defineProperty(${JSON.stringify(manifest)}, '~hash', { value: ${JSON.stringify(hash)} })`));
+                });
+                return { code: `// ${rel(file)}: routes and hash only (sygnal/vite api.contracts)\n${out.join('\n')}\n`, map: { mappings: '' } };
+            }
+            if (!isFnFile(file))
+                return null;
+            if (client) {
+                const [f] = fnFiles({ [rel(file)]: await load(file) }, dir);
+                const opts = JSON.stringify({ prefix, headers: { [header]: `${f.ns}:${f.hash}` } });
+                const lines = f.fns.map(([name, meta]) => {
+                    const errors = {};
+                    Object.keys(meta.errors || {}).forEach((c) => { errors[c] = { status: meta.errors[c]?.status }; });
+                    return exportLine(name, `__serverFunction(${JSON.stringify(f.keys.concat(name).join('.'))}, ${JSON.stringify({ kind: meta.kind, errors })}, __o)`);
+                });
+                return {
+                    code: `// ${rel(file)}: client stubs (sygnal/vite api.functions)\nimport { __serverFunction } from 'sygnal/api';\nconst __o = ${opts};\n${lines.join('\n')}\n`,
+                    map: { mappings: '' },
+                };
+            }
+            // server code and tests: the module as written, each export given its id
+            const ns = fnNamespace(rel(file), dir);
+            const named = exportedLocals(this.parse(code));
+            if (!named.length)
+                return null;
+            const keys = ns.split('/');
+            const tail = named.map(([exp, local]) => `__sygnalFn(${JSON.stringify(keys.concat(exp).join('.'))}, ${local}, ${JSON.stringify({ prefix })});`);
+            return { code: `${code}\nimport { __serverFunction as __sygnalFn } from 'sygnal/api';\n${tail.join('\n')}\n`, map: null };
+        },
+        async closeBundle() {
+            if (temp) {
+                const s = await temp;
+                temp = undefined;
+                await s.close();
+            }
+        },
+    };
+}
+/** [exported name, local binding] of a module's own named exports (declarations and `export { a as b }`) */
+function exportedLocals(ast) {
+    const out = [];
+    for (const node of ast.body || []) {
+        if (node.type !== 'ExportNamedDeclaration' || node.source)
+            continue;
+        const d = node.declaration;
+        if (d?.type === 'VariableDeclaration')
+            d.declarations.forEach((x) => x.id?.type === 'Identifier' && out.push([x.id.name, x.id.name]));
+        else if (d?.id?.name)
+            out.push([d.id.name, d.id.name]);
+        for (const s of node.specifiers || []) {
+            const exp = s.exported?.name ?? s.exported?.value;
+            if (s.local?.name && exp)
+                out.push([exp, s.local.name]);
+        }
+    }
+    return out;
+}
+/** the project's own Vite (not one next to sygnal), as an ESM URL */
+function projectVite(root) {
+    const req = node_module.createRequire(path.join(root, 'package.json'));
+    const pj = req.resolve('vite/package.json');
+    const pkg = JSON.parse(fs.readFileSync(pj, 'utf8'));
+    const dot = typeof pkg.exports === 'string' ? pkg.exports : pkg.exports?.['.'];
+    let entry = typeof dot === 'string' ? dot : dot?.import ?? pkg.module ?? pkg.main;
+    if (entry && typeof entry === 'object')
+        entry = entry.default;
+    return node_url.pathToFileURL(path.join(path.dirname(pj), entry)).href;
+}
+
+/*
+ * 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`.
+ */
+// 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);
+
+/*
+ * The guest kernel, built from the app's installed packages (README §7 option (a), §9 Q1; D209:
+ * Sygnal's npm package never ships xstream or snabbdom prebuilt into it). sygnal/vite resolves
+ * `sygnal/sandbox/kernel?raw` to this function's output (the project's own Vite), and
+ * `buildSandboxKernel()` (sygnal/sandbox/build) does it for other toolchains (Vite, esbuild or
+ * Rollup, whichever the project has).
+ *
+ * The output is one script: the platform prelude (timers, console, microtasks on `__host`,
+ * which the core's modules read when they load), then dist/sandbox-kernel.esm.js bundled as an
+ * IIFE with the installed sygnal (dist/index.esm.js and dist/host.esm.js of the same package: one
+ * core), xstream and snabbdom. `process.env.NODE_ENV` is 'production'; xstream's `globalthis`
+ * dependency is Sygnal's shim (as sygnal/vite does, G-099).
+ */
+// The platform a bare QuickJS context lacks. A plain script, so it runs before the bundle's modules.
+const PLATFORM = `var global = globalThis;
+(function () {
+  var H = globalThis.__host, G = globalThis, timers = new Map(), intervals = new Map(), seq = 0;
+  G.__sandboxTimers = timers;
+  G.queueMicrotask = G.queueMicrotask || function (f) { Promise.resolve().then(f) };
+  G.setTimeout = function (f, ms) { var id = ++seq; timers.set(id, f); H.timer(id, +ms || 0); return id };
+  G.clearTimeout = function (id) { if (timers.delete(id)) H.clearTimer(id) };
+  // the core's macrotask hop (runtime.ts macro()): its own channel, so a component's timers can't starve it
+  G.setImmediate = function (f) { var id = ++seq; timers.set(id, f); H.timer(id, -1); return id };
+  G.clearImmediate = G.clearTimeout;
+  G.setInterval = function (f, ms) { var box = {}; var tick = function () { box.id = G.setTimeout(tick, ms); f() }; box.id = G.setTimeout(tick, ms); var id = ++seq; intervals.set(id, box); return id };
+  G.clearInterval = function (id) { var b = intervals.get(id); if (b) { intervals.delete(id); G.clearTimeout(b.id) } };
+  G.requestAnimationFrame = function (f) { return G.setTimeout(function () { f(Date.now()) }, 16) };
+  G.cancelAnimationFrame = G.clearTimeout;
+  var fmt = function (a) { return a.map(function (x) { if (typeof x == 'string') return x; if (x instanceof Error) return x.name + ': ' + x.message; try { return JSON.stringify(x) } catch (e) { return String(x) } }).join(' ') };
+  G.console = {
+    log: function () { H.log('log', fmt([].slice.call(arguments))) }, info: function () { H.log('log', fmt([].slice.call(arguments))) },
+    warn: function () { H.log('warn', fmt([].slice.call(arguments))) }, error: function () { H.log('error', fmt([].slice.call(arguments))) },
+    debug: function () {},
+  };
+})();
+`;
+/** The guest kernel script for createSandbox / <Sandboxed> (`kernel`), built from the installed packages */
+async function buildSandboxKernel(opts = {}) {
+    const [path, { createRequire }, { pathToFileURL }, fs] = await Promise.all([nodeImport('node:path'), nodeImport('node:module'), nodeImport('node:url'), nodeImport('node:fs')]);
+    const root = path.resolve(opts.root || globalThis.process.cwd());
+    const fromRoot = createRequire(path.join(root, 'package.json'));
+    // the app's sygnal (else this one): its dist/ holds the kernel entry, the core and the kit
+    let main;
+    try {
+        main = fromRoot.resolve('sygnal');
+    }
+    catch {
+        main = createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs.js', document.baseURI).href))).resolve('sygnal');
+    }
+    const dist = path.dirname(main);
+    const entry = path.join(dist, 'sandbox-kernel.esm.js');
+    const files = {
+        sygnal: path.join(dist, 'index.esm.js'),
+        'sygnal/host': path.join(dist, 'host.esm.js'),
+        globalthis: path.join(dist, 'shims/globalthis.cjs'),
+    };
+    for (const f of [entry, ...Object.values(files)])
+        if (!fs.existsSync(f))
+            throw new Error(`buildSandboxKernel: ${f} is missing (an incomplete sygnal install?)`);
+    const minify = opts.minify !== false;
+    const define = { 'process.env.NODE_ENV': '"production"' };
+    const has = (name) => { try {
+        fromRoot.resolve(name);
+        return true;
+    }
+    catch {
+        return false;
+    } };
+    const want = opts.bundler || 'auto';
+    const bundler = want !== 'auto' ? want : has('vite') ? 'vite' : has('esbuild') ? 'esbuild' : has('rollup') ? 'rollup' : null;
+    if (!bundler)
+        throw new Error('buildSandboxKernel: needs vite, esbuild or rollup installed in ' + root);
+    const load = (name) => import(/* @vite-ignore */ pathToFileURL(resolveEsm(fromRoot, fs, path, name)).href);
+    let code;
+    if (bundler === 'esbuild') {
+        const esbuild = await load('esbuild');
+        const r = await (esbuild.build || esbuild.default.build)({
+            entryPoints: [entry], bundle: true, write: false, format: 'iife', platform: 'browser', target: 'es2020',
+            minify, define, alias: files, logLevel: 'silent', legalComments: 'none',
+        });
+        code = r.outputFiles[0].text;
+    }
+    else if (bundler === 'rollup') {
+        const { rollup } = await load('rollup');
+        const plugins = [{
+                name: 'sygnal-kernel', resolveId: (id) => files[id] || null,
+                transform: (c) => (c.includes('process.env.NODE_ENV') ? c.split('process.env.NODE_ENV').join(define['process.env.NODE_ENV']) : null),
+            }];
+        const req = async (n) => { const m = await load(n); return m.default || m; };
+        if (has('@rollup/plugin-node-resolve'))
+            plugins.push((await load('@rollup/plugin-node-resolve')).nodeResolve({ browser: true }));
+        if (has('@rollup/plugin-commonjs'))
+            plugins.push((await req('@rollup/plugin-commonjs'))());
+        if (minify && has('@rollup/plugin-terser'))
+            plugins.push((await req('@rollup/plugin-terser'))({ ecma: 2020 }));
+        const b = await rollup({ input: entry, plugins, onwarn: () => { } });
+        code = (await b.generate({ format: 'iife', name: '__sygnalKernel' })).output[0].code;
+        await b.close();
+    }
+    else {
+        const vite = await load('vite');
+        const out = await vite.build({
+            configFile: false, root, logLevel: 'silent', mode: 'production', define,
+            resolve: { alias: Object.entries(files).map(([find, replacement]) => ({ find: new RegExp(`^${find.replace('/', '\\/')}$`), replacement })) },
+            build: { write: false, minify, target: 'es2020', lib: { entry, formats: ['iife'], name: '__sygnalKernel', fileName: () => 'kernel.js' }, rollupOptions: { output: { inlineDynamicImports: true } } },
+        });
+        const o = (Array.isArray(out) ? out[0] : out).output;
+        code = o.find((c) => c.type === 'chunk').code;
+    }
+    return PLATFORM + code;
+}
+// a package's ESM entry, as resolved from the app (import() needs a file URL, not a bare name, to resolve from there)
+function resolveEsm(req, fs, path, name) {
+    try {
+        const pj = req.resolve(`${name}/package.json`);
+        const pkg = JSON.parse(fs.readFileSync(pj, 'utf8'));
+        const dot = typeof pkg.exports == 'string' ? pkg.exports : pkg.exports?.['.'];
+        let e = typeof dot == 'string' ? dot : dot?.import ?? pkg.module ?? pkg.main ?? 'index.js';
+        if (e && typeof e == 'object')
+            e = e.default;
+        return path.join(path.dirname(pj), e);
+    }
+    catch {
+        return req.resolve(name);
+    }
+}
+
+/**
+ * sygnal/sandbox's guest kernel in sygnal/vite (README §7 (a), D209): `import kernel from
+ * 'sygnal/sandbox/kernel?raw'` (or without `?raw`) resolves to a module whose default export is
+ * the kernel script, built once per server or build with the project's own Vite from the
+ * installed sygnal, xstream and snabbdom (src/sandbox/build.ts). Nothing is shipped prebuilt.
+ */
+const SANDBOX_KERNEL = /^sygnal\/sandbox\/kernel(\?raw)?$/;
+const SANDBOX_KERNEL_ID = '\0sygnal-sandbox-kernel';
+const built = new Map();
+async function sandboxKernelModule(root) {
+    if (!built.has(root))
+        built.set(root, buildSandboxKernel({ root, bundler: 'vite' }));
+    return `// sygnal/sandbox's guest kernel, built from the installed packages (sygnal/vite)\nexport default ${JSON.stringify(await built.get(root))};\n`;
+}
+
 /**
  * Sygnal Vite Plugin
  *
@@ -1114,7 +2032,41 @@ function sygnal(options = {}) {
     let devSnippet = devtoolsImport + (devOn ? flags + devImports : '');
     const devInject = devOn || devtoolsOn;
     let astroClient;
-    return {
+    // CV-2: its own plugin, before Vite's JSX transform (this plugin's transform runs after it)
+    let warnedCompile = false;
+    const co = options.compile === true ? {} : options.compile || null;
+    const compileOn = (k) => !!co && co[k] !== false;
+    // (its own Vitest flag: it may be used without the main plugin, e.g. added to a config that already
+    // has sygnal())
+    let cVitest = false;
+    const compilePlugin = co && {
+        name: 'vite-plugin-sygnal:compile',
+        enforce: 'pre',
+        config() {
+            cVitest = !!nodeProcess?.env?.VITEST;
+        },
+        transform(code, id, opts) {
+            const isVitest = cVitest;
+            const file = id.split('?')[0];
+            if (!/\.[jt]sx$/.test(file) || file.includes('/node_modules/') || id.startsWith('\0'))
+                return null;
+            if (isVitest && !compileOn('test'))
+                return null;
+            // server code renders to strings (never under Vitest: renderComponent's mock DOM needs vnodes)
+            const ssr = !!opts?.ssr && !isVitest && compileOn('ssr');
+            if (!ssr && !compileOn('views'))
+                return null;
+            if (viteMajor(this, root) < 8) {
+                if (!warnedCompile) {
+                    warnedCompile = true;
+                    this.warn('[sygnal] `compile` needs Vite 8; views are not compiled');
+                }
+                return null;
+            }
+            return compileViews(code, file, (c, o) => this.parse(c, o), { ssr, blocks: !ssr && compileOn('blocks') });
+        },
+    };
+    const main = {
         name: 'vite-plugin-sygnal',
         config(config, env) {
             isServe = env.command === 'serve';
@@ -1191,7 +2143,9 @@ function sygnal(options = {}) {
                 const include = result.optimizeDeps?.include || [];
                 result.optimizeDeps = {
                     ...result.optimizeDeps,
-                    exclude: [VIKE_CLIENT],
+                    // sygnal/sandbox: its worker script is found by `new URL(..., import.meta.url)`, which
+                    // only works served unbundled
+                    exclude: [VIKE_CLIENT, 'sygnal/sandbox'],
                     ...(sygnalInNodeModules(root) ? { include: [...include, 'sygnal'] } : {}),
                 };
             }
@@ -1222,6 +2176,9 @@ function sygnal(options = {}) {
         resolveId: {
             order: 'pre',
             async handler(source, importer, opts) {
+                // sygnal/sandbox: the guest kernel, built from the installed packages (every mode)
+                if (SANDBOX_KERNEL.test(source))
+                    return SANDBOX_KERNEL_ID;
                 if (!isServe || isVitest)
                     return null;
                 if (source === DEV_CLIENT)
@@ -1248,6 +2205,8 @@ function sygnal(options = {}) {
             },
         },
         load(id) {
+            if (id === SANDBOX_KERNEL_ID)
+                return sandboxKernelModule(root);
             if (id === DEV_CLIENT_ID)
                 return devClientModule();
             if (id === MCP_CLIENT_ID && mcpOn)
@@ -1316,6 +2275,9 @@ function sygnal(options = {}) {
             });
         },
     };
+    const api = options.api ? apiPlugin(options.api) : null;
+    const plugins = [compilePlugin, main, api].filter(Boolean);
+    return plugins.length > 1 ? plugins : main;
     function devTransform(code, id, opts) {
         if (!isServe)
             return null;
@@ -1474,10 +2436,12 @@ const ADAPTER_PEERS = {
     'ui/menu': ['@zag-js/vanilla', '@zag-js/menu'],
     'ui/select': ['@zag-js/vanilla', '@zag-js/select'],
     'ui/combobox': ['@zag-js/vanilla', '@zag-js/combobox'],
+    // sygnal/sandbox: QuickJS and its WASM variant (stock packages, README §9 Q6)
+    sandbox: ['quickjs-emscripten-core', '@jitl/quickjs-wasmfile-release-sync'],
 };
 // G-440: a dynamic import's specifier may be a template literal without substitutions
-const ADAPTER_RE = /(?:\bfrom|\bimport)\s*\(?\s*(['"`])sygnal\/(react|zag|ui\/(?:menu|select|combobox))\1/g;
-const ADAPTER_ID = /^sygnal\/(react|zag|ui\/(?:menu|select|combobox))$/;
+const ADAPTER_RE = /(?:\bfrom|\bimport)\s*\(?\s*(['"`])sygnal\/(react|zag|sandbox|ui\/(?:menu|select|combobox))\1/g;
+const ADAPTER_ID = /^sygnal\/(react|zag|sandbox|ui\/(?:menu|select|combobox))$/;
 /**
  * The adapter entries an app module imports (statically, dynamically or in a re-export), or null.
  * G-415: real imports only. The module's AST from the plugin context's parse() (Vite and Rollup