sygnal 5.4.0 → 6.0.0

package/dist/astro/index.mjs

@@ -1,7 +1,59 @@
 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 }] : [];
+}
 
 /**
  * Sygnal Vite Plugin
@@ -17,7 +69,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 +108,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 +136,31 @@ 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).
  *
  * Why not Vite's `define`? Vite's dependency optimizer does not apply user
  * `define` replacements to pre-bundled dependencies (only process.env.NODE_ENV),
@@ -127,7 +205,7 @@ const OVERLAY_PLUGIN = 'sygnal-check';
 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 +218,15 @@ 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.
+    const devtoolsOn = options.devtools !== false;
+    const redux = typeof options.devtools == 'object' && !!options.devtools?.redux;
+    const devtoolsImport = !devtoolsOn ? ''
+        : redux ? `import { connectReduxDevtools as __sygnalReduxDevtools } from 'sygnal/devtools';__sygnalReduxDevtools();`
+            : `import 'sygnal/devtools';`;
+    // 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 +242,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 +279,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;
         },
@@ -228,7 +339,7 @@ function sygnal(options = {}) {
                 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.
@@ -251,7 +362,9 @@ function sygnal(options = {}) {
             // 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;
         },
@@ -267,84 +380,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,
@@ -547,6 +752,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 +784,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 +946,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 +979,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 +1015,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 +1032,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 });
             },
         },