@octanejs/rspack-plugin 0.1.4 → 0.1.6

package/package.json

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

package/src/loader.js

@@ -104,6 +104,9 @@ export default function octaneLoader(source, inputSourceMap) {
 			profile,
 			...(options.exclude === undefined ? null : { exclude: options.exclude }),
 			...(options.renderers === undefined ? null : { renderers: options.renderers }),
+			...(options.universalRuntime === undefined
+				? null
+				: { universalRuntime: options.universalRuntime }),
 			...(options.requireDirective === undefined
 				? null
 				: { requireDirective: options.requireDirective }),
@@ -138,6 +141,9 @@ export default function octaneLoader(source, inputSourceMap) {
 						result.kind === 'compile' &&
 						(result.code.includes('_$__serverRpc(') ||
 							result.code.includes('export const _$_server_$_')),
+					...(result.universalRuntime === undefined
+						? null
+						: { universalRuntime: result.universalRuntime }),
 					...(result.clientReference === undefined
 						? null
 						: { clientReference: { ...result.clientReference } }),

package/src/plugin.js

@@ -237,6 +237,8 @@ export class OctaneRspackPlugin {
 			profile,
 			exclude: this.options.exclude ?? [],
 			renderers: this.options.renderers?.signature,
+			runtime: this.options.runtime,
+			universalRuntime: this.options.universalRuntime,
 			// Ownership flips which modules compile vs pass through — cached
 			// transform results must not survive a requireDirective toggle.
 			requireDirective: this.options.requireDirective === true,
@@ -248,8 +250,12 @@ export class OctaneRspackPlugin {
 			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 runtimeRequest = neutralCompiler.resolveRuntimeRequest('octane', environment);
+		const runtimeRequest =
+			this.options.runtime ?? neutralCompiler.resolveRuntimeRequest('octane', environment);
 
 		compiler.options.resolve ??= {};
 		addUniqueExtensions(compiler.options.resolve);
@@ -266,6 +272,9 @@ export class OctaneRspackPlugin {
 			...(this.options.dev === undefined ? null : { dev: this.options.dev }),
 			...(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 }),
 			...(this.options.requireDirective === undefined
 				? null
 				: { requireDirective: this.options.requireDirective }),

package/src/shared.js

@@ -43,8 +43,35 @@ const LOADER_OPTION_KEYS = new Set([
 	'exclude',
 	'renderers',
 	'requireDirective',
+	'universalRuntime',
 ]);
-const PLUGIN_OPTION_KEYS = new Set([...LOADER_OPTION_KEYS, 'transpile']);
+const PLUGIN_OPTION_KEYS = new Set([...LOADER_OPTION_KEYS, 'runtime', 'transpile']);
+
+function normalizeUniversalRuntime(value) {
+	if (value === undefined) return undefined;
+	if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+		throw new TypeError('@octanejs/rspack-plugin: `universalRuntime` must be an object.');
+	}
+	for (const key of Object.keys(value)) {
+		if (key !== 'runtime' && key !== 'thread') {
+			throw new TypeError(`@octanejs/rspack-plugin: unknown \`universalRuntime.${key}\` option.`);
+		}
+	}
+	if (
+		typeof value.runtime !== 'string' ||
+		!/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(value.runtime)
+	) {
+		throw new TypeError(
+			'@octanejs/rspack-plugin: `universalRuntime.runtime` must be a lowercase runtime ID.',
+		);
+	}
+	if (value.thread !== 'background' && value.thread !== 'main-thread') {
+		throw new TypeError(
+			'@octanejs/rspack-plugin: `universalRuntime.thread` must be "background" or "main-thread".',
+		);
+	}
+	return Object.freeze({ runtime: value.runtime, thread: value.thread });
+}
 
 function assertBooleanOption(options, key) {
 	if (options[key] !== undefined && typeof options[key] !== 'boolean') {
@@ -66,6 +93,17 @@ 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 (
 		options.environment !== undefined &&
 		options.environment !== 'client' &&
@@ -86,6 +124,7 @@ function normalizeOptions(value, plugin) {
 	if (plugin) assertBooleanOption(options, 'transpile');
 	const renderers =
 		options.renderers === undefined ? undefined : normalizeRendererConfig(options.renderers);
+	const universalRuntime = normalizeUniversalRuntime(options.universalRuntime);
 
 	const normalized = {
 		...(options.root === undefined ? null : { root: options.root }),
@@ -95,10 +134,12 @@ function normalizeOptions(value, plugin) {
 		...(options.profile === undefined ? null : { profile: options.profile }),
 		...(options.exclude === undefined ? null : { exclude: [...options.exclude] }),
 		...(renderers === undefined ? null : { renderers }),
+		...(universalRuntime === undefined ? null : { universalRuntime }),
 		...(options.requireDirective === undefined
 			? null
 			: { requireDirective: options.requireDirective }),
 		...(plugin && options.transpile !== undefined ? { transpile: options.transpile } : null),
+		...(plugin && options.runtime !== undefined ? { runtime: options.runtime } : null),
 	};
 	if (normalized.exclude) Object.freeze(normalized.exclude);
 	return Object.freeze(normalized);
@@ -121,6 +162,12 @@ export function getOctaneRspackBuildInfo(module) {
 		typeof value.clientReference.id === 'string' &&
 		typeof value.clientReference.moduleId === 'string' &&
 		typeof value.clientReference.renderer === 'string';
+	const universalRuntimeValid =
+		value?.universalRuntime !== null &&
+		typeof value?.universalRuntime === 'object' &&
+		typeof value.universalRuntime.runtime === 'string' &&
+		(value.universalRuntime.thread === 'background' ||
+			value.universalRuntime.thread === 'main-thread');
 	if (
 		value &&
 		typeof value === 'object' &&
@@ -129,7 +176,8 @@ export function getOctaneRspackBuildInfo(module) {
 			value.transformKind === 'slots' ||
 			value.transformKind === 'client-only-stub') &&
 		typeof value.serverRpc === 'boolean' &&
-		(value.clientReference === undefined || nestedReferenceValid)
+		(value.clientReference === undefined || nestedReferenceValid) &&
+		(value.universalRuntime === undefined || universalRuntimeValid)
 	) {
 		return value;
 	}

package/types/index.d.ts

@@ -11,6 +11,18 @@ export interface OctaneRendererRuleOptions {
 	renderer: string;
 }
 
+/** @experimental Static source restrictions enforced for a renderer. */
+export interface OctaneRendererValidationOptions {
+	/** Host elements that may directly contain authored primitive text. */
+	textParents?: readonly string[];
+	/** Unbound JavaScript globals that renderer-owned source may not reference. */
+	forbiddenGlobals?: readonly string[];
+	/** Package IDs whose static imports, subpaths, and CommonJS requires are forbidden. */
+	forbiddenImports?: readonly string[];
+	/** Allowed static JSX attributes by host name; `*` supplies shared patterns. */
+	hostProps?: Readonly<Record<string, readonly string[]>>;
+}
+
 export type OctaneRendererRegistryEntry =
 	| string
 	| {
@@ -20,6 +32,7 @@ export type OctaneRendererRegistryEntry =
 			intrinsics?: string;
 			text?: 'reject' | 'ignore' | 'host';
 			capabilities?: readonly string[];
+			validation?: OctaneRendererValidationOptions;
 	  };
 
 /** Static metadata for a component prop lowered for another renderer. */
@@ -51,6 +64,7 @@ export interface OctaneResolvedRendererConfig {
 				readonly intrinsics?: string;
 				readonly text: 'reject' | 'ignore' | 'host';
 				readonly capabilities: readonly string[];
+				readonly validation?: Readonly<OctaneRendererValidationOptions>;
 			}
 		>
 	>;
@@ -86,6 +100,11 @@ export interface OctaneRspackLoaderOptions {
 	exclude?: string[];
 	/** @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';
+	};
 	/**
 	 * Mixed-toolchain ownership gate: when `true`, Octane compiles only
 	 * project modules that declare `'use octane'` in their directive prologue.
@@ -100,6 +119,12 @@ export interface OctaneRspackLoaderOptions {
 }
 
 export interface OctaneRspackPluginOptions extends OctaneRspackLoaderOptions {
+	/**
+	 * Override the exact module used for plain `octane` imports in this graph.
+	 * Universal host integrations use this to share one hook/context runtime
+	 * between compiled templates and plain TypeScript custom hooks.
+	 */
+	runtime?: string;
 	/**
 	 * Add Rspack's built-in SWC loader to strip TypeScript after Octane runs.
 	 * Disable this when another rule already owns TypeScript transpilation.
@@ -112,6 +137,11 @@ export interface OctaneRspackBuildInfo {
 	canonicalId: string;
 	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';
+	};
 	/** Stable identity shared by the client compile and its inert server stub. */
 	clientReference?: {
 		readonly id: string;