@octanejs/rspack-plugin 0.1.37 → 0.1.38

package/README.md

@@ -83,9 +83,21 @@ new OctaneRspackPlugin({
 });
 ```
 
-Options remain serializable data—there are no renderer callbacks—so the same
+Renderer options remain serializable data—there are no renderer callbacks—so the same
 configuration is safe to reuse across compiler environments and caches.
 
+For one-shot production builds, the experimental class-plugin option
+`cssModuleConstants: true` folds proven named-string exports from JavaScript
+CSS-module providers such as `css-loader` with CSS extraction. An immutable CSS
+provider can instead supply a `cssModuleConstants(module)` callback. It runs on
+the main thread and its facts are checked against the exact completed loader
+source. Ordinary mutable default maps and native `css/module` are left alone.
+Eligible consumers are compiled once more and are not stored in the persistent
+module cache; other modules keep normal caching. The option is disabled by
+default and does not change development, HMR, or watch output. See
+[CSS-module constants](../../docs/compiler-css-module-constants.md) for the
+provider contract and stylesheet-ownership rules.
+
 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`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/rspack-plugin",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -45,13 +45,16 @@
   },
   "peerDependencies": {
     "@rspack/core": "^2.0.0",
-    "octane": "0.1.42"
+    "octane": "0.1.43"
   },
   "devDependencies": {
     "@rspack/core": "^2.1.4",
+    "@types/jsdom": "30.0.0",
     "@types/node": "^24.13.3",
+    "css-loader": "6.11.0",
+    "jsdom": "^30.0.1",
     "vitest": "^4.1.10",
-    "octane": "0.1.42"
+    "octane": "0.1.43"
   },
   "scripts": {
     "test": "vitest run --config vitest.config.js"

package/src/css-module-constants.js

@@ -0,0 +1,377 @@
+import {
+	cleanModuleId,
+	isPlainCssModuleId,
+	readCssModuleExports,
+	validateCssModuleConstants,
+} from 'octane/compiler/bundler';
+import {
+	CSS_MODULE_BUILD_INFO_KEY,
+	CSS_MODULE_CONTEXT_KEY,
+	cssModuleSourceHash,
+} from './css-module-data.js';
+
+const PLUGIN_NAME = 'OctaneRspackCssModuleConstants';
+const DIAGNOSTIC_OWNER = '@octanejs/rspack-plugin';
+const JAVASCRIPT_TYPES = new Set(['javascript/auto', 'javascript/esm']);
+const HASH = /^[a-f0-9]{64}$/;
+
+function iterable(value) {
+	return value != null && typeof value[Symbol.iterator] === 'function' ? value : [];
+}
+
+function identifier(module) {
+	if (typeof module?.identifier !== 'function') return null;
+	const id = module.identifier();
+	return typeof id === 'string' ? id : null;
+}
+
+function moduleSource(module) {
+	const source = module?.originalSource?.()?.source();
+	if (typeof source === 'string') return source;
+	return Buffer.isBuffer(source) ? source.toString('utf8') : null;
+}
+
+/** Reacquire current-build objects; native-backed Modules never enter our state. */
+function currentModules(modules) {
+	const result = new Map();
+	const seen = new Set();
+	const visit = (module) => {
+		if (module == null || seen.has(module)) return;
+		seen.add(module);
+		// Concatenation can move a provider under another module. Prefer the
+		// original child if a wrapper happens to share its identifier.
+		for (const child of iterable(module.modules)) visit(child);
+		if (module.rootModule != null) visit(module.rootModule);
+		const id = identifier(module);
+		if (id !== null && !result.has(id)) result.set(id, module);
+	};
+	for (const module of iterable(modules)) visit(module);
+	return result;
+}
+
+function candidateInfo(module) {
+	const info = module?.buildInfo?.[CSS_MODULE_BUILD_INFO_KEY];
+	if (
+		info == null ||
+		typeof info.sourceHash !== 'string' ||
+		!HASH.test(info.sourceHash) ||
+		!Array.isArray(info.requests) ||
+		!info.requests.every((request) => typeof request === 'string') ||
+		!Array.isArray(info.consumed) ||
+		!info.consumed.every((request) => typeof request === 'string')
+	) {
+		return null;
+	}
+	return info;
+}
+
+function changed(importer, request, reason) {
+	const location =
+		request === undefined
+			? JSON.stringify(importer)
+			: `${JSON.stringify(importer)} (${JSON.stringify(request)})`;
+	throw new Error(`${DIAGNOSTIC_OWNER}: CSS-module proof changed for ${location}: ${reason}.`);
+}
+
+/**
+ * A resource path is not an import identity: issuer rules, layers, queries,
+ * dependency categories, and replacements can select different modules. Read
+ * the effective target of the actual ESM edge after the make phase instead.
+ */
+function targetForRequest(compilation, importer, request) {
+	const targets = new Map();
+	for (const connection of compilation.moduleGraph.getOutgoingConnections(importer)) {
+		const dependency = connection.dependency;
+		if (dependency?.request !== request || dependency.category !== 'esm') continue;
+		if (dependency.attributes != null && Object.keys(dependency.attributes).length > 0) {
+			return null;
+		}
+		const target = connection.module;
+		const id = identifier(target);
+		if (id === null) return null;
+		targets.set(id, target);
+	}
+	return targets.size === 1 ? targets.values().next().value : null;
+}
+
+function sortedStrings(values) {
+	return [...new Set([...iterable(values)].filter((value) => typeof value === 'string'))].sort();
+}
+
+function moduleDependencies(module) {
+	const info = module.buildInfo;
+	return {
+		files: sortedStrings(info?.fileDependencies),
+		contexts: sortedStrings(info?.contextDependencies),
+		missing: sortedStrings(info?.missingDependencies),
+		build: sortedStrings(info?.buildDependencies),
+	};
+}
+
+function providerMeta(module) {
+	const info = module.buildInfo;
+	return Object.freeze(info != null && typeof info === 'object' ? { ...info } : {});
+}
+
+function readTargetProof(module, option, environment, cache) {
+	const id = identifier(module);
+	if (id === null || !JAVASCRIPT_TYPES.has(module.type) || typeof module.resource !== 'string') {
+		// Native css/* has no final JavaScript export map at this stage. Likewise
+		// asset/source can contain ESM-looking text without exporting its bindings.
+		return null;
+	}
+	const code = moduleSource(module);
+	if (code === null) return null;
+	const fingerprint = cssModuleSourceHash(code);
+	const cached = cache.get(id);
+	if (cached !== undefined) {
+		if (cached.fingerprint !== fingerprint)
+			changed(id, undefined, 'provider source changed during collection');
+		return cached.proof;
+	}
+	const exports = readCssModuleExports(code, { allowPureVar: true });
+	const supplied =
+		typeof option !== 'function'
+			? null
+			: validateCssModuleConstants(
+					option(
+						Object.freeze({
+							id,
+							resource: module.resource,
+							code,
+							meta: providerMeta(module),
+							environment,
+							layer: module.layer,
+							type: module.type,
+						}),
+					),
+					exports,
+					id,
+					DIAGNOSTIC_OWNER,
+				);
+	const named =
+		isPlainCssModuleId(cleanModuleId(module.resource)) && exports?.pure === true
+			? new Map(exports.named)
+			: new Map();
+	for (const [name, value] of supplied?.named ?? []) named.set(name, value);
+	const defaultMap = supplied?.default ?? new Map();
+	const proof =
+		named.size === 0 && defaultMap.size === 0
+			? null
+			: {
+					id,
+					fingerprint,
+					named: [...named].sort(([left], [right]) => left.localeCompare(right)),
+					default: [...defaultMap].sort(([left], [right]) => left.localeCompare(right)),
+					dependencies: moduleDependencies(module),
+				};
+	cache.set(id, { fingerprint, proof });
+	return proof;
+}
+
+function sameStrings(left, right) {
+	const a = [...new Set(left)].sort();
+	const b = [...new Set(right)].sort();
+	return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+function verifyTarget(compilation, importer, entry) {
+	const target = targetForRequest(compilation, importer, entry.request);
+	if (identifier(target) !== entry.id)
+		changed(identifier(importer), entry.request, 'the effective module identity differs');
+	if (!JAVASCRIPT_TYPES.has(target.type))
+		changed(identifier(importer), entry.request, 'the target is no longer JavaScript ESM');
+	const source = moduleSource(target);
+	if (source === null || cssModuleSourceHash(source) !== entry.fingerprint) {
+		changed(identifier(importer), entry.request, 'the final provider source differs');
+	}
+}
+
+function verifyGraph(compilation, state) {
+	if (state.receipts.size === 0) return;
+	const modules = currentModules(compilation.modules);
+	for (const [id, receipt] of state.receipts) {
+		const importer = modules.get(id);
+		const info = candidateInfo(importer);
+		if (
+			info === null ||
+			info.sourceHash !== receipt.sourceHash ||
+			!sameStrings(
+				info.consumed,
+				receipt.imports.map((entry) => entry.request),
+			)
+		) {
+			changed(id, undefined, 'the authored importer or committed-use receipt differs');
+		}
+		for (const entry of receipt.imports) verifyTarget(compilation, importer, entry);
+	}
+}
+
+function verifyFinalSources(compilation, state) {
+	if (state.receipts.size === 0) return;
+	const modules = currentModules(compilation.modules);
+	const checked = new Map();
+	for (const receipt of state.receipts.values()) {
+		for (const entry of receipt.imports) {
+			if (checked.has(entry.id)) {
+				if (checked.get(entry.id) !== entry.fingerprint)
+					changed(entry.id, undefined, 'conflicting source receipts');
+				continue;
+			}
+			checked.set(entry.id, entry.fingerprint);
+			const module = modules.get(entry.id);
+			// The full graph was checked at seal, before optimization. An unused
+			// component and its stylesheet may now be gone, which is intentional.
+			if (module === undefined) continue;
+			const source = moduleSource(module);
+			if (
+				!JAVASCRIPT_TYPES.has(module.type) ||
+				source === null ||
+				cssModuleSourceHash(source) !== entry.fingerprint
+			) {
+				changed(entry.id, undefined, 'the emitted provider source differs');
+			}
+		}
+	}
+}
+
+async function collectAndRebuild(compilation, state, option, environment) {
+	if (state.started) return;
+	state.started = true;
+	const cache = new Map();
+	// Collect from the complete first graph before rebuilding anything. This is
+	// both deterministic and safe for mutually importing virtual CSS providers.
+	{
+		const modules = currentModules(compilation.modules);
+		const candidates = [...modules]
+			.filter(([, module]) => candidateInfo(module)?.requests.length > 0)
+			.map(([id]) => id)
+			.sort();
+		for (const id of candidates) {
+			const importer = modules.get(id);
+			const info = candidateInfo(importer);
+			const imports = [];
+			for (const request of [...new Set(info.requests)].sort()) {
+				const target = targetForRequest(compilation, importer, request);
+				if (target === null) continue;
+				const proof = readTargetProof(target, option, environment, cache);
+				if (proof !== null) imports.push({ request, ...proof });
+			}
+			if (imports.length > 0) {
+				state.proofs.set(id, { sourceHash: info.sourceHash, imports });
+			}
+		}
+	}
+	// A derived CSS provider can itself be an Octane importer. Its first-pass
+	// source is not a stable proof if this batch will recompile it. Deopt those
+	// edges rather than chase a fixed point or rebuild any importer twice. This
+	// deliberately bounded pass need not find every possible constant.
+	const scheduled = new Set(state.proofs.keys());
+	for (const [id, proof] of state.proofs) {
+		const imports = proof.imports.filter((entry) => !scheduled.has(entry.id));
+		if (imports.length === 0) state.proofs.delete(id);
+		else if (imports.length !== proof.imports.length) state.proofs.set(id, { ...proof, imports });
+	}
+	// Rspack owns graph mutation. Do not write source objects, synthesize entry
+	// dependencies, or invoke importModule (which executes application modules).
+	// Its public rebuildModule dispatcher batches synchronous requests. Ignore
+	// callback Module values: Rspack may return those in a different order, and
+	// only the current graph's exact identifiers authenticate the rebuilt inputs.
+	const pending = (() => {
+		const modules = currentModules(compilation.modules);
+		return [...state.proofs.keys()].map((id) => {
+			const importer = modules.get(id);
+			if (importer === undefined)
+				changed(id, undefined, 'the importer disappeared before rebuilding');
+			return new Promise((resolve, reject) => {
+				compilation.rebuildModule(importer, (error) => (error ? reject(error) : resolve()));
+			});
+		});
+	})();
+	const results = await Promise.allSettled(pending);
+	for (const result of results) if (result.status === 'rejected') throw result.reason;
+	const rebuiltModules = currentModules(compilation.modules);
+	for (const [id, proof] of state.proofs) {
+		const rebuilt = rebuiltModules.get(id);
+		const info = candidateInfo(rebuilt);
+		if (info === null || info.sourceHash !== proof.sourceHash) {
+			changed(id, undefined, 'the authored source changed while rebuilding');
+		}
+		const entries = new Map(proof.imports.map((entry) => [entry.request, entry]));
+		const consumed = [...new Set(info.consumed)].sort();
+		if (consumed.some((request) => !entries.has(request))) {
+			changed(id, undefined, 'the compiler consumed an unprovided import');
+		}
+		if (consumed.length > 0) {
+			state.receipts.set(id, {
+				sourceHash: proof.sourceHash,
+				imports: consumed.map((request) => entries.get(request)),
+			});
+		}
+	}
+	verifyGraph(compilation, state);
+}
+
+function oneShotProduction(compiler) {
+	return (
+		compiler.options.mode === 'production' && compiler.watchMode !== true && !compiler.options.watch
+	);
+}
+
+/** Install the opt-in, main-thread, same-compilation CSS proof controller. */
+export function installCssModuleConstants(compiler, { option, environment }) {
+	if (option === undefined || option === false) return;
+	if (option !== true && typeof option !== 'function') {
+		throw new TypeError(`${DIAGNOSTIC_OWNER}: cssModuleConstants must be a boolean or function.`);
+	}
+	const NormalModule = compiler.webpack?.NormalModule;
+	if (
+		typeof NormalModule?.getCompilationHooks !== 'function' ||
+		typeof compiler.hooks.thisCompilation?.tap !== 'function' ||
+		typeof compiler.hooks.finishMake?.tapPromise !== 'function'
+	) {
+		throw new TypeError(
+			`${DIAGNOSTIC_OWNER}: cssModuleConstants requires Rspack's module and finishMake hooks.`,
+		);
+	}
+	const states = new WeakMap();
+	compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
+		const state = {
+			enabled: compiler.options.mode === 'production',
+			discoverOnly: !oneShotProduction(compiler),
+			started: false,
+			proofs: new Map(),
+			receipts: new Map(),
+		};
+		states.set(compilation, state);
+		if (!state.enabled) return;
+		NormalModule.getCompilationHooks(compilation).loader.tap(PLUGIN_NAME, (context, module) => {
+			context[CSS_MODULE_CONTEXT_KEY] = {
+				enabled: true,
+				...(state.discoverOnly ? { discoverOnly: true } : null),
+				proof: state.discoverOnly ? null : (state.proofs.get(identifier(module)) ?? null),
+			};
+		});
+		// Production watch may cache ordinary candidate metadata for a later
+		// one-shot build, but never authenticates or consumes cross-module facts.
+		if (state.discoverOnly) return;
+		// All finishModules taps have completed, and module concatenation has not
+		// yet rewritten the effective graph. This catches later provider rebuilds.
+		compilation.hooks.seal.tap({ name: PLUGIN_NAME, stage: Number.MAX_SAFE_INTEGER }, () =>
+			verifyGraph(compilation, state),
+		);
+		compilation.hooks.processAssets.tap(
+			{
+				name: PLUGIN_NAME,
+				stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_REPORT,
+			},
+			() => verifyFinalSources(compilation, state),
+		);
+	});
+	compiler.hooks.finishMake.tapPromise(PLUGIN_NAME, async (compilation) => {
+		const state = states.get(compilation);
+		if (state?.enabled && !state.discoverOnly && oneShotProduction(compiler)) {
+			await collectAndRebuild(compilation, state, option, environment);
+		}
+	});
+}

