@octanejs/rspack-plugin 0.1.6 → 0.1.8

package/README.md

@@ -67,6 +67,34 @@ new OctaneRspackPlugin({
 Options remain serializable data—there are no renderer callbacks—so the same
 configuration is safe to reuse across compiler environments and caches.
 
+Rspack layers can compile the same authored module against distinct universal
+renderer graphs. Configure the background graph at the top level, then key
+`layerSpecializations` by the exact value of `module.layer`:
+
+```js
+new OctaneRspackPlugin({
+	runtime: '@fixture/native-background-runtime',
+	renderers: backgroundRenderers,
+	universalRuntime: { runtime: 'native', thread: 'background' },
+	layerSpecializations: {
+		'native:main': {
+			runtime: '@fixture/native-main-runtime',
+			renderers: mainThreadRenderers,
+			universalRuntime: { runtime: 'native', thread: 'main-thread' },
+		},
+	},
+});
+```
+
+The compiler selects `renderers` and `universalRuntime` from each transformed
+module's layer. The plugin also installs `runtime` as an exact `octane` alias
+for requests whose issuer belongs to that layer. Unconfigured and unknown
+layers keep the top-level options. All renderer configurations participate in
+source-dependency discovery and watching, and their normalized signatures and
+runtime identities salt Rspack's persistent cache. The standalone loader
+supports layer-specific compiler options but cannot install runtime aliases,
+so `runtime` specializations require `OctaneRspackPlugin`.
+
 Rspack's dev server enables the loader's hot context. If you run a custom dev
 server, add Rspack's `HotModuleReplacementPlugin` as usual.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/rspack-plugin",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -45,13 +45,13 @@
   },
   "peerDependencies": {
     "@rspack/core": "^2.0.0",
-    "octane": "0.1.11"
+    "octane": "0.1.13"
   },
   "devDependencies": {
-    "@rspack/core": "^2.1.3",
-    "@types/node": "^24.3.0",
-    "vitest": "^4.1.9",
-    "octane": "0.1.11"
+    "@rspack/core": "^2.1.4",
+    "@types/node": "^24.13.3",
+    "vitest": "^4.1.10",
+    "octane": "0.1.13"
   },
   "scripts": {
     "test": "vitest run --config vitest.config.js"

package/src/loader.js

@@ -2,7 +2,11 @@ import { 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 { inferRspackEnvironment, normalizeLoaderOptions } from './shared.js';
+import {
+	inferRspackEnvironment,
+	normalizeLoaderOptions,
+	selectLayerCompilerOptions,
+} from './shared.js';
 
 function realRoot(path) {
 	try {
@@ -99,14 +103,20 @@ export default function octaneLoader(source, inputSourceMap) {
 			environment === 'client' &&
 			(options.dev ?? (this.mode === undefined || this.mode !== 'production'));
 		const profile = environment === 'client' && options.profile === true;
+		const compilerOptions =
+			options.layerSpecializations === undefined
+				? options
+				: selectLayerCompilerOptions(options, this._module);
 		const compiler = createOctaneCompiler({
 			root,
 			profile,
 			...(options.exclude === undefined ? null : { exclude: options.exclude }),
-			...(options.renderers === undefined ? null : { renderers: options.renderers }),
-			...(options.universalRuntime === undefined
+			...(compilerOptions.renderers === undefined
 				? null
-				: { universalRuntime: options.universalRuntime }),
+				: { renderers: compilerOptions.renderers }),
+			...(compilerOptions.universalRuntime === undefined
+				? null
+				: { universalRuntime: compilerOptions.universalRuntime }),
 			...(options.requireDirective === undefined
 				? null
 				: { requireDirective: options.requireDirective }),

package/src/plugin.js

@@ -78,6 +78,54 @@ function addProjectRendererAliases(resolveOptions, renderers, root) {
 	resolveOptions.alias = { ...aliases, ...additions };
 }
 
+function layerSpecializationCacheIdentity(layerSpecializations) {
+	if (layerSpecializations === undefined) return undefined;
+	return Object.fromEntries(
+		Object.entries(layerSpecializations).map(([layer, specialization]) => [
+			layer,
+			{
+				...(specialization.runtime === undefined ? null : { runtime: specialization.runtime }),
+				...(specialization.renderers === undefined
+					? null
+					: { renderers: specialization.renderers.signature }),
+				...(specialization.universalRuntime === undefined
+					? null
+					: { universalRuntime: specialization.universalRuntime }),
+			},
+		]),
+	);
+}
+
+function createDiscoveryCompiler(options, root, profile, specialization) {
+	const renderers = specialization?.renderers ?? options.renderers;
+	const universalRuntime = specialization?.universalRuntime ?? options.universalRuntime;
+	return createOctaneCompiler({
+		root,
+		profile,
+		...(options.exclude === undefined ? null : { exclude: options.exclude }),
+		...(renderers === undefined ? null : { renderers }),
+		...(universalRuntime === undefined ? null : { universalRuntime }),
+	});
+}
+
+function discoverAll(compilers) {
+	if (compilers.length === 1) return compilers[0].discoverSourceDependencies();
+	const packages = new Set();
+	const dependencies = new Set();
+	const missingDependencies = new Set();
+	for (const compiler of compilers) {
+		const discovery = compiler.discoverSourceDependencies();
+		for (const value of discovery.packages ?? []) packages.add(value);
+		for (const value of discovery.dependencies ?? []) dependencies.add(value);
+		for (const value of discovery.missingDependencies ?? []) missingDependencies.add(value);
+	}
+	return {
+		packages: [...packages].sort(),
+		dependencies: [...dependencies].sort(),
+		missingDependencies: [...missingDependencies].sort(),
+	};
+}
+
 function addDependencies(collection, values) {
 	if (!collection?.add) return;
 	for (const value of values ?? []) collection.add(value);
@@ -239,21 +287,18 @@ export class OctaneRspackPlugin {
 			renderers: this.options.renderers?.signature,
 			runtime: this.options.runtime,
 			universalRuntime: this.options.universalRuntime,
+			layerSpecializations: layerSpecializationCacheIdentity(this.options.layerSpecializations),
 			// 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.renderers === undefined ? null : { renderers: this.options.renderers }),
-			...(this.options.universalRuntime === undefined
-				? null
-				: { universalRuntime: this.options.universalRuntime }),
-		});
+		const neutralCompiler = createDiscoveryCompiler(this.options, root, profile);
+		const discoveryCompilers = [neutralCompiler];
+		for (const specialization of Object.values(this.options.layerSpecializations ?? {})) {
+			discoveryCompilers.push(createDiscoveryCompiler(this.options, root, profile, specialization));
+		}
 		const runtimeRequest =
 			this.options.runtime ?? neutralCompiler.resolveRuntimeRequest('octane', environment);
 
@@ -261,6 +306,9 @@ export class OctaneRspackPlugin {
 		addUniqueExtensions(compiler.options.resolve);
 		addRuntimeAlias(compiler.options.resolve, runtimeRequest, root);
 		addProjectRendererAliases(compiler.options.resolve, this.options.renderers, root);
+		for (const specialization of Object.values(this.options.layerSpecializations ?? {})) {
+			addProjectRendererAliases(compiler.options.resolve, specialization.renderers, root);
+		}
 
 		compiler.options.module ??= {};
 		compiler.options.module.rules ??= [];
@@ -275,6 +323,9 @@ export class OctaneRspackPlugin {
 			...(this.options.universalRuntime === undefined
 				? null
 				: { universalRuntime: this.options.universalRuntime }),
+			...(this.options.layerSpecializations === undefined
+				? null
+				: { layerSpecializations: this.options.layerSpecializations }),
 			...(this.options.requireDirective === undefined
 				? null
 				: { requireDirective: this.options.requireDirective }),
@@ -292,21 +343,32 @@ export class OctaneRspackPlugin {
 				use: [{ loader: 'builtin:swc-loader', options: { detectSyntax: 'auto' } }],
 			});
 		}
+		for (const [layer, specialization] of Object.entries(this.options.layerSpecializations ?? {})) {
+			if (specialization.runtime === undefined) continue;
+			compiler.options.module.rules.push({
+				issuerLayer: layer,
+				resolve: {
+					alias: {
+						octane$: resolveRuntimeModule(specialization.runtime, root),
+					},
+				},
+			});
+		}
 
 		let discovery;
 		const discover = () => {
 			if (discovery === undefined) {
-				discovery = neutralCompiler.discoverSourceDependencies();
+				discovery = discoverAll(discoveryCompilers);
 				this.sourceDependencies = Object.freeze([...(discovery.packages ?? [])]);
 			}
 			return discovery;
 		};
 		compiler.hooks.invalid?.tap(PLUGIN_NAME, (filename) => {
-			neutralCompiler.invalidate(filename);
+			for (const current of discoveryCompilers) current.invalidate(filename);
 			discovery = undefined;
 		});
 		compiler.hooks.watchRun?.tap(PLUGIN_NAME, () => {
-			neutralCompiler.invalidate();
+			for (const current of discoveryCompilers) current.invalidate();
 			discovery = undefined;
 		});
 		compiler.hooks.thisCompilation?.tap(PLUGIN_NAME, (compilation) => {

package/src/shared.js

@@ -44,8 +44,19 @@ const LOADER_OPTION_KEYS = new Set([
 	'renderers',
 	'requireDirective',
 	'universalRuntime',
+	'layerSpecializations',
 ]);
 const PLUGIN_OPTION_KEYS = new Set([...LOADER_OPTION_KEYS, 'runtime', 'transpile']);
+const LAYER_SPECIALIZATION_KEYS = new Set(['runtime', 'renderers', 'universalRuntime']);
+
+function normalizeRuntimeRequest(value, label = 'runtime') {
+	if (value !== undefined && (typeof value !== 'string' || value.trim() !== value || !value)) {
+		throw new TypeError(
+			`@octanejs/rspack-plugin: \`${label}\` must be a non-empty module request string.`,
+		);
+	}
+	return value;
+}
 
 function normalizeUniversalRuntime(value) {
 	if (value === undefined) return undefined;
@@ -73,6 +84,68 @@ function normalizeUniversalRuntime(value) {
 	return Object.freeze({ runtime: value.runtime, thread: value.thread });
 }
 
+function normalizeLayerSpecializations(value) {
+	if (value === undefined) return undefined;
+	if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+		throw new TypeError('@octanejs/rspack-plugin: `layerSpecializations` must be an object map.');
+	}
+	const entries = Object.entries(value).sort(([left], [right]) =>
+		left < right ? -1 : left > right ? 1 : 0,
+	);
+	const normalized = [];
+	for (const [layer, specialization] of entries) {
+		if (!layer || layer.trim() !== layer) {
+			throw new TypeError(
+				'@octanejs/rspack-plugin: `layerSpecializations` keys must be non-empty layer names without surrounding whitespace.',
+			);
+		}
+		if (
+			specialization === null ||
+			typeof specialization !== 'object' ||
+			Array.isArray(specialization)
+		) {
+			throw new TypeError(
+				`@octanejs/rspack-plugin: \`layerSpecializations.${layer}\` must be an object.`,
+			);
+		}
+		for (const key of Object.keys(specialization)) {
+			if (!LAYER_SPECIALIZATION_KEYS.has(key)) {
+				throw new TypeError(
+					`@octanejs/rspack-plugin: unknown \`layerSpecializations.${layer}.${key}\` option.`,
+				);
+			}
+		}
+		const runtime = normalizeRuntimeRequest(
+			specialization.runtime,
+			`layerSpecializations.${layer}.runtime`,
+		);
+		const renderers =
+			specialization.renderers === undefined
+				? undefined
+				: normalizeRendererConfig(specialization.renderers);
+		const universalRuntime = normalizeUniversalRuntime(specialization.universalRuntime);
+		normalized.push([
+			layer,
+			Object.freeze({
+				...(runtime === undefined ? null : { runtime }),
+				...(renderers === undefined ? null : { renderers }),
+				...(universalRuntime === undefined ? null : { universalRuntime }),
+			}),
+		]);
+	}
+	return Object.freeze(Object.fromEntries(normalized));
+}
+
+/** Select the compiler-facing options for a module's Rspack layer. */
+export function selectLayerCompilerOptions(options, module) {
+	const layer = typeof module?.layer === 'string' ? module.layer : undefined;
+	const specialization = layer === undefined ? undefined : options.layerSpecializations?.[layer];
+	return {
+		renderers: specialization?.renderers ?? options.renderers,
+		universalRuntime: specialization?.universalRuntime ?? options.universalRuntime,
+	};
+}
+
 function assertBooleanOption(options, key) {
 	if (options[key] !== undefined && typeof options[key] !== 'boolean') {
 		throw new TypeError(`@octanejs/rspack-plugin: \`${key}\` must be a boolean.`);
@@ -93,17 +166,7 @@ function normalizeOptions(value, plugin) {
 	if (options.root !== undefined && typeof options.root !== 'string') {
 		throw new TypeError('@octanejs/rspack-plugin: `root` must be a path string.');
 	}
-	if (
-		plugin &&
-		options.runtime !== undefined &&
-		(typeof options.runtime !== 'string' ||
-			options.runtime.trim() !== options.runtime ||
-			!options.runtime)
-	) {
-		throw new TypeError(
-			'@octanejs/rspack-plugin: `runtime` must be a non-empty module request string.',
-		);
-	}
+	if (plugin) normalizeRuntimeRequest(options.runtime);
 	if (
 		options.environment !== undefined &&
 		options.environment !== 'client' &&
@@ -125,6 +188,7 @@ function normalizeOptions(value, plugin) {
 	const renderers =
 		options.renderers === undefined ? undefined : normalizeRendererConfig(options.renderers);
 	const universalRuntime = normalizeUniversalRuntime(options.universalRuntime);
+	const layerSpecializations = normalizeLayerSpecializations(options.layerSpecializations);
 
 	const normalized = {
 		...(options.root === undefined ? null : { root: options.root }),
@@ -135,6 +199,7 @@ function normalizeOptions(value, plugin) {
 		...(options.exclude === undefined ? null : { exclude: [...options.exclude] }),
 		...(renderers === undefined ? null : { renderers }),
 		...(universalRuntime === undefined ? null : { universalRuntime }),
+		...(layerSpecializations === undefined ? null : { layerSpecializations }),
 		...(options.requireDirective === undefined
 			? null
 			: { requireDirective: options.requireDirective }),

package/types/index.d.ts

@@ -32,6 +32,8 @@ export type OctaneRendererRegistryEntry =
 			intrinsics?: string;
 			text?: 'reject' | 'ignore' | 'host';
 			capabilities?: readonly string[];
+			/** Host event prop names or prefix patterns retained as first-screen listener sentinels. */
+			firstScreenEvents?: readonly string[];
 			validation?: OctaneRendererValidationOptions;
 	  };
 
@@ -64,6 +66,7 @@ export interface OctaneResolvedRendererConfig {
 				readonly intrinsics?: string;
 				readonly text: 'reject' | 'ignore' | 'host';
 				readonly capabilities: readonly string[];
+				readonly firstScreenEvents?: readonly string[];
 				readonly validation?: Readonly<OctaneRendererValidationOptions>;
 			}
 		>
@@ -80,6 +83,24 @@ export interface OctaneResolvedRendererConfig {
 	readonly signature: string;
 }
 
+/** Compile-only host identity attached to a universal renderer graph. */
+export interface OctaneUniversalRuntimeOptions {
+	readonly runtime: string;
+	readonly thread: 'background' | 'main-thread';
+}
+
+/** Compiler options selected for modules issued from one Rspack layer. */
+export interface OctaneRspackLoaderLayerSpecializationOptions {
+	renderers?: OctaneRendererConfigOptions | OctaneResolvedRendererConfig;
+	universalRuntime?: OctaneUniversalRuntimeOptions;
+}
+
+/** Plugin-owned compiler and runtime options selected for one Rspack layer. */
+export interface OctaneRspackLayerSpecializationOptions extends OctaneRspackLoaderLayerSpecializationOptions {
+	/** Override exact `octane` imports for modules issued from this layer. */
+	runtime?: string;
+}
+
 export interface OctaneRspackLoaderOptions {
 	/** Project root used to canonicalize module IDs and discover package manifests. */
 	root?: string;
@@ -101,24 +122,32 @@ export interface OctaneRspackLoaderOptions {
 	/** @experimental Renderer registry and ordered per-file selection rules. */
 	renderers?: OctaneRendererConfigOptions | OctaneResolvedRendererConfig;
 	/** Compile-only host runtime/thread identity for a universal renderer graph. */
-	universalRuntime?: {
-		readonly runtime: string;
-		readonly thread: 'background' | 'main-thread';
-	};
+	universalRuntime?: OctaneUniversalRuntimeOptions;
+	/**
+	 * Compiler options selected by the current module's Rspack layer. Unknown
+	 * layers retain the top-level compiler options. Runtime aliases remain a
+	 * class-plugin concern and cannot be configured by the standalone loader.
+	 */
+	layerSpecializations?: Readonly<Record<string, OctaneRspackLoaderLayerSpecializationOptions>>;
 	/**
-	 * 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.
+	 * Mixed-toolchain ownership gate: when `true`, a project `.tsrx` is
+	 * Octane's by extension, and a project `.tsx` (full compile) or plain
+	 * `.ts`/`.js` (hook slotting) is Octane's only when it opens with a
+	 * leading `@jsxImportSource octane` pragma comment (any registered
+	 * renderer's intrinsics module also counts). Unmarked project modules
+	 * pass through to the host framework's own pipeline. Installed and
+	 * linked packages keep their Octane package-manifest decision.
 	 * @default false
 	 */
 	requireDirective?: boolean;
 }
 
 export interface OctaneRspackPluginOptions extends OctaneRspackLoaderOptions {
+	/**
+	 * Compiler and exact-runtime overrides selected by the current module's
+	 * Rspack layer. Unknown layers retain the top-level plugin options.
+	 */
+	layerSpecializations?: Readonly<Record<string, OctaneRspackLayerSpecializationOptions>>;
 	/**
 	 * Override the exact module used for plain `octane` imports in this graph.
 	 * Universal host integrations use this to share one hook/context runtime
@@ -138,10 +167,7 @@ export interface OctaneRspackBuildInfo {
 	transformKind: 'compile' | 'slots' | 'client-only-stub';
 	serverRpc: boolean;
 	/** Universal host runtime/thread identity, when this module was specialized. */
-	universalRuntime?: {
-		readonly runtime: string;
-		readonly thread: 'background' | 'main-thread';
-	};
+	universalRuntime?: OctaneUniversalRuntimeOptions;
 	/** Stable identity shared by the client compile and its inert server stub. */
 	clientReference?: {
 		readonly id: string;

package/types/options.test-d.ts

@@ -0,0 +1,41 @@
+import type { OctaneRspackLoaderOptions, OctaneRspackPluginOptions } from './index.js';
+
+const loaderOptions: OctaneRspackLoaderOptions = {
+	layerSpecializations: {
+		'native:main': {
+			renderers: {
+				registry: {
+					native: {
+						module: '@fixture/native-main-renderer',
+						capabilities: ['main-thread-render-only'],
+						firstScreenEvents: ['bind*', 'catch*'],
+					},
+				},
+				default: 'native',
+			},
+			universalRuntime: { runtime: 'native', thread: 'main-thread' },
+		},
+	},
+};
+
+const pluginOptions: OctaneRspackPluginOptions = {
+	layerSpecializations: {
+		'native:main': {
+			runtime: '@fixture/native-main-runtime',
+			universalRuntime: { runtime: 'native', thread: 'main-thread' },
+		},
+	},
+};
+
+const unsupportedLoaderRuntime: OctaneRspackLoaderOptions = {
+	layerSpecializations: {
+		'native:main': {
+			// @ts-expect-error The standalone loader cannot install an issuer-layer runtime alias.
+			runtime: '@fixture/native-main-runtime',
+		},
+	},
+};
+
+void loaderOptions;
+void pluginOptions;
+void unsupportedLoaderRuntime;