@solidjs/compiler 2.0.0-rc.5 → 2.0.0-rc.6

package/README.md

@@ -78,14 +78,38 @@ 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.
+
+Destructured bindings in keyed `@for` loops and `@catch` clauses stay deferred against Solid's item and error accessors, including nested patterns, defaults, computed keys, and rest.
+
+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 post-rewrite 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`
@@ -110,7 +134,7 @@ Pass `sourceMap: true` to receive a JSON source map string in `result.map`.
 
 ### 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");
@@ -133,16 +157,25 @@ The runtime module defaults to `@solidjs/web/server-functions`. Function IDs use
 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.
 
+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 +184,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

@@ -12,16 +12,60 @@ function transform(code, options) {
 
   const nativeOptions = 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");
@@ -427,6 +471,7 @@ function isMissingPackage(error, packageName) {
 module.exports = {
   transform,
   transformAsync,
+  projectTsrxForTypecheck,
   transformDirectives,
   transformDirectivesAsync,
   transformLazy,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@solidjs/compiler",
   "description": "Solid's native Oxc JSX compiler",
-  "version": "2.0.0-rc.5",
+  "version": "2.0.0-rc.6",
   "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"
@@ -62,11 +62,11 @@
     "emnapi": "^1.11.3"
   },
   "optionalDependencies": {
-    "@solidjs/compiler-darwin-x64": "2.0.0-rc.5",
-    "@solidjs/compiler-darwin-arm64": "2.0.0-rc.5",
-    "@solidjs/compiler-linux-x64-gnu": "2.0.0-rc.5",
-    "@solidjs/compiler-linux-arm64-gnu": "2.0.0-rc.5",
-    "@solidjs/compiler-win32-x64-msvc": "2.0.0-rc.5",
-    "@solidjs/compiler-wasm32-wasi": "2.0.0-rc.5"
+    "@solidjs/compiler-darwin-x64": "2.0.0-rc.6",
+    "@solidjs/compiler-darwin-arm64": "2.0.0-rc.6",
+    "@solidjs/compiler-linux-x64-gnu": "2.0.0-rc.6",
+    "@solidjs/compiler-linux-arm64-gnu": "2.0.0-rc.6",
+    "@solidjs/compiler-win32-x64-msvc": "2.0.0-rc.6",
+    "@solidjs/compiler-wasm32-wasi": "2.0.0-rc.6"
   }
 }

package/types.d.ts

@@ -2,6 +2,13 @@ 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;
@@ -44,6 +51,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;
@@ -52,6 +63,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;