package/src/css-module-data.js

@@ -0,0 +1,90 @@
+import { createHash } from 'node:crypto';
+
+// Only plain data crosses Rspack's worker boundary. The provider callback and
+// native module graph stay on the main thread for the current compilation.
+export const CSS_MODULE_CONTEXT_KEY = '__octaneCssModuleConstants';
+export const CSS_MODULE_BUILD_INFO_KEY = 'octaneCssModuleConstants';
+
+export function cssModuleSourceHash(source) {
+	return createHash('sha256').update(String(source)).digest('hex');
+}
+
+export function clearCssModuleBuildInfo(module) {
+	if (module?.buildInfo && typeof module.buildInfo === 'object') {
+		delete module.buildInfo[CSS_MODULE_BUILD_INFO_KEY];
+	}
+}
+
+/** Prepare a proof for this exact authored loader input, never a previous build. */
+export function prepareCssModuleConstants(context, compiler, source, id, options) {
+	const data = context[CSS_MODULE_CONTEXT_KEY];
+	if (
+		data?.enabled !== true ||
+		context.mode !== 'production' ||
+		context.hot === true ||
+		options.dev ||
+		options.hmr
+	) {
+		return null;
+	}
+	const requests = compiler.findCssModuleImportRequests(source, id, options.environment);
+	if (requests.length === 0) return null;
+	// A host callback may close over configuration outside Rspack's cache key.
+	// Only eligible CSS consumers pay for the conservative one-shot rebuild.
+	if (data.discoverOnly !== true) context.cacheable?.(false);
+	const sourceHash = cssModuleSourceHash(source);
+	const requested = new Set(requests);
+	const imports = new Map();
+	if (data.discoverOnly !== true && data.proof?.sourceHash === sourceHash) {
+		for (const entry of data.proof.imports) {
+			if (!requested.has(entry.request)) continue;
+			imports.set(entry.request, {
+				...entry,
+				named: new Map(entry.named),
+				default: new Map(entry.default),
+			});
+		}
+	}
+	const transformOptions =
+		imports.size === 0
+			? null
+			: {
+					resolveCssModuleConstant(request, imported, property) {
+						const entry = imports.get(request);
+						if (entry === undefined) return undefined;
+						if (property === null) return entry.named.get(imported);
+						if (imported === 'default') {
+							return entry.default.get(property);
+						}
+						if (imported === '*') {
+							return entry.named.get(property);
+						}
+						return undefined;
+					},
+					// Keep each retained template's ordinary stylesheet ownership edge.
+					preserveCssModuleReferences: [...imports.keys()],
+				};
+	return { sourceHash, requests, imports, transformOptions };
+}
+
+/** Publish only committed folds and their real loader dependencies. */
+export function finishCssModuleConstants(context, prepared, result) {
+	if (prepared === null || result?.kind !== 'compile' || !context._module) return;
+	const consumed = [...new Set(result.cssModuleConstantImports ?? [])].filter((request) =>
+		prepared.imports.has(request),
+	);
+	for (const request of consumed) {
+		const dependencies = prepared.imports.get(request).dependencies;
+		for (const file of dependencies.files) context.addDependency?.(file);
+		for (const directory of dependencies.contexts) context.addContextDependency?.(directory);
+		for (const file of dependencies.missing) context.addMissingDependency?.(file);
+		for (const file of dependencies.build) context.addBuildDependency?.(file);
+	}
+	const module = context._module;
+	if (!module.buildInfo || typeof module.buildInfo !== 'object') module.buildInfo = {};
+	module.buildInfo[CSS_MODULE_BUILD_INFO_KEY] = {
+		sourceHash: prepared.sourceHash,
+		requests: [...prepared.requests],
+		consumed,
+	};
+}

