@octanejs/rspack-plugin 0.1.47 → 0.1.49

package/README.md

@@ -196,6 +196,18 @@ export default {
 
 The class plugin is recommended unless another integration owns those concerns.
 
+## Scoped CSS
+
+Scoped `<style>` blocks compile to `injectStyle(hash, css)` calls — one per
+style scope, in lexical order — emitted as module-level statements in client
+compilations and inside the component body per request in server
+compilations, where the render collects them into the response's
+`<style data-octane>` tags. A theme (`export const theme = <style>…</style>`)
+is an ordinary module value, so importing it injects its sheet ahead of the
+importer's own scopes. There is no virtual CSS module and no CSS HMR path:
+editing a block re-evaluates the module like any other source change. Neither
+the plugin nor the loader needs a CSS rule for this.
+
 ## App-level metadata
 
 Transformed Rspack modules receive a serializable `buildInfo.octane` record

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/rspack-plugin",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -54,7 +54,7 @@
     "css-loader": "6.11.0",
     "jsdom": "^30.0.1",
     "vitest": "^4.1.10",
-    "octane": "0.2.0"
+    "octane": "0.2.7"
   },
   "scripts": {
     "test": "vitest run --config vitest.config.js"

package/src/descriptor-children.js

@@ -0,0 +1,116 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute } from 'node:path';
+import {
+	cleanModuleId,
+	findDescriptorChildrenExports,
+	findDescriptorChildrenImports,
+} from 'octane/compiler/bundler';
+
+/**
+ * A loader runs before Rspack publishes outgoing module-graph edges. Resolve
+ * each JSX import with its ESM resolver, then prove the named export from the
+ * resolved authored source. Every file in the proof becomes a loader dependency
+ * so changing a marker or any barrel invalidates its compiled consumers.
+ */
+export async function loadDescriptorChildrenImports(context, source, id) {
+	if (typeof context.getResolve !== 'function' || !/<\s*[A-Z_$]/.test(source)) return null;
+	const imports = findDescriptorChildrenImports(source, id).filter(
+		(candidate) => candidate.local !== undefined && candidate.request !== 'octane',
+	);
+	if (imports.length === 0) return null;
+	const resolver = context.getResolve({ dependencyType: 'esm' });
+	const analyses = new Map();
+	const classifications = new Map();
+	const proven = new Set();
+
+	async function analyze(resolvedId) {
+		const filename = cleanModuleId(resolvedId);
+		if (!isAbsolute(filename) || !/\.(?:[cm]?[jt]sx?|tsrx)$/.test(filename)) return null;
+		let analysis = analyses.get(filename);
+		if (analysis === undefined) {
+			context.addDependency?.(filename);
+			analysis = readFile(filename, 'utf8')
+				.then((code) => {
+					// An ordinary source with neither the marker's name nor an
+					// import/re-export pair cannot prove any binding. Keep that
+					// common case out of the parser entirely.
+					const mayReexport = code.includes('export') && code.includes('from');
+					return {
+						exports: code.includes('descriptorChildren')
+							? new Set(findDescriptorChildrenExports(code, filename))
+							: new Set(),
+						code: mayReexport ? code : null,
+						reexports: mayReexport ? undefined : [],
+					};
+				})
+				.catch((error) => {
+					if (error?.code === 'ENOENT') context.addMissingDependency?.(filename);
+					return null;
+				});
+			analyses.set(filename, analysis);
+		}
+		return analysis;
+	}
+
+	async function resolveImport(request, importer) {
+		try {
+			return await resolver(dirname(cleanModuleId(importer)), request);
+		} catch {
+			// Let Rspack's module factory report unresolved imports with its own
+			// issuer trace; no export can be proven from a missing dependency.
+			return null;
+		}
+	}
+
+	async function isMarked(resolvedId, imported, ancestors = new Set()) {
+		const key = `${resolvedId}\0${imported}`;
+		if (ancestors.has(key)) return false;
+		let classification = ancestors.size === 0 ? classifications.get(key) : undefined;
+		if (classification === undefined) {
+			classification = (async () => {
+				const analysis = await analyze(resolvedId);
+				if (analysis === null) return false;
+				if (analysis.exports.has(imported)) return true;
+				const reexports = (analysis.reexports ??=
+					analysis.code !== null
+						? findDescriptorChildrenImports(analysis.code, cleanModuleId(resolvedId)).filter(
+								(candidate) => candidate.exported !== undefined,
+							)
+						: []);
+				const nextAncestors = new Set(ancestors);
+				nextAncestors.add(key);
+				for (const candidate of reexports) {
+					if (candidate.exported !== imported) continue;
+					const target = await resolveImport(candidate.request, resolvedId);
+					if (typeof target === 'string' && target !== resolvedId) {
+						if (await isMarked(target, candidate.imported, nextAncestors)) return true;
+					}
+				}
+				return false;
+			})();
+			// A result inside a cycle can depend on the starting point. Only root
+			// classifications are safe to share across independent import paths.
+			if (ancestors.size === 0) classifications.set(key, classification);
+		}
+		return classification;
+	}
+
+	const byRequest = new Map();
+	for (const candidate of imports) {
+		const values = byRequest.get(candidate.request) ?? [];
+		values.push(candidate);
+		byRequest.set(candidate.request, values);
+	}
+	await Promise.all(
+		[...byRequest].map(async ([request, candidates]) => {
+			const target = await resolveImport(request, id);
+			if (typeof target !== 'string' || target === id) return;
+			await Promise.all(
+				candidates.map(async ({ imported }) => {
+					if (await isMarked(target, imported)) proven.add(`${request}\0${imported}`);
+				}),
+			);
+		}),
+	);
+	return proven.size === 0 ? null : (request, imported) => proven.has(`${request}\0${imported}`);
+}

