@octanejs/rspack-plugin 0.1.0 → 0.1.4

package/README.md

@@ -44,8 +44,28 @@ new OctaneRspackPlugin({ environment: 'server' });
 
 Set `transpile: false` when an existing rule already strips TypeScript. Set
 `hmr: false` to disable Octane HMR codegen even when Rspack HMR is active.
-Options contain only serializable strings, booleans, and string arrays, so the
-same configuration is safe to reuse across compiler environments and caches.
+Set `profile: true` to produce a client profiling build; server compilations
+always keep profiling disabled.
+The experimental `renderers` option accepts the same declarative registry,
+filename rules, and module/export boundary metadata as `compiler.renderers` in
+Octane app config:
+
+```js
+new OctaneRspackPlugin({
+	renderers: {
+		registry: { three: '@octanejs/three/renderer' },
+		boundaries: {
+			'@octanejs/three': {
+				Canvas: { ownerRenderer: 'dom', childRenderer: 'three', prop: 'children' },
+			},
+		},
+		rules: [{ include: 'src/scenes/**/*.tsrx', renderer: 'three' }],
+	},
+});
+```
+
+Options remain serializable data—there are no renderer callbacks—so the same
+configuration is safe to reuse across compiler environments and caches.
 
 Rspack's dev server enables the loader's hot context. If you run a custom dev
 server, add Rspack's `HotModuleReplacementPlugin` as usual.
