@solidjs/compiler 2.0.0-rc.10

package/README.md

@@ -0,0 +1,222 @@
+# @solidjs/compiler
+
+Solid 2.0's native Oxc JSX compiler. Integrations call `transform()` once per source module; this package is not a Vite, Rollup, or Babel plugin by itself. The JavaScript fallback is [`@solidjs/babel-plugin`](../babel-plugin).
+
+> **Solid 2.0 (Release Candidate).** Pin exact versions. The Node `transform()` interface is the supported public contract; the Rust `compile` API is unstable.
+
+## Installation
+
+```bash
+npm install @solidjs/compiler
+```
+
+The package ships prebuilt native binaries as optional per-platform packages (`@solidjs/compiler-darwin-arm64`, `-darwin-x64`, `-linux-x64-gnu`, `-linux-arm64-gnu`, `-win32-x64-msvc`). Your package manager installs the one matching your platform. On other platforms, build from source with `pnpm run build` inside `packages/compiler` (requires a Rust toolchain).
+
+### WebAssembly and StackBlitz
+
+A WASI fallback covers environments such as StackBlitz WebContainers, where Node reports a native platform but cannot load `.node` addons. Package managers install `@solidjs/compiler-wasm32-wasi` as an optional dependency. The package entry prefers a native binding and falls back to WASI when native addons are unavailable.
+
+- `NAPI_RS_FORCE_WASI=error` requires the WASI binding (useful in tests).
+- `SOLID_COMPILER_NATIVE=/path/to/binding.node` loads an explicit native addon.
+
+## Usage
+
+Omitted options match `@solidjs/babel-plugin` (and the old `babel-preset-solid`): `moduleName` is `"@solidjs/web"`, `generate` is `"dom"`, and control-flow tags (`For`, `Show`, `Switch`, `Match`, `Loading`, `Reveal`, `Portal`, `Repeat`, `Dynamic`, `Errored`) are auto-imported from that module.
+
+```js
+const { transform } = require("@solidjs/compiler");
+
+const result = transform(`const view = <div>Hello</div>;`, {
+  filename: "App.jsx"
+});
+
+console.log(result.code);
+```
+
+`transformAsync()` is the same transform behind a promise, for integration points that expect one.
+
+### Client DOM
+
+```js
+const result = transform(source, {
+  filename: "App.jsx",
+  generate: "dom",
+  hydratable: true
+});
+```
+
+`contextToCustomElements` defaults to `true`. Use `dev: true` with `hydratable: true` to emit hydration walk helpers such as `getFirstChild` / `getNextSibling`.
+
+### SSR
+
+SSR still imports runtime helpers from `@solidjs/web`. Set `generate: "ssr"` (and `hydratable: true` when the client will hydrate).
+
+```js
+const result = transform(source, {
+  filename: "entry-server.jsx",
+  generate: "ssr",
+  hydratable: true
+});
+```
+
+### Universal and dynamic
+
+Custom renderers use `generate: "universal"` with `moduleName` pointing at the renderer package. Dynamic mode uses that renderer as the fallback and can route a configured set of native tags to the DOM renderer.
+
+```js
+const result = transform(source, {
+  filename: "hybrid.jsx",
+  moduleName: "solid-custom-dom",
+  generate: "dynamic",
+  renderers: [
+    {
+      name: "dom",
+      moduleName: "@solidjs/web",
+      elements: ["div", "span", "button", "input"]
+    }
+  ]
+});
+```
+
+### 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`. 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`
+- `sourceNames` (`boolean | { components?: boolean; bindings?: 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. 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`
+- `delegatedEvents`
+- `omitQuotes`
+- `omitAttributeSpacing`
+- `inlineStyles`
+- `effectWrapper`: import name string, or `false` to disable
+- `memoWrapper`: import name string, or `false` to disable
+- `wrapConditionals`
+- `staticMarker`
+- `validate`
+- `omitNestedClosingTags`
+- `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 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");
+
+const result = transformDirectives(source, {
+  filename: "/project/src/api.ts",
+  root: "/project",
+  mode: "server" // or "client"
+});
+
+result.valid; // false when no directive matched — keep the original module
+result.code;
+result.functions; // [{ id, name, exports }] for manifest building
+```
+
+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?, 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`. 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, 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.
+
+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
+
+Compared against `@solidjs/babel-plugin` compiling identical sources under identical options (Apple M5, 10 cores, 32 GB RAM, Node 26, release build, in-process, median of 7 iterations after warmup — run `pnpm bench` in this package to reproduce):
+
+| 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 |
+
+Native throughput stays roughly flat as input grows, while Babel's per-file cost grows super-linearly.
+
+## Architecture
+
+Parse with Oxc, transform JSX with `VisitMut`, build replacements with `AstBuilder`, codegen once. Unsupported features are rejected rather than silently ignored. The module layout follows the Babel plugin (`shared`, `dom`, `ssr`, `universal`) where that mapping is useful.

package/index.js

@@ -0,0 +1,531 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const native = requireBinding();
+
+function transform(code, options) {
+  if (typeof code !== "string") {
+    throw new TypeError("@solidjs/compiler transform() expects source code as a string");
+  }
+
+  const nativeOptions = validateOptions(code, options);
+  const result = native.transform(code, nativeOptions);
+  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 result = native.transformDirectives(code, nativeOptions);
+  return {
+    code: result.code,
+    map: result.map ?? null,
+    valid: result.valid,
+    functions: result.functions
+  };
+}
+
+function transformDirectivesAsync(code, options) {
+  return Promise.resolve().then(() => transformDirectives(code, options));
+}
+
+function transformLazy(code, options) {
+  if (typeof code !== "string") {
+    throw new TypeError("@solidjs/compiler transformLazy() expects source code as a string");
+  }
+
+  const nativeOptions = validateLazyOptions(options);
+  const result = native.transformLazy(code, nativeOptions);
+  return {
+    code: result.code,
+    map: result.map ?? null
+  };
+}
+
+function transformLazyAsync(code, options) {
+  return Promise.resolve().then(() => transformLazy(code, options));
+}
+
+function transformRefresh(code, options) {
+  if (typeof code !== "string") {
+    throw new TypeError("@solidjs/compiler transformRefresh() expects source code as a string");
+  }
+
+  const nativeOptions = validateRefreshOptions(options);
+  const result = native.transformRefresh(code, nativeOptions);
+  return {
+    code: result.code,
+    map: result.map ?? null
+  };
+}
+
+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 = 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", "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" && typeof value !== "string") {
+      throw new TypeError("@solidjs/compiler `filename` option must be a string");
+    }
+    if (key === "sourceMap" && typeof value !== "boolean") {
+      throw new TypeError("@solidjs/compiler `sourceMap` option must be boolean");
+    }
+    nativeOptions[key] = value;
+  }
+  return nativeOptions;
+}
+
+const lazyOptionKeys = new Set(["filename", "sourceMap"]);
+
+function validateLazyOptions(options) {
+  if (options == null) return options;
+  if (typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("@solidjs/compiler transformLazy() expects options to be an object");
+  }
+
+  const nativeOptions = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (!lazyOptionKeys.has(key)) {
+      throw new Error(`@solidjs/compiler received unknown option \`${key}\``);
+    }
+    if (key === "filename" && typeof value !== "string") {
+      throw new TypeError("@solidjs/compiler `filename` option must be a string");
+    }
+    if (key === "sourceMap" && typeof value !== "boolean") {
+      throw new TypeError("@solidjs/compiler `sourceMap` option must be boolean");
+    }
+    nativeOptions[key] = value;
+  }
+  return nativeOptions;
+}
+
+const refreshOptionKeys = new Set([
+  "filename",
+  "bundler",
+  "fixRender",
+  "granular",
+  "jsx",
+  "importSource",
+  "sourceMap"
+]);
+
+// The runtime modes `solid-js/refresh` knows (its `RuntimeType`).
+const refreshBundlers = new Set(["vite", "standard"]);
+
+function validateRefreshOptions(options) {
+  if (options == null) return options;
+  if (typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("@solidjs/compiler transformRefresh() expects options to be an object");
+  }
+
+  const nativeOptions = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (!refreshOptionKeys.has(key)) {
+      throw new Error(`@solidjs/compiler received unknown option \`${key}\``);
+    }
+    if ((key === "filename" || key === "importSource") && typeof value !== "string") {
+      throw new TypeError(`@solidjs/compiler \`${key}\` option must be a string`);
+    }
+    if (
+      (key === "fixRender" || key === "granular" || key === "sourceMap") &&
+      typeof value !== "boolean"
+    ) {
+      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 "vite" or "standard"');
+    }
+    if (key === "jsx") {
+      // The Babel plugin's JSX-granularity mode (its default!) is not
+      // ported; only the vite-plugin-solid configuration (`jsx: false`) is.
+      if (value !== false) {
+        throw new Error(
+          "@solidjs/compiler transformRefresh() does not support `jsx: true` yet; pass `jsx: false`"
+        );
+      }
+      nativeOptions.jsx = false;
+      continue;
+    }
+    nativeOptions[key] = value;
+  }
+  return nativeOptions;
+}
+
+const directivesOptionKeys = new Set([
+  "filename",
+  "root",
+  "mode",
+  "env",
+  "directive",
+  "sourceMap",
+  "register",
+  "create"
+]);
+
+function validateDirectivesOptions(options) {
+  if (options == null || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("@solidjs/compiler transformDirectives() expects options to be an object");
+  }
+
+  const nativeOptions = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (!directivesOptionKeys.has(key)) {
+      throw new Error(`@solidjs/compiler received unknown option \`${key}\``);
+    }
+    if (key === "mode") {
+      if (value !== "server" && value !== "client") {
+        throw new TypeError('@solidjs/compiler `mode` option must be "server" or "client"');
+      }
+    }
+    if (key === "env") {
+      if (value !== "production" && value !== "development") {
+        throw new TypeError('@solidjs/compiler `env` option must be "production" or "development"');
+      }
+    }
+    if (key === "register" || key === "create") {
+      validateImportDefinition(key, value);
+    }
+    nativeOptions[key] = value;
+  }
+  if (typeof nativeOptions.filename !== "string") {
+    throw new TypeError("@solidjs/compiler transformDirectives() requires `filename`");
+  }
+  return nativeOptions;
+}
+
+function validateImportDefinition(key, value) {
+  if (typeof value !== "object" || value == null || Array.isArray(value)) {
+    throw new TypeError(`@solidjs/compiler \`${key}\` option must be an object`);
+  }
+  for (const nested of Object.keys(value)) {
+    if (nested !== "kind" && nested !== "name" && nested !== "source") {
+      throw new Error(`@solidjs/compiler received unknown \`${key}\` option \`${nested}\``);
+    }
+  }
+  if (typeof value.source !== "string") {
+    throw new TypeError(`@solidjs/compiler \`${key}.source\` must be a string`);
+  }
+  if (value.kind != null && value.kind !== "named" && value.kind !== "default") {
+    throw new TypeError(`@solidjs/compiler \`${key}.kind\` must be "named" or "default"`);
+  }
+}
+
+const nativeOptionKeys = new Set([
+  "filename",
+  "moduleName",
+  "generate",
+  "hydratable",
+  "dev",
+  "sourceNames",
+  "sourceMap",
+  "contextToCustomElements",
+  "delegateEvents",
+  "delegatedEvents",
+  "omitQuotes",
+  "omitAttributeSpacing",
+  "inlineStyles",
+  "effectWrapper",
+  "wrapConditionals",
+  "memoWrapper",
+  "requireImportSource",
+  "validate",
+  "staticMarker",
+  "omitNestedClosingTags",
+  "omitLastClosingTag",
+  "serverComponents",
+  "hoistProps",
+  "builtIns",
+  "renderers"
+]);
+
+function validateOptions(code, options) {
+  if (options == null) return options;
+  if (typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("@solidjs/compiler transform() expects options to be an object");
+  }
+
+  const nativeOptions = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (key === "effectWrapper" || key === "memoWrapper") {
+      if (typeof value !== "string" && typeof value !== "boolean") {
+        throw new TypeError(
+          `@solidjs/compiler \`${key}\` option must be a string import name or false`
+        );
+      }
+      nativeOptions[key] = value;
+      continue;
+    }
+    if (key === "requireImportSource") {
+      if (value !== false && typeof value !== "string") {
+        throw new TypeError(
+          "@solidjs/compiler `requireImportSource` option must be false or a string"
+        );
+      }
+      if (value !== false) nativeOptions.requireImportSource = value;
+      continue;
+    }
+    if (key === "wrapConditionals") {
+      if (typeof value !== "boolean") {
+        throw new TypeError("@solidjs/compiler `wrapConditionals` option must be boolean");
+      }
+      nativeOptions.wrapConditionals = value;
+      continue;
+    }
+    if (key === "validate") {
+      if (typeof value !== "boolean") {
+        throw new TypeError("@solidjs/compiler `validate` option must be boolean");
+      }
+      nativeOptions.validate = value;
+      continue;
+    }
+    if (key === "sourceNames") {
+      validateSourceNames(value);
+      nativeOptions.sourceNames = value;
+      continue;
+    }
+    if (nativeOptionKeys.has(key)) {
+      if (key === "renderers") validateRenderers(value);
+      nativeOptions[key] = value;
+      continue;
+    }
+    throw new Error(`@solidjs/compiler received unknown option \`${key}\``);
+  }
+  return nativeOptions;
+}
+
+const sourceNameKinds = new Set(["components", "bindings"]);
+
+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)) {
+    throw new TypeError("@solidjs/compiler `renderers` option must be an array");
+  }
+
+  for (const renderer of renderers) {
+    if (typeof renderer !== "object" || renderer == null || Array.isArray(renderer)) {
+      throw new TypeError("@solidjs/compiler renderer entries must be objects");
+    }
+    for (const key of Object.keys(renderer)) {
+      if (key !== "name" && key !== "moduleName" && key !== "elements") {
+        throw new Error(`@solidjs/compiler received unknown renderer option \`${key}\``);
+      }
+    }
+    if (renderer.name !== "dom") {
+      throw new Error(
+        "@solidjs/compiler dynamic renderers only support the `dom` renderer override"
+      );
+    }
+  }
+}
+
+function platformArchSuffix() {
+  const { platform, arch } = process;
+  if (platform === "darwin" && (arch === "x64" || arch === "arm64")) return `darwin-${arch}`;
+  if (platform === "linux" && (arch === "x64" || arch === "arm64")) return `linux-${arch}-gnu`;
+  if (platform === "win32" && arch === "x64") return "win32-x64-msvc";
+  return null;
+}
+
+function tryPackage(packageName) {
+  try {
+    return { binding: require(packageName) };
+  } catch (error) {
+    if (isMissingPackage(error, packageName)) return { missing: true };
+    return { error };
+  }
+}
+
+function requireBinding() {
+  const explicit = process.env.SOLID_COMPILER_NATIVE;
+  if (explicit) return require(explicit);
+
+  const forceWasi = process.env.NAPI_RS_FORCE_WASI;
+  if (forceWasi === "true" || forceWasi === "error") {
+    const wasi = requireWasi();
+    if (wasi) return wasi;
+    if (forceWasi === "error") {
+      throw new Error("WASI binding not found and NAPI_RS_FORCE_WASI is set to error");
+    }
+  }
+
+  let nativeError;
+  const suffix = platformArchSuffix();
+
+  // 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");
+  for (const file of localCandidates) {
+    const full = path.join(__dirname, file);
+    if (fs.existsSync(full)) {
+      try {
+        return require(full);
+      } catch (error) {
+        // 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;
+
+  if (nativeError) {
+    nativeError.message +=
+      "\nThe native binding could not be loaded and the optional " +
+      "@solidjs/compiler-wasm32-wasi fallback is not installed.";
+    throw nativeError;
+  }
+
+  throw new Error(
+    `Could not find an @solidjs/compiler binding for ${process.platform}-${process.arch}` +
+      (suffix
+        ? ` (expected @solidjs/compiler-${suffix}, @solidjs/compiler-wasm32-wasi, or a local build)`
+        : " (no prebuilt binary is published for this platform)") +
+      ". Install with WASM support or run `pnpm run build` in packages/compiler."
+  );
+}
+
+function requireWasi() {
+  const next = tryPackage("@solidjs/compiler-wasm32-wasi");
+  if (next.binding) return next.binding;
+  if (next.error) throw next.error;
+
+  const localWasi = path.join(__dirname, "compiler.wasi.cjs");
+  if (fs.existsSync(localWasi)) return require(localWasi);
+  return null;
+}
+
+function isMissingPackage(error, packageName) {
+  return (
+    error &&
+    error.code === "MODULE_NOT_FOUND" &&
+    typeof error.message === "string" &&
+    error.message.includes(`'${packageName}'`)
+  );
+}
+
+module.exports = {
+  transform,
+  transformAsync,
+  projectTsrxForTypecheck,
+  transformDirectives,
+  transformDirectivesAsync,
+  transformLazy,
+  transformLazyAsync,
+  transformRefresh,
+  transformRefreshAsync,
+  transformSourceNames,
+  transformSourceNamesAsync
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@solidjs/compiler",
+  "description": "Solid's native Oxc JSX compiler",
+  "version": "2.0.0-rc.10",
+  "author": "Ryan Carniato",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solidjs/solid.git",
+    "directory": "packages/compiler"
+  },
+  "main": "index.js",
+  "types": "types.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "types.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "napi build --release --strip --manifest-path ./Cargo.toml",
+    "build:debug": "napi build --manifest-path ./Cargo.toml",
+    "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 && 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"
+  },
+  "napi": {
+    "binaryName": "compiler",
+    "targets": [
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu",
+      "x86_64-pc-windows-msvc",
+      "wasm32-wasip1-threads"
+    ],
+    "wasm": {
+      "browser": {
+        "fs": false,
+        "asyncInit": false,
+        "buffer": false,
+        "errorEvent": true
+      }
+    }
+  },
+  "devDependencies": {
+    "@emnapi/core": "^1.11.3",
+    "@emnapi/runtime": "^1.11.3",
+    "@napi-rs/cli": "^3.7.2",
+    "@napi-rs/wasm-runtime": "^1.1.6",
+    "emnapi": "^1.11.3"
+  },
+  "optionalDependencies": {
+    "@solidjs/compiler-darwin-x64": "2.0.0-rc.10",
+    "@solidjs/compiler-darwin-arm64": "2.0.0-rc.10",
+    "@solidjs/compiler-linux-x64-gnu": "2.0.0-rc.10",
+    "@solidjs/compiler-linux-arm64-gnu": "2.0.0-rc.10",
+    "@solidjs/compiler-win32-x64-msvc": "2.0.0-rc.10",
+    "@solidjs/compiler-wasm32-wasi": "2.0.0-rc.10"
+  }
+}

package/types.d.ts

@@ -0,0 +1,290 @@
+/** 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;
+}
+
+export interface TransformOptions {
+  filename?: 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.
+   * 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;
+  delegatedEvents?: string[];
+  omitQuotes?: boolean;
+  omitAttributeSpacing?: boolean;
+  inlineStyles?: boolean;
+  effectWrapper?: "effect" | false;
+  wrapConditionals?: boolean;
+  memoWrapper?: "memo" | false;
+  staticMarker?: string;
+  validate?: boolean;
+  omitNestedClosingTags?: boolean;
+  omitLastClosingTag?: boolean;
+  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;
+  renderers?: RendererOption[];
+}
+
+export interface RendererOption {
+  name: string;
+  moduleName?: string;
+  elements: string[];
+}
+
+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;
+export function transformAsync(
+  code: string,
+  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;
+  source: string;
+}
+
+/**
+ * Options for the experimental `"use server"` directive pass. Applies to
+ * plain `.js`/`.ts` modules as well as JSX/TSX.
+ */
+export interface TransformDirectivesOptions {
+  /** Required — function IDs hash the root-relative file path. */
+  filename: string;
+  /** Project root for ID hashing. Defaults to the working directory. */
+  root?: string;
+  /**
+   * `"server"` keeps the module and registers extracted functions;
+   * `"client"` replaces them with reference proxies and strips server-only
+   * code.
+   */
+  mode: "server" | "client";
+  /** `"development"` appends function names to generated IDs. */
+  env?: "production" | "development";
+  /** @default "use server" */
+  directive?: string;
+  sourceMap?: boolean;
+  /** Runtime import for `registerServerReference` (server output). */
+  register?: DirectiveImportDefinition;
+  /** Runtime import for `createServerReference` (both outputs). */
+  create?: DirectiveImportDefinition;
+}
+
+/** One extracted server function, for building a bundler manifest. */
+export interface ServerFunctionMeta {
+  /** 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[];
+}
+
+export interface TransformDirectivesResult {
+  code: string;
+  map?: string | null;
+  /** False when the module contained no matching directive. */
+  valid: boolean;
+  functions: ServerFunctionMeta[];
+}
+
+export function transformDirectives(
+  code: string,
+  options: TransformDirectivesOptions
+): TransformDirectivesResult;
+export function transformDirectivesAsync(
+  code: string,
+  options: TransformDirectivesOptions
+): Promise<TransformDirectivesResult>;
+
+/**
+ * Options for the experimental `lazy()` module-URL pass (ported from
+ * vite-plugin-solid's `lazy-module-url` Babel plugin).
+ */
+export interface TransformLazyOptions {
+  /**
+   * Mirrors the Babel plugin: without a filename the pass is a no-op (the
+   * emitted placeholder is only useful to a bundler resolving relative to a
+   * module id).
+   */
+  filename?: string;
+  sourceMap?: boolean;
+}
+
+export function transformLazy(code: string, options?: TransformLazyOptions | null): TransformResult;
+export function transformLazyAsync(
+  code: string,
+  options?: TransformLazyOptions | null
+): Promise<TransformResult>;
+
+/**
+ * Options for the experimental solid-refresh HMR pass (ported from the
+ * `solid-refresh` Babel plugin, `jsx: false` mode). Dev-only.
+ */
+export interface TransformRefreshOptions {
+  /**
+   * Used for `location` metadata (cwd-relative, matching the Babel plugin)
+   * and to pick the parser dialect. Without it no locations are emitted.
+   */
+  filename?: string;
+  /**
+   * 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?: "vite" | "standard";
+  /**
+   * Wrap top-level `render()`/`hydrate()` calls (imported from
+   * `@solidjs/web`) with `hot.dispose` cleanup.
+   * @default true
+   */
+  fixRender?: boolean;
+  /**
+   * Emit per-component `signature`/`dependencies` metadata for granular HMR.
+   * @default true
+   */
+  granular?: boolean;
+  /**
+   * The Babel plugin's JSX-granularity mode is not ported; only `false` is
+   * accepted (what vite-plugin-solid passes).
+   */
+  jsx?: false;
+  /**
+   * Module the runtime helpers (`$$registry`, `$$component`, `$$refresh`,
+   * `$$decline`) are imported from. The dev-only `solid-js/refresh` entry
+   * exposes the same frozen ABI.
+   * @default "solid-refresh"
+   */
+  importSource?: string;
+  sourceMap?: boolean;
+}
+
+export function transformRefresh(
+  code: string,
+  options?: TransformRefreshOptions | null
+): TransformResult;
+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. */
+  filename?: string;
+  sourceMap?: boolean;
+}
+
+export function transformSourceNames(
+  code: string,
+  options?: TransformSourceNamesOptions | null
+): TransformResult;
+export function transformSourceNamesAsync(
+  code: string,
+  options?: TransformSourceNamesOptions | null
+): Promise<TransformResult>;