@octanejs/app-core 0.0.2 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/app-core",
-  "version": "0.0.2",
+  "version": "0.0.6",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -79,10 +79,10 @@
     "esbuild": "^0.28.1"
   },
   "peerDependencies": {
-    "octane": "0.1.6"
+    "octane": "0.1.10"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
-    "octane": "0.1.6"
+    "octane": "0.1.10"
   }
 }

package/src/codegen.js

@@ -95,11 +95,21 @@ export function write_project_generated_file(options, name, source) {
  * `staticEntries` (production builds) lists every module path the server can
  * name in #__octane_data — page entries, layouts, and the preHydrate hook.
  * Each becomes a STATIC `() => import('/src/…')` in a lookup map, so Rollup
- * sees, chunks, and hashes them; the runtime falls back to the hidden dynamic
+ * sees, chunks, and hashes them; the runtime falls back to a native dynamic
  * import only for paths outside the map (the dev case, where the map is empty
- * and the integration serves any module by URL).
+ * and the integration serves any module by URL). The fallback resolves the
+ * project-root ID against the browsing context's real location. Project IDs
+ * are root-absolute, so this has the same URL semantics as importing from this
+ * generated module while remaining immune to an authored `<base>` element.
+ * (Rspack rewrites `import.meta.url` to `document.baseURI` in classic output,
+ * so it cannot be used directly here.) Vite serves `.tsrx` modules through its
+ * canonical `?import` URL but leaves ordinary JavaScript/TypeScript URLs
+ * unchanged, while Rspack honors its ignore hint. Keeping the import native
+ * avoids requiring `unsafe-eval` under a nonce-based Content Security Policy.
  *
  * octane specifics:
+ *   - `initializeHydrationEventCapture()` runs before any async route work so
+ *     interaction boundaries can preserve intent that precedes `hydrateRoot()`.
  *   - `import { hydrateRoot } from 'octane'` (NO `mount`).
  *   - `hydrateRoot(container, body, props)` signature (container FIRST, React-18
  *     shape) — no `{ target, props }` wrapper.
