@solidjs/compiler 2.0.0-rc.2 → 2.0.0-rc.20

package/README.md

@@ -78,17 +78,43 @@ const result = transform(source, {
 });
 ```
 
+### TSRX (experimental)
+
+TSRX (TypeScript Render Extensions) is a syntax for declarative UI whose constructs (`@if`/`@else`, `@for … @empty`, `@switch`/`@case`, `@try`/`@catch`/`@pending`, and `@{}` statement containers) desugar to the Solid control-flow components. `.tsrx` filenames route through the TSRX frontend automatically and compile to the same output as `@solidjs/babel-plugin`'s TSRX support, byte for byte.
+
+```js
+const result = transform(tsrxSource, { filename: "App.tsrx" });
+// TSRX <style> blocks are extracted alongside the JavaScript:
+result.css;
+result.cssHash;
+```
+
+Routing follows the filename by default (`syntax: "auto"`); pass `syntax: "tsrx"` or `syntax: "jsx"` to force a frontend regardless of filename. No extra install is needed — the shipped binaries include the frontend (Rust embedders can disable the default `tsrx` cargo feature).
+
+Scoped `<style>` blocks are compile-time only. The compiler removes the style element, adds its `tsrx-<hash>` class to matching native and dynamic elements, scopes and prunes the CSS, and returns the stylesheet in `css` with its scope identifier in `cssHash`. Style expressions produce class-map objects, `<style ref={styles}>` initializes the requested class map, and `:global(...)` opts individual selectors out of scoping. A bundler integration must emit the returned CSS; the core compiler does not inject a runtime style helper.
+
+Solid rejects authored TSRX lazy destructuring (`&{ … }` / `&[ … ]`). Keep accessor calls and reactive property reads explicit in Solid source.
+
+Control-flow bindings pass through exactly as authored. `@for … index` and `@for … key` hand the callback the item as an accessor (and the index as an accessor under a custom key), and `@catch (err, reset)` receives Solid's `ErrorAccessor` — write `item()`, `i()`, `err()` as you would in JSX. Destructuring a binding in one of those positions is rejected with a diagnostic, since there is nothing to destructure; the default keyed `@for` item is a raw value and destructures as usual.
+
+The frontend uses the community [oxc-tsrx](https://github.com/tsrx-org/oxc) parser at a pinned revision. Statement containers can be used as function bodies, statements, expressions (`const x = @{ … }`), and JSX children or expression containers. See `documentation/tsrx/frontend-notes.md` in the repository for the full frontend notes.
+
+`projectTsrxForTypecheck(source, { filename })` is an experimental compiler-owned projection for editor and typecheck integrations. It returns independently typecheckable TSX without running the DOM/SSR/universal transforms, injecting collision-safe imports for generated Solid control-flow and dynamic-element helpers. The tooling-only path recovers common incomplete editor snapshots while normal compilation remains strict. The result also includes an authored `.tsrx` source map, exact equal-text `mappings`, processed `css`/`cssHash`, and parser-authored embedded CSS/raw-script regions. Mapping and embedded offsets use JavaScript UTF-16 string coordinates. The ranges deliberately omit generated-only text; host adapters such as Volar attach feature capabilities to them.
+
 ### Source maps
 
-Pass `sourceMap: true` to receive a JSON source map string in `result.map`.
+Pass `sourceMap: true` to receive a JSON source map string in `result.map`. For TSRX, the compiler composes Oxc's generated-JavaScript map through the internal TSX text projection, returning the original `.tsrx` filename and source in `sources` and `sourcesContent`. Authored expressions and lazy/accessor rewrites map back to their TSRX locations; projection-only scaffolding remains explicitly unmapped rather than being attributed to nearby syntax.
 
 ### Options
 
 - `filename`
 - `moduleName` (default `"@solidjs/web"`)
+- `syntax`: `"auto"`, `"jsx"`, or `"tsrx"` (default `"auto"` — routes `.tsrx` filenames through the TSRX frontend)
 - `generate`: `"dom"`, `"ssr"`, `"universal"`, or `"dynamic"` (default `"dom"`)
 - `hydratable`
 - `dev`
+- `root` (`string`, default the working directory): the project root `sourceNames.locations` paths (and `transformSourceNames`'s `loc`) are made relative to — the same meaning as `transformDirectives`'s `root`.
+- `sourceNames` (`boolean | { components?: boolean; bindings?: boolean; locations?: boolean }`, default follows `dev`): names as written in source, carried into output so dev/observe runtimes can label the reactive graph after minification. Unset, every kind is on when `dev: true` and off otherwise; `true`/`false` sets every kind (`sourceNames: false` opts a dev build out); the object form picks, and each kind it leaves unspecified follows `dev`. Production output (`dev: false`) is byte-identical with the option set or unset. Same shape and defaults as `@solidjs/babel-plugin`'s option. `components` emits the source tag name as `createComponent`'s third argument (`createComponent(Home, props, "Home")`) — DOM and SSR output (SSR keeps the `createComponent` call it otherwise inlines to `Comp(props)`); not universal or dynamic. `bindings` names every compiled binding effect by what it writes — `effect(…, { name: "span.textContent" })`, a hole `insert(el, v, undefined, undefined, { name: "div.children" })`, a spread `spread(el, props, false, undefined, "div")` (labelled `div.spread` / `div.children` by the runtime) — DOM output only. `locations` adds the source position beside each name the other two kinds emit, as `<path>:<line>:<column>` with the path relative to `root` (posix separators, `..` when the file is outside the root) and the column 1-based (the stack-trace and editor convention, so `http://localhost:5173/src/App.tsx:18:3` links to the right place): `createComponent(Home, props, "Home", "src/App.tsx:12:5")` — the start of the opening element — and `loc` right after `name` in a binding's options, `effect(…, { name: "div.class", loc: "src/App.tsx:14:7" })` — the attribute's start, a hole's `{`, a spread's `{...props}` (a spread's location rides as one more positional string after the tag). Nothing is emitted without a `filename`. The production runtimes ignore the names. These are the JSX-level kinds only: naming the primitives themselves is the separate `transformSourceNames` pass below, which the build tool runs on every module independently of the JSX compiler
 - `sourceMap`
 - `contextToCustomElements` (default `true`)
 - `delegateEvents`