package/src/loader.js

@@ -1,7 +1,8 @@
-import { realpathSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { dirname, isAbsolute, resolve } from 'node:path';
 import remapping from '@jridgewell/remapping';
 import { canonicalModuleId, cleanModuleId, createOctaneCompiler } from 'octane/compiler/bundler';
+import { resolveRendererForFile } from 'octane/compiler/renderers';
 import {
 	clearCssModuleBuildInfo,
 	CSS_MODULE_CONTEXT_KEY,
@@ -13,6 +14,8 @@ import {
 	normalizeLoaderOptions,
 	selectLayerCompilerOptions,
 } from './shared.js';
+import { loadDescriptorChildrenImports } from './descriptor-children.js';
+import { textTypeFactsForLoader } from './text-types.js';
 
 function realRoot(path) {
 	try {
@@ -118,7 +121,6 @@ export default function octaneLoader(source, inputSourceMap) {
 			root,
 			profile,
 			...(options.strong === undefined ? null : { strong: options.strong }),
-			...(options.nativeReads === undefined ? null : { nativeReads: options.nativeReads }),
 			...(options.exclude === undefined ? null : { exclude: options.exclude }),
 			...(compilerOptions.renderers === undefined
 				? null
@@ -134,6 +136,41 @@ export default function octaneLoader(source, inputSourceMap) {
 		});
 		const id = realModuleId(this.resource ?? this.resourcePath);
 		const authoredSource = String(source);
+		const textTypeCandidate =
+			options.textTypes !== undefined && this.mode === 'production' && !dev && this.hot !== true;
+		let textTypeFilename;
+		if (textTypeCandidate) {
+			const file = cleanModuleId(id);
+			if (
+				/(?:\.tsrx|\.tsx)$/i.test(file) &&
+				existsSync(file) &&
+				compiler._isProjectOwnedSource(file)
+			) {
+				const canonical = compiler._canonicalModuleId(file);
+				const pragmaOwned =
+					file.endsWith('.tsx') && compiler._pragmaClaimsOwnership(authoredSource);
+				if (compiler._passesOwnershipGate(file, canonical, pragmaOwned)) {
+					const renderer = resolveRendererForFile(compiler.renderers, canonical);
+					if (
+						renderer.target === 'dom' &&
+						!(environment === 'server' && renderer.server === 'client-only')
+					) {
+						textTypeFilename = canonical;
+					}
+				}
+			}
+		}
+		if (textTypeFilename !== undefined) {
+			// An imported type can change while this module's source stays the same.
+			// Rspack's persistent module cache has no dependency edges to every TS
+			// Program input. Production watches stay syntax-only but must not persist
+			// their generic output for a later one-shot typed build either.
+			this.cacheable?.(false);
+		}
+		const textTypes =
+			textTypeFilename !== undefined &&
+			this._compiler?.watchMode !== true &&
+			this._compiler?.options?.watch !== true;
 		const cssModuleConstants =
 			this[CSS_MODULE_CONTEXT_KEY]?.enabled === true
 				? prepareCssModuleConstants(this, compiler, authoredSource, id, {
@@ -142,7 +179,7 @@ export default function octaneLoader(source, inputSourceMap) {
 						dev,
 					})
 				: null;
-		const finish = (clientOnlyImports, callback) => {
+		const finish = (clientOnlyImports, isDescriptorChildrenImport, textTypeFacts, callback) => {
 			try {
 				const result = compiler.transform(authoredSource, id, {
 					environment,
@@ -150,6 +187,8 @@ export default function octaneLoader(source, inputSourceMap) {
 					dev,
 					profile,
 					...(clientOnlyImports.length > 0 ? { clientOnlyImports } : null),
+					...(isDescriptorChildrenImport === null ? null : { isDescriptorChildrenImport }),
+					...(textTypeFacts === undefined ? null : { textTypeFacts }),
 					...cssModuleConstants?.transformOptions,
 				});
 
@@ -191,22 +230,46 @@ export default function octaneLoader(source, inputSourceMap) {
 			environment === 'server' && typeof compiler.clientReferenceForFile === 'function'
 				? compiler.clientReferenceForFile(id)
 				: null;
-		if (
+		const needsServerImports =
 			environment === 'server' &&
 			currentReference === null &&
-			typeof this.getResolve === 'function'
-		) {
-			const requests = compiler.findServerImportRequests(authoredSource, id);
-			if (requests.length > 0) {
-				const asyncCallback = this.async?.() ?? callback;
-				resolveClientOnlyImports(this, compiler, authoredSource, id).then(
-					(imports) => finish(imports, asyncCallback),
-					(error) => asyncCallback(error instanceof Error ? error : new Error(String(error))),
-				);
-				return;
-			}
+			typeof this.getResolve === 'function';
+		const requests = needsServerImports
+			? compiler.findServerImportRequests(authoredSource, id)
+			: [];
+		const mayUseDescriptorImports =
+			typeof this.getResolve === 'function' &&
+			(environment !== 'server' || currentReference === null) &&
+			/\.(?:tsrx|tsx)$/.test(cleanModuleId(id)) &&
+			/<\s*[A-Z_$]/.test(authoredSource) &&
+			authoredSource.includes('import');
+		if (requests.length > 0 || mayUseDescriptorImports || textTypes) {
+			const asyncCallback = this.async?.() ?? callback;
+			Promise.all([
+				requests.length > 0 ? resolveClientOnlyImports(this, compiler, authoredSource, id) : [],
+				mayUseDescriptorImports ? loadDescriptorChildrenImports(this, authoredSource, id) : null,
+				textTypes
+					? textTypeFactsForLoader(
+							this._compiler,
+							options.textTypes.tsconfig,
+							compilerOptions.renderers,
+							cleanModuleId(id),
+							authoredSource,
+						).then((facts) => ({
+							...facts,
+							// The neutral compiler uses a project-relative module identity;
+							// the checker necessarily reads the real filesystem filename.
+							filename: textTypeFilename,
+						}))
+					: undefined,
+			]).then(
+				([imports, descriptorImport, textTypeFacts]) =>
+					finish(imports, descriptorImport, textTypeFacts, asyncCallback),
+				(error) => asyncCallback(error instanceof Error ? error : new Error(String(error))),
+			);
+			return;
 		}
-		finish([], callback);
+		finish([], null, undefined, callback);
 	} catch (error) {
 		this.callback(error instanceof Error ? error : new Error(String(error)));
 	}

package/src/plugin.js

@@ -14,6 +14,11 @@ import {
 	inferRspackEnvironment,
 	normalizePluginOptions,
 } from './shared.js';
+import {
+	disposeTextTypeCompiler,
+	invalidateTextTypeCompiler,
+	registerTextTypeCompiler,
+} from './text-types.js';
 
 const PLUGIN_NAME = 'OctaneRspackPlugin';
 const PROFILE_DEFINE = '__OCTANE_PROFILE_ENABLED__';
@@ -177,7 +182,6 @@ function createDiscoveryCompiler(options, root, profile, specialization) {
 		root,
 		profile,
 		...(options.strong === undefined ? null : { strong: options.strong }),
-		...(options.nativeReads === undefined ? null : { nativeReads: options.nativeReads }),
 		...(options.exclude === undefined ? null : { exclude: options.exclude }),
 		...(renderers === undefined ? null : { renderers }),
 		...(universalRuntime === undefined ? null : { universalRuntime }),
@@ -360,6 +364,16 @@ export class OctaneRspackPlugin {
 			compiler.options.mode === 'production' &&
 			!dev &&
 			!hotModuleReplacement;
+		// Loader worker pools cannot share one TypeScript Program. Watch and HMR
+		// use syntax-only compilation, including production-mode watch builds.
+		const textTypes =
+			this.options.textTypes !== undefined &&
+			compiler.options.mode === 'production' &&
+			!dev &&
+			!hotModuleReplacement;
+		const tsconfig = textTypes
+			? realRoot(resolve(root, this.options.textTypes.tsconfig))
+			: undefined;
 		assertProfilingDefineAvailable(compiler, profile);
 		saltPersistentCacheVersion(compiler, {
 			root,
@@ -368,7 +382,6 @@ export class OctaneRspackPlugin {
 			dev,
 			profile,
 			strong: this.options.strong === true,
-			nativeReads: this.options.nativeReads === true,
 			exclude: this.options.exclude ?? [],
 			renderers: this.options.renderers?.signature,
 			runtime: this.options.runtime,
@@ -379,7 +392,14 @@ export class OctaneRspackPlugin {
 			requireDirective: this.options.requireDirective === true,
 			transpile: this.options.transpile !== false,
 			cssModuleConstants,
+			textTypes: tsconfig,
 		});
+		if (tsconfig !== undefined) {
+			registerTextTypeCompiler(compiler, tsconfig, root);
+			compiler.hooks.run?.tap(PLUGIN_NAME, () => invalidateTextTypeCompiler(compiler));
+			compiler.hooks.watchRun?.tap(PLUGIN_NAME, () => invalidateTextTypeCompiler(compiler));
+			compiler.hooks.shutdown?.tap(PLUGIN_NAME, () => disposeTextTypeCompiler(compiler));
+		}
 		installProfilingDefine(compiler, profile);
 		if (cssModuleConstants) {
 			installCssModuleConstants(compiler, {
@@ -409,9 +429,6 @@ export class OctaneRspackPlugin {
 			environment,
 			profile,
 			...(this.options.strong === undefined ? null : { strong: this.options.strong }),
-			...(this.options.nativeReads === undefined
-				? null
-				: { nativeReads: this.options.nativeReads }),
 			...(this.options.hmr === undefined ? null : { hmr: this.options.hmr }),
 			...(this.options.dev === undefined ? null : { dev: this.options.dev }),
 			...(this.options.exclude === undefined ? null : { exclude: this.options.exclude }),
@@ -425,13 +442,14 @@ export class OctaneRspackPlugin {
 			...(this.options.requireDirective === undefined
 				? null
 				: { requireDirective: this.options.requireDirective }),
+			...(tsconfig === undefined ? null : { textTypes: { tsconfig } }),
 		};
 		compiler.options.module.rules.push({
 			test: OCTANE_RULE,
 			type: 'javascript/auto',
 			enforce: 'pre',
 			use:
-				this.options.parallel === false
+				this.options.parallel === false || textTypes
 					? [{ loader: loaderPath, options: loaderOptions }]
 					: [
 							{ loader: finalizeLoaderPath, options: loaderOptions },

package/src/shared.js

@@ -41,12 +41,12 @@ const LOADER_OPTION_KEYS = new Set([
 	'dev',
 	'profile',
 	'strong',
-	'nativeReads',
 	'exclude',
 	'renderers',
 	'requireDirective',
 	'universalRuntime',
 	'layerSpecializations',
+	'textTypes',
 ]);
 const PLUGIN_OPTION_KEYS = new Set([
 	...LOADER_OPTION_KEYS,
@@ -209,7 +209,6 @@ function normalizeOptions(value, plugin) {
 	assertBooleanOption(options, 'dev');
 	assertBooleanOption(options, 'profile');
 	assertBooleanOption(options, 'strong');
-	assertBooleanOption(options, 'nativeReads');
 	assertBooleanOption(options, 'requireDirective');
 	if (
 		options.exclude !== undefined &&
@@ -218,6 +217,21 @@ function normalizeOptions(value, plugin) {
 		throw new TypeError('@octanejs/rspack-plugin: `exclude` must be an array of path strings.');
 	}
 	if (plugin) assertBooleanOption(options, 'transpile');
+	if (options.textTypes !== undefined) {
+		if (
+			options.textTypes === null ||
+			typeof options.textTypes !== 'object' ||
+			Array.isArray(options.textTypes) ||
+			Object.keys(options.textTypes).some((key) => key !== 'tsconfig') ||
+			typeof options.textTypes.tsconfig !== 'string' ||
+			options.textTypes.tsconfig.trim() !== options.textTypes.tsconfig ||
+			!options.textTypes.tsconfig
+		) {
+			throw new TypeError(
+				'@octanejs/rspack-plugin: `textTypes` must be an object with a non-empty `tsconfig` path.',
+			);
+		}
+	}
 	if (
 		plugin &&
 		options.cssModuleConstants !== undefined &&
@@ -241,7 +255,6 @@ function normalizeOptions(value, plugin) {
 		...(options.dev === undefined ? null : { dev: options.dev }),
 		...(options.profile === undefined ? null : { profile: options.profile }),
 		...(options.strong === undefined ? null : { strong: options.strong }),
-		...(options.nativeReads === undefined ? null : { nativeReads: options.nativeReads }),
 		...(options.exclude === undefined ? null : { exclude: [...options.exclude] }),
 		...(renderers === undefined ? null : { renderers }),
 		...(universalRuntime === undefined ? null : { universalRuntime }),
@@ -249,6 +262,9 @@ function normalizeOptions(value, plugin) {
 		...(options.requireDirective === undefined
 			? null
 			: { requireDirective: options.requireDirective }),
+		...(options.textTypes === undefined
+			? null
+			: { textTypes: Object.freeze({ tsconfig: options.textTypes.tsconfig }) }),
 		...(plugin && parallel !== undefined ? { parallel } : null),
 		...(plugin && options.transpile !== undefined ? { transpile: options.transpile } : null),
 		...(plugin && options.runtime !== undefined ? { runtime: options.runtime } : null),

package/src/text-types.js

@@ -0,0 +1,62 @@
+/**
+ * Type analysis is an opt-in production build concern. Keep TypeScript out of
+ * the ordinary loader's module graph and retain one project per compiler and
+ * renderer configuration, rather than one TypeScript Program per module.
+ */
+// Rspack loads the plugin from its application's module graph and the loader
+// through its loader runner. Those can instantiate this ESM module separately
+// (for example under Vitest), even though both receive the same compiler.
+// Keep the project on that compiler under a process-wide symbol instead of in
+// module-local state. Typed builds use the main-thread loader.
+const COMPILER_TEXT_TYPES = Symbol.for('@octanejs/rspack-plugin/text-types/v1');
+
+function compilerState(compiler) {
+	return compiler?.[COMPILER_TEXT_TYPES];
+}
+
+export function registerTextTypeCompiler(compiler, tsconfig, root) {
+	if (compilerState(compiler)) {
+		throw new Error('@octanejs/rspack-plugin: only one text type project may own a compiler.');
+	}
+	Object.defineProperty(compiler, COMPILER_TEXT_TYPES, {
+		value: { tsconfig, root, projects: new Map(), closed: false },
+		configurable: true,
+	});
+}
+
+export function invalidateTextTypeCompiler(compiler) {
+	const state = compilerState(compiler);
+	if (!state || state.closed) return;
+	for (const project of state.projects.values()) project.invalidate();
+}
+
+export function disposeTextTypeCompiler(compiler) {
+	const state = compilerState(compiler);
+	if (!state) return;
+	state.closed = true;
+	for (const project of state.projects.values()) project.dispose();
+	state.projects.clear();
+	delete compiler[COMPILER_TEXT_TYPES];
+}
+
+export async function textTypeFactsForLoader(compiler, tsconfig, renderers, filename, source) {
+	const state = compilerState(compiler);
+	if (!state || state.tsconfig !== tsconfig || state.closed) {
+		throw new Error(
+			'@octanejs/rspack-plugin: `textTypes` requires the OctaneRspackPlugin on the same compiler.',
+		);
+	}
+	// The optional TypeScript peer and Volar adapter are loaded only by an opted-in
+	// production compiler. import() also shares its module initialization across
+	// concurrently built modules without retaining a checker in loader options.
+	const { createTextTypeProject } = await import('octane/compiler/typescript');
+	if (state.closed)
+		throw new Error('@octanejs/rspack-plugin: compiler closed during type analysis.');
+	const key = renderers?.signature ?? 'dom';
+	let project = state.projects.get(key);
+	if (!project) {
+		project = createTextTypeProject({ tsconfig, root: state.root, renderers });
+		state.projects.set(key, project);
+	}
+	return project.snapshot(filename, source);
+}

package/types/index.d.ts

@@ -144,8 +144,6 @@ export interface OctaneRspackLoaderOptions {
 	 * @default false
 	 */
 	strong?: boolean;
-	/** Experimental native signal reads in DOM client/server render scopes. */
-	nativeReads?: boolean;
 	/**
 	 * Path fragments excluded from the plain `.ts`/`.js` hook-slot pass. With
 	 * `requireDirective`, excluded paths are exempt from Octane ownership
@@ -177,6 +175,17 @@ export interface OctaneRspackLoaderOptions {
 }
 
 export interface OctaneRspackPluginOptions extends OctaneRspackLoaderOptions {
+	/**
+	 * @experimental Prove primitive DOM text children from the TypeScript project
+	 * in one-shot production builds. Relative paths resolve from the plugin root.
+	 * Requires the optional TypeScript peer. Uses one main-thread checker per
+	 * compiler, and typed modules bypass Rspack's persistent module cache so
+	 * imported type edits are observed on the next build. Watch/HMR and
+	 * development builds retain syntax-only classification. Configure the same
+	 * tsconfig and renderers for browser and server compilation.
+	 * @default undefined
+	 */
+	textTypes?: { tsconfig: string };
 	/**
 	 * @experimental Fold proven CSS-module strings in one-shot production builds.
 	 * `true` accepts only pure, initialized named ESM string exports. A provider