@@ -73,8 +93,43 @@ export default {
 ```
 
 With the loader-only form, configure `.tsrx` resolution, TypeScript stripping,
-and the exact server runtime alias yourself. The class plugin is recommended
-unless another integration owns those concerns.
+and exact `octane$` / `octane/profiling$` aliases to the app's Octane package
+yourself. The profiling alias keeps compiler metadata and runtime recording on
+one module even when transformed raw dependencies carry a nested Octane copy.
+You must also define Octane's
+reserved profiling constant to the same boolean passed to the loader. Defining
+`false` is important too: it lets production optimization erase the inactive
+profiling runtime. The class plugin installs and owns this definition for you,
+so do not configure it separately when using `OctaneRspackPlugin`.
+
+```js
+import { rspack } from '@rspack/core';
+
+const profiling = process.env.OCTANE_PROFILE === '1';
+
+export default {
+	module: {
+		rules: [
+			{
+				test: /\.(?:tsrx|tsx|ts|js)$/,
+				enforce: 'pre',
+				type: 'javascript/auto',
+				use: {
+					loader: '@octanejs/rspack-plugin/loader',
+					options: { environment: 'client', profile: profiling },
+				},
+			},
+		],
+	},
+	plugins: [
+		new rspack.DefinePlugin({
+			__OCTANE_PROFILE_ENABLED__: JSON.stringify(profiling),
+		}),
+	],
+};
+```
+
+The class plugin is recommended unless another integration owns those concerns.
 
 ## App-level metadata
 
@@ -82,3 +137,8 @@ Transformed Rspack modules receive a serializable `buildInfo.octane` record
 containing `canonicalId`, `transformKind`, and `serverRpc`. App integrations can
 read the validated value with `getOctaneRspackBuildInfo(module)` without
 depending on compiler output parsing for module identity.
+
+When a renderer is declared `server: 'client-only'`, client compilations also
+emit `octane-client-references.json`. Its stable reference IDs map each omitted
+server module to the JavaScript chunks that contain its browser implementation;
+server compilations retain the same ID on the export-preserving inert stub.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/rspack-plugin",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -45,13 +45,13 @@
   },
   "peerDependencies": {
     "@rspack/core": "^2.0.0",
-    "octane": "0.1.5"
+    "octane": "0.1.9"
   },
   "devDependencies": {
     "@rspack/core": "^2.1.3",
     "@types/node": "^24.3.0",
     "vitest": "^4.1.9",
-    "octane": "0.1.5"
+    "octane": "0.1.9"
   },
   "scripts": {
     "test": "vitest run --config vitest.config.js"

package/src/loader.js

@@ -1,8 +1,22 @@
-import { isAbsolute, resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
 import remapping from '@jridgewell/remapping';
-import { canonicalModuleId, createOctaneCompiler } from 'octane/compiler/bundler';
+import { canonicalModuleId, cleanModuleId, createOctaneCompiler } from 'octane/compiler/bundler';
 import { inferRspackEnvironment, normalizeLoaderOptions } from './shared.js';
 
+function realRoot(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+
+function realModuleId(id) {
+	const file = cleanModuleId(id);
+	return realRoot(file) + id.slice(file.length);
+}
+
 function clearBuildInfo(module) {
 	if (module?.buildInfo && typeof module.buildInfo === 'object') {
 		delete module.buildInfo.octane;
@@ -31,6 +45,33 @@ function composeSourceMaps(outputMap, inputSourceMap) {
 	return String(chained.mappings).length > 0 ? chained : outputMap;
 }
 
+async function resolveClientOnlyImports(context, compiler, source, id) {
+	if (typeof context.getResolve !== 'function') return [];
+	const requests = compiler.findServerImportRequests(String(source), id);
+	if (requests.length === 0) return [];
+	const resolver = context.getResolve({ dependencyType: 'esm' });
+	const issuer = dirname(cleanModuleId(id));
+	const classified = [];
+	await Promise.all(
+		requests.map(async (request) => {
+			let resolved;
+			try {
+				resolved = await resolver(issuer, request);
+			} catch {
+				// Rspack's normal dependency factory reports unresolved imports with its
+				// full request/issuer trace. Do not replace that diagnostic here.
+				return;
+			}
+			if (typeof resolved !== 'string') return;
+			const reference = compiler.clientReferenceForFile(resolved);
+			if (reference !== null) classified.push({ request, resolvedId: resolved, reference });
+		}),
+	);
+	return classified.sort((left, right) =>
+		left.request < right.request ? -1 : left.request > right.request ? 1 : 0,
+	);
+}
+
 /**
  * Rspack's ESM loader entry. A compiler instance is intentionally scoped to
  * one invocation: Rspack owns output caching and invalidates it from the file
@@ -44,51 +85,92 @@ export default function octaneLoader(source, inputSourceMap) {
 	try {
 		const options = normalizeLoaderOptions(this.getOptions?.() ?? {});
 		const loaderRoot = this.rootContext ?? process.cwd();
-		const root = options.root
-			? isAbsolute(options.root)
-				? options.root
-				: resolve(loaderRoot, options.root)
-			: loaderRoot;
+		const root = realRoot(
+			options.root
+				? isAbsolute(options.root)
+					? options.root
+					: resolve(loaderRoot, options.root)
+				: loaderRoot,
+		);
 		const environment = options.environment ?? inferRspackEnvironment(this.target);
 		const hmr =
 			environment === 'client' && this.hot === true && options.hmr !== false ? 'webpack' : false;
 		const dev =
 			environment === 'client' &&
 			(options.dev ?? (this.mode === undefined || this.mode !== 'production'));
+		const profile = environment === 'client' && options.profile === true;
 		const compiler = createOctaneCompiler({
 			root,
+			profile,
 			...(options.exclude === undefined ? null : { exclude: options.exclude }),
-			...(options.parallelUse === undefined ? null : { parallelUse: options.parallelUse }),
-		});
-		const id = this.resource ?? this.resourcePath;
-		const result = compiler.transform(String(source), id, {
-			environment,
-			hmr,
-			dev,
-			...(options.parallelUse === undefined ? null : { parallelUse: options.parallelUse }),
+			...(options.renderers === undefined ? null : { renderers: options.renderers }),
+			...(options.requireDirective === undefined
+				? null
+				: { requireDirective: options.requireDirective }),
+			// Ownership diagnostics surface through Rspack's own module warnings.
+			warn: (message) => this.emitWarning?.(new Error(message)),
 		});
+		const id = realModuleId(this.resource ?? this.resourcePath);
+		const finish = (clientOnlyImports, callback) => {
+			try {
+				const result = compiler.transform(String(source), id, {
+					environment,
+					hmr,
+					dev,
+					profile,
+					...(clientOnlyImports.length > 0 ? { clientOnlyImports } : null),
+				});
 
-		if (result === null) {
-			this.callback(null, source, this.sourceMap === false ? undefined : inputSourceMap);
-			return;
-		}
+				if (result === null) {
+					callback(null, source, this.sourceMap === false ? undefined : inputSourceMap);
+					return;
+				}
+
+				registerDependencies(this, result);
+				if (result.kind === 'none') {
+					callback(null, source, this.sourceMap === false ? undefined : inputSourceMap);
+					return;
+				}
+				setBuildInfo(this._module, {
+					canonicalId: canonicalModuleId(id, root),
+					transformKind: result.kind,
+					serverRpc:
+						result.kind === 'compile' &&
+						(result.code.includes('_$__serverRpc(') ||
+							result.code.includes('export const _$_server_$_')),
+					...(result.clientReference === undefined
+						? null
+						: { clientReference: { ...result.clientReference } }),
+				});
+				const sourceMap =
+					this.sourceMap === false ? undefined : composeSourceMaps(result.map, inputSourceMap);
+				callback(null, result.code, sourceMap);
+			} catch (error) {
+				callback(error instanceof Error ? error : new Error(String(error)));
+			}
+		};
 
-		registerDependencies(this, result);
-		if (result.kind === 'none') {
-			this.callback(null, source, this.sourceMap === false ? undefined : inputSourceMap);
-			return;
+		const callback = this.callback.bind(this);
+		const currentReference =
+			environment === 'server' && typeof compiler.clientReferenceForFile === 'function'
+				? compiler.clientReferenceForFile(id)
+				: null;
+		if (
+			environment === 'server' &&
+			currentReference === null &&
+			typeof this.getResolve === 'function'
+		) {
+			const requests = compiler.findServerImportRequests(String(source), id);
+			if (requests.length > 0) {
+				const asyncCallback = this.async?.() ?? callback;
+				resolveClientOnlyImports(this, compiler, source, id).then(
+					(imports) => finish(imports, asyncCallback),
+					(error) => asyncCallback(error instanceof Error ? error : new Error(String(error))),
+				);
+				return;
+			}
 		}
-		setBuildInfo(this._module, {
-			canonicalId: canonicalModuleId(id, root),
-			transformKind: result.kind,
-			serverRpc:
-				result.kind === 'compile' &&
-				(result.code.includes('_$__serverRpc(') ||
-					result.code.includes('export const _$_server_$_')),
-		});
-		const sourceMap =
-			this.sourceMap === false ? undefined : composeSourceMaps(result.map, inputSourceMap);
-		this.callback(null, result.code, sourceMap);
+		finish([], callback);
 	} catch (error) {
 		this.callback(error instanceof Error ? error : new Error(String(error)));
 	}

package/src/plugin.js

@@ -1,14 +1,34 @@
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createOctaneCompiler } from 'octane/compiler/bundler';
-import { inferRspackEnvironment, normalizePluginOptions } from './shared.js';
+import {
+	CLIENT_REFERENCE_MANIFEST_FILENAME,
+	createClientReferenceManifest,
+	createOctaneCompiler,
+} from 'octane/compiler/bundler';
+import {
+	getOctaneRspackBuildInfo,
+	inferRspackEnvironment,
+	normalizePluginOptions,
+} from './shared.js';
 
 const PLUGIN_NAME = 'OctaneRspackPlugin';
+const PROFILE_DEFINE = '__OCTANE_PROFILE_ENABLED__';
+const PLUGIN_VERSION = createRequire(import.meta.url)('../package.json').version;
 const loaderPath = fileURLToPath(new URL('./loader.js', import.meta.url));
 const OCTANE_RULE = /\.(?:tsrx|tsx|ts|js)$/i;
 const TYPESCRIPT_RULE = /\.(?:tsrx|tsx|ts)$/i;
 
+function realRoot(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+
 function addUniqueExtensions(resolveOptions) {
 	const extensions = resolveOptions.extensions ?? ['.js', '.json', '.wasm'];
 	resolveOptions.extensions = [
@@ -33,14 +53,157 @@ function addRuntimeAlias(resolveOptions, request, root) {
 	resolveOptions.alias = {
 		...aliases,
 		octane$: resolveRuntimeModule(request, root),
+		// Compiler-emitted metadata imports this public subpath directly. Pin it
+		// alongside the runtime entry so raw/linked packages with their own nested
+		// Octane copy cannot split metadata registration from runtime recording.
+		'octane/profiling$': resolveRuntimeModule('octane/profiling', root),
 	};
 }
 
+function projectRendererModule(request, root) {
+	// Renderer config uses project-root IDs such as `/src/object-renderer.ts`.
+	// They are never host-filesystem absolute paths, even if the same path happens
+	// to exist on a developer machine or inside a container.
+	return resolve(root, request.replace(/^[/\\]+/, ''));
+}
+
+function addProjectRendererAliases(resolveOptions, renderers, root) {
+	if (renderers === undefined) return;
+	const aliases = resolveOptions.alias === false ? {} : (resolveOptions.alias ?? {});
+	const additions = {};
+	for (const renderer of Object.values(renderers.registry)) {
+		if (!renderer.module.startsWith('/')) continue;
+		additions[`${renderer.module}$`] = projectRendererModule(renderer.module, root);
+	}
+	resolveOptions.alias = { ...aliases, ...additions };
+}
+
 function addDependencies(collection, values) {
 	if (!collection?.add) return;
 	for (const value of values ?? []) collection.add(value);
 }
 
+function iterable(value) {
+	return value && typeof value === 'object' && Symbol.iterator in value ? value : [];
+}
+
+function isJavaScriptAsset(filename) {
+	return (
+		/\.(?:c|m)?js(?:\?|$)/.test(filename) && !/\.hot-update\.(?:c|m)?js(?:\?|$)/.test(filename)
+	);
+}
+
+function moduleChunks(compilation, module, inherited) {
+	const chunks = new Set(inherited);
+	for (const chunk of iterable(compilation.chunkGraph.getModuleChunksIterable(module)))
+		chunks.add(chunk);
+	return chunks;
+}
+
+function visitClientReferenceModules(
+	compilation,
+	module,
+	inheritedChunks,
+	visit,
+	seen = new Set(),
+) {
+	if (!module || seen.has(module)) return;
+	seen.add(module);
+	const chunks = moduleChunks(compilation, module, inheritedChunks);
+	visit(module, chunks);
+	for (const child of iterable(module.modules)) {
+		visitClientReferenceModules(compilation, child, chunks, visit, seen);
+	}
+	if (module.rootModule) {
+		visitClientReferenceModules(compilation, module.rootModule, chunks, visit, seen);
+	}
+}
+
+/** Emit the client-only module identity mapped to its concrete browser chunks. */
+function emitClientReferenceManifest(compiler, compilation) {
+	const entries = [];
+	for (const topLevelModule of iterable(compilation.modules)) {
+		visitClientReferenceModules(
+			compilation,
+			topLevelModule,
+			[],
+			(module, chunks) => {
+				const reference = getOctaneRspackBuildInfo(module)?.clientReference;
+				if (reference === undefined) return;
+				const files = new Set();
+				for (const chunk of chunks) {
+					for (const file of iterable(chunk?.files)) {
+						const filename = String(file);
+						if (isJavaScriptAsset(filename)) files.add(filename);
+					}
+				}
+				entries.push({ reference, chunks: files });
+			},
+			new Set(),
+		);
+	}
+	const manifest = createClientReferenceManifest(entries);
+	if (Object.keys(manifest.references).length === 0) return;
+	const source = JSON.stringify(manifest, null, 2) + '\n';
+	compilation.emitAsset(
+		CLIENT_REFERENCE_MANIFEST_FILENAME,
+		new compiler.webpack.sources.RawSource(source),
+	);
+}
+
+function defineMatchesBoolean(value, expected) {
+	return value === expected || value === JSON.stringify(expected);
+}
+
+function assertProfilingDefineAvailable(compiler, enabled) {
+	for (const plugin of compiler.options.plugins ?? []) {
+		// Rspack's DefinePlugin keeps its constructor argument in `_args`. Inspecting
+		// the configured plugin list catches conflicts regardless of apply order;
+		// otherwise DefinePlugin keeps the first value and emits only a warning,
+		// which can leave compiler metadata and runtime specialization out of sync.
+		const definitions = plugin?._args?.[0];
+		if (
+			definitions === null ||
+			typeof definitions !== 'object' ||
+			!Object.prototype.hasOwnProperty.call(definitions, PROFILE_DEFINE)
+		) {
+			continue;
+		}
+		if (!defineMatchesBoolean(definitions[PROFILE_DEFINE], enabled)) {
+			throw new TypeError(
+				`@octanejs/rspack-plugin: ${PROFILE_DEFINE} is reserved by Octane and conflicts with \`profile: ${enabled}\`. Remove the custom DefinePlugin entry and configure profiling through OctaneRspackPlugin.`,
+			);
+		}
+	}
+}
+
+function installProfilingDefine(compiler, enabled) {
+	const DefinePlugin = compiler.webpack?.DefinePlugin;
+	if (typeof DefinePlugin !== 'function') {
+		throw new TypeError(
+			'@octanejs/rspack-plugin: this Rspack compiler does not expose webpack.DefinePlugin.',
+		);
+	}
+	new DefinePlugin({ [PROFILE_DEFINE]: JSON.stringify(enabled) }).apply(compiler);
+}
+
+function hasHotModuleReplacement(compiler) {
+	return (compiler.options.plugins ?? []).some(
+		(plugin) => plugin?.name === 'HotModuleReplacementPlugin',
+	);
+}
+
+function saltPersistentCacheVersion(compiler, inputs) {
+	const cache = compiler.options.cache;
+	if (cache === null || typeof cache !== 'object' || cache.type !== 'persistent') return;
+	const digest = createHash('sha256')
+		.update(JSON.stringify({ pluginVersion: PLUGIN_VERSION, ...inputs }))
+		.digest('hex')
+		.slice(0, 16);
+	const octaneVersion = `octane-rspack@${PLUGIN_VERSION}:${digest}`;
+	cache.version = cache.version ? `${cache.version}|${octaneVersion}` : octaneVersion;
+}
+
 export class OctaneRspackPlugin {
 	constructor(options = {}) {
 		this.options = normalizePluginOptions(options);
@@ -50,36 +213,62 @@ export class OctaneRspackPlugin {
 	apply(compiler) {
 		const configuredRoot = this.options.root;
 		const compilerRoot = compiler.options.context ?? process.cwd();
-		const root = configuredRoot
-			? isAbsolute(configuredRoot)
-				? configuredRoot
-				: resolve(compilerRoot, configuredRoot)
-			: compilerRoot;
+		const root = realRoot(
+			configuredRoot
+				? isAbsolute(configuredRoot)
+					? configuredRoot
+					: resolve(compilerRoot, configuredRoot)
+				: compilerRoot,
+		);
 		const environment = this.options.environment ?? inferRspackEnvironment(compiler.options.target);
+		const profile = environment === 'client' && this.options.profile === true;
+		const hmr =
+			environment === 'client' && hasHotModuleReplacement(compiler) && this.options.hmr !== false;
+		const dev =
+			environment === 'client' &&
+			(this.options.dev ??
+				(compiler.options.mode === undefined || compiler.options.mode !== 'production'));
+		assertProfilingDefineAvailable(compiler, profile);
+		saltPersistentCacheVersion(compiler, {
+			root,
+			environment,
+			hmr,
+			dev,
+			profile,
+			exclude: this.options.exclude ?? [],
+			renderers: this.options.renderers?.signature,
+			// Ownership flips which modules compile vs pass through — cached
+			// transform results must not survive a requireDirective toggle.
+			requireDirective: this.options.requireDirective === true,
+			transpile: this.options.transpile !== false,
+		});
+		installProfilingDefine(compiler, profile);
 		const neutralCompiler = createOctaneCompiler({
 			root,
+			profile,
 			...(this.options.exclude === undefined ? null : { exclude: this.options.exclude }),
-			...(this.options.parallelUse === undefined
-				? null
-				: { parallelUse: this.options.parallelUse }),
+			...(this.options.renderers === undefined ? null : { renderers: this.options.renderers }),
 		});
 		const runtimeRequest = neutralCompiler.resolveRuntimeRequest('octane', environment);
 
 		compiler.options.resolve ??= {};
 		addUniqueExtensions(compiler.options.resolve);
 		addRuntimeAlias(compiler.options.resolve, runtimeRequest, root);
+		addProjectRendererAliases(compiler.options.resolve, this.options.renderers, root);
 
 		compiler.options.module ??= {};
 		compiler.options.module.rules ??= [];
 		const loaderOptions = {
 			root,
 			environment,
+			profile,
 			...(this.options.hmr === undefined ? null : { hmr: this.options.hmr }),
 			...(this.options.dev === undefined ? null : { dev: this.options.dev }),
-			...(this.options.parallelUse === undefined
-				? null
-				: { parallelUse: this.options.parallelUse }),
 			...(this.options.exclude === undefined ? null : { exclude: this.options.exclude }),
+			...(this.options.renderers === undefined ? null : { renderers: this.options.renderers }),
+			...(this.options.requireDirective === undefined
+				? null
+				: { requireDirective: this.options.requireDirective }),
 		};
 		compiler.options.module.rules.push({
 			test: OCTANE_RULE,
@@ -115,6 +304,15 @@ export class OctaneRspackPlugin {
 			const current = discover();
 			addDependencies(compilation.fileDependencies, current.dependencies);
 			addDependencies(compilation.missingDependencies, current.missingDependencies);
+			if (environment === 'client') {
+				compilation.hooks.processAssets.tap(
+					{
+						name: PLUGIN_NAME,
+						stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_REPORT,
+					},
+					() => emitClientReferenceManifest(compiler, compilation),
+				);
+			}
 		});
 	}
 }

package/src/shared.js

@@ -1,3 +1,5 @@
+import { normalizeRendererConfig } from 'octane/compiler/renderers';
+
 const CLIENT_TARGETS = new Set(['web', 'webworker', 'electron-renderer', 'browserslist']);
 
 function targetValues(target) {
@@ -32,7 +34,16 @@ export function inferRspackEnvironment(target) {
 	return 'client';
 }
 
-const LOADER_OPTION_KEYS = new Set(['root', 'environment', 'hmr', 'dev', 'parallelUse', 'exclude']);
+const LOADER_OPTION_KEYS = new Set([
+	'root',
+	'environment',
+	'hmr',
+	'dev',
+	'profile',
+	'exclude',
+	'renderers',
+	'requireDirective',
+]);
 const PLUGIN_OPTION_KEYS = new Set([...LOADER_OPTION_KEYS, 'transpile']);
 
 function assertBooleanOption(options, key) {
@@ -64,7 +75,8 @@ function normalizeOptions(value, plugin) {
 	}
 	assertBooleanOption(options, 'hmr');
 	assertBooleanOption(options, 'dev');
-	assertBooleanOption(options, 'parallelUse');
+	assertBooleanOption(options, 'profile');
+	assertBooleanOption(options, 'requireDirective');
 	if (
 		options.exclude !== undefined &&
 		(!Array.isArray(options.exclude) || options.exclude.some((entry) => typeof entry !== 'string'))
@@ -72,14 +84,20 @@ function normalizeOptions(value, plugin) {
 		throw new TypeError('@octanejs/rspack-plugin: `exclude` must be an array of path strings.');
 	}
 	if (plugin) assertBooleanOption(options, 'transpile');
+	const renderers =
+		options.renderers === undefined ? undefined : normalizeRendererConfig(options.renderers);
 
 	const normalized = {
 		...(options.root === undefined ? null : { root: options.root }),
 		...(options.environment === undefined ? null : { environment: options.environment }),
 		...(options.hmr === undefined ? null : { hmr: options.hmr }),
 		...(options.dev === undefined ? null : { dev: options.dev }),
-		...(options.parallelUse === undefined ? null : { parallelUse: options.parallelUse }),
+		...(options.profile === undefined ? null : { profile: options.profile }),
 		...(options.exclude === undefined ? null : { exclude: [...options.exclude] }),
+		...(renderers === undefined ? null : { renderers }),
+		...(options.requireDirective === undefined
+			? null
+			: { requireDirective: options.requireDirective }),
 		...(plugin && options.transpile !== undefined ? { transpile: options.transpile } : null),
 	};
 	if (normalized.exclude) Object.freeze(normalized.exclude);
@@ -97,12 +115,21 @@ export function normalizePluginOptions(value) {
 /** Read the serializable metadata attached to an Octane-transformed module. */
 export function getOctaneRspackBuildInfo(module) {
 	const value = module?.buildInfo?.octane;
+	const nestedReferenceValid =
+		value?.clientReference !== null &&
+		typeof value?.clientReference === 'object' &&
+		typeof value.clientReference.id === 'string' &&
+		typeof value.clientReference.moduleId === 'string' &&
+		typeof value.clientReference.renderer === 'string';
 	if (
 		value &&
 		typeof value === 'object' &&
 		typeof value.canonicalId === 'string' &&
-		(value.transformKind === 'compile' || value.transformKind === 'slots') &&
-		typeof value.serverRpc === 'boolean'
+		(value.transformKind === 'compile' ||
+			value.transformKind === 'slots' ||
+			value.transformKind === 'client-only-stub') &&
+		typeof value.serverRpc === 'boolean' &&
+		(value.clientReference === undefined || nestedReferenceValid)
 	) {
 		return value;
 	}

package/types/index.d.ts

@@ -2,6 +2,70 @@ import type { Compiler, RspackPluginInstance } from '@rspack/core';
 
 export type OctaneRspackEnvironment = 'client' | 'server';
 
+export interface OctaneRendererRuleOptions {
+	/** Glob or globs matched against canonical project-relative module IDs. */
+	include: string | readonly string[];
+	/** Optional glob or globs that remove files from this rule. */
+	exclude?: string | readonly string[];
+	/** Renderer alias declared in `registry`, or the built-in `dom` alias. */
+	renderer: string;
+}
+
+export type OctaneRendererRegistryEntry =
+	| string
+	| {
+			module: string;
+			target?: 'dom' | 'universal';
+			server?: 'render' | 'client-only' | 'unsupported';
+			intrinsics?: string;
+			text?: 'reject' | 'ignore' | 'host';
+			capabilities?: readonly string[];
+	  };
+
+/** Static metadata for a component prop lowered for another renderer. */
+export interface OctaneRendererBoundaryOptions {
+	ownerRenderer: string;
+	childRenderer: string;
+	prop: string;
+	server?: 'omit-child';
+}
+
+/** @experimental Declarative renderer selection shared with other Octane compilers. */
+export interface OctaneRendererConfigOptions {
+	registry?: Readonly<Record<string, OctaneRendererRegistryEntry>>;
+	/** Boundary metadata keyed by stable module ID and export name. */
+	boundaries?: Readonly<Record<string, Readonly<Record<string, OctaneRendererBoundaryOptions>>>>;
+	default?: string;
+	rules?: readonly OctaneRendererRuleOptions[];
+}
+
+/** Canonical renderer configuration accepted when another Octane integration resolved it. */
+export interface OctaneResolvedRendererConfig {
+	readonly registry: Readonly<
+		Record<
+			string,
+			{
+				readonly module: string;
+				readonly target: 'dom' | 'universal';
+				readonly server: 'render' | 'client-only' | 'unsupported';
+				readonly intrinsics?: string;
+				readonly text: 'reject' | 'ignore' | 'host';
+				readonly capabilities: readonly string[];
+			}
+		>
+	>;
+	readonly boundaries: Readonly<
+		Record<string, Readonly<Record<string, Readonly<OctaneRendererBoundaryOptions>>>>
+	>;
+	readonly default: string;
+	readonly rules: readonly {
+		readonly include: readonly string[];
+		readonly exclude: readonly string[];
+		readonly renderer: string;
+	}[];
+	readonly signature: string;
+}
+
 export interface OctaneRspackLoaderOptions {
 	/** Project root used to canonicalize module IDs and discover package manifests. */
 	root?: string;
@@ -11,10 +75,28 @@ export interface OctaneRspackLoaderOptions {
 	hmr?: boolean;
 	/** Emit client development metadata. Defaults to Rspack's non-production mode. */
 	dev?: boolean;
-	/** Enable Octane's parallel `use()` compilation pipeline. Default `true`. */
-	parallelUse?: boolean;
-	/** Path fragments excluded from the plain `.ts`/`.js` hook-slot pass. */
+	/** Emit client profiling metadata and enable the profiling runtime. Default `false`. */
+	profile?: boolean;
+	/**
+	 * Path fragments excluded from the plain `.ts`/`.js` hook-slot pass. With
+	 * `requireDirective`, excluded paths are exempt from Octane ownership
+	 * entirely — including `.tsrx`/`.tsx` — for projects routing those paths
+	 * through a different tsrx compiler (e.g. `@tsrx/react`).
+	 */
 	exclude?: string[];
+	/** @experimental Renderer registry and ordered per-file selection rules. */
+	renderers?: OctaneRendererConfigOptions | OctaneResolvedRendererConfig;
+	/**
+	 * Mixed-toolchain ownership gate: when `true`, Octane compiles only
+	 * project modules that declare `'use octane'` in their directive prologue.
+	 * Undirected project `.tsx`/`.ts`/`.js` pass through to the host
+	 * framework's own pipeline; an undirected project `.tsrx` is a build
+	 * error. Installed and linked packages keep their Octane package-manifest
+	 * decision. The directive is always tolerated and stripped from compiled
+	 * output, even when this option is off.
+	 * @default false
+	 */
+	requireDirective?: boolean;
 }
 
 export interface OctaneRspackPluginOptions extends OctaneRspackLoaderOptions {
@@ -28,8 +110,14 @@ export interface OctaneRspackPluginOptions extends OctaneRspackLoaderOptions {
 
 export interface OctaneRspackBuildInfo {
 	canonicalId: string;
-	transformKind: 'compile' | 'slots';
+	transformKind: 'compile' | 'slots' | 'client-only-stub';
 	serverRpc: boolean;
+	/** Stable identity shared by the client compile and its inert server stub. */
+	clientReference?: {
+		readonly id: string;
+		readonly moduleId: string;
+		readonly renderer: string;
+	};
 }
 
 export declare class OctaneRspackPlugin implements RspackPluginInstance {