package/src/finalize-loader.js

@@ -1,3 +1,9 @@
+import {
+	clearCssModuleBuildInfo,
+	CSS_MODULE_BUILD_INFO_KEY,
+	CSS_MODULE_CONTEXT_KEY,
+} from './css-module-data.js';
+
 /**
  * Rspack does not copy a module's layer or buildInfo into parallel-loader
  * workers. Pitch data is structured-cloned into the worker before compilation.
@@ -5,6 +11,8 @@
 export function pitch() {
 	this.data ??= {};
 	this.data.octaneLayer = this._module?.layer ?? null;
+	this.data[CSS_MODULE_CONTEXT_KEY] = this[CSS_MODULE_CONTEXT_KEY] ?? null;
+	clearCssModuleBuildInfo(this._module);
 	if (this._module?.buildInfo && typeof this._module.buildInfo === 'object') {
 		delete this._module.buildInfo.octane;
 	}
@@ -19,6 +27,12 @@ export default function finalizeOctaneLoader(source, sourceMap, metadata) {
 		}
 		this._module.buildInfo.octane = result.buildInfo;
 	}
+	if (result?.cssModuleBuildInfo) {
+		if (!this._module.buildInfo || typeof this._module.buildInfo !== 'object') {
+			this._module.buildInfo = {};
+		}
+		this._module.buildInfo[CSS_MODULE_BUILD_INFO_KEY] = result.cssModuleBuildInfo;
+	}
 	for (const dependency of result?.missingDependencies ?? []) {
 		this.addMissingDependency(dependency);
 	}

package/src/loader.js

@@ -2,6 +2,12 @@ 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 {
+	clearCssModuleBuildInfo,
+	CSS_MODULE_CONTEXT_KEY,
+	finishCssModuleConstants,
+	prepareCssModuleConstants,
+} from './css-module-data.js';
 import {
 	inferRspackEnvironment,
 	normalizeLoaderOptions,
@@ -85,6 +91,7 @@ async function resolveClientOnlyImports(context, compiler, source, id) {
 export default function octaneLoader(source, inputSourceMap) {
 	this.cacheable?.(true);
 	clearBuildInfo(this._module);
+	clearCssModuleBuildInfo(this._module);
 
 	try {
 		const options = normalizeLoaderOptions(this.getOptions?.() ?? {});
@@ -125,14 +132,24 @@ export default function octaneLoader(source, inputSourceMap) {
 			warn: (message) => this.emitWarning?.(new Error(message)),
 		});
 		const id = realModuleId(this.resource ?? this.resourcePath);
+		const authoredSource = String(source);
+		const cssModuleConstants =
+			this[CSS_MODULE_CONTEXT_KEY]?.enabled === true
+				? prepareCssModuleConstants(this, compiler, authoredSource, id, {
+						environment,
+						hmr,
+						dev,
+					})
+				: null;
 		const finish = (clientOnlyImports, callback) => {
 			try {
-				const result = compiler.transform(String(source), id, {
+				const result = compiler.transform(authoredSource, id, {
 					environment,
 					hmr,
 					dev,
 					profile,
 					...(clientOnlyImports.length > 0 ? { clientOnlyImports } : null),
+					...cssModuleConstants?.transformOptions,
 				});
 
 				if (result === null) {
@@ -141,6 +158,7 @@ export default function octaneLoader(source, inputSourceMap) {
 				}
 
 				registerDependencies(this, result);
+				finishCssModuleConstants(this, cssModuleConstants, result);
 				if (result.kind === 'none') {
 					callback(null, source, this.sourceMap === false ? undefined : inputSourceMap);
 					return;
@@ -177,10 +195,10 @@ export default function octaneLoader(source, inputSourceMap) {
 			currentReference === null &&
 			typeof this.getResolve === 'function'
 		) {
-			const requests = compiler.findServerImportRequests(String(source), id);
+			const requests = compiler.findServerImportRequests(authoredSource, id);
 			if (requests.length > 0) {
 				const asyncCallback = this.async?.() ?? callback;
-				resolveClientOnlyImports(this, compiler, source, id).then(
+				resolveClientOnlyImports(this, compiler, authoredSource, id).then(
 					(imports) => finish(imports, asyncCallback),
 					(error) => asyncCallback(error instanceof Error ? error : new Error(String(error))),
 				);

package/src/parallel-loader.js

@@ -1,4 +1,5 @@
 import octaneLoader from './loader.js';
+import { CSS_MODULE_BUILD_INFO_KEY, CSS_MODULE_CONTEXT_KEY } from './css-module-data.js';
 
 /**
  * Run the unchanged public Octane loader inside Rspack's worker pool. Rspack
@@ -10,6 +11,7 @@ export default function parallelOctaneLoader(source, sourceMap) {
 	const module = this._module;
 	const finalizer = this.loaders[this.loaderIndex - 1];
 	module.layer = finalizer?.loaderItem?.data?.octaneLayer ?? undefined;
+	this[CSS_MODULE_CONTEXT_KEY] = finalizer?.loaderItem?.data?.[CSS_MODULE_CONTEXT_KEY] ?? undefined;
 
 	const callback = this.callback.bind(this);
 	const async = this.async.bind(this);
@@ -22,6 +24,9 @@ export default function parallelOctaneLoader(source, sourceMap) {
 			...(metadata ?? {}),
 			__octaneParallelLoader: {
 				buildInfo: module.buildInfo?.octane ?? null,
+				...(module.buildInfo?.[CSS_MODULE_BUILD_INFO_KEY] === undefined
+					? null
+					: { cssModuleBuildInfo: module.buildInfo[CSS_MODULE_BUILD_INFO_KEY] }),
 				missingDependencies,
 			},
 		});

package/src/plugin.js

@@ -1,13 +1,14 @@
 import { createHash } from 'node:crypto';
-import { realpathSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { isAbsolute, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
 	CLIENT_REFERENCE_MANIFEST_FILENAME,
 	createClientReferenceManifest,
 	createOctaneCompiler,
 } from 'octane/compiler/bundler';
+import { installCssModuleConstants } from './css-module-constants.js';
 import {
 	getOctaneRspackBuildInfo,
 	inferRspackEnvironment,
@@ -23,6 +24,12 @@ const parallelLoaderPath = fileURLToPath(new URL('./parallel-loader.js', import.
 const DEFAULT_MAX_WORKERS = 4;
 const OCTANE_RULE = /\.(?:tsrx|tsx|ts|js)$/i;
 const TYPESCRIPT_RULE = /\.(?:tsrx|tsx|ts)$/i;
+const RUNTIME_SUBPATHS = [
+	'octane/server',
+	'octane/internal/client',
+	'octane/internal/server',
+	'octane/profiling',
+];
 
 function realRoot(path) {
 	try {
@@ -40,10 +47,10 @@ function addUniqueExtensions(resolveOptions) {
 	];
 }
 
-function resolveRuntimeModule(request, root) {
+function resolveRuntimeModule(resolver, request, root) {
 	if (isAbsolute(request)) return request;
 	try {
-		return createRequire(join(root, 'package.json')).resolve(request);
+		return resolver.resolveSync({}, root, request);
 	} catch {
 		// Let Rspack produce its normal resolution diagnostic. This fallback also
 		// keeps config inspection usable before peer dependencies are installed.
@@ -51,18 +58,82 @@ function resolveRuntimeModule(request, root) {
 	}
 }
 
-function addRuntimeAlias(resolveOptions, request, root) {
-	const aliases = resolveOptions.alias === false ? {} : (resolveOptions.alias ?? {});
-	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 octanePackageRoot(entry) {
+	if (typeof entry !== 'string' || !isAbsolute(entry)) return undefined;
+	let directory = dirname(entry);
+	while (true) {
+		try {
+			const { name } = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8'));
+			if (name === 'octane') return directory;
+			if (name !== undefined) return undefined;
+		} catch {
+			// Entry files may be several directories below their package manifest.
+		}
+		const parent = dirname(directory);
+		if (parent === directory) return undefined;
+		directory = parent;
+	}
+}
+
+function mergeRuntimeAliases(aliases, additions) {
+	return {
+		...additions,
+		...(aliases === false ? {} : aliases),
+		octane$: additions.octane$,
 	};
 }
 
+function addRuntimeAliases(compiler, request, root, explicitRuntime) {
+	const resolveOptions = compiler.options.resolve;
+	// The factory is created before Rspack applies mode/target defaults. Merge
+	// the finalized ESM options (including `...`) before resolving; require
+	// conditions would select Octane's separate, non-tree-shakeable CJS graph.
+	const { byDependency, ...base } = resolveOptions;
+	const esm = compiler.webpack.util.cleverMerge(base, byDependency?.esm ?? {});
+	const resolver = compiler.resolverFactory.get('normal', { ...esm, dependencyType: 'esm' });
+	const packageResolver = compiler.resolverFactory.get('normal', {
+		...esm,
+		alias: false,
+		dependencyType: 'esm',
+	});
+	const selected = resolveRuntimeModule(resolver, 'octane', root);
+	const override = explicitRuntime ? resolveRuntimeModule(resolver, request, root) : undefined;
+	const packageRoot = octanePackageRoot(override) ?? octanePackageRoot(selected) ?? root;
+	const aliases = esm.alias === false ? {} : (esm.alias ?? {});
+	const additions = {};
+	for (const subpath of RUNTIME_SUBPATHS) {
+		// Resolve package self-references without a broad `octane` alias. Linked
+		// packages must share the selected runtime's refs, context, and profiler.
+		// A consumer's explicit subpath override remains authoritative.
+		additions[`${subpath}$`] =
+			aliases[`${subpath}$`] ??
+			aliases[subpath] ??
+			resolveRuntimeModule(packageResolver, subpath, packageRoot);
+	}
+	const runtime = explicitRuntime
+		? override
+		: request === 'octane' || selected === false
+			? selected
+			: (additions[`${request}$`] ?? resolveRuntimeModule(resolver, request, root));
+	additions.octane$ = runtime;
+	// Exact entries precede any existing prefix alias; unrelated Octane subpaths
+	// (including universal renderer entries) keep their normal resolution.
+	resolveOptions.alias = mergeRuntimeAliases(resolveOptions.alias, additions);
+	if (byDependency?.esm?.alias !== undefined && byDependency.esm.alias !== false) {
+		// Rspack applies this map again during module resolution. A package
+		// selection here must not restore its client entry in a server graph.
+		// Preserve `false`: it explicitly disables all aliases for ESM requests.
+		resolveOptions.byDependency = {
+			...byDependency,
+			esm: {
+				...byDependency.esm,
+				alias: mergeRuntimeAliases(byDependency.esm.alias, additions),
+			},
+		};
+	}
+	return resolver;
+}
+
 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
@@ -274,12 +345,20 @@ export class OctaneRspackPlugin {
 		);
 		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 hotModuleReplacement = hasHotModuleReplacement(compiler);
+		const hmr = environment === 'client' && hotModuleReplacement && this.options.hmr !== false;
 		const dev =
 			environment === 'client' &&
 			(this.options.dev ??
 				(compiler.options.mode === undefined || compiler.options.mode !== 'production'));
+		// Disabling Octane's own HMR wrapper does not make a hot CSS provider's
+		// exports immutable across replacement.
+		const cssModuleConstants =
+			this.options.cssModuleConstants !== undefined &&
+			this.options.cssModuleConstants !== false &&
+			compiler.options.mode === 'production' &&
+			!dev &&
+			!hotModuleReplacement;
 		assertProfilingDefineAvailable(compiler, profile);
 		saltPersistentCacheVersion(compiler, {
 			root,
@@ -297,8 +376,15 @@ export class OctaneRspackPlugin {
 			// transform results must not survive a requireDirective toggle.
 			requireDirective: this.options.requireDirective === true,
 			transpile: this.options.transpile !== false,
+			cssModuleConstants,
 		});
 		installProfilingDefine(compiler, profile);
+		if (cssModuleConstants) {
+			installCssModuleConstants(compiler, {
+				option: this.options.cssModuleConstants,
+				environment,
+			});
+		}
 		const neutralCompiler = createDiscoveryCompiler(this.options, root, profile);
 		const discoveryCompilers = [neutralCompiler];
 		for (const specialization of Object.values(this.options.layerSpecializations ?? {})) {
@@ -309,7 +395,6 @@ export class OctaneRspackPlugin {
 
 		compiler.options.resolve ??= {};
 		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);
@@ -364,17 +449,27 @@ export class OctaneRspackPlugin {
 				use: [{ loader: 'builtin:swc-loader', options: { detectSyntax: 'auto' } }],
 			});
 		}
+		const layerRuntimeAliases = [];
 		for (const [layer, specialization] of Object.entries(this.options.layerSpecializations ?? {})) {
 			if (specialization.runtime === undefined) continue;
+			const alias = { octane$: specialization.runtime };
+			layerRuntimeAliases.push([alias, specialization.runtime]);
 			compiler.options.module.rules.push({
 				issuerLayer: layer,
-				resolve: {
-					alias: {
-						octane$: resolveRuntimeModule(specialization.runtime, root),
-					},
-				},
+				resolve: { alias },
 			});
 		}
+		compiler.hooks.afterResolvers.tap(PLUGIN_NAME, () => {
+			const resolver = addRuntimeAliases(
+				compiler,
+				runtimeRequest,
+				root,
+				this.options.runtime !== undefined,
+			);
+			for (const [alias, request] of layerRuntimeAliases) {
+				alias.octane$ = resolveRuntimeModule(resolver, request, root);
+			}
+		});
 
 		let discovery;
 		const discover = () => {

package/src/shared.js

@@ -47,7 +47,13 @@ const LOADER_OPTION_KEYS = new Set([
 	'universalRuntime',
 	'layerSpecializations',
 ]);
-const PLUGIN_OPTION_KEYS = new Set([...LOADER_OPTION_KEYS, 'parallel', 'runtime', 'transpile']);
+const PLUGIN_OPTION_KEYS = new Set([
+	...LOADER_OPTION_KEYS,
+	'parallel',
+	'runtime',
+	'transpile',
+	'cssModuleConstants',
+]);
 const LAYER_SPECIALIZATION_KEYS = new Set(['runtime', 'renderers', 'universalRuntime']);
 
 function normalizeRuntimeRequest(value, label = 'runtime') {
@@ -210,6 +216,16 @@ function normalizeOptions(value, plugin) {
 		throw new TypeError('@octanejs/rspack-plugin: `exclude` must be an array of path strings.');
 	}
 	if (plugin) assertBooleanOption(options, 'transpile');
+	if (
+		plugin &&
+		options.cssModuleConstants !== undefined &&
+		typeof options.cssModuleConstants !== 'boolean' &&
+		typeof options.cssModuleConstants !== 'function'
+	) {
+		throw new TypeError(
+			'@octanejs/rspack-plugin: `cssModuleConstants` must be a boolean or a provider function.',
+		);
+	}
 	const parallel = plugin ? normalizeParallelOption(options.parallel) : undefined;
 	const renderers =
 		options.renderers === undefined ? undefined : normalizeRendererConfig(options.renderers);
@@ -233,6 +249,9 @@ function normalizeOptions(value, plugin) {
 		...(plugin && parallel !== undefined ? { parallel } : null),
 		...(plugin && options.transpile !== undefined ? { transpile: options.transpile } : null),
 		...(plugin && options.runtime !== undefined ? { runtime: options.runtime } : null),
+		...(plugin && options.cssModuleConstants !== undefined
+			? { cssModuleConstants: options.cssModuleConstants }
+			: null),
 	};
 	if (normalized.exclude) Object.freeze(normalized.exclude);
 	return Object.freeze(normalized);

package/types/index.d.ts

@@ -1,7 +1,29 @@
 import type { Compiler, RspackPluginInstance } from '@rspack/core';
+import type { OctaneCssModuleConstants } from 'octane/compiler';
+
+export type { OctaneCssModuleConstants } from 'octane/compiler';
 
 export type OctaneRspackEnvironment = 'client' | 'server';
 
+/** Exact JavaScript CSS-provider module from the current Rspack graph. */
+export interface OctaneRspackCssModuleConstantModule {
+	/** Full module identity, including its loader chain, resource query, and layer. */
+	readonly id: string;
+	/** The resolved NormalModule resource, including its query. */
+	readonly resource: string;
+	/** Completed loader output, inspected without evaluating the module. */
+	readonly code: string;
+	/** Provider metadata copied from the module's buildInfo. */
+	readonly meta: Readonly<Record<string, unknown>>;
+	readonly environment: OctaneRspackEnvironment;
+	readonly layer?: string;
+	readonly type: string;
+}
+
+export type OctaneRspackCssModuleConstantsProvider = (
+	module: OctaneRspackCssModuleConstantModule,
+) => OctaneCssModuleConstants | null | undefined;
+
 export interface OctaneRendererRuleOptions {
 	/** Glob or globs matched against canonical project-relative module IDs. */
 	include: string | readonly string[];
@@ -152,6 +174,18 @@ export interface OctaneRspackLoaderOptions {
 }
 
 export interface OctaneRspackPluginOptions extends OctaneRspackLoaderOptions {
+	/**
+	 * @experimental Fold proven CSS-module strings in one-shot production builds.
+	 * `true` accepts only pure, initialized named ESM string exports. A provider
+	 * may additionally authenticate immutable exports against the exact completed
+	 * loader source; ordinary mutable default maps are not constants. The provider
+	 * runs on the main thread, never in a loader worker. Malformed or stale facts
+	 * fail the build. Native `css/module`, development, HMR, and watch builds keep
+	 * their ordinary compilation. Eligible consumers are rebuilt once and are not
+	 * stored in Rspack's persistent module cache. Requires the class plugin.
+	 * @default false
+	 */
+	cssModuleConstants?: boolean | OctaneRspackCssModuleConstantsProvider;
 	/**
 	 * Compile Octane modules in Rspack worker threads. Enabled by default with
 	 * at most four workers; set `false` to keep compilation on the main thread.