@solidjs/compiler 2.0.0-rc.2

package/README.md

@@ -0,0 +1,162 @@
+# @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"]
+    }
+  ]
+});
+```
+
+### Source maps
+
+Pass `sourceMap: true` to receive a JSON source map string in `result.map`.
+
+### Options
+
+- `filename`
+- `moduleName` (default `"@solidjs/web"`)
+- `generate`: `"dom"`, `"ssr"`, `"universal"`, or `"dynamic"` (default `"dom"`)
+- `hydratable`
+- `dev`
+- `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`
+- `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.
+
+```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
+```
+
+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.
+
+## 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};
+
+let output = compile(
+    "const view = <div>{name()}</div>;",
+    &CompileOptions::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.
+
+> **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,414 @@
+"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);
+  return {
+    code: result.code,
+    map: result.map ?? null
+  };
+}
+
+function transformAsync(code, options) {
+  return Promise.resolve().then(() => transform(code, 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));
+}
+
+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"
+]);
+
+const refreshBundlers = new Set(["esm", "vite", "webpack5", "rspack-esm", "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 "esm", "vite", "webpack5", "rspack-esm" 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",
+  "sourceMap",
+  "contextToCustomElements",
+  "delegateEvents",
+  "delegatedEvents",
+  "omitQuotes",
+  "omitAttributeSpacing",
+  "inlineStyles",
+  "effectWrapper",
+  "wrapConditionals",
+  "memoWrapper",
+  "requireImportSource",
+  "validate",
+  "staticMarker",
+  "omitNestedClosingTags",
+  "omitLastClosingTag",
+  "serverComponents",
+  "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 (nativeOptionKeys.has(key)) {
+      if (key === "renderers") validateRenderers(value);
+      nativeOptions[key] = value;
+      continue;
+    }
+    throw new Error(`@solidjs/compiler received unknown option \`${key}\``);
+  }
+  return nativeOptions;
+}
+
+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();
+
+  if (suffix) {
+    const next = tryPackage(`@solidjs/compiler-${suffix}`);
+    if (next.binding) return next.binding;
+    if (next.error) nativeError = next.error;
+  }
+
+  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) {
+        nativeError = error;
+        break;
+      }
+    }
+  }
+
+  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,
+  transformDirectives,
+  transformDirectivesAsync,
+  transformLazy,
+  transformLazyAsync,
+  transformRefresh,
+  transformRefreshAsync
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@solidjs/compiler",
+  "description": "Solid's native Oxc JSX compiler",
+  "version": "2.0.0-rc.2",
+  "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",
+    "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.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"
+  }
+}

package/types.d.ts

@@ -0,0 +1,174 @@
+export interface TransformOptions {
+  filename?: string;
+  /** Default `"@solidjs/web"`. */
+  moduleName?: string;
+  generate?: "dom" | "ssr" | "universal" | "dynamic";
+  hydratable?: boolean;
+  dev?: boolean;
+  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;
+  /** 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;
+}
+
+export function transform(code: string, options?: TransformOptions | null): TransformResult;
+export function transformAsync(
+  code: string,
+  options?: TransformOptions | null
+): Promise<TransformResult>;
+
+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 (`<hash>-<count>[-<name>]`). */
+  id: string;
+  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: `import.meta.hot` (esm/vite),
+   * `import.meta.webpackHot` (webpack5/rspack-esm) or `module.hot`
+   * (standard).
+   * @default "standard"
+   */
+  bundler?: "esm" | "vite" | "webpack5" | "rspack-esm" | "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>;