@octanejs/rsbuild-plugin 0.1.48 → 0.1.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/rsbuild-plugin",
-  "version": "0.1.48",
+  "version": "0.1.50",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -48,12 +48,12 @@
     }
   },
   "dependencies": {
-    "@octanejs/app-core": "0.0.49",
-    "@octanejs/rspack-plugin": "0.1.48"
+    "@octanejs/app-core": "0.0.51",
+    "@octanejs/rspack-plugin": "0.1.50"
   },
   "peerDependencies": {
     "@rsbuild/core": "^2.0.0",
-    "octane": "^0.1.51 || ^0.2.0"
+    "octane": "^0.2.13"
   },
   "devDependencies": {
     "@rsbuild/core": "^2.1.6",
@@ -62,6 +62,6 @@
     "@types/node": "^24.13.3",
     "playwright": "^1.61.1",
     "vitest": "^4.1.10",
-    "octane": "0.2.4"
+    "octane": "0.2.13"
   }
 }

package/src/build.js

@@ -10,6 +10,8 @@ import path from 'node:path';
  *   root: string,
  *   config: import('@octanejs/app-core').ResolvedOctaneConfig,
  *   assetMapFilename?: string,
+ *   clientBuildFilename?: string,
+ *   independentHydrationManifestFilename?: string,
  *   log?: (message: string) => void,
  * }} options
  */
