@solidjs/vite-plugin 3.0.0-next.36 → 3.0.0-next.38

package/dist/esm/index.mjs

@@ -1,12 +1,12 @@
 import * as babel from '@babel/core';
 import remapping from '@ampproject/remapping';
 import solid from '@solidjs/babel-plugin';
-import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import fs, { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync } from 'fs';
 import { mergeAndConcat } from 'merge-anything';
 import { createRequire } from 'module';
 import path from 'path';
 import { Readable } from 'node:stream';
-import { createFilter, normalizePath, loadEnv, runnerImport, defaultClientConditions, defaultServerConditions, defaultExternalConditions } from 'vite';
+import { createFilter, normalizePath, loadEnv, runnerImport, transformWithOxc, defaultClientConditions, defaultServerConditions, defaultExternalConditions } from 'vite';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { crawlFrameworkPkgs } from 'vitefu';
 
@@ -63,7 +63,16 @@ function webRequestFromNode(req, urlPath, res) {
     signal = controller.signal;
   }
   const method = req.method || 'GET';
-  const body = method === 'GET' || method === 'HEAD' ? undefined : Readable.toWeb(req);
+  // Only attach a body when the request actually carries one. A web Request
+  // built by the browser for a bodyless POST has `body === null`, and the
+  // runtime keys off that (a present body that decodes to nothing is a 400
+  // since @solidjs/web 2.0.0-rc.5) — so an unconditionally attached (empty)
+  // stream misparses bodyless calls. HTTP/1 signals a body via
+  // Content-Length/Transfer-Encoding (RFC 9112 §6); the h2 compat API sets
+  // `stream.endAfterHeaders` when END_STREAM rode the headers frame.
+  const h2Stream = req.stream;
+  const hasBody = method !== 'GET' && method !== 'HEAD' && (h2Stream ? !h2Stream.endAfterHeaders : req.headers['transfer-encoding'] !== undefined || req.headers['content-length'] !== undefined && req.headers['content-length'] !== '0');
+  const body = hasBody ? Readable.toWeb(req) : undefined;
   return new Request(url, {
     method,
     headers,
@@ -137,6 +146,75 @@ function joinBase(base, pathname) {
   return (base.endsWith('/') ? base.slice(0, -1) : base) + pathname;
 }
 
+const TSRX_CSS_QUERY = '?solid-tsrx-css&lang.css';
+const NULL_BYTE_PLACEHOLDER$1 = '/@id/__x00__';
+function cleanModuleId(id) {
+  const query = id.indexOf('?');
+  return query === -1 ? id : id.slice(0, query);
+}
+function isTsrxModule(id) {
+  return cleanModuleId(id).toLowerCase().endsWith('.tsrx');
+}
+function isTsrxCssModule(id) {
+  const unwrapped = id.startsWith('\0') ? id.slice(1) : id.startsWith(NULL_BYTE_PLACEHOLDER$1) ? id.slice(NULL_BYTE_PLACEHOLDER$1.length) : id;
+  const queryIndex = unwrapped.indexOf('?');
+  if (queryIndex === -1 || !unwrapped.slice(0, queryIndex).toLowerCase().endsWith('.tsrx')) {
+    return false;
+  }
+  const params = unwrapped.slice(queryIndex + 1).split('&');
+  return params.includes('solid-tsrx-css') && params.includes('lang.css');
+}
+function resolveTsrxCssModule(id) {
+  if (!isTsrxCssModule(id)) return null;
+  if (id.startsWith('\0')) return id;
+  if (id.startsWith(NULL_BYTE_PLACEHOLDER$1)) {
+    return '\0' + id.slice(NULL_BYTE_PLACEHOLDER$1.length);
+  }
+  return '\0' + id;
+}
+function tsrxCssModuleId(id) {
+  return cleanModuleId(id) + TSRX_CSS_QUERY;
+}
+function resolvedTsrxCssModuleId(id) {
+  return '\0' + tsrxCssModuleId(id);
+}
+function tsrxCssSourceId(id) {
+  if (!id.startsWith('\0') || !isTsrxCssModule(id)) return null;
+  return cleanModuleId(id.slice(1));
+}
+function updateTsrxCss(cache, id, css) {
+  const key = cleanModuleId(id);
+  if (css) {
+    cache.set(key, css);
+  } else {
+    cache.delete(key);
+  }
+}
+function prependTsrxCssImport(code, id) {
+  return `import ${JSON.stringify(tsrxCssModuleId(id))};\n${code}`;
+}
+function offsetSourceMapLine(map) {
+  if (map && typeof map === 'object' && 'mappings' in map && typeof map.mappings === 'string') {
+    return {
+      ...map,
+      mappings: ';' + map.mappings
+    };
+  }
+  if (map && typeof map === 'object' && 'sections' in map && Array.isArray(map.sections)) {
+    return {
+      ...map,
+      sections: map.sections.map(section => ({
+        ...section,
+        offset: {
+          ...section.offset,
+          line: section.offset.line + 1
+        }
+      }))
+    };
+  }
+  return map;
+}
+
 /**
  * Dev-mode asset resolution: the `virtual:solid-manifest` module exports a
  * resolver function in dev (instead of the static object a build produces),
@@ -246,6 +324,9 @@ const cssFileRegExp = /\.(css|less|sass|scss|styl|stylus|pcss|postcss|sss)$/;
 // importer controls them — so they must not be SSR'd as style tags.
 const nonAmbientQueryRegExp = /[?&](url|inline|raw)\b/;
 const NULL_BYTE_PLACEHOLDER = '/@id/__x00__';
+function isCssModuleUrl(url) {
+  return cssFileRegExp.test(url.split('?')[0]) || isTsrxCssModule(url);
+}
 
 // Per Vite's convention virtual module ids are prefixed with `\0`, which
 // cannot appear in an HTML attribute (the parser replaces it). Serialize the
@@ -302,7 +383,7 @@ async function collectModuleDeps(env, file, deps, crawled, filter, onFile, impor
   const node = await getModuleNode(env, file, importer);
   if (!node?.id || deps.has(node)) return;
   deps.add(node);
-  const isCss = cssFileRegExp.test(node.url.split('?')[0]);
+  const isCss = isCssModuleUrl(node.url);
   if (!isCss && node.file && !node.id.startsWith('\0') && !filter(node.file)) return;
   if (node.file) onFile?.(node.file);
   if (isCss) return;
@@ -334,8 +415,7 @@ async function collectDevStyleSources(env, files, onFile, filter = defaultStyleF
   const seen = new Set();
   for (const node of deps) {
     if (!node.id) continue;
-    const cleanUrl = node.url.split('?')[0];
-    if (!cssFileRegExp.test(cleanUrl) || nonAmbientQueryRegExp.test(node.url)) continue;
+    if (!isCssModuleUrl(node.url) || nonAmbientQueryRegExp.test(node.url)) continue;
     const id = wrapId(node.id);
     if (seen.has(id)) continue;
     seen.add(id);
@@ -549,7 +629,11 @@ function boundaryModules() {
 }
 
 /**
- * Agent diagnostics surface (`diagnostics: true`, dev serve only).
+ * Agent diagnostics surface (dev serve only).
+ *
+ * Enabled automatically when the app declares `@solidjs/diagnostics` in
+ * its package.json (the `diagnostics` option overrides: `true` forces it
+ * on and errors if the package is missing, `false` opts out entirely).
  *
  * Three pieces:
  * - an injected client module (virtual, imported by index.html or the
@@ -577,6 +661,36 @@ const METHODS = ['begin', 'end', 'active', 'whyDidRun', 'costs'];
 
 /** How long the endpoint waits for a page to answer before failing the call. */
 const RESPONSE_TIMEOUT_MS = 10_000;
+
+/**
+ * Whether the app *declares* `@solidjs/diagnostics` — the auto-enable
+ * signal. Declaration in the nearest package.json (walking up from the
+ * Vite root, so a `client/` root still finds the app manifest) rather
+ * than node_modules presence: presence-based detection escapes the app
+ * into ancestor installs, which surprise-enables the surface for every
+ * fixture app inside a monorepo that happens to have the package
+ * somewhere above it (this broke the plugin's own example suites). A
+ * declared dependency is unambiguous intent, and resolution then works
+ * regardless of hoisting. `diagnostics: true` remains the override for
+ * setups the heuristic can't see.
+ */
+function detectDiagnosticsPackage(root) {
+  let dir = path.resolve(root);
+  while (true) {
+    const manifestPath = path.join(dir, 'package.json');
+    if (fs.existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        return !!(manifest.dependencies?.[DIAGNOSTICS_PACKAGE] ?? manifest.devDependencies?.[DIAGNOSTICS_PACKAGE] ?? manifest.optionalDependencies?.[DIAGNOSTICS_PACKAGE]);
+      } catch {
+        return false;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
 function diagnosticsClientModuleCode() {
   // Runtime imports resolve to the APP's diagnostics package (see the
   // resolveId assist below) — the page speaks its own package's protocol.
@@ -603,18 +717,26 @@ function readJsonBody(req) {
     req.on('error', reject);
   });
 }
-function solidDiagnostics() {
+function solidDiagnostics(mode = 'auto') {
   let root = process.cwd();
   let base = '/';
+  // Resolved at configResolved: explicit `true` is unconditional (missing
+  // package becomes a hard error at bridge resolution); `'auto'` enables
+  // only when the app has the package installed.
+  let enabled = mode === true;
   return {
     name: 'solid:diagnostics',
     // Dev-serve only: the channels this fronts exist in dev builds only.
+    // Test mode excluded — vitest (including browser mode) runs a dev
+    // serve, and injecting the bridge into test pages perturbs suites
+    // that never asked for it.
     apply(_config, env) {
-      return env.command === 'serve' && !env.isPreview;
+      return env.command === 'serve' && !env.isPreview && env.mode !== 'test';
     },
     configResolved(config) {
       root = config.root;
       base = config.base;
+      if (mode === 'auto') enabled = detectDiagnosticsPackage(root);
     },
     async resolveId(source, importer) {
       if (source === DIAGNOSTICS_CLIENT_ID) {
@@ -630,7 +752,7 @@ function solidDiagnostics() {
           skipSelf: true
         });
         if (!resolved || resolved.id.startsWith('__vite-optional-peer-dep:')) {
-          this.error(`[@solidjs/vite-plugin] the diagnostics option requires ${DIAGNOSTICS_PACKAGE} ` + 'installed in the app (it provides the in-page bridge). Install it as a ' + 'development dependency or remove `diagnostics: true`.');
+          this.error(`[@solidjs/vite-plugin] the diagnostics surface requires ${DIAGNOSTICS_PACKAGE} ` + 'installed in the app (it provides the in-page bridge). Install it as a ' + 'development dependency, or set `diagnostics: false` to opt out.');
         }
         return resolved;
       }
@@ -643,6 +765,7 @@ function solidDiagnostics() {
     // Plain (index.html) apps get the client module injected here;
     // start-mode apps import it from the generated client entry instead.
     transformIndexHtml() {
+      if (!enabled) return undefined;
       return [{
         tag: 'script',
         attrs: {
@@ -653,6 +776,11 @@ function solidDiagnostics() {
       }];
     },
     configureServer(server) {
+      // The whole surface (announcement, middleware, bridge injection) only
+      // exists when enabled, so the discovery breadcrumb never lies about
+      // a dead endpoint.
+      if (!enabled) return;
+
       // Announce the surface in the startup block. This is a discovery
       // channel: agents watching dev-server output learn the endpoint and
       // the skill documents without any project-level pointer (AGENTS.md).
@@ -661,7 +789,7 @@ function solidDiagnostics() {
         originalPrintUrls();
         const local = server.resolvedUrls?.local[0];
         const endpoint = local ? new URL(DIAGNOSTICS_ENDPOINT, local).href : DIAGNOSTICS_ENDPOINT;
-        server.config.logger.info(`  ➜  Solid diagnostics: ${endpoint} ` + `(GET status; POST {"method":"begin"|"end"|"whyDidRun"|"costs"})\n` + `  ➜  Agent skills: node_modules/${DIAGNOSTICS_PACKAGE}/skills/agent-loops/SKILL.md, ` + `node_modules/solid-js/skills/reactivity-diagnostics/SKILL.md`);
+        server.config.logger.info(`  ➜  Solid diagnostics: ${endpoint} ` + `(GET status; POST {"method":"begin"|"end"|"whyDidRun"|"costs"})` + (mode === 'auto' ? ' — auto-enabled; `diagnostics: false` opts out' : '') + `\n  ➜  Agent skills: node_modules/${DIAGNOSTICS_PACKAGE}/skills/agent-loops/SKILL.md, ` + `node_modules/solid-js/skills/reactivity-diagnostics/SKILL.md`);
       };
       const pending = new Map();
       let nextId = 1;
@@ -672,6 +800,11 @@ function solidDiagnostics() {
         clearTimeout(entry.timer);
         entry.resolve(data);
       });
+
+      // No host/origin validation here: on all supported Vite versions
+      // (peer range ^8) Vite's own DNS-rebinding host check runs ahead of
+      // plugin middleware — verified: requests with a disallowed Host
+      // header get Vite's 403 before reaching this handler.
       server.middlewares.use(DIAGNOSTICS_ENDPOINT, async (req, res) => {
         // The middleware mounts on the exact path; anything deeper is 404.
         if (req.url && req.url !== '/' && req.url !== '') {
@@ -794,7 +927,7 @@ async function compile(id, code, options) {
     mode: options.mode,
     env: options.env,
     directive: options.directive,
-    sourceMap: true,
+    sourceMap: options.sourceMap !== false,
     register: options.definitions.register,
     create: options.definitions.create
   });
@@ -920,11 +1053,11 @@ function xxHash32(buffer, seed = 0) {
  * root — not the invocation directory — so running `vite` from outside the
  * project keeps compiling the same files. Absolute patterns are used as-is.
  *
- * @default include "src/**\/*.{jsx,tsx,ts,js,mjs,cjs}", exclude "node_modules/**\/*.{jsx,tsx,ts,js,mjs,cjs}"
+ * @default include "src/**\/*.{jsx,tsx,tsrx,ts,js,mjs,cjs}", exclude "node_modules/**\/*.{jsx,tsx,tsrx,ts,js,mjs,cjs}"
  */
 
-const DEFAULT_INCLUDE = 'src/**/*.{jsx,tsx,ts,js,mjs,cjs}';
-const DEFAULT_EXCLUDE = 'node_modules/**/*.{jsx,tsx,ts,js,mjs,cjs}';
+const DEFAULT_INCLUDE = 'src/**/*.{jsx,tsx,tsrx,ts,js,mjs,cjs}';
+const DEFAULT_EXCLUDE = 'node_modules/**/*.{jsx,tsx,tsrx,ts,js,mjs,cjs}';
 const DEFAULT_MANIFEST = 'virtual:solid-server-function-manifest';
 const DEFAULT_DIRECTIVE = 'use server';
 const DEFAULT_RUNTIME = '@solidjs/web/server-functions';
@@ -1167,9 +1300,11 @@ function serverFunctions(options = {}, internal = {}) {
     `export function handleServerFunctionRequest(request, options) {`, `  const { event: eventInit, ...rest } = options || {};`, `  return handle(request, {`, `    provideEvent: provideRequestEvent,`, `    ...(eventInit ? { createEvent: (req) => ({ request: req, locals: {}, ...eventInit }) } : {}),`, `    ...rest,`, `  });`, `}`].join('\n');
   }
 
-  // Function IDs are `xxHash32(root-relative path)-<count>` (see compile.ts),
-  // so the hash segment maps an incoming ID back to its module. Rebuilt
-  // whenever a transform has grown the manifest.
+  // Function IDs are `<name>-<xxHash32(root-relative path)>[-<ordinal>]`
+  // (identity-keyed, solidjs/solid#3109). The name is a JS identifier and
+  // never contains `-`, so the hash is always the second segment and maps
+  // an incoming ID back to its module. Rebuilt whenever a transform has
+  // grown the manifest.
   const hashIndex = new Map();
   let hashIndexSize = -1;
   function moduleForFunctionId(functionId) {
@@ -1181,7 +1316,7 @@ function serverFunctions(options = {}, internal = {}) {
       }
       hashIndexSize = manifest.server.size;
     }
-    return hashIndex.get(functionId.split('-', 1)[0]);
+    return hashIndex.get(functionId.split('-')[1]);
   }
   function moduleDevUrl(entry) {
     const relative = path.relative(root, entry).split(path.sep).join('/');
@@ -1219,10 +1354,11 @@ function serverFunctions(options = {}, internal = {}) {
         if (internal.externalDevServer || !isRunnableEnvironment(ssrEnvironment)) {
           return;
         }
-        // A call's address is `<endpoint>/<id>` (solidjs/solid#3076) — the
-        // mount plus exactly one path segment. Bare-mount requests still
-        // reach the runtime handler (it answers 404), so misdirected posts
-        // fail through the endpoint rather than falling through to SSR.
+        // A call's address is `<endpoint>/<id>` — plain HTTP — or
+        // `<endpoint>/data/<id>` — the scripted transport's own path
+        // (solidjs/solid#3076, #3094). Bare-mount requests still reach the
+        // runtime handler (it answers 404), so misdirected posts fail
+        // through the endpoint rather than falling through to SSR.
         const underMount = (pathname, mount) => pathname === mount || pathname.startsWith(mount + '/');
         server.middlewares.use((req, res, next) => {
           const url = new URL(req.url || '/', 'http://localhost');
@@ -1241,9 +1377,15 @@ function serverFunctions(options = {}, internal = {}) {
             // Make sure the referenced module has been evaluated in the SSR
             // environment so its registration exists — functions only client
             // code references are never loaded by the SSR render itself.
-            // The id lives in the path segment after the mount.
+            // The id lives in the path segment after the mount — behind a
+            // literal `data` segment on the scripted transport's address
+            // (solidjs/solid#3094). Segment count keeps the two apart: an id
+            // occupies exactly one segment, so `data/<id>` is only ever a
+            // data address, and a function id spelled `data` still parses at
+            // the bare one.
             const mount = basePrefixed ? resolvedEndpoint : endpoint;
-            const segment = url.pathname.slice(mount.length + 1);
+            let segment = url.pathname.slice(mount.length + 1);
+            if (segment.startsWith('data/')) segment = segment.slice(5);
             let functionId = null;
             if (segment && !segment.includes('/')) {
               try {
@@ -1252,14 +1394,6 @@ function serverFunctions(options = {}, internal = {}) {
                 // not an address; the runtime handler answers the 404
               }
             }
-            if (!functionId) {
-              // TRANSITIONAL (remove before 3.0 stable): the retired header
-              // and `?id=` addressing, kept only for the RC window where this
-              // plugin meets a @solidjs/web older than the path-addressing
-              // change (solidjs/solid#3076).
-              const headerId = req.headers['x-server-function-id'];
-              functionId = (typeof headerId === 'string' ? headerId.split('#')[0] : undefined) || url.searchParams.get('id');
-            }
             if (functionId) {
               const entry = moduleForFunctionId(functionId);
               if (entry) await ssrEnvironment.runner.import(moduleDevUrl(entry));
@@ -1288,6 +1422,46 @@ function serverFunctions(options = {}, internal = {}) {
       }
     });
   }
+  async function transformModule(ctx, code, fileId, opts, tsrx) {
+    const mode = getEnvironmentConsumer(ctx.environment, opts);
+    const [id] = fileId.split('?');
+    if (!id || !filter(id) || isTsrxModule(id) !== tsrx) return null;
+
+    // The directive has to appear literally, so anything without the
+    // substring can skip the native parse entirely.
+    if (!code.includes(directive)) return null;
+    const result = await compile(id, code, {
+      ...(mode === 'server' ? serverOptions : clientOptions),
+      mode,
+      env,
+      root,
+      sourceMap: !tsrx || !!internal.tsrxSourceMap
+    });
+    if (!result.valid) return null;
+    const preloader = preload[mode];
+    if (preloader) preloader.defer();
+    invalidateModules(currentServer, mergeManifestRecord(manifest.server, new Set([id])), manifestId);
+    return {
+      // Appended (not prepended) so the source map for the compiled module
+      // stays valid; imports hoist and the endpoint is only read at call time.
+      code: (result.code || '') + endpointConfigureSnippet(mode),
+      map: result.map
+    };
+  }
+  const compilerPlugin = {
+    name: 'solid:server-functions/compiler',
+    enforce: 'pre',
+    transform(code, fileId, opts) {
+      return transformModule(this, code, fileId, opts, false);
+    }
+  };
+  const tsrxCompilerPlugin = {
+    name: 'solid:server-functions/tsrx-compiler',
+    enforce: 'pre',
+    transform(code, fileId, opts) {
+      return transformModule(this, code, fileId, opts, true);
+    }
+  };
   return [{
     name: 'solid:server-functions/setup',
     enforce: 'pre',
@@ -1364,44 +1538,7 @@ function serverFunctions(options = {}, internal = {}) {
       }
       return null;
     }
-  }, {
-    name: 'solid:server-functions/compiler',
-    enforce: 'pre',
-    async transform(code, fileId, opts) {
-      const mode = getEnvironmentConsumer(this.environment, opts);
-      const [id] = fileId.split('?');
-      if (!filter(id)) {
-        return null;
-      }
-
-      // Fast path: the directive has to appear literally, so anything
-      // without the substring can skip the native parse entirely.
-      if (!code.includes(directive)) {
-        return null;
-      }
-      const result = await compile(id, code, {
-        ...(mode === 'server' ? serverOptions : clientOptions),
-        mode,
-        env,
-        root
-      });
-      if (result.valid) {
-        const preloader = preload[mode];
-        if (preloader) {
-          preloader.defer();
-        }
-        invalidateModules(currentServer, mergeManifestRecord(manifest.server, new Set([id])), manifestId);
-        return {
-          // Appended (not prepended) so the source map for the compiled
-          // module stays valid; imports hoist and the endpoint is only
-          // read at call time, never during module evaluation.
-          code: (result.code || '') + endpointConfigureSnippet(mode),
-          map: result.map
-        };
-      }
-      return null;
-    }
-  }, ...startPlugins];
+  }, compilerPlugin, ...(internal.tsrxAfterSolid ? [tsrxCompilerPlugin] : []), ...startPlugins];
 }
 
 const DEVTOOLS_PACKAGE = '@solidjs/start-devtools';
@@ -1496,9 +1633,9 @@ const ERROR_BOUNDARY_ID = 'virtual:solid-ssr-error-boundary.tsx';
 const MANIFEST_ID = 'virtual:solid-manifest';
 const SERVER_FUNCTION_HANDLER_ID = 'virtual:solid-server-function-handler';
 const STORAGE_SOURCE = '@solidjs/web/storage';
-const ENTRY_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js', '.mjs'];
-const APP_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js'];
-const DOCUMENT_EXTENSIONS = ['.tsx', '.jsx'];
+const ENTRY_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js', '.mjs', '.tsrx'];
+const APP_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js', '.tsrx'];
+const DOCUMENT_EXTENSIONS = ['.tsx', '.jsx', '.tsrx'];
 function probe(root, stem, extensions) {
   for (const ext of extensions) {
     if (existsSync(path.resolve(root, stem + ext))) return stem + ext;
@@ -1606,7 +1743,9 @@ function startServe(options, internal = {}) {
   const serverComponents = !!internal.serverComponents;
   const errorBoundary = options.errorBoundary !== false;
   const styleFilter = internal.styleFilter;
-  const diagnostics = !!internal.diagnostics;
+  // `'auto'` resolves against the project root in configResolved, before
+  // any of the (lazy) uses in entry codegen and the entry transform.
+  let diagnostics = internal.diagnostics === true;
   let devtoolsEnabled = false;
   let devtoolsResolutions = {};
   let devtoolsIds = {};
@@ -1898,7 +2037,8 @@ function startServe(options, internal = {}) {
     lines.push(``, `async function dispatchRequest(request, event, options) {`);
     if (composeServerFunctions) {
       lines.push(
-      // A call's address is `<endpoint>/<id>` (solidjs/solid#3076); the
+      // A call's address is `<endpoint>/<id>` or `<endpoint>/data/<id>`
+      // (solidjs/solid#3076, #3094); the prefix gate covers both, and the
       // bare mount still routes so a misaddressed request 404s through the
       // runtime handler instead of rendering a page at it.
       `  const requestPath = new URL(request.url).pathname;`, `  if (requestPath === endpoint || requestPath.startsWith(endpoint + '/')) {`,
@@ -1971,6 +2111,7 @@ function startServe(options, internal = {}) {
       devtoolsResolutions = {};
       devtoolsIds = {};
       entries = resolveEntries(root, options, clientMode);
+      internal.onDocumentResolved?.(entries.document);
       middlewarePath = options.middleware ? path.resolve(root, normalizeUserPath(root, options.middleware, 'middleware')) : null;
       // Server-mode only, like `entryServer`/`external` (a documented
       // no-op in client mode so configs survive the `ssr` boolean flip).
@@ -2114,6 +2255,12 @@ function startServe(options, internal = {}) {
       root = config.root;
       base = config.base;
       isBuild = config.command === 'build';
+      // Test mode excluded for the same reason as the surface plugin's
+      // `apply`: vitest runs a dev serve, and test pages should not get
+      // the bridge import injected into their client entries.
+      if (internal.diagnostics === 'auto' && !isBuild && config.mode !== 'test') {
+        diagnostics = detectDiagnosticsPackage(root);
+      }
     },
     resolveId(source, importer, opts) {
       if (source === HANDLER_ID) {
@@ -2964,6 +3111,11 @@ const LAZY_PLACEHOLDER_PREFIX = '__SOLID_LAZY_MODULE__:';
  * solid-refresh#85 — is no longer used at all).
  */
 const REFRESH_RUNTIME_SOURCE = 'solid-js/refresh';
+
+// Appended to the document shell's client compile instead of a refresh
+// boundary (see documentModuleId in solidPlugin): self-accept, then
+// invalidate — Vite's spelling for "this module cannot hot-update, reload".
+const DOCUMENT_HMR_DECLINE = '\nif (import.meta.hot) {\n  import.meta.hot.accept(() => import.meta.hot.invalidate());\n}\n';
 const DEFAULT_STYLE_EXCLUDE = /node_modules/;
 const VIRTUAL_MANIFEST_ID = 'virtual:solid-manifest';
 const RESOLVED_VIRTUAL_MANIFEST_ID = '\0' + VIRTUAL_MANIFEST_ID;
@@ -3225,7 +3377,8 @@ function solidPlugin(options = {}) {
   // resolve against the Vite root, not process.cwd() — running `vite` from
   // outside the project would otherwise change what the filter matches.
   let filter = createFilter(options.include, options.exclude);
-  const serverComponents = typeof options.serverFunctions === 'object' && !!options.serverFunctions.components;
+  const serverComponentsOption = typeof options.serverFunctions === 'object' ? options.serverFunctions.components : undefined;
+  const serverComponents = !!serverComponentsOption;
   // `start: true` is sugar for the empty options bag — one start mode,
   // two spellings — so normalize here and let everything downstream see a
   // single shape (`false` behaves exactly like omission).
@@ -3255,6 +3408,15 @@ function solidPlugin(options = {}) {
   const externalDevServer = !!options.ssr && !!startOptions?.external;
   let needHmr = false;
   let replaceDev = false;
+  // Resolved absolute path of the start-mode document shell (normalized to
+  // forward slashes, matching Vite ids), reported back by the start plugin's
+  // config hook. The document is the one module whose client compile must
+  // decline HMR instead of taking a refresh boundary: it hydrates the whole
+  // `document`, and no component swap can re-claim `document.documentElement`
+  // — an accepted update would be absorbed with nothing visibly changing
+  // (solidjs/solid#3151). Declining makes a save invalidate the module, so
+  // Vite falls back to a full page reload: the honest cost.
+  let documentModuleId = null;
   // The live dev server, kept so the dev manifest module can bake the bridge
   // endpoint URL in when its code is generated (see devManifestBridgeUrl).
   let devServer = null;
@@ -3266,6 +3428,7 @@ function solidPlugin(options = {}) {
   let base = '/';
   let clientOutDir = null;
   let solidPkgsConfig;
+  const tsrxCss = new Map();
 
   // The client build's manifest, read back by SSR builds. In builder-mode
   // (single process, e.g. SolidStart's nitro plugin) the client build runs
@@ -3360,6 +3523,44 @@ function solidPlugin(options = {}) {
     const relativeId = path.relative(projectRoot, file).split(path.sep).join('/') + query;
     return code + `\nexport const $$moduleUrl = ${JSON.stringify(relativeId)};\n`;
   }
+  function nativeTsrxCss(result) {
+    const css = result.css;
+    return typeof css === 'string' ? css : '';
+  }
+  function babelTsrxCss(result) {
+    const css = result.metadata?.css;
+    return typeof css === 'string' ? css : '';
+  }
+  async function compileTsrxCss(source, id) {
+    const solidOptions = getSolidOptions(options, false, replaceDev, isTestMode);
+    if (options.compiler === 'babel') {
+      const babelUserOptions = await getBabelUserOptions(options, source, id, false);
+      const babelOptions = mergeAndConcat(babelUserOptions, {
+        root: projectRoot,
+        // Keep .tsrx: the Babel plugin uses it to select its TSRX parser.
+        filename: id,
+        sourceFileName: id,
+        ast: false,
+        code: false,
+        sourceMaps: false,
+        configFile: false,
+        babelrc: false,
+        parserOpts: {
+          plugins: ['jsx', 'decorators', 'typescript']
+        },
+        plugins: [[solid, solidOptions]]
+      });
+      const result = await babel.transformAsync(source, babelOptions);
+      return result ? babelTsrxCss(result) : '';
+    }
+    const compiler = await loadNativeCompiler();
+    const result = await compiler.transformAsync(source, {
+      ...solidOptions,
+      filename: id,
+      sourceMap: false
+    });
+    return nativeTsrxCss(result);
+  }
   const mainPlugin = {
     name: 'solid',
     enforce: 'pre',
@@ -3450,6 +3651,7 @@ function solidPlugin(options = {}) {
           dedupe: nestedDeps
         },
         optimizeDeps: {
+          extensions: ['.tsrx'],
           include: [...nestedDeps,
           // Dev refresh wrappers import the solid-js/refresh runtime in
           // every mode; pre-bundle it up front so its discovery doesn't
@@ -3470,7 +3672,28 @@ function solidPlugin(options = {}) {
               jsx: {
                 runtime: 'classic'
               }
-            }
+            },
+            plugins: [{
+              name: 'solid:tsrx-dep-scan',
+              async transform(source, id) {
+                if (!isTsrxModule(id) || isTsrxCssModule(id)) return null;
+                const compiler = await loadNativeCompiler();
+                const result = await compiler.transformAsync(source, {
+                  ...getSolidOptions(options, false, replaceDev, isTestMode),
+                  filename: cleanModuleId(id),
+                  sourceMap: false
+                });
+                const stripped = await transformWithOxc(result.code, cleanModuleId(id) + '.tsx', {
+                  lang: 'tsx',
+                  sourcemap: false,
+                  target: 'esnext'
+                });
+                return {
+                  code: stripped.code,
+                  map: null
+                };
+              }
+            }]
           }
         },
         ...(Object.keys(test).length ? {
@@ -3529,8 +3752,13 @@ function solidPlugin(options = {}) {
         resolve: projectRoot
       });
       styleFilter = createStyleFilter(projectRoot);
-      if (serverComponents && !(options.start && options.ssr)) {
-        config.logger.warn('[@solidjs/vite-plugin] serverFunctions.components is set without SSR start mode (the `start` ' + 'option with `ssr: true`), so the plugin only installs the endpoint response transform ' + '(server functions returning components stream correctly). The document wiring — render ' + 'plugin, bootstrap script, and the client-side installServerComponents() call — is ' + "emitted by SSR start mode's generated entries; without it, server components only mount " + 'from post-boot streams and your client code must call installServerComponents() itself.');
+      // `components: 'external'` is the acknowledgement that a composing
+      // host (e.g. the Astro adapter or TanStack Start's Solid integration)
+      // owns the document wiring itself — behavior is identical to `true`,
+      // only this warning is skipped. Under SSR start mode it's redundant
+      // but harmless (treated exactly as `true`).
+      if (serverComponents && serverComponentsOption !== 'external' && !(options.start && options.ssr)) {
+        config.logger.warn('[@solidjs/vite-plugin] serverFunctions.components is set without SSR start mode (the `start` ' + 'option with `ssr: true`), so the plugin only installs the endpoint response transform ' + '(server functions returning components stream correctly). The document wiring — the ' + 'render plugin (with the direct-call transform) and the client-side ' + "installServerComponents() call — is emitted by SSR start mode's generated entries; " + 'without it, server components only mount from post-boot streams and your client code ' + 'must call installServerComponents() itself. If a composing host owns that wiring, set ' + "`components: 'external'` to acknowledge it and silence this warning.");
       }
       needHmr = config.command === 'serve' && config.mode !== 'production' && options.hot !== false && !options.refresh?.disabled;
     },
@@ -3568,9 +3796,21 @@ function solidPlugin(options = {}) {
         return origSend(...args);
       };
     },
-    hotUpdate({
-      modules
+    async hotUpdate({
+      file,
+      modules,
+      read
     }) {
+      if (isTsrxModule(file) && this.environment.name === 'client') {
+        updateTsrxCss(tsrxCss, file, await compileTsrxCss(await read(), file));
+        const cssModule = this.environment.moduleGraph.getModuleById(resolvedTsrxCssModuleId(file));
+        if (cssModule) {
+          this.environment.moduleGraph.invalidateModule(cssModule);
+          if (!modules.includes(cssModule)) modules = [...modules, cssModule];
+          return modules;
+        }
+      }
+
       // solid-refresh only injects HMR boundaries into client modules, so
       // non-client environments have no accept handlers. Without this, Vite
       // would see no boundaries and send full-reload messages that race with
@@ -3589,11 +3829,26 @@ function solidPlugin(options = {}) {
           this.environment.hot.send({
             type: 'full-reload'
           });
+          // Server-only modules are the exception to the suppression: a file
+          // with no modules in the client graph has no browser HMR path at
+          // all — nothing client-side accepts it, so staying silent leaves
+          // the browser rendering stale server output until a manual refresh
+          // (e.g. the document shell, which only the server ever imports;
+          // solidjs/solid#3151). Reload the page: the honest cost, and there
+          // is no client update to race with by construction.
+          const clientEnv = devServer?.environments.client;
+          if (clientEnv && !clientEnv.moduleGraph.getModulesByFile(file)?.size) {
+            clientEnv.hot.send({
+              type: 'full-reload'
+            });
+          }
         }
         return [];
       }
     },
     resolveId(id) {
+      const tsrxCssId = resolveTsrxCssModule(id);
+      if (tsrxCssId) return tsrxCssId;
       if (id === VIRTUAL_MANIFEST_ID) return RESOLVED_VIRTUAL_MANIFEST_ID;
     },
     moduleParsed(info) {
@@ -3606,7 +3861,7 @@ function solidPlugin(options = {}) {
       for (const depId of info.dynamicallyImportedIds || []) {
         const cleanId = depId.split('?')[0];
         if (/node_modules/.test(cleanId) || cleanId.startsWith('\0')) continue;
-        if (!/\.[mc]?[tj]sx?$/i.test(cleanId)) continue;
+        if (!(/\.[mc]?[tj]sx?$/i.test(cleanId) || isTsrxModule(cleanId))) continue;
         if (emittedLazyChunks.has(depId)) continue;
         emittedLazyChunks.add(depId);
         emittedLazyChunkRefs.push(this.emitFile({
@@ -3617,6 +3872,8 @@ function solidPlugin(options = {}) {
       }
     },
     load(id) {
+      const tsrxSource = tsrxCssSourceId(id);
+      if (tsrxSource) return tsrxCss.get(tsrxSource) ?? '';
       if (id === RESOLVED_VIRTUAL_MANIFEST_ID) {
         if (!isBuild) {
           return devManifestCode(projectRoot, base, devServer ? devManifestBridgeUrl(devServer) : null);
@@ -3658,6 +3915,7 @@ function solidPlugin(options = {}) {
       }
     },
     async transform(source, id, transformOptions) {
+      if (isTsrxCssModule(id)) return null;
       const isSsr = getEnvironmentConsumer(this.environment, transformOptions) === 'server';
       const currentFileExtension = getExtension(id);
       const extensionsToWatch = options.extensions || [];
@@ -3673,14 +3931,15 @@ function solidPlugin(options = {}) {
       // while the transform pipeline below works on the clean file path.
       const moduleId = id;
       id = id.replace(/\?.*$/, '');
-      if (!(/\.[mc]?[tj]sx$/i.test(id) || allExtensions.includes(currentFileExtension))) {
+      const isTsrx = isTsrxModule(id);
+      if (!(/\.[mc]?[tj]sx$/i.test(id) || isTsrx || allExtensions.includes(currentFileExtension))) {
         return null;
       }
       const inNodeModules = /node_modules/.test(id);
       const solidOptions = getSolidOptions(options, !!isSsr, replaceDev, isTestMode);
 
       // We need to know if the current file extension has a typescript options tied to it
-      const shouldBeProcessedWithTypescript = /\.[mc]?tsx$/i.test(id) || extensionsToWatch.some(extension => {
+      const shouldBeProcessedWithTypescript = /\.[mc]?tsx$/i.test(id) || isTsrx || extensionsToWatch.some(extension => {
         if (typeof extension === 'string') {
           return extension.includes('tsx');
         }
@@ -3692,14 +3951,19 @@ function solidPlugin(options = {}) {
       if (shouldBeProcessedWithTypescript) {
         plugins.push('typescript');
       }
-      const needRefresh = needHmr && !isSsr && !inNodeModules;
+
+      // See the documentModuleId declaration: the document shell declines HMR
+      // (no refresh boundary, explicit self-invalidation) so edits full-reload.
+      const isDocumentShell = documentModuleId !== null && id === documentModuleId;
+      const needRefresh = needHmr && !isSsr && !inNodeModules && !isDocumentShell;
+      const declineHmr = isDocumentShell && needHmr && !isSsr;
       const babelUserOptions = await getBabelUserOptions(options, source, id, !!isSsr);
 
       // The native compiler picks its parser dialect from the file
       // extension; custom extensions registered through `options.extensions`
       // are unknown to it, so borrow a standard one matching the configured
       // TypeScript-ness.
-      const nativeFilename = /\.(?:[mc]?[jt]s|[jt]sx)$/i.test(id) ? id : id + (shouldBeProcessedWithTypescript ? '.tsx' : '.jsx');
+      const nativeFilename = isTsrx || /\.(?:[mc]?[jt]s|[jt]sx)$/i.test(id) ? id : id + (shouldBeProcessedWithTypescript ? '.tsx' : '.jsx');
 
       // Shared native prelude for every mode: the lazy() module-URL pass,
       // then (dev/client/non-node_modules) the solid-refresh HMR pass, both
@@ -3709,6 +3973,97 @@ function solidPlugin(options = {}) {
       const compiler = await loadNativeCompiler();
       let code = source;
       const maps = [];
+      if (isTsrx) {
+        // Solid lowering preserves authored TypeScript annotations; secondary
+        // passes therefore parse the generated module as TSX even though no
+        // template syntax remains.
+        const generatedFilename = id + '.tsx';
+        const babelBaseOptions = {
+          root: projectRoot,
+          filename: id,
+          sourceFileName: id,
+          ast: false,
+          sourceMaps: true,
+          configFile: false,
+          babelrc: false,
+          parserOpts: {
+            plugins
+          }
+        };
+        let css = '';
+        if (options.compiler !== 'babel') {
+          const result = await compiler.transformAsync(code, {
+            ...solidOptions,
+            filename: id,
+            sourceMap: true
+          });
+          code = result.code || '';
+          css = nativeTsrxCss(result);
+          maps.push(result.map);
+          if (options.babel) {
+            // The support pass cannot parse authored TSRX. On this route it
+            // intentionally sees the lowered ordinary JavaScript instead.
+            const supportOptions = mergeAndConcat(babelUserOptions, babelBaseOptions);
+            // This pass sees native-lowered ordinary JavaScript, so do not
+            // route it back through Babel's TSRX parser.
+            supportOptions.filename = generatedFilename;
+            const supportResult = await babel.transformAsync(code, supportOptions);
+            if (!supportResult) return undefined;
+            code = supportResult.code || '';
+            maps.push(supportResult.map);
+          }
+        } else {
+          const babelOptions = mergeAndConcat(babelUserOptions, {
+            ...babelBaseOptions,
+            plugins: [[solid, solidOptions]]
+          });
+          const result = await babel.transformAsync(code, babelOptions);
+          if (!result) return undefined;
+          code = result.code || '';
+          css = babelTsrxCss(result);
+          maps.push(result.map);
+        }
+        const lazyResult = await compiler.transformLazyAsync(code, {
+          filename: generatedFilename,
+          sourceMap: true
+        });
+        code = lazyResult.code;
+        maps.push(lazyResult.map);
+        if (needRefresh) {
+          const refreshResult = await compiler.transformRefreshAsync(code, {
+            filename: generatedFilename,
+            bundler: 'vite',
+            fixRender: true,
+            ...(typeof options.refresh?.granular === 'boolean' ? {
+              granular: options.refresh.granular
+            } : {}),
+            jsx: false,
+            importSource: REFRESH_RUNTIME_SOURCE,
+            sourceMap: true
+          });
+          code = refreshResult.code;
+          maps.push(refreshResult.map);
+        }
+        code = injectSsrModuleId(await resolveLazyModuleUrls(this, code, id), moduleId, !!isSsr);
+        let map = options.compiler === 'babel' ? combineSourcemaps(maps) : null;
+        updateTsrxCss(tsrxCss, id, css);
+        if (css) {
+          code = prependTsrxCssImport(code, id);
+          map = offsetSourceMapLine(map);
+        }
+        // Vite selects its TypeScript stripping by file extension. Since the
+        // real module identity remains `.tsrx`, strip the annotations here
+        // after Solid lowering instead of handing typed JavaScript to Rollup.
+        const stripped = await transformWithOxc(code, generatedFilename, {
+          lang: 'tsx',
+          sourcemap: map != null,
+          target: 'esnext'
+        }, map ?? undefined);
+        return {
+          code: stripped.code,
+          map: map == null ? null : stripped.map
+        };
+      }
       const lazyResult = await compiler.transformLazyAsync(code, {
         filename: nativeFilename,
         sourceMap: true
@@ -3764,7 +4119,7 @@ function solidPlugin(options = {}) {
         maps.push(result.map);
         const finalCode = injectSsrModuleId(await resolveLazyModuleUrls(this, result.code || '', id), moduleId, !!isSsr);
         return {
-          code: finalCode,
+          code: declineHmr ? finalCode + DOCUMENT_HMR_DECLINE : finalCode,
           map: combineSourcemaps(maps)
         };
       }
@@ -3785,26 +4140,30 @@ function solidPlugin(options = {}) {
       maps.push(result.map);
       const finalCode = injectSsrModuleId(await resolveLazyModuleUrls(this, result.code || '', id), moduleId, !!isSsr);
       return {
-        code: finalCode,
+        code: declineHmr ? finalCode + DOCUMENT_HMR_DECLINE : finalCode,
         map: combineSourcemaps(maps)
       };
     }
   };
 
-  // The directive transform must run before the JSX transform (it operates
-  // on raw directives, and client-mode module-level extraction must happen
-  // before templates are generated), so its sub-plugins go first. The
-  // boundary markers (`server-only` / `client-only`) are always on.
-  const plugins = options.serverFunctions ? [boundaryModules(), ...serverFunctions(options.serverFunctions === true ? {} : options.serverFunctions, {
+  // Ordinary modules need the directive transform before JSX. Authored TSRX
+  // cannot be parsed by that standalone pass, so its companion compiler runs
+  // after mainPlugin has lowered the file to ordinary JavaScript while keeping
+  // the original .tsrx id for stable server-function hashes.
+  const serverFunctionPlugins = options.serverFunctions ? serverFunctions(options.serverFunctions === true ? {} : options.serverFunctions, {
     devMiddleware: true,
     externalDevServer,
+    tsrxAfterSolid: true,
+    tsrxSourceMap: options.compiler === 'babel',
     // With start mode on (either variant), the dev middleware dispatches
     // the endpoint through the SSR handler so user middleware and the
     // stub-backed request event front it exactly like page SSR.
     ...(startOptions ? {
       ssrHandler: SSR_HANDLER_ID
     } : {})
-  }), mainPlugin] : [boundaryModules(), mainPlugin];
+  }) : [];
+  const tsrxServerFunctionPlugin = serverFunctionPlugins.find(plugin => plugin.name === 'solid:server-functions/tsrx-compiler');
+  const plugins = [boundaryModules(), ...serverFunctionPlugins.filter(plugin => plugin !== tsrxServerFunctionPlugin), mainPlugin, ...(tsrxServerFunctionPlugin ? [tsrxServerFunctionPlugin] : [])];
 
   // The `start` option opts into start-mode serving on top of the transforms;
   // the `ssr` boolean picks the mode (a bare `ssr: true` keeps the
@@ -3819,14 +4178,20 @@ function solidPlugin(options = {}) {
       serverComponents,
       ssr: !!options.ssr,
       styleFilter: filterDevStyles,
-      diagnostics: !!options.diagnostics
+      diagnostics: options.diagnostics ?? 'auto',
+      onDocumentResolved(documentPath) {
+        // Normalize to forward slashes to match Vite's transform ids.
+        documentModuleId = documentPath ? documentPath.split(path.sep).join('/') : null;
+      }
     }));
   }
 
   // Agent diagnostics endpoint + injected bridge (dev serve only — the
-  // plugin no-ops itself for builds and preview via `apply`).
-  if (options.diagnostics) {
-    plugins.push(solidDiagnostics());
+  // plugin no-ops itself for builds and preview via `apply`, and in the
+  // default auto mode additionally disables itself unless the app has
+  // `@solidjs/diagnostics` installed).
+  if (options.diagnostics !== false) {
+    plugins.push(solidDiagnostics(options.diagnostics === true ? true : 'auto'));
   }
 
   // Builder-mode (environments API) client-before-server build ordering.