@@ -105,12 +131,12 @@ Pass `sourceMap: true` to receive a JSON source map string in `result.map`.
 - `omitLastClosingTag`
 - `builtIns` (default `["For", "Show", "Switch", "Match", "Loading", "Reveal", "Portal", "Repeat", "Dynamic", "Errored"]`)
 - `requireImportSource`
-- `serverComponents`
+- `hoistProps` (default `true`; SSR only)
 - `renderers`
 
 ### Server function directives (experimental)
 
-`transformDirectives(code, options)` is a second pass for `"use server"`. It applies to plain `.js`/`.ts` as well as JSX/TSX.
+`transformDirectives(code, options)` is a second pass for `"use server"`. It accepts ordinary JavaScript/TypeScript, including JSX/TSX. For a `.tsrx` module, run `transform()` first, then pass its generated code to `transformDirectives()` with the same original `.tsrx` filename so function IDs use the manifest path. `transformDirectives()` does not parse raw TSRX syntax itself.
 
 ```js
 const { transformDirectives } = require("@solidjs/compiler");
@@ -126,23 +152,90 @@ result.code;
 result.functions; // [{ id, name, exports }] for manifest building
 ```
 
-The runtime module defaults to `@solidjs/web/server-functions`. Function IDs use `xxhash32(root-relative path)-<count>` (name-suffixed with `env: "development"`). There are also experimental `transformLazy` and `transformRefresh` passes.
+A function-level `"use server"` function is extracted out of its lexical position, so it may only reference its own parameters and locals, module top-level bindings, and globals. Capturing anything else is a compile error. That includes `this` and `arguments` in a marked arrow, which an arrow takes from the function it was written in. Use a `function` if the server function needs its own `this` or `arguments`.
+
+A function-level directive only works where the pass can extract the function: a function declaration (at any nesting depth), a function expression, or an arrow with a block body. Methods, getters, and setters are never extracted, so a directive on one is a compile error rather than a directive that silently does nothing. Assign a function to a property instead.
+
+A module-level `"use server"` module can only export server functions. Its client build is rebuilt from those exports alone, so anything else would be missing from the browser bundle. Re-exports, `export *`, class and enum exports, destructured exports, and exports declared without an initializer are compile errors naming the export and its position. Type-only and `declare` exports are erased and are fine.
+
+The runtime module defaults to `@solidjs/web/server-functions`. Function IDs are `<name>-<xxhash32(root-relative path)>`, the same in every env. The name is the function's dotted binding path, such as `handlers.save`, built from every named container on the way down (variable bindings, property keys, class names, class members, and named functions), so an id identifies a function by where it is bound rather than by its position in the file. Adding, removing, or reordering functions does not move the ids of the others. There are also experimental `transformLazy` and `transformRefresh` passes.
+
+### Source names for primitives
+
+`transformSourceNames(code, { filename?, locations?, root?, sourceMap? })` is the pass behind `@solidjs/vite-plugin`'s `sourceNames.primitives` option: it names reactive primitives after the identifier they are declared as, so the dev and observe runtimes label graph nodes `count` / `doubled` / `todos.title` instead of `signal` / `computed` / `store.title`. With `locations` (default `true` — the pass only runs for the dev and observe postures) and a `filename`, the options literal also carries the call's position right after the name, `createSignal(0, { name: "count", loc: "src/store.ts:3:22" })` (`filename` relative to `root`, column 1-based); an explicit `name` is kept and `loc` still added, an explicit `loc` is never overridden. It is plain JavaScript in and out (JSX passes through untouched), which is why it is its own pass rather than a `transform()` option — primitives live in `.ts`/`.js` modules as much as in components. This standalone pass is the single owner of primitive naming: the build tool runs it on every module — `.ts`, `.js`, and JSX files alike — independently of which JSX compiler (this one or `@solidjs/babel-plugin`) handles the file's JSX, so there is no Babel counterpart and `transform()`'s `sourceNames` covers only the JSX-level kinds. `@solidjs/vite-plugin` (solid-vite-plugin #371, `solid: { sourceNames }`) runs it ahead of the JSX transform for the dev and `observe` postures.
+
+```js
+const [count, setCount] = createSignal(0);          // createSignal(0, { name: "count" })
+const doubled = createMemo(() => count() * 2);      // createMemo(…, { name: "doubled" })
+const [todos, setTodos] = createStore({ list: [] }); // createStore(…, { name: "todos" })
+export function createCounter() {
+  const [value, setValue] = createSignal(0);        // { name: "createCounter.value" }
+  …
+}
+function Counter() {
+  const [n, setN] = createSignal(0);                // { name: "n" } — no prefix in a component
+}
+```
+
+The name comes from the first element of the array pattern, the variable binding, the object-literal property key, or the class field the call initialises; a call in any other position (a hole in the pattern, an argument, an assignment) is left alone. Inside a non-component function — anything not PascalCase: `createCounter`, `useTheme`, a method — the name is prefixed with that function's, so a composed primitive's nodes fold under it (`createCounter.value`, `createCounter.twice`); components contribute no prefix, and anonymous callbacks inherit the nearest named function. Only calls that resolve to imports from `solid-js` or `@solidjs/signals` are named (aliases and namespace imports included; a shadowing local or another library's `createSignal` is not). The pass never overrides an explicit `name`, leaves a spread or non-literal options argument alone, fills omitted positional arguments with `void 0`, and reaches the call through `as`/`satisfies`/`!` and type arguments. Named: `createSignal`, `createMemo`, `createOptimistic`, `createStore`, `createOptimisticStore`, `createProjection`. A two-argument `createStore(x, y)` is only named when `y` is a non-empty object literal of option keys (`shallow`/`name`) — otherwise it may be a derive passed by reference with its seed.
 
 ## Rust compiler core
 
 The crate also exposes a host-independent Rust API. The crate name is `solidjs-compiler`; the Node `transform()` delegates to the same core.
 
 ```rust
-use solidjs_compiler::{compile, CompileOptions};
+use solidjs_compiler::{
+    compile, project_tsrx_for_typecheck, CompileOptions,
+    TsrxTypecheckProjectionOptions,
+};
 
 let output = compile(
     "const view = <div>{name()}</div>;",
     &CompileOptions::default(),
 )?;
+
+let tsrx_source = "export function View() @{ <div /> }";
+let virtual_tsx =
+    project_tsrx_for_typecheck(tsrx_source, &TsrxTypecheckProjectionOptions::default())?;
 ```
 
 `CompileOptions::default()` uses `module_name: "@solidjs/web"` and the same control-flow `built_ins` as the Babel plugin. Build with `--no-default-features` when embedding without the Node-API adapter.
 
+A frontend that builds its own Oxc AST instead of source text hands the program to `compile_program`, which runs the same back ends `compile` reaches after parsing. The program must be allocated in the allocator passed beside it, and `source` must be its `source_text`: the authored text its spans index, so source maps and diagnostics land on authored positions (keep authored spans on carried-over nodes and leave synthesized nodes at `SPAN`). The caller must build against the same Oxc release as this crate.
+
+```rust
+use oxc_allocator::Allocator;
+use solidjs_compiler::{compile_program, CompileOptions};
+
+let allocator = Allocator::default();
+let program = my_frontend::lower(&allocator, authored_source)?; // oxc_ast::ast::Program
+let output = compile_program(&allocator, program, authored_source, &CompileOptions::default())?;
+```
+
+TSRX's scoped-CSS engine is exported as `solidjs_compiler::style` for other frontends, in every build (it does not need the `tsrx` feature). It has no dependency on TSRX syntax or Oxc: describe the elements a `<style>` block governs as `Element` values, and `compile_style` returns the scoped stylesheet, its hash, the class map and the ids of the elements to annotate, the same bytes a `.tsrx` file with that stylesheet at that `StyleLocation` gets.
+
+```rust
+use solidjs_compiler::style::{compile_style, Element, ElementKind, StyleInput, StyleKind, StyleLocation};
+
+let elements = [Element {
+    id: 1,
+    kind: ElementKind::Native("div".into()),
+    attributes: Vec::new(),
+    has_spread: false,
+    children: Vec::new(),
+}];
+let output = compile_style(StyleInput {
+    css: "div { color: red }",
+    location: StyleLocation { filename: "view.rx", line: 3, column: 4 },
+    elements: &elements,
+    kind: StyleKind::Block,
+    minify: false,
+})?;
+// output.css, output.hash, output.class_map, output.scoped_elements
+```
+
+The unstable Rust typecheck projection reports embedded ranges in authored UTF-8 bytes. The N-API adapter converts those ranges to UTF-16 code units for JavaScript tooling.
+
 > **Stability:** the Rust API is unstable while the compiler is pre-1.0. Options, output, and error types may change in any release — pin an exact revision when embedding it.
 
 ## Performance
@@ -151,9 +244,9 @@ Compared against `@solidjs/babel-plugin` compiling identical sources under ident
 
 | Workload                                        | babel-plugin | compiler | Speedup |
 | ----------------------------------------------- | -----------: | -------: | ------: |
-| Fixture corpus (88 files, 175 KB, all 10 modes) |           440 ms |    19 ms |     23x |
-| 129 KB single module                            |           545 ms |   9.4 ms |     58x |
-| 1 MB single module                              |        24,975 ms |    70 ms |    355x |
+| Fixture corpus (88 files, 175 KB, all 10 modes) |       440 ms |    19 ms |     23x |
+| 129 KB single module                            |       545 ms |   9.4 ms |     58x |
+| 1 MB single module                              |    24,975 ms |    70 ms |    355x |
 
 Native throughput stays roughly flat as input grows, while Babel's per-file cost grows super-linearly.
 

package/index.js

@@ -10,24 +10,68 @@ function transform(code, options) {
     throw new TypeError("@solidjs/compiler transform() expects source code as a string");
   }
 
-  const nativeOptions = validateOptions(code, options);
+  const nativeOptions = hostRoot(validateOptions(code, options));
   const result = native.transform(code, nativeOptions);
-  return {
+  const output = {
     code: result.code,
     map: result.map ?? null
   };
+  // Preserve the established JSX result shape. Native TSRX transforms always
+  // return a CSS string (including `""` when no styles are present), which
+  // makes the sidecar fields a route-specific extension.
+  if (result.css != null) {
+    output.css = result.css;
+    output.cssHash = result.cssHash ?? null;
+  }
+  return output;
 }
 
 function transformAsync(code, options) {
   return Promise.resolve().then(() => transform(code, options));
 }
 
+function projectTsrxForTypecheck(code, options) {
+  if (typeof code !== "string") {
+    throw new TypeError(
+      "@solidjs/compiler projectTsrxForTypecheck() expects source code as a string"
+    );
+  }
+  const nativeOptions = validateTypecheckProjectionOptions(options);
+  const result = native.projectTsrxForTypecheck(code, nativeOptions);
+  return {
+    code: result.code,
+    map: result.map,
+    mappings: result.mappings,
+    css: result.css,
+    cssHash: result.cssHash ?? null,
+    embeddedRegions: result.embeddedRegions
+  };
+}
+
+function validateTypecheckProjectionOptions(options) {
+  if (options == null) return options;
+  if (typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError(
+      "@solidjs/compiler projectTsrxForTypecheck() expects options to be an object"
+    );
+  }
+  for (const key of Object.keys(options)) {
+    if (key !== "filename") {
+      throw new Error(`@solidjs/compiler received unknown option \`${key}\``);
+    }
+  }
+  if (options.filename !== undefined && typeof options.filename !== "string") {
+    throw new TypeError("@solidjs/compiler `filename` option must be a string");
+  }
+  return options;
+}
+
 function transformDirectives(code, options) {
   if (typeof code !== "string") {
     throw new TypeError("@solidjs/compiler transformDirectives() expects source code as a string");
   }
 
-  const nativeOptions = validateDirectivesOptions(options);
+  const nativeOptions = hostRoot(validateDirectivesOptions(options));
   const result = native.transformDirectives(code, nativeOptions);
   return {
     code: result.code,
@@ -75,6 +119,47 @@ function transformRefreshAsync(code, options) {
   return Promise.resolve().then(() => transformRefresh(code, options));
 }
 
+function transformSourceNames(code, options) {
+  if (typeof code !== "string") {
+    throw new TypeError("@solidjs/compiler transformSourceNames() expects source code as a string");
+  }
+
+  const nativeOptions = hostRoot(validateSourceNamesOptions(options));
+  const result = native.transformSourceNames(code, nativeOptions);
+  return {
+    code: result.code,
+    map: result.map ?? null
+  };
+}
+
+function transformSourceNamesAsync(code, options) {
+  return Promise.resolve().then(() => transformSourceNames(code, options));
+}
+
+const sourceNamesOptionKeys = new Set(["filename", "locations", "root", "sourceMap"]);
+
+function validateSourceNamesOptions(options) {
+  if (options == null) return options;
+  if (typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("@solidjs/compiler transformSourceNames() expects options to be an object");
+  }
+
+  const nativeOptions = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (!sourceNamesOptionKeys.has(key)) {
+      throw new Error(`@solidjs/compiler received unknown option \`${key}\``);
+    }
+    if ((key === "filename" || key === "root") && typeof value !== "string") {
+      throw new TypeError(`@solidjs/compiler \`${key}\` option must be a string`);
+    }
+    if ((key === "sourceMap" || key === "locations") && typeof value !== "boolean") {
+      throw new TypeError(`@solidjs/compiler \`${key}\` option must be boolean`);
+    }
+    nativeOptions[key] = value;
+  }
+  return nativeOptions;
+}
+
 const lazyOptionKeys = new Set(["filename", "sourceMap"]);
 
 function validateLazyOptions(options) {
@@ -109,7 +194,8 @@ const refreshOptionKeys = new Set([
   "sourceMap"
 ]);
 
-const refreshBundlers = new Set(["esm", "vite", "webpack5", "rspack-esm", "standard"]);
+// The runtime modes `solid-js/refresh` knows (its `RuntimeType`).
+const refreshBundlers = new Set(["vite", "standard"]);
 
 function validateRefreshOptions(options) {
   if (options == null) return options;
@@ -132,9 +218,7 @@ function validateRefreshOptions(options) {
       throw new TypeError(`@solidjs/compiler \`${key}\` option must be boolean`);
     }
     if (key === "bundler" && !refreshBundlers.has(value)) {
-      throw new TypeError(
-        '@solidjs/compiler `bundler` option must be "esm", "vite", "webpack5", "rspack-esm" or "standard"'
-      );
+      throw new TypeError('@solidjs/compiler `bundler` option must be "vite" or "standard"');
     }
     if (key === "jsx") {
       // The Babel plugin's JSX-granularity mode (its default!) is not
@@ -213,10 +297,12 @@ function validateImportDefinition(key, value) {
 
 const nativeOptionKeys = new Set([
   "filename",
+  "root",
   "moduleName",
   "generate",
   "hydratable",
   "dev",
+  "sourceNames",
   "sourceMap",
   "contextToCustomElements",
   "delegateEvents",
@@ -232,7 +318,7 @@ const nativeOptionKeys = new Set([
   "staticMarker",
   "omitNestedClosingTags",
   "omitLastClosingTag",
-  "serverComponents",
+  "hoistProps",
   "builtIns",
   "renderers"
 ]);
@@ -277,6 +363,21 @@ function validateOptions(code, options) {
       nativeOptions.validate = value;
       continue;
     }
+    if (key === "sourceNames") {
+      validateSourceNames(value);
+      nativeOptions.sourceNames = value;
+      continue;
+    }
+    // Removed with binding slots (2026-10-16). Still accepted, and ignored,
+    // because @solidjs/vite-plugin passes it for server-component builds.
+    if (key === "serverComponents") continue;
+    if (key === "root") {
+      if (typeof value !== "string") {
+        throw new TypeError("@solidjs/compiler `root` option must be a string");
+      }
+      nativeOptions.root = value;
+      continue;
+    }
     if (nativeOptionKeys.has(key)) {
       if (key === "renderers") validateRenderers(value);
       nativeOptions[key] = value;
@@ -287,6 +388,23 @@ function validateOptions(code, options) {
   return nativeOptions;
 }
 
+const sourceNameKinds = new Set(["components", "bindings", "locations"]);
+
+function validateSourceNames(value) {
+  if (typeof value === "boolean") return;
+  if (typeof value !== "object" || value == null || Array.isArray(value)) {
+    throw new TypeError("@solidjs/compiler `sourceNames` option must be boolean or an object");
+  }
+  for (const [kind, enabled] of Object.entries(value)) {
+    if (!sourceNameKinds.has(kind)) {
+      throw new Error(`@solidjs/compiler received unknown \`sourceNames\` kind \`${kind}\``);
+    }
+    if (typeof enabled !== "boolean") {
+      throw new TypeError(`@solidjs/compiler \`sourceNames.${kind}\` must be boolean`);
+    }
+  }
+}
+
 function validateRenderers(renderers) {
   if (renderers == null) return;
   if (!Array.isArray(renderers)) {
@@ -327,6 +445,23 @@ function tryPackage(packageName) {
   }
 }
 
+// The binding makes `filename` relative to `root` (`loc` paths, directive
+// hashes), resolving both against its own working directory. A WASI binding
+// cannot see the host's (it starts at `/`), so hand it a `root` that needs
+// none: absolute beside an absolute filename (the working directory when
+// unset), relative beside a relative one. The result is unchanged on a native
+// binding.
+function hostRoot(nativeOptions) {
+  if (nativeOptions == null || typeof nativeOptions.filename !== "string") return nativeOptions;
+  const { filename, root } = nativeOptions;
+  if (path.isAbsolute(filename)) {
+    nativeOptions.root = path.resolve(root ?? ".");
+  } else if (root !== undefined && path.isAbsolute(root)) {
+    nativeOptions.root = path.relative(process.cwd(), root) || ".";
+  }
+  return nativeOptions;
+}
+
 function requireBinding() {
   const explicit = process.env.SOLID_COMPILER_NATIVE;
   if (explicit) return require(explicit);
@@ -343,12 +478,10 @@ function requireBinding() {
   let nativeError;
   const suffix = platformArchSuffix();
 
-  if (suffix) {
-    const next = tryPackage(`@solidjs/compiler-${suffix}`);
-    if (next.binding) return next.binding;
-    if (next.error) nativeError = next.error;
-  }
-
+  // Local builds first: the published package ships no local binary (see
+  // "files"), so a `compiler.node` next to this file can only be a
+  // development build — which must shadow the installed platform package,
+  // or the monorepo's own tests silently run against the last release.
   const localCandidates = [];
   if (suffix) localCandidates.push(`compiler.${suffix}.node`);
   localCandidates.push("compiler.node");
@@ -358,12 +491,20 @@ function requireBinding() {
       try {
         return require(full);
       } catch (error) {
-        nativeError = error;
-        break;
+        // A present-but-unloadable dev build is an error, not a fallback:
+        // degrading to the published binary would silently test stale code.
+        error.message += `\nA local development build (${file}) exists but could not be loaded. Rebuild with \`pnpm run build:debug\` or delete it to use the installed @solidjs/compiler-* package.`;
+        throw error;
       }
     }
   }
 
+  if (suffix) {
+    const next = tryPackage(`@solidjs/compiler-${suffix}`);
+    if (next.binding) return next.binding;
+    if (next.error) nativeError = next.error;
+  }
+
   const wasi = requireWasi();
   if (wasi) return wasi;
 
@@ -405,10 +546,13 @@ function isMissingPackage(error, packageName) {
 module.exports = {
   transform,
   transformAsync,
+  projectTsrxForTypecheck,
   transformDirectives,
   transformDirectivesAsync,
   transformLazy,
   transformLazyAsync,
   transformRefresh,
-  transformRefreshAsync
+  transformRefreshAsync,
+  transformSourceNames,
+  transformSourceNamesAsync
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@solidjs/compiler",
   "description": "Solid's native Oxc JSX compiler",
-  "version": "2.0.0-rc.2",
+  "version": "2.0.0-rc.20",
   "author": "Ryan Carniato",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,7 @@
     "bench": "pnpm run build && node scripts/bench.mjs",
     "lint": "cargo clippy --manifest-path ./Cargo.toml -- -D warnings",
     "test": "pnpm run test:rust && pnpm run build:debug && vitest run",
-    "test:rust": "cargo test --manifest-path ./Cargo.toml && cargo test --manifest-path ./Cargo.toml --no-default-features",
+    "test:rust": "cargo test --manifest-path ./Cargo.toml && cargo test --manifest-path ./Cargo.toml --no-default-features && cargo test --manifest-path ./Cargo.toml --no-default-features --features tsrx",
     "artifacts": "napi artifacts",
     "napi:version": "napi version && node ./sync-optional-deps.mjs",
     "create-npm-dirs": "napi create-npm-dirs"
@@ -57,16 +57,16 @@
   "devDependencies": {
     "@emnapi/core": "^1.11.3",
     "@emnapi/runtime": "^1.11.3",
-    "@napi-rs/cli": "^3.7.2",
+    "@napi-rs/cli": "^3.10.6",
     "@napi-rs/wasm-runtime": "^1.1.6",
     "emnapi": "^1.11.3"
   },
   "optionalDependencies": {
-    "@solidjs/compiler-darwin-x64": "2.0.0-rc.2",
-    "@solidjs/compiler-darwin-arm64": "2.0.0-rc.2",
-    "@solidjs/compiler-linux-x64-gnu": "2.0.0-rc.2",
-    "@solidjs/compiler-linux-arm64-gnu": "2.0.0-rc.2",
-    "@solidjs/compiler-win32-x64-msvc": "2.0.0-rc.2",
-    "@solidjs/compiler-wasm32-wasi": "2.0.0-rc.2"
+    "@solidjs/compiler-darwin-x64": "2.0.0-rc.20",
+    "@solidjs/compiler-darwin-arm64": "2.0.0-rc.20",
+    "@solidjs/compiler-linux-x64-gnu": "2.0.0-rc.20",
+    "@solidjs/compiler-linux-arm64-gnu": "2.0.0-rc.20",
+    "@solidjs/compiler-win32-x64-msvc": "2.0.0-rc.20",
+    "@solidjs/compiler-wasm32-wasi": "2.0.0-rc.20"
   }
 }

package/types.d.ts

@@ -1,10 +1,60 @@
+/** The object form of `sourceNames`: which kinds of source name to carry into output. */
+export interface SourceNamesOptions {
+  /** Component owner labels: the tag as written, as `createComponent`'s third argument. */
+  components?: boolean;
+  /** Binding effect labels: the element and attribute (or hole) each compiled effect writes. */
+  bindings?: boolean;
+  /**
+   * Source locations beside each emitted name: `file:line:col` (`filename`
+   * relative to `root`, column 1-based) as `createComponent`'s fourth
+   * argument and as `loc` after `name` in a binding's options. Only where
+   * the name is emitted, and only with a `filename`.
+   */
+  locations?: boolean;
+}
+
 export interface TransformOptions {
   filename?: string;
+  /**
+   * Project root the `sourceNames.locations` paths are made relative to.
+   * Defaults to the working directory.
+   */
+  root?: string;
   /** Default `"@solidjs/web"`. */
   moduleName?: string;
+  /**
+   * Source syntax frontend, matching `@solidjs/babel-plugin`: `"auto"`
+   * (default) routes `.tsrx` filenames through the TSRX frontend and
+   * everything else through standard JSX; `"tsrx"` and `"jsx"` force a
+   * frontend regardless of filename. TSRX support is experimental.
+   */
+  syntax?: "auto" | "jsx" | "tsrx";
   generate?: "dom" | "ssr" | "universal" | "dynamic";
   hydratable?: boolean;
   dev?: boolean;
+  /**
+   * Names as written in source, carried into output so the dev and observe
+   * runtimes can label the reactive graph after minification.
+   * `components`: the tag as a third `createComponent` argument
+   * (`createComponent(Home, props, "Home")`) — DOM and SSR output (SSR
+   * keeps the `createComponent` call it would otherwise inline to
+   * `Comp(props)`); not universal or dynamic. `bindings`: every compiled
+   * binding effect named by what it writes — `span.textContent`,
+   * `div.class:active`, a hole `div.children`, a spread `div.spread` — as
+   * an options argument on `effect`/`insert`/`spread`; DOM output only.
+   * `locations`: the source position (`src/App.tsx:12:5`, `filename`
+   * relative to `root`) beside each emitted name — a fourth `createComponent`
+   * argument, `loc` after `name` in a binding's options — so a console
+   * report can point at the line; nothing without a `filename`.
+   * The production runtimes ignore the names. Defaults to `dev`: unset,
+   * every kind is on in dev and off otherwise; `true`/`false` sets every
+   * kind; an object picks, and each kind it leaves unspecified follows
+   * `dev`. Primitive names (`createSignal(0, { name: "count" })`) are not a
+   * kind here — they come from the standalone `transformSourceNames` pass,
+   * which the build tool runs on every module independently of this
+   * transform.
+   */
+  sourceNames?: boolean | SourceNamesOptions;
   sourceMap?: boolean;
   contextToCustomElements?: boolean;
   delegateEvents?: boolean;
@@ -19,7 +69,10 @@ export interface TransformOptions {
   validate?: boolean;
   omitNestedClosingTags?: boolean;
   omitLastClosingTag?: boolean;
+  /** @deprecated Ignored. Binding slots, the only thing it compiled for, are removed. */
   serverComponents?: boolean;
+  /** SSR-only, default `true`: component props literals with getters compile to module-level constructors with shared getters (#3511). */
+  hoistProps?: boolean;
   /** Default `["For", "Show", "Switch", "Match", "Loading", "Reveal", "Portal", "Repeat", "Dynamic", "Errored"]`. */
   builtIns?: string[];
   requireImportSource?: false | string;
@@ -35,6 +88,10 @@ export interface RendererOption {
 export interface TransformResult {
   code: string;
   map?: string | null;
+  /** Extracted scoped CSS for TSRX sources. */
+  css?: string | null;
+  /** Space-separated TSRX scope hashes. */
+  cssHash?: string | null;
 }
 
 export function transform(code: string, options?: TransformOptions | null): TransformResult;
@@ -43,6 +100,49 @@ export function transformAsync(
   options?: TransformOptions | null
 ): Promise<TransformResult>;
 
+export interface ProjectTsrxForTypecheckOptions {
+  filename?: string;
+}
+
+export interface TsrxTypecheckEmbeddedRegion {
+  kind: "css" | "script";
+  /** Authored JavaScript string offset in UTF-16 code units. */
+  start: number;
+  /** Authored JavaScript string offset in UTF-16 code units. */
+  end: number;
+  content: string;
+}
+
+export interface TsrxTypecheckMapping {
+  /** Authored JavaScript string offset in UTF-16 code units. */
+  sourceStart: number;
+  /** Generated JavaScript string offset in UTF-16 code units. */
+  generatedStart: number;
+  sourceLength: number;
+  generatedLength: number;
+}
+
+export interface TsrxTypecheckProjectionResult {
+  /** Valid post-semantic-rewrite TypeScript/TSX. */
+  code: string;
+  /** JSON source map from virtual TSX back to the authored `.tsrx` source. */
+  map: string;
+  /** Exact equal-text ranges suitable for editor feature mappings. */
+  mappings: TsrxTypecheckMapping[];
+  css: string;
+  cssHash: string | null;
+  embeddedRegions: TsrxTypecheckEmbeddedRegion[];
+}
+
+/**
+ * Experimental compiler-owned TSRX projection for typechecking and editor
+ * tooling. This API is host-independent and does not run a runtime renderer.
+ */
+export function projectTsrxForTypecheck(
+  code: string,
+  options?: ProjectTsrxForTypecheckOptions | null
+): TsrxTypecheckProjectionResult;
+
 export interface DirectiveImportDefinition {
   kind?: "named" | "default";
   name?: string;
@@ -77,8 +177,12 @@ export interface TransformDirectivesOptions {
 
 /** One extracted server function, for building a bundler manifest. */
 export interface ServerFunctionMeta {
-  /** The wire ID (`<hash>-<count>[-<name>]`). */
+  /** The wire ID (`<name>-<hash>[-<ordinal>]`). */
   id: string;
+  /**
+   * The dotted binding path that names the function, such as
+   * `handlers.save`. `anonymous` when no enclosing binding applies.
+   */
   name: string;
   /** Export names bound to this function (module-level directives only). */
   exports: string[];
@@ -132,12 +236,12 @@ export interface TransformRefreshOptions {
    */
   filename?: string;
   /**
-   * Selects the HMR API: `import.meta.hot` (esm/vite),
-   * `import.meta.webpackHot` (webpack5/rspack-esm) or `module.hot`
-   * (standard).
+   * Selects the HMR API — the runtime modes `solid-js/refresh` knows:
+   * `import.meta.hot` (vite), or `module.hot` / `import.meta.webpackHot`
+   * (standard: webpack, Rspack — the runtime probes for whichever exists).
    * @default "standard"
    */
-  bundler?: "esm" | "vite" | "webpack5" | "rspack-esm" | "standard";
+  bundler?: "vite" | "standard";
   /**
    * Wrap top-level `render()`/`hydrate()` calls (imported from
    * `@solidjs/web`) with `hot.dispose` cleanup.
@@ -172,3 +276,51 @@ export function transformRefreshAsync(
   code: string,
   options?: TransformRefreshOptions | null
 ): Promise<TransformResult>;
+
+/**
+ * Options for the `sourceNames.primitives` pass: reactive primitives named
+ * after the identifier they are declared as. `const [count, setCount] =
+ * createSignal(0)` becomes `createSignal(0, { name: "count" })`; inside a
+ * non-component function the name is prefixed with that function's
+ * (`createCounter.count`). Only calls resolving to imports from `solid-js` /
+ * `@solidjs/signals` are named, and an explicit `name` is never overridden.
+ * Plain JavaScript in and out, so it applies to `.ts`/`.js` modules too.
+ * This standalone pass is the single owner of primitive naming: the build
+ * tool (`@solidjs/vite-plugin`) runs it on every module — `.ts`, `.js` and
+ * JSX files alike — independently of which JSX compiler (this one or
+ * `@solidjs/babel-plugin`) handles the file's JSX. `transform()`'s
+ * `sourceNames` option covers only the JSX-level kinds.
+ */
+export interface TransformSourceNamesOptions {
+  /**
+   * Picks the parser dialect (`.ts`, `.tsx`, `.js`, `.jsx`); TSX without
+   * one. Also the file the `loc` strings name: without one no `loc` is
+   * written.
+   */
+  filename?: string;
+  /**
+   * Write `loc` after `name` in each options literal: the call's
+   * `file:line:col` (`filename` relative to `root`, column 1-based), so
+   * `createSignal(0, { name: "count", loc: "src/store.ts:3:22" })`. An
+   * explicit `name` is kept and `loc` still added; an explicit `loc` is
+   * never overridden. The pass only runs for the dev and observe postures,
+   * so this is on by default.
+   * @default true
+   */
+  locations?: boolean;
+  /**
+   * Project root the `loc` paths are made relative to. Defaults to the
+   * working directory.
+   */
+  root?: string;
+  sourceMap?: boolean;
+}
+
+export function transformSourceNames(
+  code: string,
+  options?: TransformSourceNamesOptions | null
+): TransformResult;
+export function transformSourceNamesAsync(
+  code: string,
+  options?: TransformSourceNamesOptions | null
+): Promise<TransformResult>;