@octanejs/rspack-plugin 0.1.49 → 0.1.51

package/package.json

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

package/src/loader.js

@@ -121,6 +121,9 @@ export default function octaneLoader(source, inputSourceMap) {
 			root,
 			profile,
 			...(options.strong === undefined ? null : { strong: options.strong }),
+			...(options.knownAttributeSpreads === undefined
+				? null
+				: { knownAttributeSpreads: options.knownAttributeSpreads }),
 			...(options.exclude === undefined ? null : { exclude: options.exclude }),
 			...(compilerOptions.renderers === undefined
 				? null
@@ -205,11 +208,16 @@ export default function octaneLoader(source, inputSourceMap) {
 				}
 				setBuildInfo(this._module, {
 					canonicalId: canonicalModuleId(id, root),
+					resourceQuery: id.slice(cleanModuleId(id).length),
 					transformKind: result.kind,
+					...(result.streamedSignals === true ? { streamedSignals: true } : null),
 					serverRpc:
 						result.kind === 'compile' &&
 						(result.code.includes('_$__serverRpc(') ||
 							result.code.includes('export const _$_server_$_')),
+					...(Array.isArray(result.independentWidgets) && result.independentWidgets.length > 0
+						? { independentWidgets: result.independentWidgets }
+						: null),
 					...(result.universalRuntime === undefined
 						? null
 						: { universalRuntime: result.universalRuntime }),

package/src/plugin.js

@@ -5,10 +5,12 @@ import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
 	CLIENT_REFERENCE_MANIFEST_FILENAME,
+	INDEPENDENT_HYDRATION_MANIFEST_FILENAME,
 	createClientReferenceManifest,
 	createOctaneCompiler,
 } from 'octane/compiler/bundler';
 import { installCssModuleConstants } from './css-module-constants.js';
+import { createStreamedSignalHmrRuntimeModule } from './streamed-signals-hmr.js';
 import {
 	getOctaneRspackBuildInfo,
 	inferRspackEnvironment,
@@ -182,6 +184,9 @@ function createDiscoveryCompiler(options, root, profile, specialization) {
 		root,
 		profile,
 		...(options.strong === undefined ? null : { strong: options.strong }),
+		...(options.knownAttributeSpreads === undefined
+			? null
+			: { knownAttributeSpreads: options.knownAttributeSpreads }),
 		...(options.exclude === undefined ? null : { exclude: options.exclude }),
 		...(renderers === undefined ? null : { renderers }),
 		...(universalRuntime === undefined ? null : { universalRuntime }),
@@ -234,16 +239,17 @@ function visitClientReferenceModules(
 	inheritedChunks,
 	visit,
 	seen = new Set(),
+	executableModule = module,
 ) {
 	if (!module || seen.has(module)) return;
 	seen.add(module);
 	const chunks = moduleChunks(compilation, module, inheritedChunks);
-	visit(module, chunks);
+	visit(module, chunks, executableModule);
 	for (const child of iterable(module.modules)) {
-		visitClientReferenceModules(compilation, child, chunks, visit, seen);
+		visitClientReferenceModules(compilation, child, chunks, visit, seen, module);
 	}
 	if (module.rootModule) {
-		visitClientReferenceModules(compilation, module.rootModule, chunks, visit, seen);
+		visitClientReferenceModules(compilation, module.rootModule, chunks, visit, seen, module);
 	}
 }
 
@@ -279,6 +285,158 @@ function emitClientReferenceManifest(compiler, compilation) {
 	);
 }
 
+function emitIndependentHydrationManifest(compiler, compilation, mode) {
+	const modules = collectIndependentHydrationModules(compilation);
+	const widgets = {};
+	for (const { template, target } of independentHydrationTargets(modules)) {
+		const activationChunks = new Set(target.chunks);
+		for (const chunk of target.chunks) {
+			for (const referenced of iterable(chunk?.getAllReferencedChunks?.())) {
+				activationChunks.add(referenced);
+			}
+		}
+		const files = [...activationChunks]
+			.flatMap((chunk) => [...iterable(chunk.files), ...iterable(chunk.auxiliaryFiles)])
+			.map(String);
+		widgets[template.boundaryId] = {
+			version: 1,
+			boundaryId: template.boundaryId,
+			// Rspack chunks are runtime payloads, not native module namespaces. The
+			// initial runtime module below owns the actual chunk-load + require closure.
+			moduleId: template.boundaryId,
+			exportName: template.exportName,
+			captureSchema: template.captureSchema,
+			hookSeed: template.hookSeed,
+			idSeed: template.idSeed,
+			signalSites: template.signalSites,
+			styles: [...new Set(files.filter((file) => /\.css(?:\?|$)/.test(file)))].sort(),
+			parentDependencies: false,
+		};
+	}
+	const records = Object.fromEntries(
+		Object.entries(widgets).sort(([left], [right]) => left.localeCompare(right)),
+	);
+	// Match the native __webpack_hash__ value captured by the executing entry.
+	// A widget-schema hash does not fence changes elsewhere in its client graph.
+	const buildId = compilation.hash;
+	if (typeof buildId !== 'string' || !buildId) {
+		throw new Error('Octane client build has no completed compilation hash.');
+	}
+	const independentHydration = Object.keys(records).length !== 0;
+	compilation.emitAsset(
+		'octane-client-build.json',
+		new compiler.webpack.sources.RawSource(
+			JSON.stringify(
+				{ version: 1, buildId, mode, capabilities: { independentHydration } },
+				null,
+				2,
+			) + '\n',
+		),
+	);
+	if (!independentHydration) return;
+	compilation.emitAsset(
+		INDEPENDENT_HYDRATION_MANIFEST_FILENAME,
+		new compiler.webpack.sources.RawSource(
+			JSON.stringify({ version: 1, buildId, widgets: records }, null, 2) + '\n',
+		),
+	);
+}
+
+function collectIndependentHydrationModules(compilation) {
+	const modules = [];
+	for (const topLevelModule of iterable(compilation.modules)) {
+		visitClientReferenceModules(
+			compilation,
+			topLevelModule,
+			[],
+			(module, chunks, executableModule) => {
+				const info = getOctaneRspackBuildInfo(module);
+				if (info !== null) modules.push({ module, executableModule, info, chunks });
+			},
+			new Set(),
+		);
+	}
+	return modules;
+}
+
+function independentHydrationTargets(modules) {
+	const targets = [];
+	for (const { info } of modules) {
+		for (const template of info.independentWidgets ?? []) {
+			const query = template.request.slice(template.request.indexOf('?'));
+			const candidates = modules.filter(
+				(candidate) =>
+					candidate.info.canonicalId === template.moduleId &&
+					candidate.info.resourceQuery?.includes(query),
+			);
+			const target =
+				candidates.find(
+					(candidate) =>
+						candidate.executableModule != null && candidate.executableModule !== candidate.module,
+				) ?? candidates[0];
+			if (target === undefined) {
+				throw new Error(
+					`Octane independent Hydrate ${JSON.stringify(template.boundaryId)} has no emitted activation chunk.`,
+				);
+			}
+			targets.push({ template, target });
+		}
+	}
+	return targets;
+}
+
+function independentHydrationRuntimeModule(compiler, compilation) {
+	const { RuntimeGlobals, RuntimeModule } = compiler.webpack;
+	return class OctaneIndependentHydrationRuntimeModule extends RuntimeModule {
+		constructor() {
+			super('octane independent hydration loaders');
+			this.fullHash = true;
+		}
+
+		generate() {
+			const registrations = [];
+			const seen = new Set();
+			for (const { template, target } of independentHydrationTargets(
+				collectIndependentHydrationModules(compilation),
+			)) {
+				if (seen.has(template.boundaryId)) continue;
+				seen.add(template.boundaryId);
+				const candidates = [target.executableModule, target.module, target.module?.rootModule];
+				const executable = candidates.find(
+					(module) => module != null && compilation.chunkGraph.getModuleId(module) != null,
+				);
+				if (executable === undefined) {
+					throw new Error(
+						`Octane independent Hydrate ${JSON.stringify(template.boundaryId)} has no executable Rspack module.`,
+					);
+				}
+				const moduleId = compilation.chunkGraph.getModuleId(executable);
+				const activationChunks = new Set(target.chunks);
+				for (const chunk of target.chunks) {
+					for (const referenced of iterable(chunk?.getAllReferencedChunks?.())) {
+						activationChunks.add(referenced);
+					}
+				}
+				const chunkIds = [...activationChunks]
+					.filter((chunk) => chunk !== this.chunk && chunk?.id != null)
+					.map((chunk) => chunk.id)
+					.sort((left, right) => String(left).localeCompare(String(right)));
+				const load =
+					chunkIds.length === 0
+						? 'Promise.resolve()'
+						: `Promise.all(${JSON.stringify(chunkIds)}.map(${RuntimeGlobals.ensureChunk}))`;
+				registrations.push(
+					`${RuntimeGlobals.global}.__OCTANE_INDEPENDENT_MODULES__[${JSON.stringify(template.boundaryId)}] = function() { return ${load}.then(function() { return ${RuntimeGlobals.require}(${JSON.stringify(moduleId)}); }); };`,
+				);
+			}
+			return [
+				`${RuntimeGlobals.global}.__OCTANE_INDEPENDENT_MODULES__ ||= Object.create(null);`,
+				...registrations,
+			].join('\n');
+		}
+	};
+}
+
 function defineMatchesBoolean(value, expected) {
 	return value === expected || value === JSON.stringify(expected);
 }
@@ -382,6 +540,7 @@ export class OctaneRspackPlugin {
 			dev,
 			profile,
 			strong: this.options.strong === true,
+			knownAttributeSpreads: this.options.knownAttributeSpreads,
 			exclude: this.options.exclude ?? [],
 			renderers: this.options.renderers?.signature,
 			runtime: this.options.runtime,
@@ -429,6 +588,9 @@ export class OctaneRspackPlugin {
 			environment,
 			profile,
 			...(this.options.strong === undefined ? null : { strong: this.options.strong }),
+			...(this.options.knownAttributeSpreads === undefined
+				? null
+				: { knownAttributeSpreads: this.options.knownAttributeSpreads }),
 			...(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 }),
@@ -515,12 +677,56 @@ export class OctaneRspackPlugin {
 			addDependencies(compilation.fileDependencies, current.dependencies);
 			addDependencies(compilation.missingDependencies, current.missingDependencies);
 			if (environment === 'client') {
+				const IndependentHydrationRuntimeModule = independentHydrationRuntimeModule(
+					compiler,
+					compilation,
+				);
+				compilation.hooks.additionalTreeRuntimeRequirements?.tap(
+					PLUGIN_NAME,
+					(chunk, runtimeRequirements) => {
+						if (!chunk.hasRuntime?.()) return;
+						const modules = collectIndependentHydrationModules(compilation);
+						const featureModules = modules.filter(
+							({ info }) =>
+								info.streamedSignals === true || (info.independentWidgets?.length ?? 0) > 0,
+						);
+						if (
+							featureModules.length > 0 &&
+							compiler.options.plugins.some(
+								(plugin) => plugin instanceof compiler.webpack.HotModuleReplacementPlugin,
+							)
+						) {
+							runtimeRequirements.add(compiler.webpack.RuntimeGlobals.interceptModuleExecution);
+							runtimeRequirements.add(compiler.webpack.RuntimeGlobals.moduleCache);
+							runtimeRequirements.add(compiler.webpack.RuntimeGlobals.global);
+							compilation.addRuntimeModule(
+								chunk,
+								createStreamedSignalHmrRuntimeModule(compiler, compilation, featureModules),
+							);
+						}
+						if (independentHydrationTargets(modules).length === 0) {
+							return;
+						}
+						runtimeRequirements.add(compiler.webpack.RuntimeGlobals.ensureChunk);
+						runtimeRequirements.add(compiler.webpack.RuntimeGlobals.global);
+						runtimeRequirements.add(compiler.webpack.RuntimeGlobals.require);
+						compilation.addRuntimeModule(chunk, new IndependentHydrationRuntimeModule());
+					},
+				);
 				compilation.hooks.processAssets.tap(
 					{
 						name: PLUGIN_NAME,
 						stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_REPORT,
 					},
-					() => emitClientReferenceManifest(compiler, compilation),
+					() => {
+						emitClientReferenceManifest(compiler, compilation);
+						emitIndependentHydrationManifest(
+							compiler,
+							compilation,
+							this.options.clientBuildMode ??
+								(compiler.options.mode === 'development' ? 'development' : 'production'),
+						);
+					},
 				);
 			}
 		});

package/src/shared.js

@@ -41,6 +41,7 @@ const LOADER_OPTION_KEYS = new Set([
 	'dev',
 	'profile',
 	'strong',
+	'knownAttributeSpreads',
 	'exclude',
 	'renderers',
 	'requireDirective',
@@ -54,6 +55,7 @@ const PLUGIN_OPTION_KEYS = new Set([
 	'runtime',
 	'transpile',
 	'cssModuleConstants',
+	'clientBuildMode',
 ]);
 const LAYER_SPECIALIZATION_KEYS = new Set(['runtime', 'renderers', 'universalRuntime']);
 
@@ -198,6 +200,16 @@ function normalizeOptions(value, plugin) {
 		throw new TypeError('@octanejs/rspack-plugin: `root` must be a path string.');
 	}
 	if (plugin) normalizeRuntimeRequest(options.runtime);
+	if (
+		plugin &&
+		options.clientBuildMode !== undefined &&
+		options.clientBuildMode !== 'production' &&
+		options.clientBuildMode !== 'development'
+	) {
+		throw new TypeError(
+			'@octanejs/rspack-plugin: `clientBuildMode` must be "production" or "development".',
+		);
+	}
 	if (
 		options.environment !== undefined &&
 		options.environment !== 'client' &&
@@ -255,6 +267,9 @@ 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.knownAttributeSpreads === undefined
+			? null
+			: { knownAttributeSpreads: options.knownAttributeSpreads }),
 		...(options.exclude === undefined ? null : { exclude: [...options.exclude] }),
 		...(renderers === undefined ? null : { renderers }),
 		...(universalRuntime === undefined ? null : { universalRuntime }),
@@ -266,6 +281,9 @@ function normalizeOptions(value, plugin) {
 			? null
 			: { textTypes: Object.freeze({ tsconfig: options.textTypes.tsconfig }) }),
 		...(plugin && parallel !== undefined ? { parallel } : null),
+		...(plugin && options.clientBuildMode !== undefined
+			? { clientBuildMode: options.clientBuildMode }
+			: null),
 		...(plugin && options.transpile !== undefined ? { transpile: options.transpile } : null),
 		...(plugin && options.runtime !== undefined ? { runtime: options.runtime } : null),
 		...(plugin && options.cssModuleConstants !== undefined
@@ -307,6 +325,8 @@ export function getOctaneRspackBuildInfo(module) {
 			value.transformKind === 'slots' ||
 			value.transformKind === 'client-only-stub') &&
 		typeof value.serverRpc === 'boolean' &&
+		(value.resourceQuery === undefined || typeof value.resourceQuery === 'string') &&
+		(value.independentWidgets === undefined || Array.isArray(value.independentWidgets)) &&
 		(value.clientReference === undefined || nestedReferenceValid) &&
 		(value.universalRuntime === undefined || universalRuntimeValid)
 	) {

package/src/streamed-signals-hmr.js

@@ -0,0 +1,59 @@
+/**
+ * Fence feature-bearing documents through Rspack's native module-execution
+ * interceptor, before authored factories run. No compiled source is rewritten.
+ * @param {import('@rspack/core').Compiler} compiler
+ * @param {import('@rspack/core').Compilation} compilation
+ * @param {Array<{ module: import('@rspack/core').Module, executableModule?: import('@rspack/core').Module }>} modules
+ */
+export function createStreamedSignalHmrRuntimeModule(compiler, compilation, modules) {
+	const { RuntimeGlobals, RuntimeModule } = compiler.webpack;
+	return new (class extends RuntimeModule {
+		constructor() {
+			super('octane streamed signal HMR fence', RuntimeModule.STAGE_TRIGGER);
+		}
+
+		generate() {
+			const ids = new Set();
+			for (const { module, executableModule } of modules) {
+				for (const candidate of [executableModule, module, module?.rootModule]) {
+					const id = candidate == null ? null : compilation.chunkGraph.getModuleId(candidate);
+					if (id != null) {
+						ids.add(String(id));
+						break;
+					}
+				}
+			}
+			return `
+var octaneSignalModules = new Set(${JSON.stringify([...ids].sort())});
+var octaneSignalFenceInstalled = false;
+var octaneSignalGenerationChanged = false;
+var octaneSignalModuleExecuted = false;
+function octaneReloadSignalDocument() {
+  ${RuntimeGlobals.global}.location?.reload?.();
+  throw new Error('[octane] The streamed signal client build changed. Reload this document.');
+}
+function octaneTrackSignalGeneration(hot) {
+  if (!hot || octaneSignalFenceInstalled) return;
+  octaneSignalFenceInstalled = true;
+  if (hot.status() !== 'idle') octaneSignalGenerationChanged = true;
+  hot.addStatusHandler(function(status) {
+    if (status === 'apply') octaneSignalGenerationChanged = true;
+    if (octaneSignalModuleExecuted && (status === 'check' || status === 'dispose' || status === 'apply')) octaneReloadSignalDocument();
+  });
+}
+// A newly introduced runtime may itself arrive during hot application. The
+// entry's cached hot module supplies that state before any feature executes.
+for (var octaneCachedId in ${RuntimeGlobals.moduleCache}) {
+  octaneTrackSignalGeneration(${RuntimeGlobals.moduleCache}[octaneCachedId].hot);
+  if (octaneSignalFenceInstalled) break;
+}
+${RuntimeGlobals.interceptModuleExecution}.push(function(options) {
+  var hot = options.module.hot;
+  octaneTrackSignalGeneration(hot);
+  if (!hot || !octaneSignalModules.has(String(options.id))) return;
+  if (octaneSignalGenerationChanged || hot.status() !== 'idle') octaneReloadSignalDocument();
+  octaneSignalModuleExecuted = true;
+});`;
+		}
+	})();
+}

package/types/index.d.ts

@@ -1,5 +1,5 @@
 import type { Compiler, RspackPluginInstance } from '@rspack/core';
-import type { OctaneCssModuleConstants } from 'octane/compiler';
+import type { KnownAttributeSpread, OctaneCssModuleConstants } from 'octane/compiler';
 
 export type { OctaneCssModuleConstants } from 'octane/compiler';
 
@@ -144,6 +144,8 @@ export interface OctaneRspackLoaderOptions {
 	 * @default false
 	 */
 	strong?: boolean;
+	/** Fixed native-attribute shapes for trusted imported spread helpers. */
+	knownAttributeSpreads?: readonly KnownAttributeSpread[];
 	/**
 	 * Path fragments excluded from the plain `.ts`/`.js` hook-slot pass. With
 	 * `requireDirective`, excluded paths are exempt from Octane ownership
@@ -175,6 +177,8 @@ export interface OctaneRspackLoaderOptions {
 }
 
 export interface OctaneRspackPluginOptions extends OctaneRspackLoaderOptions {
+	/** Build intent for SSR metadata; independent of optimization/HMR settings. */
+	clientBuildMode?: 'production' | 'development';
 	/**
 	 * @experimental Prove primitive DOM text children from the TypeScript project
 	 * in one-shot production builds. Relative paths resolve from the plugin root.
@@ -226,8 +230,25 @@ export interface OctaneRspackPluginOptions extends OctaneRspackLoaderOptions {
 
 export interface OctaneRspackBuildInfo {
 	canonicalId: string;
+	/** Resource query retained separately from the canonical source identity. */
+	resourceQuery?: string;
 	transformKind: 'compile' | 'slots' | 'client-only-stub';
+	streamedSignals?: true;
 	serverRpc: boolean;
+	/** Strict-independent Hydrate templates completed into the emitted client manifest. */
+	independentWidgets?: readonly {
+		readonly version: 1;
+		readonly boundaryId: string;
+		readonly moduleId: string;
+		readonly exportName: string;
+		readonly request: string;
+		readonly captureSchema: readonly { readonly name: string; readonly type: 'json' }[];
+		readonly hookSeed: number;
+		readonly idSeed: number;
+		readonly signalSites: readonly string[];
+		readonly styles: readonly string[];
+		readonly parentDependencies: false;
+	}[];
 	/** Universal host runtime/thread identity, when this module was specialized. */
 	universalRuntime?: OctaneUniversalRuntimeOptions;
 	/** Stable identity shared by the client compile and its inert server stub. */