sygnal 5.4.0 → 6.1.0

package/dist/astro/index.mjs

@@ -1,7 +1,624 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/**
+ * G-099: xstream does `require('globalthis').getPolyfill()`, which pulls the
+ * `globalthis` polyfill and its dependency chain (define-properties,
+ * get-intrinsic, object-keys, has-symbols, ...; ~4 KB gzip) into every app
+ * bundle. Every runtime Sygnal supports has a native `globalThis`, so
+ * `sygnal/vite` (and the sygnal/astro integration) alias the package to
+ * dist/shims/globalthis.cjs (src/vite/globalthis-shim.ts) unless
+ * `nativeGlobalThis: false`. A `resolve.alias`, not a resolveId hook: Vite's
+ * dependency pre-bundling only applies aliases.
+ */
+// Node built-ins (this runs in Node). The package has no @types/node.
+// @ts-ignore
+/**
+ * Absolute path of the stub in the sygnal package this code belongs to (found
+ * by walking up from this file: dist/vite, dist/astro or src/vite), or
+ * undefined when it is missing (e.g. sygnal not built).
+ */
+function globalThisShim() {
+    try {
+        let dir = path.dirname(fileURLToPath(import.meta.url));
+        while (dir !== path.dirname(dir)) {
+            const pkgFile = path.join(dir, 'package.json');
+            if (fs.existsSync(pkgFile) && JSON.parse(fs.readFileSync(pkgFile, 'utf8')).name === 'sygnal') {
+                const file = path.join(dir, 'dist', 'shims', 'globalthis.cjs');
+                return fs.existsSync(file) ? file : undefined;
+            }
+            dir = path.dirname(dir);
+        }
+    }
+    catch (_) { }
+    return undefined;
+}
+/**
+ * Whether a Vite `resolve.alias` value (object or array form) already maps
+ * `globalthis` (R2-7): the user's alias wins and the stub is not added.
+ */
+function hasGlobalThisAlias(alias) {
+    if (!alias)
+        return false;
+    if (!Array.isArray(alias))
+        return Object.prototype.hasOwnProperty.call(alias, 'globalthis');
+    return alias.some((a) => a && (a.find instanceof RegExp ? a.find.test('globalthis') : a.find === 'globalthis'));
+}
+/**
+ * Vite `resolve.alias` entries for the stub (empty when it is missing, or
+ * when `userAlias` — the user's `resolve.alias` — already maps `globalthis`).
+ */
+function globalThisAlias(userAlias) {
+    const shim = hasGlobalThisAlias(userAlias) ? undefined : globalThisShim();
+    return shim ? [{ find: /^globalthis$/, replacement: shim }] : [];
+}
+
+/**
+ * PLAN-6 E-1: the dev MCP endpoint of sygnal/vite (`sygnal({ mcp: true })`), dev server only.
+ *
+ * `/__sygnal/mcp` speaks MCP's streamable HTTP transport: JSON-RPC 2.0 over POST, answered as
+ * one `application/json` body, in both protocol eras (G-655: a dual-era server):
+ *
+ * - legacy, the `initialize` revisions (2024-11-05 … 2025-11-25). G-638: JSON replies make a
+ *   complete server under the spec (the client must accept JSON or SSE; a server without a GET
+ *   stream answers 405; session ids are optional, "MAY assign"). Methods: initialize, ping,
+ *   tools/list, tools/call; notifications get 202; batches (2025-03-26) are answered.
+ * - modern, the stateless 2026-07-28 revision (no initialize, no sessions, no ping): each request
+ *   carries `_meta['io.modelcontextprotocol/protocolVersion']` and `.../clientCapabilities`, and
+ *   the `MCP-Protocol-Version`, `Mcp-Method` and (tools/call) `Mcp-Name` headers, which must
+ *   match the body (else 400 with -32020 HeaderMismatch; missing `_meta` fields: 400, -32602).
+ *   Methods: server/discover, tools/list, tools/call; any other gets 404 with -32601. Results
+ *   carry `resultType: 'complete'` and `_meta['io.modelcontextprotocol/serverInfo']`; tools/list
+ *   and server/discover are cacheable results (`ttlMs`, `cacheScope`). No subscriptions/listen
+ *   (the tool list never changes), no MRTR input requests, no logging.
+ *
+ * The era comes from each request: a 2026-07-28 header or `_meta` version is modern, anything else
+ * legacy (no header: 2025-03-26, as the spec allows). An unknown version gets 400 with -32022
+ * (UnsupportedProtocolVersion, `data: { supported, requested }`), so a modern client retries
+ * with one this server speaks. The server never sends requests or notifications of its own (no
+ * sampling, no progress, tools/list never changes), so an SSE stream would carry nothing; without
+ * session ids each POST stands alone (the page state lives in the browser, not in a session).
+ * GET and DELETE get 405. Spec: modelcontextprotocol.io/specification/2026-07-28/basic/versioning
+ * and .../basic/transports/streamable-http. Hand-written like sygnal-check's stdio server (no
+ * dependency, D209).
+ *
+ * Tools that read the page (get_state, dispatch, component_tree, recent_actions,
+ * get_diagnostics, copy_as_test, agent_tools) go to an open tab through a PageBridge: in the dev
+ * server, Vite's HMR channel (custom events 'sygnal:mcp:*', see src/extra/devMcp.ts), request /
+ * response with ids and a timeout. With several tabs the most recently loaded or focused one
+ * answers, or the `tab` argument picks one; the result says which (`tab`), and `tabs` lists
+ * them with their apps. G-638: every run() app of a page is served: `app` (an index, or the
+ * root component's name) picks one on get_state, dispatch, component_tree, copy_as_test and
+ * agent_tools (default: the first, or the app that has `component`); `apps` lists them. check / graph / explain run sygnal-check's own MCP server in-process when sygnal-check
+ * is installed in the project.
+ *
+ * Security (the endpoint can read and change the running app): requests must come from the
+ * loopback interface; the Host header must be localhost, a *.localhost name, a loopback IP or a
+ * name in Vite's `server.allowedHosts`; a request with an Origin header must come from a
+ * localhost / loopback origin (a web page elsewhere, or a DNS-rebinding page, gets 403).
+ */
+// @ts-ignore
+const MCP_PATH = '/__sygnal/mcp';
+const MCP_HELLO = 'sygnal:mcp:hello';
+const MCP_REQUEST = 'sygnal:mcp:request';
+const MCP_RESPONSE = 'sygnal:mcp:response';
+/** G-655: the stateless revisions (per-request `_meta`, no initialize), newest first */
+const MODERN_VERSIONS = ['2026-07-28'];
+/** the `initialize` revisions, newest first; initialize answers with the client's version when it knows it */
+const LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+const SUPPORTED_VERSIONS = [...MODERN_VERSIONS, ...LEGACY_VERSIONS];
+const META = 'io.modelcontextprotocol/';
+const INSTRUCTIONS = 'The running Sygnal apps in the dev server\'s open page: component_tree to orient, get_state / recent_actions / get_diagnostics to read, dispatch or agent_tools to act, copy_as_test to turn a session into a test; apps lists the page\'s run() apps when there are several (`app` picks one). check, graph and explain (when present) are sygnal-check on the sources.';
+/** 2026-07-28 cacheable results (tools/list, server/discover): the list is fixed while the dev server runs, not across restarts */
+const CACHE = { ttlMs: 0, cacheScope: 'private' };
+const MAX_BODY = 1 << 20;
+class ToolError extends Error {
+}
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const tabSchema = { type: 'integer', description: 'The tab to ask (see tabs); default: the most recently loaded or focused tab' };
+const componentSchema = { type: ['string', 'integer'], description: 'A component name, or an instance id (see component_tree); default: the root' };
+const appSchema = { type: ['string', 'integer'], description: "The app on the page: an index or the root component's name (see apps); default: the first app, or the one that has `component`" };
+const obj = (properties, required) => ({
+    type: 'object', properties: { ...properties, tab: tabSchema }, ...(required ? { required } : {}), additionalProperties: false,
+});
+/** The tools answered by the page */
+const PAGE_TOOLS = [
+    {
+        name: 'get_state',
+        title: 'Get component state',
+        description: "The live state of a component instance in the open page (the root by default). With several instances of a component (Collection items) you get each one's id and state. `path` reads one field: 'todos.0.text' or ['todos', 0, 'text'].",
+        inputSchema: obj({ component: componentSchema, app: appSchema, path: { type: ['string', 'array'], items: { type: ['string', 'integer'] }, description: "A field path: 'a.b.0' or ['a', 'b', 0]" } }),
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'dispatch',
+        title: 'Dispatch an action',
+        description: "Send an action to a component instance in the open page, as if its intent had produced it (recorded with cause 'agent'), and wait for the render. Returns the instance's new state. The action must be one of the component's model entries (an unknown name lists them).",
+        inputSchema: obj({ component: componentSchema, app: appSchema, action: { type: 'string', description: "The action name, e.g. 'ADD'" }, data: { description: 'The action data (any JSON value)' } }, ['action']),
+    },
+    {
+        name: 'component_tree',
+        title: 'Component tree (inspect)',
+        description: "The running apps' graph from inspect(): component instances (id, parentId, kind), their actions and what triggers them, state keys, context, EVENTS, children, intent selectors (matched or not) and the runtime diagnostics attached to each. `app` keeps one app's instances, `component` only that component's.",
+        inputSchema: obj({ component: componentSchema, app: { ...appSchema, description: "Only this app's instances: an index or the root component's name (see apps); default: every app" } }),
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'recent_actions',
+        title: 'Recent actions',
+        description: "The DevTools action log of the open page, newest last: type, data, component, instance, cause ('intent', 'agent', 'reply', ...), the sinks it reached and the state before / after a STATE change.",
+        inputSchema: obj({
+            limit: { type: 'integer', minimum: 1, maximum: 500, description: 'How many (default 20)' },
+            component: { type: 'string', description: 'Only this component' },
+            type: { type: 'string', description: 'Only this action type' },
+            cause: { type: 'string', enum: ['intent', 'next', 'reply', 'built-in', 'simulateAction', 'behavior', 'agent', 'setState'], description: 'Only this cause' },
+        }),
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'get_diagnostics',
+        title: 'Runtime diagnostics',
+        description: 'The runtime diagnostics the open page reported (SYG codes): code, severity, component, message, fix and docsUrl, with a summary. Use explain for a code you do not know.',
+        inputSchema: obj({
+            code: { type: 'string', description: "Only this code, e.g. 'SYG104'" },
+            severity: { type: 'string', enum: ['error', 'warn', 'info'] },
+            limit: { type: 'integer', minimum: 1, maximum: 500, description: 'How many, newest (default 100)' },
+        }),
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'copy_as_test',
+        title: 'Copy session as test',
+        description: "DevTools' Copy as test: a Vitest + renderComponent test file that replays what happened to a component instance in the open page (default: the root) and asserts its final state. Returns { code, complete, warnings, replayed }.",
+        inputSchema: obj({ component: componentSchema, app: appSchema, componentImport: { type: 'string', description: "Where the test imports the component from: a module path ('./App.jsx') or a whole import line" } }),
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'agent_tools',
+        title: "The app's agent tools",
+        description: "The open page's own agent tools (the `agent` statics, sygnal/ai): without `call`, the tools offered now (name, description, inputSchema, annotations) and the readable context; with `call`, runs that tool with `input` under the app's rules (validation, `when`, a consequential tool asks the person in the page first).",
+        inputSchema: obj({
+            call: { type: 'string', description: 'A tool name from the list' },
+            input: { description: 'The tool input' },
+            all: { type: 'boolean', description: 'List also the declared tools that are not offered, with why' },
+            app: { ...appSchema, description: "The app whose tools to use: an index or the root component's name (see apps); default: the first" },
+        }),
+    },
+    {
+        name: 'apps',
+        title: 'Apps on the page',
+        description: "The Sygnal apps (run() calls) running in the open page: index, root component, root instance id and instance count. The first is the default of the tools' `app` argument.",
+        inputSchema: obj({}),
+        annotations: { readOnlyHint: true },
+    },
+];
+const TABS_TOOL = {
+    name: 'tabs',
+    title: 'Open pages',
+    description: 'The pages of this dev server connected to the endpoint (id, url, title, apps: { index, component } per run() app); the page tools use the most recently loaded or focused one unless given `tab`.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true },
+};
+/** sygnal-check's MCP server (its `src/mcp.js`), loaded from the project; undefined when missing */
+async function loadCheckServer(root) {
+    try {
+        const main = createRequire(path.join(root, 'package.json')).resolve('sygnal-check');
+        const file = path.join(path.dirname(main), 'mcp.js');
+        if (!fs.existsSync(file))
+            return undefined;
+        const mod = await import(/* @vite-ignore */ pathToFileURL(file).href);
+        if (typeof mod.createMcpServer !== 'function' || !Array.isArray(mod.TOOLS))
+            return undefined;
+        return { tools: mod.TOOLS, server: mod.createMcpServer({ cwd: root }) };
+    }
+    catch (_) {
+        return undefined;
+    }
+}
+/** The JSON-RPC side of the endpoint (transport-free; tests drive it directly) */
+function createDevMcpServer(o) {
+    const timeout = o.timeout && o.timeout > 0 ? o.timeout : 10000;
+    const result = (id, value) => ({ jsonrpc: '2.0', id, result: value });
+    const error = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+    let check;
+    const getCheck = async () => (check === undefined ? (check = (await o.check) || null) : check);
+    const pickTab = (want) => {
+        const tabs = o.bridge.tabs();
+        if (!tabs.length) {
+            const url = o.url?.();
+            throw new ToolError(`no page is connected: open the app${url ? ` (${url})` : ''} in a browser, with the dev server running`);
+        }
+        if (want !== undefined && want !== null) {
+            const tab = tabs.find(t => t.id === Number(want));
+            if (!tab)
+                throw new ToolError(`no tab ${want}; open tabs: ${tabs.map(t => `${t.id} ${t.url}`).join(', ')}`);
+            return { tab };
+        }
+        const tab = tabs.reduce((a, b) => (b.active > a.active ? b : a));
+        return { tab, note: tabs.length > 1 ? `${tabs.length} tabs are open; used tab ${tab.id} (the most recently loaded or focused). Pass tab to choose one (see tabs).` : undefined };
+    };
+    const content = (value, isError = false) => {
+        const structured = isObj(value) ? value : { value };
+        return { content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }], structuredContent: structured, isError };
+    };
+    async function callTool(name, args) {
+        if (name === 'tabs')
+            return content({ tabs: o.bridge.tabs().map(({ id, url, title, apps }) => ({ id, url, title, ...(apps ? { apps } : {}) })) });
+        const { tab: want, ...rest } = args;
+        const { tab, note } = pickTab(want);
+        const value = await o.bridge.request(tab.id, name, rest, timeout);
+        const out = isObj(value) ? value : { value };
+        return content({ ...out, tab: { id: tab.id, url: tab.url, title: tab.title }, ...(note ? { tabNote: note } : {}) });
+    }
+    const serverInfo = { name: 'sygnal-dev', title: 'Sygnal dev server', version: o.version || '0.0.0' };
+    async function handleMessage(msg, modern) {
+        if (!isObj(msg) || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+            return isObj(msg) && 'id' in msg && !('result' in msg || 'error' in msg) ? error(msg.id ?? null, -32600, 'Invalid Request') : null;
+        }
+        if (!('id' in msg) || msg.id === null)
+            return null; // a notification
+        const { id, method } = msg;
+        const params = isObj(msg.params) ? msg.params : {};
+        // G-655: 2026-07-28 removed initialize and ping, and added server/discover
+        if (modern ? method === 'initialize' || method === 'ping' : method === 'server/discover')
+            return error(id, -32601, `Method not found: ${method}`);
+        switch (method) {
+            case 'initialize': {
+                const requested = params.protocolVersion;
+                return result(id, {
+                    protocolVersion: LEGACY_VERSIONS.includes(requested) ? requested : LEGACY_VERSIONS[0],
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo,
+                    instructions: INSTRUCTIONS,
+                });
+            }
+            case 'server/discover':
+                return result(id, { supportedVersions: SUPPORTED_VERSIONS, capabilities: { tools: {} }, instructions: INSTRUCTIONS, ...CACHE });
+            case 'ping':
+                return result(id, {});
+            case 'tools/list': {
+                const c = await getCheck();
+                return result(id, { tools: [...PAGE_TOOLS, TABS_TOOL, ...(c ? c.tools : [])], ...(modern ? CACHE : {}) });
+            }
+            case 'tools/call': {
+                const name = params.name;
+                const args = isObj(params.arguments) ? params.arguments : {};
+                if (name === 'tabs' || PAGE_TOOLS.some(t => t.name === name)) {
+                    try {
+                        return result(id, await callTool(name, args));
+                    }
+                    catch (err) {
+                        return result(id, { content: [{ type: 'text', text: err instanceof ToolError ? err.message : `${name} failed: ${err?.message || err}` }], isError: true });
+                    }
+                }
+                const c = await getCheck();
+                if (c && c.tools.some((t) => t.name === name)) {
+                    // without `_meta`, sygnal-check's server answers in the initialize era's shape (G-656: it
+                    // speaks 2026-07-28 too, but this endpoint checked the envelope and adds the fields itself)
+                    const { _meta, ...rest } = params;
+                    return { ...c.server.handle({ ...msg, params: { ...rest, arguments: args } }), id };
+                }
+                return error(id, -32602, `Unknown tool: ${name}`);
+            }
+            default:
+                return error(id, -32601, `Method not found: ${method}`);
+        }
+    }
+    /**
+     * One message (or a legacy batch); never throws. `modern`: a 2026-07-28 request whose envelope
+     * (version, headers, `_meta` fields) the transport checked (see mcpMiddleware); its result is
+     * marked `resultType: 'complete'` and names the server in `_meta`.
+     */
+    async function handle(msg, modern = false) {
+        if (Array.isArray(msg)) {
+            if (modern)
+                return error(null, -32600, 'Invalid Request: one JSON-RPC message per POST');
+            const out = (await Promise.all(msg.map((m) => handle(m)))).filter(Boolean);
+            return out.length ? out : null;
+        }
+        try {
+            const out = await handleMessage(msg, modern);
+            if (modern && out && isObj(out.result)) {
+                const meta = isObj(out.result._meta) ? out.result._meta : {};
+                out.result = { resultType: 'complete', ...out.result, _meta: { ...meta, [META + 'serverInfo']: serverInfo } };
+            }
+            return out;
+        }
+        catch (err) {
+            return error(isObj(msg) && 'id' in msg ? msg.id ?? null : null, -32603, `Internal error: ${err?.message || err}`);
+        }
+    }
+    return { handle };
+}
+// ---------------------------------------------------------------- security
+const LOOPBACK_IP = /^(127\.\d{1,3}\.\d{1,3}\.\d{1,3}|::1|::ffff:127\.\d{1,3}\.\d{1,3}\.\d{1,3})$/;
+/** The host part of a Host header value or URL host ('[::1]:5173' → '::1') */
+function hostname(host) {
+    const h = host.trim().toLowerCase();
+    if (h.startsWith('['))
+        return h.slice(1, h.indexOf(']') > 0 ? h.indexOf(']') : undefined);
+    const i = h.lastIndexOf(':');
+    return i > 0 && h.indexOf(':') === i ? h.slice(0, i) : h;
+}
+const isLocalName = (h) => h === 'localhost' || h.endsWith('.localhost') || LOOPBACK_IP.test(h);
+/** Vite's allowedHosts entries: 'example.test', or '.example.test' for it and its subdomains */
+function inAllowed(h, allowed) {
+    if (!Array.isArray(allowed))
+        return false;
+    return allowed.some((a) => {
+        if (typeof a !== 'string' || !a)
+            return false;
+        const e = a.toLowerCase();
+        return e.startsWith('.') ? h === e.slice(1) || h.endsWith(e) : h === e;
+    });
+}
+/** Why the request is refused (403), or null */
+function refusal(req, allowedHosts) {
+    const remote = String(req?.socket?.remoteAddress || '');
+    if (!LOOPBACK_IP.test(remote))
+        return `the Sygnal MCP endpoint only answers requests from this machine (not ${remote || 'an unknown address'})`;
+    const host = req?.headers?.host;
+    if (typeof host !== 'string' || !host)
+        return 'missing Host header';
+    const h = hostname(host);
+    if (!isLocalName(h) && !inAllowed(h, allowedHosts))
+        return `Host ${host} is not a local name (add it to server.allowedHosts to allow it)`;
+    const origin = req?.headers?.origin;
+    if (origin !== undefined && origin !== 'null') {
+        let oh = '';
+        try {
+            oh = new URL(String(origin)).hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        }
+        catch (_) { }
+        if (!oh || (!isLocalName(oh) && !inAllowed(oh, allowedHosts)))
+            return `Origin ${origin} is not allowed`;
+    }
+    else if (origin === 'null') {
+        return 'Origin null is not allowed';
+    }
+    return null;
+}
+// ---------------------------------------------------------------- HTTP
+function send(res, status, body, headers = {}) {
+    res.statusCode = status;
+    for (const k in headers)
+        res.setHeader(k, headers[k]);
+    if (body === undefined)
+        return res.end();
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify(body));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (c) => {
+            size += c.length;
+            if (size > MAX_BODY) {
+                reject(new Error('too large'));
+                req.destroy?.();
+            }
+            else
+                chunks.push(c);
+        });
+        req.on('end', () => resolve(globalThis.Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+/** An `Mcp-Name` value: plain, or the spec's `=?base64?…?=` sentinel for one that isn't header-safe */
+function headerValue(v) {
+    const m = /^=\?base64\?(.*)\?=$/.exec(v);
+    return m ? globalThis.Buffer.from(m[1], 'base64').toString('utf8') : v;
+}
+/**
+ * G-655: why a 2026-07-28 request's envelope is refused, as [code, message], or null. The spec
+ * (basic/index "_meta", transports/streamable-http "Server Validation"): `_meta` must carry the
+ * protocol version and the client capabilities (-32602), and the MCP-Protocol-Version, Mcp-Method
+ * and (tools/call, resources/read, prompts/get) Mcp-Name headers must be there and match the body
+ * (-32020 HeaderMismatch). This server marks no parameter with `x-mcp-header`, so no
+ * Mcp-Param-* header is required.
+ */
+function modernEnvelope(msg, headers) {
+    const params = isObj(msg.params) ? msg.params : {};
+    const meta = isObj(params._meta) ? params._meta : {};
+    if (typeof meta[META + 'protocolVersion'] !== 'string')
+        return [-32602, `Invalid params: _meta["${META}protocolVersion"] is required`];
+    if (!isObj(meta[META + 'clientCapabilities']))
+        return [-32602, `Invalid params: _meta["${META}clientCapabilities"] is required`];
+    const header = headers['mcp-protocol-version'];
+    if (header !== meta[META + 'protocolVersion']) {
+        return [-32020, header === undefined ? 'Header mismatch: MCP-Protocol-Version header is required' : `Header mismatch: MCP-Protocol-Version header value '${header}' does not match body value '${meta[META + 'protocolVersion']}'`];
+    }
+    const method = headers['mcp-method'];
+    if (method !== msg.method)
+        return [-32020, method === undefined ? 'Header mismatch: Mcp-Method header is required' : `Header mismatch: Mcp-Method header value '${method}' does not match body value '${msg.method}'`];
+    if (msg.method === 'tools/call' || msg.method === 'prompts/get' || msg.method === 'resources/read') {
+        const want = msg.method === 'resources/read' ? params.uri : params.name;
+        const name = headers['mcp-name'];
+        if (typeof name !== 'string')
+            return [-32020, 'Header mismatch: Mcp-Name header is required'];
+        if (headerValue(name) !== want)
+            return [-32020, `Header mismatch: Mcp-Name header value '${name}' does not match body value '${want}'`];
+    }
+    return null;
+}
+/** The connect middleware for MCP_PATH */
+function mcpMiddleware(server, allowedHosts) {
+    return async (req, res, next) => {
+        const url = String(req.url || '').replace(/[?#].*$/, '');
+        if (url !== MCP_PATH && url !== MCP_PATH + '/')
+            return next();
+        const why = refusal(req, allowedHosts());
+        if (why)
+            return send(res, 403, { jsonrpc: '2.0', id: null, error: { code: -32000, message: `Forbidden: ${why}` } });
+        // G-638: no SSE stream on GET (the spec's "MUST ... return 405" for a server that offers none), no sessions to DELETE
+        if (req.method !== 'POST')
+            return send(res, 405, { jsonrpc: '2.0', id: null, error: { code: -32000, message: 'Method not allowed: this endpoint takes JSON-RPC over POST and answers with application/json (no SSE stream, no sessions)' } }, { Allow: 'POST' });
+        let msg;
+        try {
+            msg = JSON.parse(await readBody(req));
+        }
+        catch (err) {
+            if (err?.message === 'too large')
+                return send(res, 413, { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Request too large' } });
+            return send(res, 400, { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+        }
+        // G-655: the era is per request: a 2026-07-28 version in the header or in `_meta` is modern
+        // (stateless), anything else the initialize era (no header: 2025-03-26)
+        const id = isObj(msg) && 'id' in msg ? msg.id ?? null : null;
+        const fail = (status, code, message, data) => send(res, status, { jsonrpc: '2.0', id, error: { code, message, ...(data ? { data } : {}) } });
+        const header = req.headers['mcp-protocol-version'];
+        const meta = isObj(msg) && isObj(msg.params) && isObj(msg.params._meta) ? msg.params._meta : {};
+        const metaVersion = meta[META + 'protocolVersion'];
+        for (const requested of [header, metaVersion]) {
+            if (requested !== undefined && !SUPPORTED_VERSIONS.includes(requested)) {
+                return fail(400, -32022, 'Unsupported protocol version', { supported: SUPPORTED_VERSIONS, requested });
+            }
+        }
+        const modern = MODERN_VERSIONS.includes(header) || MODERN_VERSIONS.includes(metaVersion);
+        if (modern) {
+            if (!isObj(msg))
+                return fail(400, -32600, 'Invalid Request: one JSON-RPC message per POST');
+            if ('id' in msg && msg.id !== null) {
+                const why = modernEnvelope(msg, req.headers);
+                if (why)
+                    return fail(400, why[0], why[1]);
+            }
+        }
+        const out = await server.handle(msg, modern);
+        if (out === null || out === undefined)
+            return send(res, 202);
+        // 2026-07-28: a method this server doesn't implement is 404 (the JSON-RPC body tells it from a missing endpoint)
+        send(res, modern && out.error?.code === -32601 ? 404 : 200, out);
+    };
+}
+// ---------------------------------------------------------------- the page bridge (Vite's HMR channel)
+/** A PageBridge over the dev server's HMR channel (server.ws / environments.client.hot) */
+function hmrBridge(server) {
+    const ws = server?.ws || server?.environments?.client?.hot;
+    const tabs = new Map();
+    const pending = new Map();
+    let nextTab = 1;
+    let nextReq = 1;
+    let clock = 0;
+    const fail = (client) => {
+        const t = tabs.get(client);
+        tabs.delete(client);
+        if (!t)
+            return;
+        for (const [id, p] of pending) {
+            if (p.client !== client)
+                continue;
+            clearTimeout(p.timer);
+            pending.delete(id);
+            p.reject(new ToolError(`tab ${t.id} closed before it answered`));
+        }
+    };
+    if (ws && typeof ws.on === 'function') {
+        ws.on(MCP_HELLO, (data, client) => {
+            if (!client)
+                return;
+            let t = tabs.get(client);
+            if (!t) {
+                tabs.set(client, t = { id: nextTab++, url: '', title: '', active: 0 });
+                // Vite's socket client carries its WebSocket: a closed tab leaves at once
+                try {
+                    client.socket?.once?.('close', () => fail(client));
+                }
+                catch (_) { }
+            }
+            t.url = String(data?.url || '');
+            t.title = String(data?.title || '');
+            if (Array.isArray(data?.apps))
+                t.apps = data.apps.map((a) => ({ index: Number(a?.index), component: String(a?.component ?? '') }));
+            // an apps update (an HMR swap, a second run()) is not a focus
+            if (!data?.update || !t.active)
+                t.active = ++clock;
+        });
+        ws.on(MCP_RESPONSE, (data, client) => {
+            const p = data && pending.get(data.id);
+            if (!p || p.client !== client)
+                return;
+            if (data.waiting) {
+                clearTimeout(p.timer);
+                p.timer = setTimeout(() => expire(data.id), 5 * 60000);
+                return;
+            }
+            clearTimeout(p.timer);
+            pending.delete(data.id);
+            if (data.ok)
+                p.resolve(data.result);
+            else
+                p.reject(new ToolError(String(data.error || 'the page reported an error')));
+        });
+    }
+    /** tabs whose socket is still open (when the channel tells) */
+    const live = () => {
+        let open;
+        try {
+            open = ws?.clients;
+        }
+        catch (_) { }
+        for (const c of [...tabs.keys()]) {
+            const closed = c.socket && typeof c.socket.readyState === 'number' && c.socket.readyState > 1;
+            if (closed || (open instanceof Set && c.socket && !open.has(c)))
+                fail(c);
+        }
+        return tabs;
+    };
+    function expire(id) {
+        const p = pending.get(id);
+        if (!p)
+            return;
+        pending.delete(id);
+        p.reject(new ToolError(`tab ${p.tab} did not answer in time (is the page frozen, or a dialog open?)`));
+    }
+    return {
+        tabs: () => [...live().values()].map(t => ({ ...t, ...(t.apps ? { apps: t.apps.map(a => ({ ...a })) } : {}) })),
+        request(tabId, tool, args, ms) {
+            const client = [...live().entries()].find(([, t]) => t.id === tabId)?.[0];
+            if (!client)
+                return Promise.reject(new ToolError(`no tab ${tabId}`));
+            const id = nextReq++;
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => expire(id), ms);
+                pending.set(id, { tab: tabId, resolve, reject, timer, client });
+                try {
+                    client.send({ type: 'custom', event: MCP_REQUEST, data: { id, tool, args } });
+                }
+                catch (err) {
+                    clearTimeout(timer);
+                    pending.delete(id);
+                    fail(client);
+                    reject(new ToolError(`tab ${tabId} is gone: ${err?.message || err}`));
+                }
+            });
+        },
+    };
+}
+/** Wire the endpoint into a Vite dev server */
+function attachMcp(server, root, options, version) {
+    const bridge = hmrBridge(server);
+    const mcp = createDevMcpServer({
+        ...options,
+        bridge,
+        version,
+        check: loadCheckServer(root),
+        url: () => server?.resolvedUrls?.local?.[0],
+    });
+    server.middlewares.use(mcpMiddleware(mcp, () => server?.config?.server?.allowedHosts));
+    return mcp;
+}
+/** 'virtual:sygnal/mcp': connects the page (dev only) */
+function mcpClientModule(options) {
+    const confirm = options.confirm === undefined ? 'page' : options.confirm;
+    return `import { agentTools } from 'sygnal';
+import { installMcpBridge } from 'sygnal/devtools';
+if (import.meta.hot) installMcpBridge(import.meta.hot, { agentTools, confirm: ${JSON.stringify(confirm)} });
+`;
+}
 
 /**
  * Sygnal Vite Plugin
@@ -17,7 +634,10 @@ import { pathToFileURL } from 'node:url';
  * What it does:
  *   1. Configures the automatic JSX transform with sygnal as the import source:
  *      `oxc` (Vite 8), plus `esbuild` under Vite 7 and older
- *   2. Detects files that call `run()` from sygnal and auto-injects HMR wiring
+ *   2. Detects files that call `run()` from sygnal and auto-injects HMR wiring.
+ *      A module that calls `defineElement()` from 'sygnal/element' at the top level
+ *      (and doesn't import run()) gets `if (import.meta.hot) import.meta.hot.accept()`
+ *      appended: re-running it swaps the elements' component, keeping their state
  *   3. Dev mode (`vite` / `vite dev` only; never `vite build`). Into every
  *      file that imports `run` from sygnal (including entries with manual HMR
  *      wiring or `disableHmr`) it inserts, on an existing line:
@@ -53,9 +673,14 @@ import { pathToFileURL } from 'node:url';
  *      current findings when the page loads ('sygnal:check:request'), and only
  *      that client is answered; after a source change the new findings go to
  *      every connected client, and only when they changed. Error-severity
- *      findings also open Vite's error overlay (`overlay: false`: never).
- *      sygnal-check's codes are currently all warnings or info, so in practice
- *      everything goes to the console. Warnings never use the overlay: while
+ *      findings also open Vite's error overlay (`overlay: false`: never):
+ *      SYG112, SYG124, SYG125, SYG128, SYG405 and the checker's other
+ *      error-severity codes. The a11y lane SYG701-708 is a warning, also
+ *      under `diagnostics.strict` (D144, amending D111); `check.a11y: 'error'`
+ *      makes it an error (and opens the overlay). Without that opt-in a 7xx
+ *      finding never opens the overlay, even from an older sygnal-check that
+ *      reports it as an error under strict. Everything else is a warning or
+ *      info and goes to the console. Warnings never use the overlay: while
  *      one is open Vite's client reloads the page on the next HMR update
  *      (`overlay: 'warn'` is treated as 'error', with a notice). The dev
  *      client closes a sygnal-check overlay before each update, and the
@@ -76,13 +701,35 @@ import { pathToFileURL } from 'node:url';
  *   7. Vike and Astro (G-014): the app is started by sygnal's own client
  *      entry, which user code doesn't import. Client-side imports of
  *      'sygnal/vike/onRenderClient' resolve to a dev wrapper that sets the
- *      flag and loads the checks first. Astro resolves its renderer entry on
+ *      flag and loads the checks first. That entry is excluded from
+ *      pre-bundling in dev (B-020), so it shares the pages' core. Astro resolves its renderer entry on
  *      the server and the browser loads the file itself, so the same snippet
  *      is added to sygnal's 'astro/client' file by the transform. That file
  *      imports the public 'sygnal' entry (one shared core, B-019), so its
  *      'sygnal' import gets the run() wrapper too: every `diagnostics` mode
  *      and ignore list works for islands. The sygnal/astro integration adds
  *      this plugin in `astro dev`.
+ *   8. `nativeGlobalThis` (G-099, default true): a `resolve.alias` from
+ *      `globalthis` (xstream's `require('globalthis').getPolyfill()`) to the
+ *      package's dist/shims/globalthis.cjs, which returns the native
+ *      globalThis. Drops the polyfill chain (~4 KB gzip) from every bundle,
+ *      in dev (including pre-bundling), build and Vitest. Dependencies left
+ *      external (SSR, Vitest) still load the real package from Node. The
+ *      sygnal/astro integration adds the same alias in `astro build`. Any
+ *      dependency's `require('globalthis')` gets the stub; a `globalthis`
+ *      entry in the user's own `resolve.alias` wins (R2-7).
+ *   9. `devtools` option (D77, default true): in dev the same files (run()
+ *      importers, the Vike wrapper, the Astro client) also get
+ *      `import 'sygnal/devtools';`, first, which installs the DevTools bridge
+ *      (window.__SYGNAL_DEVTOOLS__) for the browser extension. Independent of
+ *      `diagnostics` ('off' still injects it). Never in `vite build` or under
+ *      Vitest: production builds carry no DevTools code. `devtools: false`
+ *      injects nothing. PLAN-4 3-E: `devtools: { redux: true }` also calls
+ *      connectReduxDevtools() (actions + state to the Redux DevTools extension).
+ *  10. `mcp` option (PLAN-6 E-1, default false): the dev server serves an MCP endpoint at
+ *      /__sygnal/mcp (./mcp.ts: streamable HTTP, loopback / local Host / local Origin only)
+ *      and the dev entries also import 'virtual:sygnal/mcp', which connects the page over the
+ *      HMR channel (installMcpBridge from 'sygnal/devtools'). Never in `vite build` or Vitest.
  *
  * Why not Vite's `define`? Vite's dependency optimizer does not apply user
  * `define` replacements to pre-bundled dependencies (only process.env.NODE_ENV),
@@ -123,11 +770,14 @@ const CHECK_EVENT = 'sygnal:check';
 // Sent by the dev client when it loads: the server answers that client only
 const CHECK_REQUEST = 'sygnal:check:request';
 const OVERLAY_PLUGIN = 'sygnal-check';
+// PLAN-6 E-1: the page side of the dev MCP endpoint
+const MCP_CLIENT = 'virtual:sygnal/mcp';
+const MCP_CLIENT_ID = '\0' + MCP_CLIENT;
 // Register the runtime checks with the core that loaded last (see the Vike wrapper)
 const REINSTALL_IMPORT = `import { installChecks as __sygnalInstallChecks } from 'sygnal/diagnostics';`;
 const REINSTALL_CALL = 'try { __sygnalInstallChecks() } catch (e) { console.warn(e) }\n';
 function sygnal(options = {}) {
-    const { disableJsx = false, disableHmr = false, vitestSetup = true } = options;
+    const { disableJsx = false, disableHmr = false, vitestSetup = true, nativeGlobalThis = true } = options;
     const diagnostics = normalizeDiagnostics(options.diagnostics);
     const devOn = diagnostics.mode !== 'off';
     // A mode other than the flag's 'warn', or an ignore list, needs run()'s option
@@ -140,6 +790,18 @@ function sygnal(options = {}) {
     // Statements run before the app starts: dev flag (+ strict flag)
     const flags = DEV_FLAG + (diagnostics.strict ? STRICT_FLAG : '');
     const devImports = `import 'sygnal/diagnostics';import '${DEV_CLIENT}';`;
+    // D77: the DevTools bridge, dev only. First, so the diagnostics entry finds it.
+    // E-1: the MCP endpoint needs the bridge, so `mcp` turns it on
+    const mcpOn = !!options.mcp;
+    const mcpOptions = typeof options.mcp === 'object' && options.mcp ? options.mcp : {};
+    const devtoolsOn = options.devtools !== false || mcpOn;
+    const redux = typeof options.devtools == 'object' && !!options.devtools?.redux;
+    const devtoolsImport = (!devtoolsOn ? ''
+        : redux ? `import { connectReduxDevtools as __sygnalReduxDevtools } from 'sygnal/devtools';__sygnalReduxDevtools();`
+            : `import 'sygnal/devtools';`) + (mcpOn ? `import '${MCP_CLIENT}';` : '');
+    // What a dev entry gets: DevTools, then (unless diagnostics are 'off') flags + checks
+    const devSnippet = devtoolsImport + (devOn ? flags + devImports : '');
+    const devInject = devOn || devtoolsOn;
     let astroClient;
     return {
         name: 'vite-plugin-sygnal',
@@ -155,6 +817,12 @@ function sygnal(options = {}) {
                     noExternal: ['sygnal'],
                 },
             };
+            // G-099: xstream's `require('globalthis')` gets the native-globalThis
+            // stub. An alias (not resolveId) so it also applies to pre-bundling.
+            // R2-7: not when the user's config already aliases `globalthis`.
+            const alias = nativeGlobalThis ? globalThisAlias(config?.resolve?.alias) : [];
+            if (alias.length)
+                result.resolve = { alias };
             if (!disableJsx) {
                 result.oxc = {
                     jsx: {
@@ -186,13 +854,31 @@ function sygnal(options = {}) {
                         result.test = { setupFiles: [setup] };
                 }
             }
-            else if (isServe && devOn && sygnalInNodeModules(root)) {
+            else if (isServe && devInject && sygnalInNodeModules(root)) {
                 // The dependency scan reads the original sources, which don't import
-                // the checks entry: pre-bundle it with sygnal so the first page load
-                // doesn't trigger a re-optimization. Only for an installed sygnal: a
-                // linked one is served from source, and pre-bundling the checks alone
-                // would give them their own copy of the core.
-                result.optimizeDeps = { ...result.optimizeDeps, include: ['sygnal/diagnostics'] };
+                // the checks (or DevTools) entry: pre-bundle it with sygnal so the first
+                // page load doesn't trigger a re-optimization. Only for an installed
+                // sygnal: a linked one is served from source, and pre-bundling the
+                // checks alone would give them their own copy of the core.
+                const include = [...(devtoolsOn ? ['sygnal/devtools'] : []), ...(devOn ? ['sygnal/diagnostics'] : [])];
+                result.optimizeDeps = { ...result.optimizeDeps, include };
+            }
+            // B-020: Vike adds its client entry 'sygnal/vike/onRenderClient' to
+            // optimizeDeps.include. With a linked sygnal, the pages' 'sygnal' is
+            // served from source while that pre-bundle inlines a second copy of the
+            // core. Unbundled, the entry's own `import 'sygnal'` resolves like the
+            // pages' imports (source when linked, the shared pre-bundle when
+            // installed): one core. Vike honours the exclude list.
+            // G-098: Vite doesn't discover the imports of an excluded dependency, so for an
+            // installed sygnal 'sygnal' is pre-bundled up front (pages that reach it only through
+            // the JSX runtime would otherwise get it, and its CommonJS xstream, unbundled).
+            if (isServe && !isVitest) {
+                const include = result.optimizeDeps?.include || [];
+                result.optimizeDeps = {
+                    ...result.optimizeDeps,
+                    exclude: [VIKE_CLIENT],
+                    ...(sygnalInNodeModules(root) ? { include: [...include, 'sygnal'] } : {}),
+                };
             }
             return result;
         },
@@ -225,10 +911,12 @@ function sygnal(options = {}) {
                     return null;
                 if (source === DEV_CLIENT)
                     return DEV_CLIENT_ID;
+                if (source === MCP_CLIENT && mcpOn)
+                    return MCP_CLIENT_ID;
                 if (source === 'sygnal' && importer && wrapRun && runtimeImporters.has(cleanId(importer))) {
                     return RUNTIME_ID;
                 }
-                if (source === VIKE_CLIENT && devOn && !opts?.ssr) {
+                if (source === VIKE_CLIENT && devInject && !opts?.ssr) {
                     if (importer !== VIKE_CLIENT_ID)
                         return VIKE_CLIENT_ID;
                     // The wrapper's own import of the real entry: resolve it normally.
@@ -245,18 +933,28 @@ function sygnal(options = {}) {
         load(id) {
             if (id === DEV_CLIENT_ID)
                 return devClientModule();
+            if (id === MCP_CLIENT_ID && mcpOn)
+                return mcpClientModule(mcpOptions);
             if (id === RUNTIME_ID)
                 return runtimeModule(diagnostics);
             // The checks register again once the real entry has loaded: a
             // pre-bundled copy of it can carry its own copy of the Sygnal core
             // (e.g. with a linked sygnal), which then holds the diagnostics bridge.
             if (id === VIKE_CLIENT_ID) {
-                return `${devImports}${REINSTALL_IMPORT}\nexport * from '${VIKE_CLIENT}';\n${flags}\n${REINSTALL_CALL}`;
+                if (!devOn)
+                    return `${devtoolsImport}\nexport * from '${VIKE_CLIENT}';\n`;
+                return `${devtoolsImport}${devImports}${REINSTALL_IMPORT}\nexport * from '${VIKE_CLIENT}';\n${flags}\n${REINSTALL_CALL}`;
             }
             return null;
         },
         configureServer(server) {
-            if (isVitest || options.check === false)
+            if (isVitest)
+                return;
+            // E-1: the MCP endpoint (a middleware ahead of Vite's own; it does its own host checks)
+            if (mcpOn && server?.middlewares) {
+                attachMcp(server, root, mcpOptions, sygnalVersion(root));
+            }
+            if (options.check === false)
                 return;
             const checkOptions = typeof options.check === 'object' && options.check ? options.check : {};
             // Deferred: the dev server doesn't wait for the first check
@@ -267,84 +965,176 @@ function sygnal(options = {}) {
             }, 0);
         },
         transform(code, id, opts) {
-            if (!isServe)
-                return null;
-            // sygnal/astro/client (Astro islands): flags + checks first. It imports
-            // the public 'sygnal' entry (the app's core, B-019), which resolves to
-            // the run() wrapper when the diagnostics option needs it.
-            if (devOn && !isVitest && !opts?.ssr) {
-                astroClient = astroClient || astroClientFiles(root);
-                if (astroClient.has(cleanId(id))) {
-                    if (wrapRun)
-                        runtimeImporters.add(cleanId(id));
-                    return withSourcemap(code, [[0, flags + devImports]], '', id);
-                }
-            }
-            // Only transform JS/TS/JSX/TSX files
-            if (!/\.[jt]sx?$/.test(id))
-                return null;
-            // Skip node_modules
-            if (id.includes('node_modules'))
-                return null;
-            // Must import run from sygnal
-            if (!code.includes('sygnal'))
-                return null;
-            // Match against the code with comments blanked out (same offsets), so
-            // e.g. `// run(App)` or a commented-out import is never matched.
-            const noComments = blankOut(code, false);
-            // Find: import { run, ... } from 'sygnal'
-            const runImportRe = /import\s+\{[^}]*\brun\b[^}]*\}\s+from\s+['"]sygnal['"]/;
-            if (!runImportRe.test(noComments))
-                return null;
-            // Dev snippet: injected into every file that imports run() — also when
-            // HMR wiring below is skipped. Inserted after any shebang line and
-            // directive prologue, without adding a line. Nothing under Vitest: a
-            // global flag set by one test file would leak dev/strict mode into the
-            // later test files of the same worker; there the checks come from
-            // test.setupFiles and renderComponent() manages the modes.
-            const inserts = [];
-            if (devOn && !isVitest) {
-                inserts.push(flagInsertion(code, flags + devImports));
+            // SYG666 (PLAN-5 W-2): an adapter entry imported without its optional peers; every mode
+            const adapters = adapterImports(this, code, id);
+            if (adapters)
+                return checkPeers(this, adapters, id).then(() => devTransform.call(this, code, id, opts));
+            return devTransform.call(this, code, id, opts);
+        },
+    };
+    function devTransform(code, id, opts) {
+        if (!isServe)
+            return null;
+        // sygnal/astro/client (Astro islands): flags + checks first. It imports
+        // the public 'sygnal' entry (the app's core, B-019), which resolves to
+        // the run() wrapper when the diagnostics option needs it.
+        if (devInject && !isVitest && !opts?.ssr) {
+            astroClient = astroClient || astroClientFiles(root);
+            if (astroClient.has(cleanId(id))) {
                 if (wrapRun)
                     runtimeImporters.add(cleanId(id));
+                return withSourcemap(code, [[0, devSnippet]], '', id);
             }
-            const done = (tail = '') => (inserts.length || tail ? withSourcemap(code, inserts, tail, id) : null);
-            // Skip HMR wiring if disabled, in tests, or already manually wired
-            if (disableHmr || isVitest || /\.(test|spec)\.[jt]sx?$/.test(id))
-                return done();
-            if (noComments.includes('import.meta.hot'))
-                return done();
-            // Strings and template literals blanked out too: a statement-level match only
-            const runCall = RUN_CALL_RE.exec(blankOut(code, true));
-            if (!runCall)
-                return done();
-            const [, binding, componentName] = runCall;
-            // Find the import path for this component
-            // Handles: import App from './App.jsx'
-            //          import App from "./App"
-            const componentImportRe = new RegExp(`import\\s+${componentName.replace(/\$/g, '\\$')}\\s+from\\s+['"]([^'"]+)['"]`);
-            const componentImportMatch = noComments.match(componentImportRe);
-            if (!componentImportMatch)
-                return done();
-            const componentPath = componentImportMatch[1];
-            // Pattern 3: bare run(App, ...) — no result captured → const __sygnal = run(
-            if (!binding) {
-                inserts.push([runCall.index, 'const __sygnal = ']);
-                return done(hmrBlock(componentPath, '__sygnal.hmr', '__sygnal.dispose'));
-            }
-            // Pattern 2: const app = run(App, ...)
-            if (binding[0] !== '{') {
-                return done(hmrBlock(componentPath, `${binding}.hmr`, `${binding}.dispose`));
+        }
+        // Only transform JS/TS/JSX/TSX files
+        if (!/\.[jt]sx?$/.test(id))
+            return null;
+        // Skip node_modules
+        if (id.includes('node_modules'))
+            return null;
+        // Must import run from sygnal
+        if (!code.includes('sygnal'))
+            return null;
+        // Match against the code with comments blanked out (same offsets), so
+        // e.g. `// run(App)` or a commented-out import is never matched.
+        const noComments = blankOut(code, false);
+        // Find: import { run, ... } from 'sygnal'
+        const runImportRe = /import\s+\{[^}]*\brun\b[^}]*\}\s+from\s+['"]sygnal['"]/;
+        if (!runImportRe.test(noComments)) {
+            return disableHmr || isVitest ? null : elementHmr(code, noComments, id);
+        }
+        // Dev snippet: injected into every file that imports run() — also when
+        // HMR wiring below is skipped. Inserted after any shebang line and
+        // directive prologue, without adding a line. Nothing under Vitest: a
+        // global flag set by one test file would leak dev/strict mode into the
+        // later test files of the same worker; there the checks come from
+        // test.setupFiles and renderComponent() manages the modes.
+        const inserts = [];
+        if (devInject && !isVitest) {
+            inserts.push(flagInsertion(code, devSnippet));
+            if (wrapRun)
+                runtimeImporters.add(cleanId(id));
+        }
+        const done = (tail = '') => (inserts.length || tail ? withSourcemap(code, inserts, tail, id) : null);
+        // Skip HMR wiring if disabled, in tests, or already manually wired
+        if (disableHmr || isVitest || /\.(test|spec)\.[jt]sx?$/.test(id))
+            return done();
+        if (noComments.includes('import.meta.hot'))
+            return done();
+        // Strings and template literals blanked out too: a statement-level match only
+        const runCall = RUN_CALL_RE.exec(blankOut(code, true));
+        if (!runCall)
+            return done();
+        const [, binding, componentName] = runCall;
+        // Find the import path for this component
+        // Handles: import App from './App.jsx'
+        //          import App from "./App"
+        const componentImportRe = new RegExp(`import\\s+${componentName.replace(/\$/g, '\\$')}\\s+from\\s+['"]([^'"]+)['"]`);
+        const componentImportMatch = noComments.match(componentImportRe);
+        if (!componentImportMatch)
+            return done();
+        const componentPath = componentImportMatch[1];
+        // Pattern 3: bare run(App, ...) — no result captured → const __sygnal = run(
+        if (!binding) {
+            inserts.push([runCall.index, 'const __sygnal = ']);
+            return done(hmrBlock(componentPath, '__sygnal.hmr', '__sygnal.dispose'));
+        }
+        // Pattern 2: const app = run(App, ...)
+        if (binding[0] !== '{') {
+            return done(hmrBlock(componentPath, `${binding}.hmr`, `${binding}.dispose`));
+        }
+        // Pattern 1: const { hmr, dispose, ... } = run(App, ...) — only when both
+        // are bound under their own names (a rename would leave them undefined)
+        const names = binding.slice(1, -1).split(',').map(s => s.trim());
+        if (names.includes('hmr') && names.includes('dispose')) {
+            return done(hmrBlock(componentPath, 'hmr', 'dispose'));
+        }
+        return done();
+    }
+}
+// PLAN-5 W-2 (D209): the adapter entries and the optional peer dependencies each one imports
+// (the Zag packages pinned together: they depend on each other's exact versions)
+const ZAG = '~1.45.0';
+const ADAPTER_PEERS = {
+    react: ['react', 'react-dom'],
+    zag: ['@zag-js/vanilla'],
+    // D211: one subpath per Zag part, each needing only its own machine
+    'ui/menu': ['@zag-js/vanilla', '@zag-js/menu'],
+    'ui/select': ['@zag-js/vanilla', '@zag-js/select'],
+    'ui/combobox': ['@zag-js/vanilla', '@zag-js/combobox'],
+};
+// 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))$/;
+/**
+ * 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
+ * provide it; the code is plain JS by then); when there is none, or the code doesn't parse, a
+ * scan of the code with comments blanked whose `from` / `import` keyword isn't inside a string
+ * or template literal. A literal that mentions an entry (a docs snippet) is never an import.
+ */
+function adapterImports(ctx, code, id) {
+    if (!code.includes('sygnal/') || id.includes('node_modules') || !/\.[cm]?[jt]sx?$/.test(cleanId(id)))
+        return null;
+    const noComments = blankOut(code, false);
+    if (!ADAPTER_RE.test(noComments))
+        return null;
+    ADAPTER_RE.lastIndex = 0;
+    const found = new Set();
+    let ast = null;
+    try {
+        ast = typeof ctx?.parse == 'function' ? ctx.parse(code) : null;
+    }
+    catch (_) { }
+    if (ast) {
+        const walk = (n) => {
+            if (!n || typeof n != 'object')
+                return;
+            if (Array.isArray(n))
+                return n.forEach(walk);
+            if (/^(Import|Export(Named|All))Declaration$|^ImportExpression$/.test(n.type)) {
+                // G-440: import(`sygnal/zag`): a template literal without substitutions is a known specifier
+                const src = n.source, q = src?.type == 'TemplateLiteral' && !src.expressions?.length ? src.quasis?.[0]?.value?.cooked : src?.value;
+                const m = ADAPTER_ID.exec(q ?? '');
+                if (m)
+                    found.add(m[1]);
             }
-            // Pattern 1: const { hmr, dispose, ... } = run(App, ...) — only when both
-            // are bound under their own names (a rename would leave them undefined)
-            const names = binding.slice(1, -1).split(',').map(s => s.trim());
-            if (names.includes('hmr') && names.includes('dispose')) {
-                return done(hmrBlock(componentPath, 'hmr', 'dispose'));
+            for (const k in n)
+                if (k != 'type' && typeof n[k] == 'object')
+                    walk(n[k]);
+        };
+        walk(ast);
+    }
+    else {
+        // strings and templates blanked too: a keyword there is text, not an import
+        const noStrings = blankOut(code, true);
+        for (const m of noComments.matchAll(ADAPTER_RE)) {
+            if (noStrings.startsWith(m[0].slice(0, m[0][0] == 'f' ? 4 : 6), m.index))
+                found.add(m[2]);
+        }
+    }
+    return found.size ? [...found] : null;
+}
+/** SYG666: resolves each entry's peers from the importing module; reports the missing ones */
+async function checkPeers(ctx, entries, id) {
+    for (const e of entries) {
+        const missing = [];
+        for (const peer of ADAPTER_PEERS[e]) {
+            let r = null;
+            try {
+                r = await ctx.resolve(peer, id, { skipSelf: true });
             }
-            return done();
-        },
-    };
+            catch (_) { }
+            if (!r)
+                missing.push(peer);
+        }
+        if (!missing.length)
+            continue;
+        const install = missing.map(m => (m.startsWith('@zag-js/') ? `${m}@${ZAG}` : m)).join(' ');
+        ctx.error(`[Sygnal SYG666] 'sygnal/${e}' needs ${missing.join(', ')}, which ${missing.length > 1 ? "aren't" : "isn't"} installed: npm install ${install}.` +
+            (e == 'react' ? " (For Preact: alias react, react-dom and react-dom/client to preact/compat.)" : '') +
+            ' https://sygnal.js.org/reference/errors#syg666');
+    }
 }
 /**
  * Major version of the running Vite: from the plugin context (this.meta,
@@ -439,6 +1229,16 @@ function sygnalPackageDir(root) {
     catch (_) { }
     return undefined;
 }
+/** The version of the 'sygnal' package the project resolves */
+function sygnalVersion(root) {
+    const dir = sygnalPackageDir(root);
+    try {
+        return dir ? JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version : undefined;
+    }
+    catch (_) {
+        return undefined;
+    }
+}
 /** Real paths of sygnal's 'astro/client' ESM file. */
 function astroClientFiles(root) {
     const files = new Set();
@@ -547,6 +1347,8 @@ async function startChecker(server, root, opts, defaults, explicit) {
     const include = checkInclude(root, opts.include, (m) => logger.info(m));
     const ignore = opts.ignore || defaults.ignore;
     const strict = opts.strict === undefined ? defaults.strict : !!opts.strict;
+    // D144: the a11y lane is a warning unless asked for as an error, under strict too
+    const a11y = opts.a11y === 'error' ? 'error' : 'warn';
     // Only error-severity findings open Vite's overlay: while an overlay is open
     // Vite's client reloads the page on the first HMR update, so warnings stay
     // in the terminal and the browser console. overlay: 'warn' is treated as
@@ -577,12 +1379,16 @@ async function startChecker(server, root, opts, defaults, explicit) {
     const run = (initial = false) => {
         let diags;
         try {
-            diags = mod.check(include, { cwd: root, strict, ignore });
+            diags = mod.check(include, { cwd: root, strict, ignore, a11y });
         }
         catch (err) {
             logger.warn(`[sygnal] sygnal-check failed: ${err?.message || err}`, { timestamp: true });
             return;
         }
+        // A sygnal-check from before D144 reports SYG7xx as errors under strict: keep them warnings
+        if (a11y !== 'error') {
+            diags = diags.map(d => d && d.severity === 'error' && /^SYG7\d\d$/.test(d.code) ? { ...d, severity: 'warn' } : d);
+        }
         const shown = diags.filter(d => d.severity !== 'info');
         const lines = shown.map(formatLine);
         const key = lines.join('\n');
@@ -735,6 +1541,29 @@ function withSourcemap(code, inserts, tail, id) {
         map: { version: 3, sources: [id], sourcesContent: [code], names: [], mappings },
     };
 }
+// A top-level (column 0) defineElement(...) call, as a statement or a declaration's value
+const DEFINE_ELEMENT_CALL_RE = /^(?:(?:export\s+)?(?:const|let|var)\s+[\w$]+\s*=\s*)?defineElement\s*\(/m;
+const ELEMENT_IMPORT_RE = /import\s+\{[^}]*\bdefineElement\b[^}]*\}\s+from\s+['"]sygnal\/element['"]/;
+/**
+ * PLAN-4 GS-13: a module that defines custom elements with 'sygnal/element' accepts its own
+ * hot updates. Re-running it calls defineElement again for the same tags, which swaps the
+ * component in every live element and keeps each one's state; an edited component module it
+ * imports reaches it the same way. Only for a top-level defineElement call, outside test
+ * files, when the module has no HMR code of its own and doesn't import run() (an entry's
+ * run() wiring decides there).
+ */
+function elementHmr(code, noComments, id) {
+    if (/\.(test|spec)\.[jt]sx?$/.test(id))
+        return null;
+    if (!ELEMENT_IMPORT_RE.test(noComments) || noComments.includes('import.meta.hot'))
+        return null;
+    if (!DEFINE_ELEMENT_CALL_RE.test(blankOut(code, true)))
+        return null;
+    return withSourcemap(code, [], ELEMENT_HMR_BLOCK, id);
+}
+const ELEMENT_HMR_BLOCK = `
+if (import.meta.hot) import.meta.hot.accept()
+`;
 function hmrBlock(componentPath, hmrRef, disposeRef) {
     return `
 if (import.meta.hot) {
@@ -745,11 +1574,32 @@ if (import.meta.hot) {
 }
 
 const SYGNAL_RENDERER_NAME = '@sygnal/astro';
+// PLAN-4 GS-11 / D120: both island entries import this; it re-exports the default export of the
+// module the `onError` option names (undefined without it)
+const ON_ERROR_ID = 'virtual:sygnal/astro-on-error';
+/** The Vite plugin serving ON_ERROR_ID; `file` is absolute (undefined: no hook) */
+function onErrorPlugin(file) {
+    return {
+        name: 'sygnal:astro-on-error',
+        resolveId: (id) => id === ON_ERROR_ID ? '\0' + ON_ERROR_ID : undefined,
+        load: (id) => id === '\0' + ON_ERROR_ID
+            ? (file ? `export { default } from ${JSON.stringify(file)}` : 'export default undefined')
+            : undefined,
+        // Vite 6+ (Astro 6 renders in its own 'prerender' / 'ssr' environments): the island server
+        // entry imports the virtual module, so Vite must load it (not Node). `ssr.noExternal`
+        // below covers the 'ssr' environment and older Vite
+        configEnvironment: (name) => name === 'client' ? undefined : { resolve: { noExternal: ['sygnal'] } },
+    };
+}
+/** The project root as a directory path (Astro gives a file: URL) */
+const rootDir = (root) => 
+// @ts-ignore — Node's process
+!root ? process.cwd() : typeof root === 'string' ? root : fileURLToPath(root);
 function sygnalAstroIntegration(options = {}) {
     return {
         name: SYGNAL_RENDERER_NAME,
         hooks: {
-            'astro:config:setup': ({ addRenderer, updateConfig, command }) => {
+            'astro:config:setup': ({ addRenderer, updateConfig, command, config }) => {
                 addRenderer({
                     name: SYGNAL_RENDERER_NAME,
                     clientEntrypoint: 'sygnal/astro/client',
@@ -760,11 +1610,16 @@ function sygnalAstroIntegration(options = {}) {
                         jsx: 'automatic',
                         jsxImportSource: 'sygnal',
                     },
+                    // D120: the island entries import the virtual onError module, so they stay on Vite:
+                    // not pre-bundled with it, and not externalized (loaded by Node) during SSR
+                    optimizeDeps: { exclude: [ON_ERROR_ID] },
+                    ssr: { noExternal: ['sygnal'] },
                 };
+                const hook = options.onError ? path.resolve(rootDir(config?.root), options.onError) : undefined;
                 // Dev mode (G-014): islands are started by sygnal/astro/client, which
                 // user code never imports, so the sygnal Vite plugin wraps that entry
-                // in dev to set the dev flag and load the runtime checks first. It
-                // also runs sygnal-check. Nothing is added to `astro build`.
+                // in dev to install DevTools, set the dev flag and load the runtime checks first. It
+                // also runs sygnal-check. `astro build` only gets the `globalthis` alias.
                 if (command === 'dev') {
                     vite.plugins = [sygnal({
                             disableJsx: true,
@@ -772,8 +1627,18 @@ function sygnalAstroIntegration(options = {}) {
                             vitestSetup: false,
                             diagnostics: options.diagnostics,
                             check: options.check,
+                            nativeGlobalThis: options.nativeGlobalThis,
+                            devtools: options.devtools,
                         })];
                 }
+                else if (options.nativeGlobalThis !== false) {
+                    // G-099: the same `globalthis` alias the plugin adds in dev (R2-7: unless the
+                    // user's vite config already aliases `globalthis`)
+                    const alias = globalThisAlias(config?.vite?.resolve?.alias);
+                    if (alias.length)
+                        vite.resolve = { alias };
+                }
+                vite.plugins = [...(vite.plugins || []), onErrorPlugin(hook)];
                 updateConfig({ vite });
             },
         },