@@ -19,11 +21,18 @@ export async function finalizeOctaneRsbuildOutput(options) {
 	const clientDir = path.resolve(root, outDir, 'client');
 	const serverDir = path.resolve(root, outDir, 'server');
 	const assetMapFilename = options.assetMapFilename ?? 'octane-client-assets.json';
+	const clientBuildFilename = options.clientBuildFilename ?? 'octane-client-build.json';
+	const independentHydrationManifestFilename =
+		options.independentHydrationManifestFilename ?? 'octane-independent-hydration.json';
 	const log = options.log ?? (() => {});
 	const clientHtml = path.join(clientDir, 'index.html');
 	const serverHtml = path.join(serverDir, 'index.html');
 	const clientAssetMap = path.join(clientDir, assetMapFilename);
 	const serverAssetMap = path.join(serverDir, assetMapFilename);
+	const clientBuildPath = path.join(clientDir, clientBuildFilename);
+	const serverBuildPath = path.join(serverDir, clientBuildFilename);
+	const clientIndependentHydration = path.join(clientDir, independentHydrationManifestFilename);
+	const serverIndependentHydration = path.join(serverDir, independentHydrationManifestFilename);
 	const serverEntry = path.join(serverDir, 'entry.js');
 
 	if (!fs.existsSync(clientHtml)) {
@@ -37,12 +46,45 @@ export async function finalizeOctaneRsbuildOutput(options) {
 	if (!fs.existsSync(serverEntry)) {
 		throw new Error(`[@octanejs/rsbuild-plugin] Server entry was not emitted at ${serverEntry}.`);
 	}
+	if (!fs.existsSync(clientBuildPath)) {
+		throw new Error(
+			`[@octanejs/rsbuild-plugin] Client build metadata was not emitted at ${clientBuildPath}.`,
+		);
+	}
+	const clientBuild = JSON.parse(fs.readFileSync(clientBuildPath, 'utf8'));
+	if (
+		clientBuild?.version !== 1 ||
+		typeof clientBuild.buildId !== 'string' ||
+		!clientBuild.buildId ||
+		clientBuild.mode !== 'production' ||
+		typeof clientBuild.capabilities?.independentHydration !== 'boolean'
+	) {
+		throw new Error('[@octanejs/rsbuild-plugin] Invalid production client build metadata.');
+	}
+	if (fs.existsSync(clientIndependentHydration)) {
+		const widgets = JSON.parse(fs.readFileSync(clientIndependentHydration, 'utf8'));
+		if (widgets.buildId !== clientBuild.buildId) {
+			throw new Error(
+				'[@octanejs/rsbuild-plugin] Independent hydration and client build metadata disagree.',
+			);
+		}
+	} else if (clientBuild.capabilities.independentHydration) {
+		throw new Error(
+			'[@octanejs/rsbuild-plugin] Client build is missing independent hydration metadata.',
+		);
+	}
 
 	fs.mkdirSync(serverDir, { recursive: true });
 	fs.rmSync(serverHtml, { force: true });
 	fs.rmSync(serverAssetMap, { force: true });
+	fs.rmSync(serverBuildPath, { force: true });
 	fs.renameSync(clientHtml, serverHtml);
 	fs.renameSync(clientAssetMap, serverAssetMap);
+	fs.renameSync(clientBuildPath, serverBuildPath);
+	fs.rmSync(serverIndependentHydration, { force: true });
+	if (fs.existsSync(clientIndependentHydration)) {
+		fs.renameSync(clientIndependentHydration, serverIndependentHydration);
+	}
 
 	log(`Server build complete: ${path.relative(root, serverEntry)}`);
 	if (options.config.adapter?.serverTarget !== 'webworker') {

package/src/dev-server.js

@@ -5,6 +5,8 @@ import { nodeRequestToWebRequest, sendWebResponse } from '@octanejs/app-core/nod
 
 import { isRsbuildOwnedUrl } from './html.js';
 
+const INDEPENDENT_HYDRATION_MANIFEST_FILENAME = 'octane-independent-hydration.json';
+
 /**
  * @typedef {{
  *   manifest: import('@octanejs/app-core/production').ServerManifest,
@@ -27,6 +29,35 @@ function collectAssetPaths(stats) {
 	return paths;
 }
 
+/** @param {import('@rspack/core').Stats} stats */
+function readIndependentHydrationManifest(stats) {
+	const asset = stats.compilation.getAsset?.(INDEPENDENT_HYDRATION_MANIFEST_FILENAME);
+	if (!asset) return null;
+	const source = asset.source.source();
+	return JSON.parse(typeof source === 'string' ? source : Buffer.from(source).toString('utf8'));
+}
+
+/** @param {import('@rspack/core').Stats} stats */
+function readClientBuild(stats) {
+	const asset = stats.compilation.getAsset?.('octane-client-build.json');
+	if (!asset) throw new Error('The Octane client build metadata is missing.');
+	const source = asset.source.source();
+	const metadata = JSON.parse(
+		typeof source === 'string' ? source : Buffer.from(source).toString('utf8'),
+	);
+	if (
+		metadata?.version !== 1 ||
+		metadata.buildId !== stats.hash ||
+		metadata.mode !== 'development' ||
+		typeof metadata.capabilities?.independentHydration !== 'boolean'
+	) {
+		throw new Error(
+			'The Octane client build metadata is incompatible with this development compilation.',
+		);
+	}
+	return metadata;
+}
+
 /**
  * Create the early Connect middleware used by the Rsbuild Environment API.
  * Asset/internal requests fall through to Rsbuild; matched app/RPC requests
@@ -54,7 +85,7 @@ export function createOctaneDevMiddleware(options) {
 
 	let assetHash = '';
 	let assetPaths = new Set();
-	/** @type {WeakMap<object, { html: string, handler: (request: Request) => Promise<Response> }>} */
+	/** @type {WeakMap<object, { html: string, assetHash: string, handler: (request: Request) => Promise<Response> }>} */
 	const handlerCache = new WeakMap();
 
 	return async function octaneDevMiddleware(request, response, next) {
@@ -69,6 +100,7 @@ export function createOctaneDevMiddleware(options) {
 				return;
 			}
 			const clientStats = await clientApi.getStats();
+			if (clientStats.hasErrors()) throw new Error('The Octane client compilation failed.');
 			if (clientStats.hash !== assetHash) {
 				assetHash = clientStats.hash ?? '';
 				assetPaths = collectAssetPaths(clientStats);
@@ -92,13 +124,24 @@ export function createOctaneDevMiddleware(options) {
 
 			const html = await clientApi.getTransformedHtml(options.clientEntry);
 			let cached = handlerCache.get(typedBundle.manifest);
-			if (!cached || cached.html !== html) {
+			if (!cached || cached.html !== html || cached.assetHash !== assetHash) {
+				const independentHydration = readIndependentHydrationManifest(clientStats);
+				const clientBuild = readClientBuild(clientStats);
+				if (independentHydration !== null && independentHydration.buildId !== clientBuild.buildId) {
+					throw new Error(
+						'The Octane independent widget metadata belongs to another client build.',
+					);
+				}
 				cached = {
 					html,
-					handler: createHandler(typedBundle.manifest, {
-						...typedBundle.rendererDeps,
-						htmlTemplate: html,
-					}),
+					assetHash,
+					handler: createHandler(
+						{ ...typedBundle.manifest, independentHydration, clientBuild },
+						{
+							...typedBundle.rendererDeps,
+							htmlTemplate: html,
+						},
+					),
 				};
 				handlerCache.set(typedBundle.manifest, cached);
 			}

package/src/html.js

@@ -9,6 +9,42 @@ function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/**
+ * A classic bootstrap can run after the streamed shell only if its native
+ * entrypoint needs no deferred prerequisite and starts no other entry module.
+ * Keep the bundler's runtime/chunk ownership intact; reject unsafe overrides.
+ *
+ * @param {import('@rspack/core').Compilation} compilation
+ * @param {string} name
+ * @param {string} clientEntry
+ */
+export function assertEarlyHydrationEntry(compilation, name, clientEntry) {
+	const entrypoint = compilation.entrypoints.get(name);
+	const chunk = entrypoint?.getEntrypointChunk();
+	const files = entrypoint?.getFiles().filter((file) => /\.m?js(?:\?.*)?$/.test(file)) ?? [];
+	if (!chunk || files.length !== 1 || !chunk.files.has(files[0])) {
+		throw new Error(
+			'Octane early hydration requires one self-contained entry script. ' +
+				'Do not extract its runtime or initial JavaScript dependencies into deferred chunks.',
+		);
+	}
+	const entries = [...compilation.chunkGraph.getChunkEntryModulesIterable(chunk)];
+	const entry = entries[0];
+	const root = entry && 'rootModule' in entry ? (entry.rootModule ?? entry) : entry;
+	const resource =
+		root && typeof root === 'object' && 'resource' in root ? root.resource : undefined;
+	if (
+		entries.length !== 1 ||
+		typeof resource !== 'string' ||
+		fs.realpathSync(resource.split('?', 1)[0]) !== fs.realpathSync(clientEntry)
+	) {
+		throw new Error(
+			'Octane early hydration must own its entry module exclusively. ' +
+				'Keep user entries and pre-entry scripts separate from the generated hydration entry.',
+		);
+	}
+}
+
 /**
  * Rsbuild has already injected the web entry by the time `modifyHTML` runs.
  * Mark the concrete generated tag so the shared production runtime can add a

package/src/index.js

@@ -25,12 +25,15 @@ import {
 	write_project_generated_file,
 } from '@octanejs/app-core/codegen';
 import { OctaneRspackPlugin } from '@octanejs/rspack-plugin';
-import { createOctaneCompiler } from 'octane/compiler/bundler';
+import {
+	INDEPENDENT_HYDRATION_MANIFEST_FILENAME,
+	createOctaneCompiler,
+} from 'octane/compiler/bundler';
 
 import { finalizeOctaneRsbuildOutput } from './build.js';
 import { OctaneClientAssetsPlugin } from './client-assets-plugin.js';
 import { createOctaneDevMiddleware } from './dev-server.js';
-import { markHydrationEntry } from './html.js';
+import { assertEarlyHydrationEntry, markHydrationEntry } from './html.js';
 import {
 	collectClientEntries,
 	discoverServerModules,
@@ -135,9 +138,8 @@ function hasRoutes(config) {
 /**
  * @param {import('@octanejs/app-core').ResolvedOctaneConfig} config
  * @param {boolean | undefined} strongOverride
- * @param {boolean | undefined} nativeReadsOverride
  */
-function configSignature(config, strongOverride, nativeReadsOverride) {
+function configSignature(config, strongOverride) {
 	return JSON.stringify({
 		build: config.build,
 		routes: config.router.routes.map((route) =>
@@ -157,7 +159,6 @@ function configSignature(config, strongOverride, nativeReadsOverride) {
 		compiler: {
 			renderers: config.compiler.renderers.signature,
 			strong: strongOverride ?? config.compiler.strong,
-			nativeReads: nativeReadsOverride ?? config.compiler.nativeReads,
 		},
 	});
 }
@@ -237,9 +238,9 @@ function assertRootPublicPaths(config, clientEnvironment) {
  *   hmr?: boolean,
  *   parallel?: boolean | { maxWorkers?: number },
  *   cssModuleConstants?: import('@octanejs/rspack-plugin').OctaneRspackPluginOptions['cssModuleConstants'],
+ *   textTypes?: import('@octanejs/rspack-plugin').OctaneRspackPluginOptions['textTypes'],
  *   profile?: boolean,
  *   strong?: boolean,
- *   nativeReads?: boolean,
  *   exclude?: string[],
  *   requireDirective?: boolean,
  *   clientEnvironment?: string,
@@ -248,9 +249,6 @@ function assertRootPublicPaths(config, clientEnvironment) {
  * @returns {import('@rsbuild/core').RsbuildPlugin}
  */
 export function pluginOctane(inlineOptions = {}) {
-	if (inlineOptions.nativeReads !== undefined && typeof inlineOptions.nativeReads !== 'boolean') {
-		throw new TypeError('[@octanejs/rsbuild-plugin] nativeReads must be a boolean.');
-	}
 	if (inlineOptions.strong !== undefined && typeof inlineOptions.strong !== 'boolean') {
 		throw new TypeError('[@octanejs/rsbuild-plugin] `strong` must be a boolean.');
 	}
@@ -272,7 +270,6 @@ export function pluginOctane(inlineOptions = {}) {
 				: null;
 			const initialConfig = initialLoaded?.config ?? null;
 			const strong = inlineOptions.strong ?? initialConfig?.compiler.strong;
-			const nativeReads = inlineOptions.nativeReads ?? initialConfig?.compiler.nativeReads;
 			const appEnabled = hasRoutes(initialConfig);
 			const buildTargetPlan =
 				initialConfig?.build.target === undefined
@@ -282,12 +279,11 @@ export function pluginOctane(inlineOptions = {}) {
 				? createOctaneCompiler({
 						root,
 						...(strong === undefined ? null : { strong }),
-						...(nativeReads === undefined ? null : { nativeReads }),
 					})
 				: null;
 			let currentConfig = initialConfig;
 			let lastConfigSignature = initialLoaded
-				? configSignature(initialLoaded.config, inlineOptions.strong, inlineOptions.nativeReads)
+				? configSignature(initialLoaded.config, inlineOptions.strong)
 				: '';
 			let configNeedsReload = false;
 			/** @type {import('@rsbuild/core').RsbuildDevServer | null} */
@@ -335,11 +331,7 @@ export function pluginOctane(inlineOptions = {}) {
 					throw error;
 				}
 				registerConfigDependencies(context, loaded);
-				const signature = configSignature(
-					loaded.config,
-					inlineOptions.strong,
-					inlineOptions.nativeReads,
-				);
+				const signature = configSignature(loaded.config, inlineOptions.strong);
 				if (lastConfigSignature && signature !== lastConfigSignature) configNeedsReload = true;
 				lastConfigSignature = signature;
 				currentConfig = loaded.config;
@@ -408,6 +400,18 @@ export function pluginOctane(inlineOptions = {}) {
 					server: { htmlFallback: false, historyApiFallback: false },
 					environments: {
 						[clientEnvironment]: {
+							// Keep the generated bootstrap self-contained by default, including
+							// downlevel helpers. Explicit splitting remains subject to the
+							// emitted-entry ownership check instead of being silently replaced.
+							...(watchedConfig.splitChunks !== false &&
+							Object.keys(watchedConfig.splitChunks ?? {}).length === 0 &&
+							watchedConfig.environments?.[clientEnvironment]?.splitChunks !== false &&
+							Object.keys(watchedConfig.environments?.[clientEnvironment]?.splitChunks ?? {})
+								.length === 0 &&
+							watchedConfig.performance?.chunkSplit === undefined &&
+							watchedConfig.environments?.[clientEnvironment]?.performance?.chunkSplit === undefined
+								? { splitChunks: { chunks: 'async' } }
+								: {}),
 							...targetConfig,
 							source: { entry: { [CLIENT_ENTRY_NAME]: clientEntryFile } },
 							html: { template },
@@ -491,6 +495,7 @@ export function pluginOctane(inlineOptions = {}) {
 						}));
 						return create_client_entry_source({
 							staticEntries: entries,
+							clientBuildIdExpression: '__webpack_hash__',
 							generatedBy: PLUGIN_NAME,
 						});
 					},
@@ -531,7 +536,11 @@ export function pluginOctane(inlineOptions = {}) {
 							rpcModulePaths: serverModules.ids,
 							...(webWorkerServer ? { mode: 'webworker' } : null),
 							...(production && !webWorkerServer
-								? { clientAssetMapFile: CLIENT_ASSET_MAP }
+								? {
+										clientAssetMapFile: CLIENT_ASSET_MAP,
+										clientBuildFile: 'octane-client-build.json',
+										independentHydrationManifestFile: INDEPENDENT_HYDRATION_MANIFEST_FILENAME,
+									}
 								: { clientAssetMap: {} }),
 							resolveImport: (id) => resolveProjectModule(id, root),
 							configModuleId: localRequire.resolve('@octanejs/app-core/config'),
@@ -562,13 +571,16 @@ export function pluginOctane(inlineOptions = {}) {
 					new OctaneRspackPlugin({
 						root,
 						environment,
+						clientBuildMode: productionBuild ? 'production' : 'development',
 						transpile: false,
 						...(inlineOptions.parallel === undefined ? null : { parallel: inlineOptions.parallel }),
 						...(inlineOptions.cssModuleConstants === undefined
 							? null
 							: { cssModuleConstants: inlineOptions.cssModuleConstants }),
+						...(inlineOptions.textTypes === undefined
+							? null
+							: { textTypes: inlineOptions.textTypes }),
 						...(strong === undefined ? null : { strong }),
-						...(nativeReads === undefined ? null : { nativeReads }),
 						...(inlineOptions.hmr === undefined ? null : { hmr: inlineOptions.hmr }),
 						...(inlineOptions.profile === undefined
 							? null
@@ -654,6 +666,9 @@ export function pluginOctane(inlineOptions = {}) {
 
 			api.modifyHTML((html, context) => {
 				if (context.environment.name !== clientEnvironment) return html;
+				if (isProductionBuild()) {
+					assertEarlyHydrationEntry(context.compilation, CLIENT_ENTRY_NAME, clientEntryFile);
+				}
 				const entrypoint = context.compilation.entrypoints.get(CLIENT_ENTRY_NAME);
 				const entryFiles = entrypoint?.getEntrypointChunk().files ?? [];
 				return markHydrationEntry(html, entryFiles);
@@ -694,6 +709,7 @@ export function pluginOctane(inlineOptions = {}) {
 					root,
 					config: loaded.config,
 					assetMapFilename: CLIENT_ASSET_MAP,
+					independentHydrationManifestFilename: INDEPENDENT_HYDRATION_MANIFEST_FILENAME,
 					log: createLog(api.logger),
 				});
 			});

package/types/index.d.ts

@@ -10,6 +10,13 @@ export {
 } from '@octanejs/app-core/config-loader';
 
 export interface OctaneRsbuildPluginOptions {
+	/**
+	 * @experimental TypeScript text proofs in one-shot production browser and
+	 * server builds. Relative tsconfig paths resolve from the project root.
+	 * Watch/HMR and development builds retain syntax-only classification.
+	 * Requires the optional TypeScript peer; see the Rspack option for caching.
+	 */
+	textTypes?: OctaneRspackPluginOptions['textTypes'];
 	/**
 	 * @experimental Fold authenticated JavaScript CSS-module exports in one-shot
 	 * production builds. Uses the Rspack plugin's exact-source provider contract;
@@ -33,8 +40,6 @@ export interface OctaneRsbuildPluginOptions {
 	 * in with `"use strong"`.
 	 */
 	strong?: boolean;
-	/** Experimental native signal reads in DOM client/server render scopes. */
-	nativeReads?: boolean;
 	/**
 	 * Ad-hoc path fragments skipped by the plain TypeScript/JavaScript
 	 * hook-slot pass. With `requireDirective`, excluded paths are exempt from