sygnal 5.3.6 → 5.4.0

package/dist/astro/index.mjs

@@ -1,25 +1,784 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Sygnal Vite Plugin
+ *
+ * Auto-configures JSX, wires up HMR with state preservation and, in dev,
+ * turns on Sygnal's diagnostics (runtime checks and the static checker).
+ * Nothing it adds in dev reaches a production build.
+ *
+ * Usage:
+ *   import sygnal from 'sygnal/vite'
+ *   export default defineConfig({ plugins: [sygnal()] })
+ *
+ * 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
+ *   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:
+ *
+ *        if (globalThis.__SYGNAL_DEV__ === undefined) globalThis.__SYGNAL_DEV__ = true;
+ *        import 'sygnal/diagnostics';import 'virtual:sygnal/dev';
+ *
+ *      The flag turns on runtime diagnostics in 'warn' mode; 'sygnal/diagnostics'
+ *      registers the runtime checks (SYG101-106, 201, 202, 301, 401, ...);
+ *      'virtual:sygnal/dev' logs static-check results in the browser console
+ *      (see 5). With `diagnostics: { strict: true }` the snippet also sets
+ *      `globalThis.__SYGNAL_STRICT__ = true` (same guard), which turns on the
+ *      strict (SYG5xx) runtime checks of 'sygnal/diagnostics'. The snippet goes
+ *      after any shebang line and directive prologue ('use strict',
+ *      'use client'); line numbers are unchanged and the transform returns a
+ *      sourcemap. Opt out per app with `run(App, drivers, { diagnostics: 'off' })`
+ *      or for the whole dev server with `sygnal({ diagnostics: 'off' })`.
+ *   4. `diagnostics` option. The runtime core only understands
+ *      `__SYGNAL_DEV__ === true` ('warn'), so another mode or an ignore list
+ *      is passed as run()'s own `diagnostics` option: imports of 'sygnal'
+ *      from the entry files above resolve to a dev-only wrapper module
+ *      ('\0sygnal-dev:runtime') that re-exports sygnal with a run() that adds
+ *      `diagnostics: { mode, ignore }` unless the call sets `diagnostics`
+ *      itself. With the default ('warn', no ignore list) there is no wrapper.
+ *   5. `check` option: runs sygnal-check (an optional dependency, loaded
+ *      lazily from the project; `strict` defaults to `diagnostics.strict`)
+ *      over `include` (default: the existing ones of src/, pages/ and
+ *      renderer/, else the project root, with a notice) when the dev
+ *      server starts and again after every source file change. Results go to
+ *      the terminal in sygnal-check's format, and to the browser as a
+ *      'sygnal:check' HMR event that the dev client ('virtual:sygnal/dev')
+ *      logs with console.warn (non-disruptive). The dev client asks for the
+ *      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
+ *      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
+ *      server sends it again after the re-check, so it never causes a reload
+ *      and doesn't go stale. A missing sygnal-check is skipped silently; a
+ *      checker that throws only logs a warning.
+ *   6. Vitest (process.env.VITEST): appends the package's 'sygnal/diagnostics'
+ *      ESM file to `test.setupFiles` (merged with a string or array value;
+ *      not added twice), so renderComponent tests get the runtime checks.
+ *      Its directory is added to the resolved `server.fs.allow` (G-050):
+ *      in jsdom / happy-dom environments Vitest loads setup files through
+ *      Vite's /@fs/ URLs, which a linked sygnal outside the workspace would
+ *      otherwise fail. Opt out with `vitestSetup: false`. Under Vitest the transform adds
+ *      nothing (no flags, HMR wiring, run() wrapper, dev client or checker):
+ *      a __SYGNAL_DEV__ / __SYGNAL_STRICT__ flag set by one test file would
+ *      leak into later test files of the same worker, and renderComponent()
+ *      manages the diagnostics modes itself.
+ *   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
+ *      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`.
+ *
+ * Why not Vite's `define`? Vite's dependency optimizer does not apply user
+ * `define` replacements to pre-bundled dependencies (only process.env.NODE_ENV),
+ * so a `define` would never reach sygnal's own code when sygnal is pre-bundled.
+ * Vite's client does copy `define` entries onto globalThis at runtime, but only
+ * when `/@vite/client` is loaded (not under SSR or Vitest, where it would also
+ * switch diagnostics on for every test run). Injecting the flag into the
+ * entry file that calls run() is deterministic and scoped to the dev app; it
+ * runs before run() is called, which is when the diagnostics mode is resolved.
+ *
+ * The HMR transform finds the pattern:
+ *   import { run } from 'sygnal'
+ *   import App from './App.jsx'
+ *   run(App)
+ *
+ * And appends:
+ *   if (import.meta.hot) {
+ *     import.meta.hot.accept('./App.jsx', __sygnal.hmr)
+ *     import.meta.hot.dispose(__sygnal.dispose)
+ *   }
+ *
+ * HMR wiring is only added for a recognized top-level (column 0) run()
+ * statement whose result reference is actually defined (see RUN_CALL_RE). It
+ * is skipped — the dev flag is still injected — for any other shape (e.g.
+ * `app = run(App)`, nested or indented calls), for test files (*.test.*,
+ * *.spec.*) and under Vitest (process.env.VITEST).
+ */
+// Node built-ins (the plugin runs in Node). The package has no @types/node.
+// @ts-ignore
+const nodeProcess = globalThis.process;
+// Virtual modules (dev server only)
+const DEV_CLIENT = 'virtual:sygnal/dev';
+const DEV_CLIENT_ID = '\0' + DEV_CLIENT;
+const RUNTIME_ID = '\0sygnal-dev:runtime';
+const VIKE_CLIENT = 'sygnal/vike/onRenderClient';
+const VIKE_CLIENT_ID = '\0sygnal-dev:vike-client';
+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';
+// 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 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
+    const wrapRun = devOn && (diagnostics.mode !== 'warn' || diagnostics.ignore.length > 0);
+    let isServe = false;
+    let isVitest = false;
+    let root = nodeProcess.cwd();
+    // Files whose `import ... from 'sygnal'` resolves to the run() wrapper
+    const runtimeImporters = new Set();
+    // 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}';`;
+    let astroClient;
+    return {
+        name: 'vite-plugin-sygnal',
+        config(config, env) {
+            isServe = env.command === 'serve';
+            isVitest = !!nodeProcess?.env?.VITEST;
+            root = config?.root ? path.resolve(config.root) : nodeProcess.cwd();
+            const result = {
+                // Ensure sygnal is bundled for SSR rather than externalized.
+                // Without this, Node fails to resolve sygnal's exports from
+                // Vike's server chunks in production builds.
+                ssr: {
+                    noExternal: ['sygnal'],
+                },
+            };
+            if (!disableJsx) {
+                result.oxc = {
+                    jsx: {
+                        runtime: 'automatic',
+                        importSource: 'sygnal',
+                    },
+                };
+                // Vite 7 and older (Astro 6, Vitest on Vite 7) compile JSX with
+                // esbuild and ignore `oxc` (B-027); Vite 8 warns about `esbuild`
+                // from a plugin, so it is only set below Vite 8.
+                if (viteMajor(this, root) < 8) {
+                    result.esbuild = { jsx: 'automatic', jsxImportSource: 'sygnal' };
+                }
+                // Vite 8's dependency scanner doesn't use the `oxc` options: without
+                // this it compiles JSX for React, fails to resolve
+                // react/jsx-dev-runtime and skips pre-bundling (a reload on first load).
+                if (isServe && !isVitest) {
+                    result.optimizeDeps = { rolldownOptions: { transform: { jsx: { runtime: 'automatic', importSource: 'sygnal' } } } };
+                }
+            }
+            if (isVitest) {
+                if (vitestSetup) {
+                    const setup = diagnosticsSetupFile(root);
+                    const existing = [].concat(config?.test?.setupFiles || []);
+                    const loaded = existing.some(f => typeof f === 'string' &&
+                        (f === 'sygnal/diagnostics' || (!!setup && path.resolve(root, f) === setup)));
+                    // Vite merges arrays (and a string with an array) by concatenation
+                    if (setup && !loaded)
+                        result.test = { setupFiles: [setup] };
+                }
+            }
+            else if (isServe && devOn && 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'] };
+            }
+            return result;
+        },
+        configResolved(config) {
+            if (config?.root)
+                root = config.root;
+            // G-050: Vitest loads setup files by URL (/@fs/...) in browser-like
+            // environments (jsdom, happy-dom), and Vite refuses files outside
+            // server.fs.allow, which is the project's workspace by default. A linked
+            // (or hoisted) sygnal lives outside it, so allow its setup file's
+            // directory. The resolved list already holds Vite's defaults.
+            if (isVitest) {
+                const setup = diagnosticsSetupFile(root);
+                const allow = config?.server?.fs?.allow;
+                if (setup && Array.isArray(allow)) {
+                    const dir = path.dirname(setup);
+                    const inside = (base) => {
+                        const rel = path.relative(path.resolve(base), dir);
+                        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+                    };
+                    if (!allow.some(inside))
+                        allow.push(dir);
+                }
+            }
+        },
+        resolveId: {
+            order: 'pre',
+            async handler(source, importer, opts) {
+                if (!isServe || isVitest)
+                    return null;
+                if (source === DEV_CLIENT)
+                    return DEV_CLIENT_ID;
+                if (source === 'sygnal' && importer && wrapRun && runtimeImporters.has(cleanId(importer))) {
+                    return RUNTIME_ID;
+                }
+                if (source === VIKE_CLIENT && devOn && !opts?.ssr) {
+                    if (importer !== VIKE_CLIENT_ID)
+                        return VIKE_CLIENT_ID;
+                    // The wrapper's own import of the real entry: resolve it normally.
+                    // The real Vike client's run() then gets the run() wrapper too, when
+                    // it is served unbundled (a pre-bundled copy stays in 'warn' mode).
+                    const real = await this.resolve(source, importer, { ...opts, skipSelf: true });
+                    if (real && wrapRun)
+                        runtimeImporters.add(cleanId(real.id));
+                    return real;
+                }
+                return null;
+            },
+        },
+        load(id) {
+            if (id === DEV_CLIENT_ID)
+                return devClientModule();
+            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}`;
+            }
+            return null;
+        },
+        configureServer(server) {
+            if (isVitest || 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
+            const checkDefaults = { strict: diagnostics.strict, ignore: diagnostics.ignore };
+            setTimeout(() => {
+                startChecker(server, root, checkOptions, checkDefaults, options.check !== undefined)
+                    .catch(err => server?.config?.logger?.warn?.(`[sygnal] sygnal-check could not start: ${err?.message || err}`));
+            }, 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));
+                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();
+        },
+    };
+}
+/**
+ * Major version of the running Vite: from the plugin context (this.meta,
+ * Vite 7+), else from the vite package the project resolves. Infinity when
+ * unknown (treated as Vite 8+: no `esbuild` option).
+ */
+function viteMajor(ctx, root) {
+    const fromMeta = ctx?.meta?.viteVersion;
+    if (typeof fromMeta === 'string')
+        return parseInt(fromMeta, 10);
+    if (ctx?.meta?.rolldownVersion)
+        return 8;
+    try {
+        const req = createRequire(path.join(root, 'package.json'));
+        const v = JSON.parse(fs.readFileSync(req.resolve('vite/package.json'), 'utf8')).version;
+        const major = parseInt(v, 10);
+        if (major > 0)
+            return major;
+    }
+    catch (_) { }
+    return Infinity;
+}
+const MODES = ['off', 'collect', 'warn', 'error'];
+function normalizeDiagnostics(value) {
+    const o = typeof value === 'string' ? { mode: value } : value || {};
+    const mode = o.mode === undefined ? 'warn' : o.mode;
+    if (!MODES.includes(mode)) {
+        throw new Error(`[vite-plugin-sygnal] diagnostics mode must be one of ${MODES.map(m => `'${m}'`).join(', ')}; got ${JSON.stringify(mode)}`);
+    }
+    return { mode, strict: !!o.strict, ignore: Array.isArray(o.ignore) ? o.ignore.map(String) : [] };
+}
+/** Module id without a query or hash. */
+function cleanId(id) {
+    return id.replace(/[?#].*$/, '');
+}
+/** 'virtual:sygnal/dev': logs sygnal-check results in the browser console. */
+function devClientModule() {
+    // Vite's client reloads the page on the first HMR update while an error
+    // overlay is open. A sygnal-check overlay is closed before each update (the
+    // server sends it again after the re-check), so it never causes a reload.
+    return `if (import.meta.hot) {
+  let shown = 0;
+  let ours = false;
+  const closeOurs = () => {
+    if (!ours || typeof document === 'undefined') return;
+    document.querySelectorAll('vite-error-overlay').forEach((n) => n.close ? n.close() : n.remove());
+    ours = false;
+  };
+  import.meta.hot.on('vite:error', (payload) => {
+    ours = !!(payload && payload.err && payload.err.plugin === '${OVERLAY_PLUGIN}');
+  });
+  import.meta.hot.on('vite:beforeUpdate', closeOurs);
+  import.meta.hot.on('${CHECK_EVENT}', (payload) => {
+    const list = (payload && payload.diagnostics) || [];
+    if (!list.some((d) => d.severity === 'error')) closeOurs();
+    if (!list.length) {
+      if (shown) console.info('[sygnal-check] all findings resolved');
+      shown = 0;
+      return;
+    }
+    shown = list.length;
+    for (const d of list) console[d.severity === 'error' ? 'error' : 'warn']('[sygnal-check] ' + d.text);
+    console.info('[sygnal-check] ' + payload.summary);
+  });
+  import.meta.hot.send('${CHECK_REQUEST}');
+}
+`;
+}
+/** '\0sygnal-dev:runtime': sygnal with a run() that adds the plugin's diagnostics option. */
+function runtimeModule(d) {
+    const option = JSON.stringify({ mode: d.mode, ignore: d.ignore });
+    return `import { run as __run } from 'sygnal';
+export * from 'sygnal';
+export function run(app, drivers, options) {
+  if (options && options.diagnostics !== undefined) return __run(app, drivers, options);
+  return __run(app, drivers, Object.assign({}, options, { diagnostics: ${option} }));
+}
+`;
+}
+/** Directory of the 'sygnal' package the project resolves, or undefined. */
+function sygnalPackageDir(root) {
+    try {
+        const req = createRequire(path.join(root, 'package.json'));
+        let dir = path.dirname(req.resolve('sygnal'));
+        while (dir !== path.dirname(dir)) {
+            const pkgFile = path.join(dir, 'package.json');
+            if (fs.existsSync(pkgFile) && JSON.parse(fs.readFileSync(pkgFile, 'utf8')).name === 'sygnal')
+                return dir;
+            dir = path.dirname(dir);
+        }
+    }
+    catch (_) { }
+    return undefined;
+}
+/** Real paths of sygnal's 'astro/client' ESM file. */
+function astroClientFiles(root) {
+    const files = new Set();
+    const dir = sygnalPackageDir(root);
+    if (!dir)
+        return files;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        const entry = pkg.exports?.['./astro/client'];
+        const rel = typeof entry === 'string' ? entry : entry?.import;
+        if (typeof rel !== 'string')
+            return files;
+        const file = path.resolve(dir, rel);
+        files.add(file.split(path.sep).join('/'));
+        files.add(fs.realpathSync(file).split(path.sep).join('/'));
+    }
+    catch (_) { }
+    return files;
+}
+function sygnalInNodeModules(root) {
+    const dir = sygnalPackageDir(root);
+    if (!dir)
+        return false;
+    try {
+        return fs.realpathSync(dir).split(path.sep).includes('node_modules');
+    }
+    catch (_) {
+        return false;
+    }
+}
+/**
+ * Absolute path of the ESM build of 'sygnal/diagnostics' (its "import"
+ * condition), so the checks share the core instance the tests import.
+ */
+function diagnosticsSetupFile(root) {
+    const dir = sygnalPackageDir(root);
+    if (!dir)
+        return undefined;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        const entry = pkg.exports?.['./diagnostics'];
+        const rel = typeof entry === 'string' ? entry : entry?.import?.default || entry?.import || entry?.default;
+        if (typeof rel !== 'string')
+            return undefined;
+        const file = path.resolve(dir, rel);
+        return fs.existsSync(file) ? file : undefined;
+    }
+    catch (_) {
+        return undefined;
+    }
+}
+/** Load sygnal-check from the project (optional dependency); undefined when it is missing. */
+async function loadSygnalCheck(root) {
+    try {
+        const file = createRequire(path.join(root, 'package.json')).resolve('sygnal-check');
+        return await import(/* @vite-ignore */ pathToFileURL(file).href);
+    }
+    catch (_) { }
+    try {
+        const name = 'sygnal-check';
+        return await import(/* @vite-ignore */ name);
+    }
+    catch (_) {
+        return undefined;
+    }
+}
+const SOURCE_RE = /\.[cm]?[jt]sx?$/;
+/** sygnal-check's one-line format: `file:line:col CODE [severity] Component: message (fix)` */
+function formatLine(d) {
+    const where = d.file ? `${d.file}:${d.line}:${d.column}` : '<sygnal-check>';
+    const sev = d.severity === 'warn' ? '' : ` [${d.severity}]`;
+    return `${where} ${d.code}${sev} ${d.component ? d.component + ': ' : ''}${d.message}${d.fix ? ` (${d.fix})` : ''}`;
+}
+// Source directories checked by default, those that exist (Vike apps use
+// pages/ and renderer/, often without src/)
+const DEFAULT_INCLUDE = ['src', 'pages', 'renderer'];
+/**
+ * What sygnal-check checks: `include` when given, else the existing default
+ * directories, else the project root (sygnal-check skips node_modules, dist
+ * and other build output). Logs one notice when the default finds no
+ * directory, or when none of the given paths exists, so an empty check is
+ * never a silent all-clear.
+ */
+function checkInclude(root, include, notice) {
+    const exists = (p) => /[*?[{]/.test(p) || fs.existsSync(path.resolve(root, p));
+    if (include && include.length) {
+        if (!include.some(exists))
+            notice(`[sygnal] sygnal-check: none of check.include (${include.join(', ')}) exists under ${root}, so nothing is checked`);
+        return include;
+    }
+    const dirs = DEFAULT_INCLUDE.filter(exists);
+    if (dirs.length)
+        return dirs;
+    notice(`[sygnal] sygnal-check: no ${DEFAULT_INCLUDE.join('/, ')}/ directory under ${root}; checking the project root (set check.include to choose)`);
+    return ['.'];
+}
+/** Run sygnal-check now and after source changes; report to the terminal and the browser. */
+async function startChecker(server, root, opts, defaults, explicit) {
+    const mod = await loadSygnalCheck(root);
+    const logger = server?.config?.logger || console;
+    if (!mod || typeof mod.check !== 'function') {
+        if (explicit)
+            logger.info('[sygnal] sygnal-check is not installed, so static checks are off (npm i -D sygnal-check)');
+        return;
+    }
+    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;
+    // 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
+    // 'error' (with a one-time notice).
+    if (opts.overlay === 'warn') {
+        logger.info("[sygnal] check.overlay: 'warn' is treated as 'error': warnings go to the browser console, not Vite's error overlay (an open overlay makes Vite reload the page on the next update)");
+    }
+    const overlay = opts.overlay !== false;
+    let lastKey;
+    let payload = null;
+    let overlayErr = null;
+    const event = () => ({ type: 'custom', event: CHECK_EVENT, data: payload });
+    const errorMessage = () => ({ type: 'error', err: overlayErr });
+    // Every connected client (after a source change). An error with no client
+    // connected would be buffered by Vite and shown on the next page load.
+    const broadcast = (findingsChanged) => {
+        const ws = server.ws;
+        if (!ws || typeof ws.send !== 'function')
+            return;
+        try {
+            if (findingsChanged && payload)
+                ws.send(event());
+            if (overlayErr && !(ws.clients && ws.clients.size === 0))
+                ws.send(errorMessage());
+        }
+        catch (_) { }
+    };
+    const run = (initial = false) => {
+        let diags;
+        try {
+            diags = mod.check(include, { cwd: root, strict, ignore });
+        }
+        catch (err) {
+            logger.warn(`[sygnal] sygnal-check failed: ${err?.message || err}`, { timestamp: true });
+            return;
+        }
+        const shown = diags.filter(d => d.severity !== 'info');
+        const lines = shown.map(formatLine);
+        const key = lines.join('\n');
+        const changed = key !== lastKey;
+        if (changed) {
+            lastKey = key;
+            const text = typeof mod.formatDiagnostics === 'function'
+                ? mod.formatDiagnostics(diags)
+                : lines.concat(`sygnal-check: ${shown.length} finding(s)`).join('\n');
+            const summary = text.split('\n').pop() || '';
+            if (shown.length)
+                logger.warn(text, { timestamp: true });
+            else
+                logger.info(summary, { timestamp: true });
+            payload = {
+                summary,
+                diagnostics: shown.map((d, i) => ({ code: d.code, severity: d.severity, file: d.file, line: d.line, column: d.column, text: lines[i] })),
+            };
+            const forOverlay = overlay ? shown.filter(d => d.severity === 'error') : [];
+            const first = forOverlay[0];
+            overlayErr = first ? {
+                plugin: OVERLAY_PLUGIN,
+                message: forOverlay.map(formatLine).join('\n'),
+                stack: '',
+                id: path.resolve(root, first.file || ''),
+                loc: { file: path.resolve(root, first.file || ''), line: first.line, column: first.column },
+            } : null;
+        }
+        // The first check runs before any page is open; pages ask for the
+        // findings when they load (CHECK_REQUEST). After a change the overlay is
+        // sent again even when the findings are the same: the HMR update closed it.
+        if (!initial)
+            broadcast(changed);
+    };
+    run(true);
+    // A page that loads (or reloads) asks for the current findings: answer
+    // that client only, never every client.
+    try {
+        server.ws?.on?.(CHECK_REQUEST, (_data, client) => {
+            try {
+                if (payload)
+                    client?.send?.(event());
+                if (overlayErr)
+                    client?.send?.(errorMessage());
+            }
+            catch (_) { }
+        });
+    }
+    catch (_) { }
+    let timer;
+    const onChange = (file) => {
+        if (!SOURCE_RE.test(file) || file.split(/[\\/]/).includes('node_modules'))
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(run, 100);
+    };
+    const watcher = server?.watcher;
+    if (watcher && typeof watcher.on === 'function') {
+        watcher.on('change', onChange);
+        watcher.on('add', onChange);
+        watcher.on('unlink', onChange);
+    }
+    try {
+        server.httpServer?.once?.('close', () => clearTimeout(timer));
+    }
+    catch (_) { }
+}
+const DEV_FLAG = 'if (globalThis.__SYGNAL_DEV__ === undefined) globalThis.__SYGNAL_DEV__ = true;';
+const STRICT_FLAG = 'if (globalThis.__SYGNAL_STRICT__ === undefined) globalThis.__SYGNAL_STRICT__ = true;';
+// A top-level (column 0) run(Component, ...) statement: bare, or declaring a
+// new binding. Assignments to existing variables, nested calls and indented
+// calls (e.g. inside a function or test callback) do not match (B-007). It is
+// matched against the code with comments and strings blanked out.
+const RUN_CALL_RE = /^(?:(?:const|let|var)\s+(\{[^}]*\}|[\w$]+)\s*=\s*)?run\s*\(\s*([A-Z][\w$]*)/m;
+// Comments, string literals and template literals (a regex literal containing
+// a quote or `//` can over-blank; that only ever skips HMR wiring).
+const COMMENT_OR_STRING_RE = /\/\/[^\n]*|\/\*[\s\S]*?(?:\*\/|$)|(['"])(?:\\.|(?!\1)[^\\\n])*\1?|`(?:\\[\s\S]|[^\\`])*`?/g;
+/** Replace comments (and, with `strings`, string/template literals) by spaces, keeping offsets and newlines. */
+function blankOut(code, strings) {
+    return code.replace(COMMENT_OR_STRING_RE, m => !strings && m[0] !== '/' ? m : m.replace(/[^\n]/g, ' '));
+}
+// One directive ('use strict', "use client", ...) with any leading whitespace
+// and comments. It must end with `;` (group 2) or at the end of its line.
+const DIRECTIVE_RE = /(?:\s|\/\/[^\n]*|\/\*[\s\S]*?\*\/)*(['"])(?:\\.|(?!\1)[^\\\n])*\1(?:[ \t]*(;)|(?=[ \t]*(?:\/\/[^\n]*|\/\*[^\n]*?\*\/)?[ \t]*(?:\r?\n|$)))/y;
+/** Insert `text` (the dev snippet) after a shebang line and the directive prologue. */
+function flagInsertion(code, text) {
+    let at = code.startsWith('#!') ? (code.indexOf('\n') + 1 || code.length) : 0;
+    let semicolon = true;
+    DIRECTIVE_RE.lastIndex = at;
+    let m;
+    while ((m = DIRECTIVE_RE.exec(code))) {
+        at = DIRECTIVE_RE.lastIndex;
+        semicolon = !!m[2];
+    }
+    return [at, (semicolon ? '' : ';') + text];
+}
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+function vlq(n) {
+    let v = n < 0 ? (-n << 1) | 1 : n << 1;
+    let out = '';
+    do {
+        let digit = v & 31;
+        v >>>= 5;
+        if (v)
+            digit |= 32;
+        out += B64[digit];
+    } while (v);
+    return out;
+}
+/**
+ * Apply single-line insertions (at offsets in the original code) plus an
+ * appended tail, and build a v3 sourcemap without extra dependencies. No line
+ * is added before the tail, so every original line maps to itself; on a line
+ * with an insertion, the text after it maps back to its original column.
+ */
+function withSourcemap(code, inserts, tail, id) {
+    inserts.sort((a, b) => a[0] - b[0]);
+    let out = '';
+    let last = 0;
+    for (const [at, text] of inserts) {
+        out += code.slice(last, at) + text;
+        last = at;
+    }
+    out += code.slice(last) + tail;
+    let offset = 0;
+    let k = 0;
+    let prevLine = 0;
+    let prevCol = 0;
+    const mappings = code.split('\n').map((line, i) => {
+        const segments = [[0, 0]]; // [generated column, original column]
+        let shift = 0;
+        while (k < inserts.length && inserts[k][0] <= offset + line.length) {
+            const col = inserts[k][0] - offset;
+            shift += inserts[k][1].length;
+            segments.push([col + shift, col]);
+            k++;
+        }
+        offset += line.length + 1;
+        let genCol = 0;
+        return segments.map(([gen, col]) => {
+            const seg = vlq(gen - genCol) + 'A' + vlq(i - prevLine) + vlq(col - prevCol);
+            genCol = gen;
+            prevLine = i;
+            prevCol = col;
+            return seg;
+        }).join(',');
+    }).join(';');
+    return {
+        code: out,
+        map: { version: 3, sources: [id], sourcesContent: [code], names: [], mappings },
+    };
+}
+function hmrBlock(componentPath, hmrRef, disposeRef) {
+    return `
+if (import.meta.hot) {
+  import.meta.hot.accept('${componentPath}', ${hmrRef})
+  import.meta.hot.dispose(${disposeRef})
+}
+`;
+}
+
 const SYGNAL_RENDERER_NAME = '@sygnal/astro';
-function sygnalAstroIntegration() {
+function sygnalAstroIntegration(options = {}) {
     return {
         name: SYGNAL_RENDERER_NAME,
         hooks: {
-            'astro:config:setup': ({ addRenderer, updateConfig }) => {
+            'astro:config:setup': ({ addRenderer, updateConfig, command }) => {
                 addRenderer({
                     name: SYGNAL_RENDERER_NAME,
                     clientEntrypoint: 'sygnal/astro/client',
                     serverEntrypoint: 'sygnal/astro/server',
                 });
-                updateConfig({
-                    vite: {
-                        esbuild: {
-                            jsx: 'automatic',
-                            jsxImportSource: 'sygnal',
-                        },
+                const vite = {
+                    esbuild: {
+                        jsx: 'automatic',
+                        jsxImportSource: 'sygnal',
                     },
-                });
+                };
+                // 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`.
+                if (command === 'dev') {
+                    vite.plugins = [sygnal({
+                            disableJsx: true,
+                            disableHmr: true,
+                            vitestSetup: false,
+                            diagnostics: options.diagnostics,
+                            check: options.check,
+                        })];
+                }
+                updateConfig({ vite });
             },
         },
     };
 }
 
 export { sygnalAstroIntegration as default };
+//# sourceMappingURL=index.mjs.map