@@ -146,7 +156,9 @@ export function create_client_entry_source(options = {}) {
 	return `// Auto-generated by ${generatedBy}.
 // This file is written to the active integration's project cache.
 
-import { hydrateRoot, Suspense, ErrorBoundary, createElement } from ${JSON.stringify(runtimeModuleId)};
+import { hydrateRoot, initializeHydrationEventCapture, Suspense, ErrorBoundary, createElement } from ${JSON.stringify(runtimeModuleId)};
+
+initializeHydrationEventCapture();
 
 // Static import map (production): every module the server may name in
 // #__octane_data, as bundle-analyzable dynamic imports. Empty in dev.
@@ -154,11 +166,20 @@ const routeModules = {
 ${static_map_lines}
 };
 
-// Keep the fallback hidden from static import analysis. Some integrations
-// rewrite variable dynamic imports into queried URLs, which can evaluate as a
-// SECOND browser module instance and stop pages/preHydrate hooks sharing
-// singletons with statically imported copies of the same files.
-const dynamicImport = new Function('specifier', 'return import(specifier)');
+// Keep the fallback native and canonical. Vite serves static \`.tsrx\` imports
+// through \`?import\`, but ordinary JS/TS imports without it. Resolve that same
+// root-absolute URL against the browsing context's real location (not a
+// possibly-authored document <base>) so Vite's variable-import helper leaves
+// it unchanged; Rspack honors webpackIgnore. Pages/preHydrate hooks then share
+// module singletons with static imports. A Function constructor breaks CSP.
+const dynamicImport = (specifier) => {
+  const url = new URL(specifier, globalThis.location.href);
+  if (url.pathname.endsWith('.tsrx') && !url.searchParams.has('import')) {
+    const query = url.search.slice(1);
+    url.search = query ? '?import&' + query : '?import';
+  }
+  return import(/* @vite-ignore */ /* webpackIgnore: true */ url.href);
+};
 
 function importModule(path) {
   const loader = routeModules[path];
@@ -175,14 +196,9 @@ function getComponentExport(module, exportName) {
 
 function withRootBoundary(content, boundary) {
   let body = content;
-  if (boundary.pending) {
-    const child = body;
-    const Pending = boundary.pending;
-    body = (props, scope) => Suspense({
-      fallback: createElement(Pending, {}),
-      children: (_props, childScope) => child(props, childScope),
-    }, scope);
-  }
+  // Keep ErrorBoundary closest to the route. Suspense may retain its pending
+  // shell for an unhandled server render error, so it must wrap the configured
+  // catch boundary rather than hiding route errors from it.
   if (boundary.catch) {
     const child = body;
     const Catch = boundary.catch;
@@ -191,6 +207,14 @@ function withRootBoundary(content, boundary) {
       children: (_props, childScope) => child(props, childScope),
     }, scope);
   }
+  if (boundary.pending) {
+    const child = body;
+    const Pending = boundary.pending;
+    body = (props, scope) => Suspense({
+      fallback: createElement(Pending, {}),
+      children: (_props, childScope) => child(props, childScope),
+    }, scope);
+  }
   return body;
 }
 

package/src/config-loader.js

@@ -27,8 +27,9 @@ const DEFAULT_CONFIG_FILE = 'octane.config.ts';
 const OCTANE_EXTENSION_PATTERN = /\.tsrx$/;
 const BUILTINS = new Set([...builtinModules, ...builtinModules.map((id) => `node:${id}`)]);
 
-// Validation + defaults have no compiler/esbuild imports and remain safe to
-// include in production server bundles.
+// Validation + defaults have no compiler transform/esbuild imports and remain
+// safe to include in production server bundles. Their renderer config helper
+// is a dependency-free compiler subpath.
 export { resolveOctaneConfig } from './resolve-config.js';
 
 /**
@@ -236,7 +237,9 @@ async function evaluateConfigModule(root, configPath, configuredCacheDir) {
 	const contentHash = createHash('sha256').update(output).digest('hex').slice(0, 16);
 	let configModule;
 	try {
-		configModule = await import(`${pathToFileURL(outputPath).href}?v=${contentHash}`);
+		configModule = await import(
+			/* @vite-ignore */ `${pathToFileURL(outputPath).href}?v=${contentHash}`
+		);
 	} catch (error) {
 		attachDependencyMetadata(error, dependencies, missingDependencies);
 		throw error;

package/src/resolve-config.js

@@ -2,16 +2,19 @@
 /**
  * Config validation + defaults — `resolveOctaneConfig` and its validators.
  *
- * Kept in a module with NO heavy imports (no bundler or octane/compiler) because
+ * Kept in a module with NO heavy imports (no bundler or compiler transform) because
  * it is part of the PRODUCTION server bundle's graph: the generated server
  * entry re-resolves octane.config.ts through it at boot, and the whole
  * `@octanejs/app-core/production` graph is bundled into dist/server/entry.js.
  * The file-loading half (`loadOctaneConfig`) lives in
- * `load-config.js` and re-exports everything here.
+ * `config-loader.js` and re-exports everything here.
+ * `octane/compiler/renderers` is intentionally a dependency-free config helper.
  */
 
 /** @import { OctaneConfigOptions, ResolvedOctaneConfig } from '@octanejs/app-core' */
 
+import { normalizeRendererConfig } from 'octane/compiler/renderers';
+
 import { DEFAULT_OUTDIR } from './constants.js';
 
 /**
@@ -122,6 +125,13 @@ export function resolveOctaneConfig(raw, options = {}) {
 		}
 	}
 
+	if (
+		raw.compiler !== undefined &&
+		(!raw.compiler || typeof raw.compiler !== 'object' || Array.isArray(raw.compiler))
+	) {
+		throw new Error('[octane] compiler must be an object when provided.');
+	}
+
 	if (raw.router?.routes !== undefined && !Array.isArray(raw.router.routes)) {
 		throw new Error('[octane] router.routes must be an array.');
 	}
@@ -160,6 +170,9 @@ export function resolveOctaneConfig(raw, options = {}) {
 			target: raw.build?.target,
 		},
 		adapter: raw.adapter,
+		compiler: {
+			renderers: normalizeRendererConfig(raw.compiler?.renderers),
+		},
 		router: {
 			routes: raw.router?.routes ?? [],
 			preHydrate: raw.router?.preHydrate,

package/src/server/component-wrappers.js

@@ -69,6 +69,22 @@ export function createLayoutWrapper(Layout, Page, pageProps) {
 export function createRootBoundaryWrapper(Content, boundary, runtime) {
 	let body = Content;
 
+	// Compose the catch boundary closest to the route. A Suspense boundary is
+	// allowed to retain its pending shell when an unhandled server render error
+	// reaches it, so putting Suspense inside ErrorBoundary would prevent the
+	// configured catch component from observing ordinary route errors.
+	if (boundary.catch) {
+		const child = body;
+		const Catch = boundary.catch;
+		body = function RootErrorBoundary(props, scope) {
+			const children = (/** @type {any} */ _props, /** @type {any} */ childScope) =>
+				child(props, childScope, undefined);
+			const fallback = (/** @type {unknown} */ error, /** @type {() => void} */ reset) =>
+				runtime.createElement(Catch, { error, reset });
+			return runtime.ErrorBoundary({ fallback, children }, scope, undefined);
+		};
+	}
+
 	if (boundary.pending) {
 		const child = body;
 		const Pending = boundary.pending;
@@ -83,17 +99,5 @@ export function createRootBoundaryWrapper(Content, boundary, runtime) {
 		};
 	}
 
-	if (boundary.catch) {
-		const child = body;
-		const Catch = boundary.catch;
-		body = function RootErrorBoundary(props, scope) {
-			const children = (/** @type {any} */ _props, /** @type {any} */ childScope) =>
-				child(props, childScope, undefined);
-			const fallback = (/** @type {unknown} */ error, /** @type {() => void} */ reset) =>
-				runtime.createElement(Catch, { error, reset });
-			return runtime.ErrorBoundary({ fallback, children }, scope, undefined);
-		};
-	}
-
 	return body;
 }

package/src/server/node-http.js

@@ -12,7 +12,121 @@
 import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
-import { Readable } from 'node:stream';
+import { Duplex, pipeline, Readable } from 'node:stream';
+import { constants as zlibConstants, createGzip } from 'node:zlib';
+
+const MIN_COMPRESSION_BYTES = 1024;
+
+/**
+ * Read one request header in the comma-joined form HTTP negotiation expects.
+ * @param {import('node:http').IncomingMessage} request
+ * @param {string} name
+ * @returns {string | null}
+ */
+function getRequestHeader(request, name) {
+	const value = request.headers[name];
+	if (value === undefined) return null;
+	return Array.isArray(value) ? value.join(',') : value;
+}
+
+/**
+ * Return the client's quality for one content coding. An explicit coding wins
+ * over `*`, including an explicit `q=0` exclusion.
+ * @param {string | null} header
+ * @param {string} coding
+ */
+function encodingQuality(header, coding) {
+	if (header === null || header.trim() === '') return 0;
+	/** @type {number | null} */
+	let exact = null;
+	/** @type {number | null} */
+	let wildcard = null;
+	for (const entry of header.split(',')) {
+		const [rawToken, ...parameters] = entry.split(';');
+		const token = rawToken.trim().toLowerCase();
+		if (token !== coding && token !== '*') continue;
+
+		let quality = 1;
+		for (const parameter of parameters) {
+			const match = /^\s*q\s*=\s*([^\s]+)\s*$/i.exec(parameter);
+			if (!match) continue;
+			// RFC 9110 qvalues are 0..1 with at most three fractional digits.
+			quality = /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/.test(match[1]) ? Number(match[1]) : 0;
+		}
+
+		if (token === coding && exact === null) exact = quality;
+		if (token === '*' && wildcard === null) wildcard = quality;
+	}
+	return exact ?? wildcard ?? 0;
+}
+
+/** @param {string | null} contentType */
+function isCompressibleContentType(contentType) {
+	if (!contentType) return false;
+	const type = contentType.split(';', 1)[0].trim().toLowerCase();
+	if (type === 'text/event-stream') return false;
+	if (type.startsWith('text/')) return true;
+	if (type === 'image/svg+xml') return true;
+	if (type === 'application/wasm') return true;
+	if (type === 'font/ttf' || type === 'font/otf') return true;
+	if (type.endsWith('+json') || type.endsWith('+xml')) return true;
+	return (
+		type === 'application/json' ||
+		type === 'application/javascript' ||
+		type === 'application/x-javascript' ||
+		type === 'application/xml' ||
+		type === 'application/xhtml+xml' ||
+		type === 'application/rss+xml' ||
+		type === 'application/atom+xml'
+	);
+}
+
+/** @param {Headers} headers */
+function appendAcceptEncodingVary(headers) {
+	const vary = headers.get('Vary');
+	if (!vary) {
+		headers.set('Vary', 'Accept-Encoding');
+		return;
+	}
+	if (vary.trim() === '*') return;
+	if (vary.split(',').some((value) => value.trim().toLowerCase() === 'accept-encoding')) {
+		return;
+	}
+	headers.set('Vary', `${vary}, Accept-Encoding`);
+}
+
+/**
+ * Decide whether this representation is eligible for negotiated gzip. Eligible
+ * identity responses still gain `Vary: Accept-Encoding`, so shared caches do
+ * not reuse them for gzip-capable clients.
+ *
+ * @param {import('node:http').IncomingMessage} request
+ * @param {number} status
+ * @param {Headers} headers
+ * @param {boolean} hasBody
+ */
+function shouldGzip(request, status, headers, hasBody) {
+	const method = (request.method || 'GET').toUpperCase();
+	if (!hasBody || method === 'HEAD') return false;
+	if (status < 200 || status === 204 || status === 205 || status === 206 || status === 304) {
+		return false;
+	}
+	if (getRequestHeader(request, 'range') !== null || headers.has('Content-Range')) return false;
+	if (headers.has('Content-Encoding')) return false;
+	if (/(?:^|,)\s*no-transform\s*(?:,|$)/i.test(headers.get('Cache-Control') || '')) {
+		return false;
+	}
+	if (!isCompressibleContentType(headers.get('Content-Type'))) return false;
+
+	const rawLength = headers.get('Content-Length');
+	if (rawLength !== null) {
+		const length = Number(rawLength);
+		if (Number.isFinite(length) && length < MIN_COMPRESSION_BYTES) return false;
+	}
+
+	appendAcceptEncodingVary(headers);
+	return encodingQuality(getRequestHeader(request, 'accept-encoding'), 'gzip') > 0;
+}
 
 /**
  * Convert a Node.js IncomingMessage to a Web Request.
@@ -70,13 +184,40 @@ export function nodeRequestToWebRequest(nodeRequest) {
  * @param {Response} webResponse
  */
 export async function sendWebResponse(nodeResponse, webResponse) {
+	return sendWebResponseForRequest(nodeResponse, webResponse);
+}
+
+/**
+ * The built-in server supplies the request so this transport layer can
+ * negotiate compression. Serverless adapters keep calling `sendWebResponse`
+ * without transport compression because their host owns content encoding.
+ *
+ * @param {import('node:http').ServerResponse} nodeResponse
+ * @param {Response} webResponse
+ * @param {import('node:http').IncomingMessage} [nodeRequest]
+ */
+async function sendWebResponseForRequest(nodeResponse, webResponse, nodeRequest) {
+	const headers = new Headers(webResponse.headers);
+	/** @type {ReadableStream<Uint8Array> | null} */
+	let body = webResponse.body;
+	if (nodeRequest && body && shouldGzip(nodeRequest, webResponse.status, headers, true)) {
+		headers.set('Content-Encoding', 'gzip');
+		headers.delete('Content-Length');
+		// Sync-flush each input chunk so an SSR shell stays progressively
+		// observable instead of waiting for the final segment to close gzip.
+		const gzip = Duplex.toWeb(createGzip({ flush: zlibConstants.Z_SYNC_FLUSH }));
+		body = body.pipeThrough(
+			/** @type {ReadableWritablePair<Uint8Array, Uint8Array>} */ (/** @type {unknown} */ (gzip)),
+		);
+	}
+
 	nodeResponse.statusCode = webResponse.status;
 	if (webResponse.statusText) nodeResponse.statusMessage = webResponse.statusText;
-	webResponse.headers.forEach((value, key) => {
+	headers.forEach((value, key) => {
 		nodeResponse.setHeader(key, value);
 	});
-	if (webResponse.body) {
-		const reader = webResponse.body.getReader();
+	if (body) {
+		const reader = body.getReader();
 		let disconnected = nodeResponse.destroyed;
 		let disconnectReason = new Error('The client disconnected while streaming the response.');
 		/** @type {Promise<void> | null} */
@@ -207,17 +348,35 @@ export function serveStaticFile(req, res, staticDir) {
 	if (!stat.isFile()) return false;
 
 	const ext = path.extname(filePath).toLowerCase();
+	const headers = new Headers({
+		'Content-Type': MIME_TYPES[ext] || 'application/octet-stream',
+		'Content-Length': String(stat.size),
+		'Cache-Control':
+			pathname.startsWith('/assets/') || pathname.startsWith('/static/')
+				? 'public, max-age=31536000, immutable'
+				: 'public, max-age=0, must-revalidate',
+	});
+	const gzip = shouldGzip(req, 200, headers, method !== 'HEAD');
+	if (gzip) {
+		headers.set('Content-Encoding', 'gzip');
+		headers.delete('Content-Length');
+	}
+
 	res.statusCode = 200;
-	res.setHeader('Content-Type', MIME_TYPES[ext] || 'application/octet-stream');
-	res.setHeader('Content-Length', stat.size);
-	res.setHeader(
-		'Cache-Control',
-		pathname.startsWith('/assets/') || pathname.startsWith('/static/')
-			? 'public, max-age=31536000, immutable'
-			: 'public, max-age=0, must-revalidate',
-	);
+	res.setHeader('Content-Type', /** @type {string} */ (headers.get('Content-Type')));
+	const contentLength = headers.get('Content-Length');
+	if (contentLength !== null) res.setHeader('Content-Length', contentLength);
+	res.setHeader('Cache-Control', /** @type {string} */ (headers.get('Cache-Control')));
+	const contentEncoding = headers.get('Content-Encoding');
+	if (contentEncoding !== null) res.setHeader('Content-Encoding', contentEncoding);
+	const vary = headers.get('Vary');
+	if (vary !== null) res.setHeader('Vary', vary);
 	if (method === 'HEAD') {
 		res.end();
+	} else if (gzip) {
+		pipeline(fs.createReadStream(filePath), createGzip(), res, (error) => {
+			if (error && !res.destroyed) res.destroy(error);
+		});
 	} else {
 		fs.createReadStream(filePath).pipe(res);
 	}
@@ -240,7 +399,7 @@ export function createNodeServer(handler, options = {}) {
 		(async () => {
 			if (staticDir && serveStaticFile(req, res, staticDir)) return;
 			const response = await handler(nodeRequestToWebRequest(req));
-			await sendWebResponse(res, response);
+			await sendWebResponseForRequest(res, response, req);
 		})().catch((error) => {
 			console.error('[octane] Request error:', error);
 			if (!res.headersSent) {

package/src/server/production.js

@@ -5,9 +5,9 @@
  * `createHandler(manifest, deps)` is the runtime entry the generated server
  * bundle (dist/server/entry.js) calls in production. It is designed to be
  * BUNDLED: platform-agnostic (no Node imports — platform capabilities come via
- * `manifest.runtime`), and free of vite / octane-compiler imports (which is why
- * `resolveOctaneConfig` is re-exported from resolve-config.js, not
- * load-config.js).
+ * `manifest.runtime`), and free of Vite / compiler-transform imports (which is
+ * why `resolveOctaneConfig` is re-exported from resolve-config.js, not
+ * config-loader.js). Its renderer config helper is dependency-free.
  *
  * The render path mirrors the DEV middleware's `handleRenderRoute`
  * (server/render-route.js) byte-for-byte in everything hydration can see —

package/types/config.d.ts

@@ -12,6 +12,14 @@ export type {
 	AdapterServeFunction,
 	BuildTarget,
 	Context,
+	ExperimentalRendererBoundaryOptions,
+	ExperimentalRendererConfigOptions,
+	ExperimentalRendererRegistryEntry,
+	ExperimentalRendererRuleOptions,
+	ExperimentalResolvedRendererBoundary,
+	ExperimentalResolvedRendererConfig,
+	ExperimentalResolvedRendererRegistryEntry,
+	ExperimentalResolvedRendererRule,
 	Middleware,
 	OctaneAdapter,
 	OctaneConfigOptions,

package/types/index.d.ts

@@ -10,7 +10,7 @@ export const OCTANE_NONCE_STATE_KEY: 'octane.nonce';
 export const DEFAULT_OUTDIR: 'dist';
 export const ENTRY_FILENAME: 'entry.js';
 export function resolveOctaneConfig(
-	raw: OctaneConfigOptions,
+	raw: OctaneConfigOptions | ResolvedOctaneConfig,
 	options?: { requireAdapter?: boolean },
 ): ResolvedOctaneConfig;
 
@@ -177,6 +177,108 @@ export interface RootBoundaryOptions {
 	catch?: RenderRouteEntry;
 }
 
+/**
+ * @experimental Universal renderer configuration is an internal-first API and
+ * may change while the first non-DOM renderer is validated.
+ */
+export interface ExperimentalRendererRuleOptions {
+	/** Glob or globs matched against canonical project-relative module IDs. */
+	include: string | readonly string[];
+	/** Optional glob or globs that remove files from this rule. */
+	exclude?: string | readonly string[];
+	/** Renderer alias declared in `registry`, or the built-in `dom` alias. */
+	renderer: string;
+}
+
+/**
+ * @experimental A string selects the universal compiler target. The object
+ * form carries explicit target metadata for normalized configs and future
+ * renderer integrations. The `dom` alias itself is reserved by Octane.
+ */
+export type ExperimentalRendererRegistryEntry =
+	| string
+	| {
+			module: string;
+			target?: 'dom' | 'universal';
+			/** Explicit server policy; universal renderers currently support client-only or unsupported. */
+			server?: 'render' | 'client-only' | 'unsupported';
+			/** JSX import-source module used for file-local intrinsic element types. */
+			intrinsics?: string;
+			/** Policy for authored text children. @default 'reject' */
+			text?: 'reject' | 'ignore' | 'host';
+			/** Serializable feature flags consumed by compiler and runtime integrations. */
+			capabilities?: readonly string[];
+	  };
+
+/**
+ * @experimental Static metadata for a component prop whose contents are owned
+ * by another renderer. Boundary declarations are keyed by the component's
+ * public module ID and export name in {@link ExperimentalRendererConfigOptions}.
+ */
+export interface ExperimentalRendererBoundaryOptions {
+	/** Renderer that owns the boundary component itself. */
+	ownerRenderer: string;
+	/** Renderer used to lower and execute the declared child region. */
+	childRenderer: string;
+	/** Component prop containing the renderer-owned region, usually `children`. */
+	prop: string;
+	/** Omit a client-only child region from server output. */
+	server?: 'omit-child';
+}
+
+/** @experimental See {@link ExperimentalRendererRuleOptions}. */
+export interface ExperimentalRendererConfigOptions {
+	/** Renderer aliases mapped to package/project-root module IDs or explicit descriptors. */
+	registry?: Record<string, ExperimentalRendererRegistryEntry>;
+	/**
+	 * Boundary metadata keyed first by stable package/project-root module ID,
+	 * then by the component's export name (`default` for a default export).
+	 */
+	boundaries?: Readonly<
+		Record<string, Readonly<Record<string, ExperimentalRendererBoundaryOptions>>>
+	>;
+	/** Renderer used when no rule matches. @default 'dom' */
+	default?: string;
+	/** Ordered filename rules. The first matching rule wins. */
+	rules?: readonly ExperimentalRendererRuleOptions[];
+}
+
+/** @experimental Canonical form used by compiler integrations and cache keys. */
+export interface ExperimentalResolvedRendererRule {
+	readonly include: readonly string[];
+	readonly exclude: readonly string[];
+	readonly renderer: string;
+}
+
+/** @experimental Canonical form used by compiler integrations and cache keys. */
+export interface ExperimentalResolvedRendererRegistryEntry {
+	readonly module: string;
+	readonly target: 'dom' | 'universal';
+	readonly server: 'render' | 'client-only' | 'unsupported';
+	readonly intrinsics?: string;
+	readonly text: 'reject' | 'ignore' | 'host';
+	readonly capabilities: readonly string[];
+}
+
+/** @experimental Canonical renderer-owned child-region metadata. */
+export interface ExperimentalResolvedRendererBoundary {
+	readonly ownerRenderer: string;
+	readonly childRenderer: string;
+	readonly prop: string;
+	readonly server?: 'omit-child';
+}
+
+/** @experimental Canonical form used by compiler integrations and cache keys. */
+export interface ExperimentalResolvedRendererConfig {
+	readonly registry: Readonly<Record<string, ExperimentalResolvedRendererRegistryEntry>>;
+	readonly boundaries: Readonly<
+		Record<string, Readonly<Record<string, ExperimentalResolvedRendererBoundary>>>
+	>;
+	readonly default: string;
+	readonly rules: readonly ExperimentalResolvedRendererRule[];
+	readonly signature: string;
+}
+
 export interface OctaneConfigOptions {
 	build?: {
 		/** Output directory for the production build. @default 'dist' */
@@ -185,6 +287,10 @@ export interface OctaneConfigOptions {
 		target?: BuildTarget;
 	};
 	adapter?: OctaneAdapter;
+	/** @experimental Compiler-owned configuration shared by all bundler integrations. */
+	compiler?: {
+		renderers?: ExperimentalRendererConfigOptions;
+	};
 	router?: {
 		routes: Route[];
 		/**
@@ -234,6 +340,9 @@ export interface ResolvedOctaneConfig {
 		target?: BuildTarget;
 	};
 	adapter?: OctaneAdapter;
+	compiler: {
+		renderers: ExperimentalResolvedRendererConfig;
+	};
 	router: {
 		routes: Route[];
 		preHydrate?: string;

package/types/production.d.ts

@@ -9,7 +9,7 @@ import type {
 import type { RenderResult, StreamOptions, RenderOptions } from 'octane/server';
 
 export function resolveOctaneConfig(
-	raw: OctaneConfigOptions,
+	raw: OctaneConfigOptions | ResolvedOctaneConfig,
 	options?: { requireAdapter?: boolean },
 ): ResolvedOctaneConfig;