@octanejs/vite-plugin 0.1.5 → 0.1.9

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@octanejs/vite-plugin",
-  "version": "0.1.5",
+  "version": "0.1.9",
   "license": "MIT",
   "type": "module",
-  "description": "Vite metaframework plugin for the octane renderer (dev SSR + routing + hydrate)",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "Vite integration for Octane (SPA compilation plus optional routing, SSR, and hydration)",
   "author": {
     "name": "Dominic Gannaway",
     "email": "dg@domgan.com"
@@ -16,6 +19,10 @@
     "url": "git+https://github.com/octanejs/octane.git",
     "directory": "packages/vite-plugin-octane"
   },
+  "files": [
+    "src",
+    "types"
+  ],
   "module": "src/index.js",
   "main": "src/index.js",
   "bin": {
@@ -40,11 +47,17 @@
   },
   "dependencies": {
     "@ripple-ts/adapter": "^0.3.86",
-    "octane": "0.1.5"
+    "@octanejs/app-core": "0.0.5"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.16",
+    "octane": "0.1.9"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
+    "playwright": "^1.61.0",
     "type-fest": "^5.6.0",
-    "vite": "^8.0.16"
+    "vite": "^8.0.16",
+    "octane": "0.1.9"
   }
 }

package/src/client-assets.js

@@ -0,0 +1,81 @@
+// @ts-check
+import { HYDRATE_QUERY_PARAM } from 'octane/compiler/bundler';
+
+/**
+ * @typedef {{
+ *   file: string,
+ *   src?: string,
+ *   css?: string[],
+ *   imports?: string[],
+ *   dynamicImports?: string[],
+ * }} ViteManifestEntry
+ */
+
+/** @param {string | undefined} id */
+function isDeferredHydrationId(id) {
+	if (!id) return false;
+	const queryStart = id.indexOf('?');
+	if (queryStart === -1) return false;
+	const hashStart = id.indexOf('#', queryStart);
+	const query = id.slice(queryStart + 1, hashStart === -1 ? undefined : hashStart);
+	return new URLSearchParams(query).has(HYDRATE_QUERY_PARAM);
+}
+
+/**
+ * Build the route asset map consumed by the production server.
+ *
+ * A normal dynamic import stays lazy in both channels. Compiler-generated
+ * `?octane-hydrate=` imports are different: their JavaScript remains deferred,
+ * but their CSS must be present while the server-rendered boundary is inert.
+ * Once inside one of those branches, collect CSS through the whole async
+ * descendant graph so nested Hydrate/lazy components cannot flash unstyled.
+ *
+ * @param {Record<string, ViteManifestEntry>} manifest
+ * @param {string[]} moduleIds
+ * @returns {Record<string, { js: string, css: string[] }>}
+ */
+export function createClientAssetMap(manifest, moduleIds) {
+	/**
+	 * @param {string} key
+	 * @param {boolean} deferredHydrationBranch
+	 * @param {Set<string>} visited
+	 * @returns {string[]}
+	 */
+	function collectCss(key, deferredHydrationBranch, visited) {
+		const visitKey = `${deferredHydrationBranch ? 'deferred' : 'eager'}:${key}`;
+		if (visited.has(visitKey)) return [];
+		visited.add(visitKey);
+		const entry = manifest[key];
+		if (!entry) return [];
+
+		const css = [...(entry.css || [])];
+		for (const imported of entry.imports || []) {
+			css.push(...collectCss(imported, deferredHydrationBranch, visited));
+		}
+		for (const imported of entry.dynamicImports || []) {
+			const importedEntry = manifest[imported];
+			const entersDeferredHydration =
+				deferredHydrationBranch ||
+				isDeferredHydrationId(imported) ||
+				isDeferredHydrationId(importedEntry?.src);
+			if (entersDeferredHydration) {
+				css.push(...collectCss(imported, true, visited));
+			}
+		}
+		return css;
+	}
+
+	/** @type {Record<string, { js: string, css: string[] }>} */
+	const assets = {};
+	for (const moduleId of moduleIds) {
+		// Vite manifest keys are root-relative without the leading slash.
+		const manifestKey = moduleId.startsWith('/') ? moduleId.slice(1) : moduleId;
+		const entry = manifest[manifestKey];
+		if (!entry) continue;
+		assets[moduleId] = {
+			js: entry.file,
+			css: [...new Set(collectCss(manifestKey, false, new Set()))],
+		};
+	}
+	return assets;
+}

package/src/config-entry.js

@@ -13,6 +13,21 @@
 
 export { RenderRoute, ServerRoute } from './routes.js';
 export { resolveOctaneConfig } from './resolve-config.js';
+export { OCTANE_NONCE_STATE_KEY } from './constants.js';
+export {
+	DEFAULT_OUTDIR,
+	ENTRY_FILENAME,
+	compose,
+	createContext,
+	createRouter,
+	get_component_export,
+	get_route_entry_export_name,
+	get_route_entry_id,
+	get_route_entry_path,
+	handleServerRoute,
+	is_rpc_request,
+	runMiddlewareChain,
+} from '@octanejs/app-core';
 
 // Mirrors src/index.js — enforce types / DX only.
 export function defineConfig(/** @type {any} */ options) {

package/src/constants.js

@@ -1,3 +1 @@
-// @ts-check
-export const DEFAULT_OUTDIR = 'dist';
-export const ENTRY_FILENAME = 'entry.js';
+export { DEFAULT_OUTDIR, ENTRY_FILENAME, OCTANE_NONCE_STATE_KEY } from '@octanejs/app-core';

package/src/index.js

@@ -1,11 +1,12 @@
 // @ts-check
-/** @import {Plugin, ResolvedConfig, ViteDevServer, UserConfig} from 'vite' */
-/** @import {OctaneConfigOptions, ResolvedOctaneConfig, RenderRoute} from '@octanejs/vite-plugin' */
+/** @import {Plugin, RenderBuiltAssetUrl, ResolvedConfig, ViteDevServer, UserConfig} from 'vite' */
+/** @import {LoadedOctaneConfig, OctaneConfigOptions, ResolvedOctaneConfig, RenderRoute} from '@octanejs/vite-plugin' */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { createRequire } from 'node:module';
 
 import { octane as octaneCompiler } from 'octane/compiler/vite';
 
@@ -13,12 +14,14 @@ import { createRouter } from './server/router.js';
 import { createContext, runMiddlewareChain } from './server/middleware.js';
 import { handleRenderRoute } from './server/render-route.js';
 import { handleServerRoute } from './server/server-route.js';
+import { HYDRATION_NONCE_PLACEHOLDER, injectHydrationEntry } from './server/html-template.js';
 import { generateServerEntry } from './server/virtual-entry.js';
 import { nodeRequestToWebRequest, sendWebResponse } from './server/node-http.js';
 import { ENTRY_FILENAME } from './constants.js';
 import {
 	getOctaneConfigPath,
 	loadOctaneConfig,
+	loadOctaneConfigWithMetadata,
 	resolveOctaneConfig,
 	octaneConfigExists,
 } from './load-config.js';
@@ -30,6 +33,7 @@ import {
 	to_vite_root_import,
 	write_project_generated_file,
 } from './project-codegen.js';
+import { createClientAssetMap } from './client-assets.js';
 
 import { patch_global_fetch, is_rpc_request, handle_rpc_request } from '@ripple-ts/adapter/rpc';
 
@@ -37,16 +41,35 @@ import { get_route_entry_path } from './routes.js';
 
 // Re-export route classes + config helpers (public API surface).
 export { RenderRoute, ServerRoute } from './routes.js';
+export { OCTANE_NONCE_STATE_KEY } from './constants.js';
+export {
+	DEFAULT_OUTDIR,
+	ENTRY_FILENAME,
+	compose,
+	createContext,
+	createRouter,
+	get_component_export,
+	get_route_entry_export_name,
+	get_route_entry_id,
+	get_route_entry_path,
+	handleServerRoute,
+	is_rpc_request,
+	runMiddlewareChain,
+} from '@octanejs/app-core';
 export {
 	getOctaneConfigPath,
 	loadOctaneConfig,
+	loadOctaneConfigWithMetadata,
 	resolveOctaneConfig,
 	octaneConfigExists,
 } from './load-config.js';
 
 const VIRTUAL_HYDRATE_ID = 'virtual:octane-hydrate';
 const RESOLVED_VIRTUAL_HYDRATE_ID = '\0virtual:octane-hydrate';
-const OCTANE_EXTENSIONS = ['.tsrx'];
+const requireFromPlugin = createRequire(import.meta.url);
+// Mirrors octane/compiler/vite's full-compiler surface. Keeping this list in
+// sync is especially important for production `module server` discovery.
+const OCTANE_EXTENSIONS = ['.tsrx', '.tsx'];
 
 /**
  * @param {string} file_name
@@ -147,9 +170,36 @@ function has_route_config(config) {
 }
 
 /**
- * The octane metaframework Vite plugin.
+ * Every module path the server can name in #__octane_data — page entries,
+ * layouts, the preHydrate hook, and root boundaries. The generated hydrate
+ * entry maps each as a LITERAL `() => import('/src/…')`. Production needs the
+ * map so Rollup chunks and hashes the modules; dev needs it so the imports go
+ * through Vite's import analysis and share URL identity with every other
+ * importer (see the hydrate-entry load hook).
+ *
+ * @param {ResolvedOctaneConfig | null} config
+ * @returns {string[]}
+ */
+function collect_hydrate_module_paths(config) {
+	if (!has_route_config(config)) return [];
+	const cfg = /** @type {ResolvedOctaneConfig} */ (config);
+	const entries = cfg.router.routes
+		.filter((r) => r.type === 'render')
+		.flatMap((r) => [get_route_entry_path(/** @type {RenderRoute} */ (r).entry), r.layout]);
+	if (cfg.router.preHydrate) entries.push(cfg.router.preHydrate);
+	entries.push(
+		get_route_entry_path(cfg.rootBoundary.pending),
+		get_route_entry_path(cfg.rootBoundary.catch),
+	);
+	return [...new Set(entries.filter((e) => typeof e === 'string'))];
+}
+
+/**
+ * The recommended Octane Vite integration. With no octane.config.ts it behaves
+ * as a compiler plugin inside a normal Vite SPA; configured routes activate the
+ * metaframework layer.
  *
- * Returns an ARRAY: `[octaneCompiler({ hmr }), metaPlugin]`. The first element is
+ * Returns an ARRAY: `[octaneCompiler(options), metaPlugin]`. The first element is
  * octane/compiler's transform plugin — it owns ALL `.tsrx` compilation, picking
  * client vs server mode per-module from Vite's SSR signal (so the SAME file
  * compiles to a DOM-clone client body for the browser and to an HTML-building
@@ -164,7 +214,7 @@ function has_route_config(config) {
  * node builtins external) exporting `handler`/`nodeHandler` and auto-booting
  * under `node`. See server/virtual-entry.js and server/production.js.
  *
- * @param {{ hmr?: boolean, exclude?: string[] }} [inlineOptions]
+ * @param {{ hmr?: boolean, profile?: boolean, exclude?: string[], requireDirective?: boolean, renderers?: import('@octanejs/app-core').ExperimentalRendererConfigOptions }} [inlineOptions]
  * @returns {Plugin[]}
  */
 export function octane(inlineOptions = {}) {
@@ -180,10 +230,40 @@ export function octane(inlineOptions = {}) {
 	let isBuild = false;
 	/** @type {boolean} Is this the SSR sub-build closeBundle launches? */
 	let isSSRBuild = false;
+	/**
+	 * Config dependencies that select compiler renderers. A change requires a
+	 * server restart because the neutral compiler snapshots normalized renderer
+	 * metadata before the first module transform.
+	 * @type {Set<string>}
+	 */
+	const rendererConfigWatchFiles = new Set();
+	/** @type {Map<string, Promise<LoadedOctaneConfig | null>>} */
+	const startupConfigLoads = new Map();
 	/** @type {ResolvedOctaneConfig | null} Config loaded for the build (config hook, reused in closeBundle) */
 	let buildOctaneConfig = null;
 	/** @type {string[]} Module paths the generated client entry maps statically (build only) */
 	let staticEntries = [];
+	/** @type {Set<string>} Vite-root paths of modules containing `module server` */
+	const serverModuleModules = new Set();
+
+	/**
+	 * Load declarative app config early enough for the compiler plugin's own
+	 * `config` hook. Cache per project root for the paired compiler/meta hooks;
+	 * a dev-server restart constructs a fresh plugin instance and fresh snapshot.
+	 *
+	 * @param {string} projectRoot
+	 * @returns {Promise<LoadedOctaneConfig | null>}
+	 */
+	function loadStartupConfig(projectRoot) {
+		const resolvedRoot = path.resolve(projectRoot);
+		let load = startupConfigLoads.get(resolvedRoot);
+		if (load !== undefined) return load;
+		load = octaneConfigExists(resolvedRoot)
+			? loadOctaneConfigWithMetadata(resolvedRoot)
+			: Promise.resolve(null);
+		startupConfigLoads.set(resolvedRoot, load);
+		return load;
+	}
 
 	/** @type {Plugin} */
 	const metaPlugin = {
@@ -196,33 +276,31 @@ export function octane(inlineOptions = {}) {
 		async config(userConfig, env) {
 			isBuild = env?.command === 'build';
 			isSSRBuild = !!userConfig.build?.ssr;
+			const projectRoot = userConfig.root ? path.resolve(userConfig.root) : process.cwd();
+			const hasOctaneConfig = octaneConfigExists(projectRoot);
 
 			const exclude = userConfig.optimizeDeps?.exclude || [];
 			const base = {
-				// SSR owns routing, so default appType to 'custom' (no SPA HTML
-				// fallback masking SSR routes). Respect an explicit user appType, and
-				// leave `vite preview` alone — the production SSR build is previewed
+				// A zero-config project is a normal Vite SPA: leave appType unset so
+				// Vite retains its HTML transform and history fallback. An Octane app
+				// config opts into framework routing, where SSR owns navigation and the
+				// SPA fallback must not mask unmatched routes. Respect an explicit user
+				// appType, and leave `vite preview` alone — production SSR is previewed
 				// with `octane-preview` (it serves dist/server), not `vite preview`.
-				...(userConfig.appType === undefined && !env?.isPreview
+				...(hasOctaneConfig && userConfig.appType === undefined && !env?.isPreview
 					? { appType: /** @type {const} */ ('custom') }
 					: {}),
 				optimizeDeps: {
 					exclude: [
-						// `@octanejs/tanstack-query` ships a `.tsrx` provider component, so it must NOT
-						// be esbuild-prebundled — the octane transform owns `.tsrx` compilation.
-						...new Set([
-							...exclude,
-							'octane',
-							'octane/compiler',
-							'@octanejs/tanstack-query',
-							...SERVER_ONLY_ADAPTER_IDS,
-						]),
+						// The compiler plugin has already added every manifest-discovered
+						// raw Octane dependency to `exclude`; preserve that list here.
+						...new Set([...exclude, 'octane', 'octane/compiler', ...SERVER_ONLY_ADAPTER_IDS]),
 					],
 				},
-				// Workspace packages with TS source must be transformed by Vite's SSR
-				// pipeline (not require()'d raw) so ssrLoadModule gets transpiled code.
+				// Raw binding packages are supplied recursively by the compiler plugin;
+				// these core entrypoints remain explicit metaframework dependencies.
 				ssr: {
-					noExternal: ['octane', 'octane/compiler', '@octanejs/tanstack-query'],
+					noExternal: ['octane', 'octane/compiler'],
 				},
 			};
 
@@ -230,8 +308,7 @@ export function octane(inlineOptions = {}) {
 			// build.ssr, so it skips this): route the client bundle to
 			// `{outDir}/client` and emit a manifest for the server's asset map.
 			if (isBuild && !isSSRBuild) {
-				const projectRoot = userConfig.root ? path.resolve(userConfig.root) : process.cwd();
-				if (octaneConfigExists(projectRoot)) {
+				if (hasOctaneConfig) {
 					buildOctaneConfig = await loadOctaneConfig(projectRoot);
 					if (has_route_config(buildOctaneConfig)) {
 						if (!fs.existsSync(path.join(projectRoot, 'index.html'))) {
@@ -251,7 +328,28 @@ export function octane(inlineOptions = {}) {
 						if (buildOctaneConfig.build.target !== undefined) {
 							buildConfig.target = buildOctaneConfig.build.target;
 						}
-						return { ...base, build: buildConfig };
+						const userRenderBuiltUrl = userConfig.experimental?.renderBuiltUrl;
+						/** @type {RenderBuiltAssetUrl} */
+						const renderBuiltUrl = (filename, context) => {
+							const userResult = userRenderBuiltUrl?.(filename, context);
+							if (userResult !== undefined) return userResult;
+
+							// Vite's production module-preload helper otherwise resolves its
+							// root-relative dependency URLs through document.baseURI. Generate
+							// module-relative JS asset URLs so an authored <base> cannot redirect
+							// route, layout, or pre-hydrate chunk preloads off the app origin.
+							if (!context.ssr && context.type === 'asset' && context.hostType === 'js') {
+								return { relative: true };
+							}
+						};
+						return {
+							...base,
+							build: buildConfig,
+							experimental: {
+								...userConfig.experimental,
+								renderBuiltUrl,
+							},
+						};
 					}
 				}
 			}
@@ -267,12 +365,8 @@ export function octane(inlineOptions = {}) {
 		 */
 		buildStart() {
 			if (!isBuild || isSSRBuild || !has_route_config(buildOctaneConfig)) return;
-			const cfg = /** @type {ResolvedOctaneConfig} */ (buildOctaneConfig);
-			const entries = cfg.router.routes
-				.filter((r) => r.type === 'render')
-				.flatMap((r) => [get_route_entry_path(/** @type {RenderRoute} */ (r).entry), r.layout]);
-			if (cfg.router.preHydrate) entries.push(cfg.router.preHydrate);
-			staticEntries = [...new Set(entries.filter((e) => typeof e === 'string'))];
+			serverModuleModules.clear();
+			staticEntries = collect_hydrate_module_paths(buildOctaneConfig);
 		},
 
 		async configResolved(resolvedConfig) {
@@ -296,16 +390,29 @@ export function octane(inlineOptions = {}) {
 				return create_adapter_browser_stub_source();
 			}
 			if (id === RESOLVED_VIRTUAL_HYDRATE_ID) {
-				// Dev: dynamic import() of the route entry works through Vite, so the
-				// static import map stays empty (the codegen falls back to a dynamic
-				// import per entry). Production builds pass the routes' module paths
-				// (collected in buildStart) so Rollup bundles them.
+				// Production builds pass the routes' module paths (collected in
+				// buildStart) so Rollup bundles them. Dev ALSO needs the literal map —
+				// not for chunking (dev serves any module by URL) but for MODULE
+				// IDENTITY on a hot server: the codegen's fallback `dynamicImport(path)`
+				// is hidden from Vite's import analysis, so it fetches the BARE url
+				// while the page's own import chain fetches the analyzed url (`?import`
+				// for non-JS extensions, `?t=` stamps after an HMR invalidation). Two
+				// urls = two browser module instances — e.g. two app-router singletons,
+				// where preHydrate commits matches on one and the page renders the
+				// empty other, breaking hydration on every reload until the dev server
+				// restarts. Literal `import('/src/…')` entries go through import
+				// analysis and share url identity with every other importer.
+				let entries = staticEntries;
+				if (!isBuild) {
+					const loaded = octaneConfig ?? (await loadStartupConfig(root))?.config ?? null;
+					entries = collect_hydrate_module_paths(loaded);
+				}
 				const file = write_project_generated_file(
 					config,
 					'client-entry.js',
 					create_client_entry_source({
 						configPath: to_vite_root_import(getOctaneConfigPath(root), root),
-						staticEntries,
+						staticEntries: entries,
 					}),
 				);
 				return fs.readFileSync(file, 'utf-8');
@@ -313,6 +420,22 @@ export function octane(inlineOptions = {}) {
 			return null;
 		},
 
+		/**
+		 * Observe the compiler's client output after the pre-transform. A generated
+		 * __serverRpc call is an exact, syntax-level signal that this source owns a
+		 * `module server`; production uses the collected paths as static SSR imports.
+		 */
+		transform(code, id, options) {
+			if (!isBuild || options?.ssr || !is_octane_module_path(id.split('?')[0])) return null;
+			if (!code.includes('_$__serverRpc(')) return null;
+			const file = id.split('?')[0];
+			const relative = path.relative(root, file);
+			const isWithinRoot =
+				relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative);
+			serverModuleModules.add(isWithinRoot ? '/' + relative.split(path.sep).join('/') : file);
+			return null;
+		},
+
 		/**
 		 * Dev SSR middleware. Registered as a pre-hook (no return) so it runs
 		 * BEFORE Vite's HTML fallback. Config is loaded lazily on first request
@@ -321,6 +444,9 @@ export function octane(inlineOptions = {}) {
 		 * @param {ViteDevServer} vite
 		 */
 		configureServer(vite) {
+			if (rendererConfigWatchFiles.size > 0) {
+				vite.watcher.add([...rendererConfigWatchFiles]);
+			}
 			/** @type {Promise<void> | null} */
 			let initPromise = null;
 			/** @type {number} */
@@ -493,6 +619,13 @@ export function octane(inlineOptions = {}) {
 			order: 'pre',
 			async handler({ file, modules, server }) {
 				if (this.environment.name !== 'client') return;
+				if (rendererConfigWatchFiles.has(path.resolve(file))) {
+					// Renderer rules and boundary metadata are immutable inputs to every
+					// compiler environment. Rebuild the plugin/compiler snapshot instead
+					// of letting later transforms observe a mixture of old and new config.
+					await server.restart();
+					return [];
+				}
 				if (modules.length > 0 && modules.every((m) => m.isSelfAccepting)) return;
 				if (!is_octane_module_path(file)) return;
 
@@ -521,8 +654,7 @@ export function octane(inlineOptions = {}) {
 			order: 'pre',
 			handler(html) {
 				if (!isBuild || isSSRBuild || !has_route_config(buildOctaneConfig)) return html;
-				const hydrationScript = `<script type="module" src="${VIRTUAL_HYDRATE_ID}"></script>`;
-				return html.replace('</body>', `${hydrationScript}\n</body>`);
+				return injectHydrationEntry(html, VIRTUAL_HYDRATE_ID, HYDRATION_NONCE_PLACEHOLDER);
 			},
 		},
 
@@ -550,7 +682,7 @@ export function octane(inlineOptions = {}) {
 			// tags the production server emits for the matched route).
 			// ------------------------------------------------------------------
 			const manifestPath = path.join(clientOutDir, '.vite', 'manifest.json');
-			/** @type {Record<string, { file: string, css?: string[], imports?: string[] }>} */
+			/** @type {Record<string, { file: string, src?: string, css?: string[], imports?: string[], dynamicImports?: string[] }>} */
 			let clientManifest = {};
 			if (fs.existsSync(manifestPath)) {
 				clientManifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
@@ -560,35 +692,7 @@ export function octane(inlineOptions = {}) {
 				);
 			}
 
-			/**
-			 * All CSS a manifest entry needs, transitively (cycle-safe).
-			 * @param {string} key
-			 * @param {Set<string>} [visited]
-			 * @returns {string[]}
-			 */
-			const collectCss = (key, visited = new Set()) => {
-				if (visited.has(key)) return [];
-				visited.add(key);
-				const entry = clientManifest[key];
-				if (!entry) return [];
-				const css = [...(entry.css || [])];
-				for (const imp of entry.imports || []) css.push(...collectCss(imp, visited));
-				return css;
-			};
-
-			/** @type {Record<string, { js: string, css: string[] }>} */
-			const clientAssetMap = {};
-			for (const moduleId of staticEntries) {
-				// Manifest keys are root-relative without the leading slash.
-				const manifestKey = moduleId.startsWith('/') ? moduleId.slice(1) : moduleId;
-				const manifestEntry = clientManifest[manifestKey];
-				if (manifestEntry) {
-					clientAssetMap[moduleId] = {
-						js: manifestEntry.file,
-						css: [...new Set(collectCss(manifestKey))],
-					};
-				}
-			}
+			const clientAssetMap = createClientAssetMap(clientManifest, staticEntries);
 
 			// The manifest was only needed here; leaving .vite/ in dist/client would
 			// publish source file paths through the static server.
@@ -605,7 +709,14 @@ export function octane(inlineOptions = {}) {
 				generateServerEntry({
 					routes: cfg.router.routes,
 					octaneConfigPath: getOctaneConfigPath(root),
+					rootBoundary: cfg.rootBoundary,
+					rpcModulePaths: [...serverModuleModules],
 					clientAssetMap,
+					// The virtual entry has no filesystem importer, so resolve app-core
+					// from this package before handing source to Vite. This also works
+					// when app-core is nested under the plugin by a package manager.
+					productionModuleId: requireFromPlugin.resolve('@octanejs/app-core/production'),
+					nodeModuleId: requireFromPlugin.resolve('@octanejs/app-core/node'),
 				}),
 			);
 
@@ -700,13 +811,60 @@ export function octane(inlineOptions = {}) {
 	// compiler's `.ts`/`.js` hook-slotting pass must skip. Hand-slot-forwarding
 	// bindings should not need it: they declare
 	// `"octane": { "hookSlots": { "manual": ["src"] } }` in their own package.json and the
-	// compiler plugin skips them via a nearest-manifest lookup (published
-	// bindings live in node_modules and are skipped outright).
+	// compiler plugin skips those directories via a nearest-manifest lookup.
+	// Other installed raw-source Octane packages are transformed automatically.
+	/**
+	 * @type {{
+	 *   hmr?: boolean,
+	 *   profile?: boolean,
+	 *   exclude?: string[],
+	 *   requireDirective?: boolean,
+	 *   renderers?: import('@octanejs/app-core').ExperimentalRendererConfigOptions,
+	 * }}
+	 */
 	const compilerOptions = {};
 	if (inlineOptions.hmr !== undefined) compilerOptions.hmr = inlineOptions.hmr;
+	if (inlineOptions.profile !== undefined) compilerOptions.profile = inlineOptions.profile;
 	if (inlineOptions.exclude !== undefined) compilerOptions.exclude = inlineOptions.exclude;
+	if (inlineOptions.requireDirective !== undefined) {
+		compilerOptions.requireDirective = inlineOptions.requireDirective;
+	}
+	if (inlineOptions.renderers !== undefined) compilerOptions.renderers = inlineOptions.renderers;
+	const compilerPlugin = /** @type {Plugin} */ (octaneCompiler(compilerOptions));
+	const compilerConfigHook = compilerPlugin.config;
+	if (typeof compilerConfigHook === 'function') {
+		compilerPlugin.config = function compilerConfigWithAppRenderers(userConfig, env) {
+			const projectRoot = userConfig.root ? path.resolve(userConfig.root) : process.cwd();
+			// Inline renderer metadata is an explicit full override. Preserve the
+			// synchronous no-config/inline path used by compiler-only SPA projects.
+			if (inlineOptions.renderers !== undefined) {
+				rendererConfigWatchFiles.clear();
+				return compilerConfigHook.call(this, userConfig, env);
+			}
+
+			const configPath = getOctaneConfigPath(projectRoot);
+			if (!octaneConfigExists(projectRoot)) {
+				delete compilerOptions.renderers;
+				rendererConfigWatchFiles.clear();
+				// A newly-created octane.config.ts can introduce renderer rules. Watch
+				// the missing path so dev restarts into the configured compiler.
+				rendererConfigWatchFiles.add(path.resolve(configPath));
+				return compilerConfigHook.call(this, userConfig, env);
+			}
+
+			return loadStartupConfig(projectRoot).then((loaded) => {
+				const config = /** @type {LoadedOctaneConfig} */ (loaded);
+				compilerOptions.renderers = config.config.compiler.renderers;
+				rendererConfigWatchFiles.clear();
+				for (const file of [...config.dependencies, ...config.missingDependencies]) {
+					rendererConfigWatchFiles.add(path.resolve(file));
+				}
+				return compilerConfigHook.call(this, userConfig, env);
+			});
+		};
+	}
 	// The compiler plugin is untyped JS (its `enforce` infers as `string`).
-	return [/** @type {Plugin} */ (octaneCompiler(compilerOptions)), metaPlugin];
+	return [compilerPlugin, metaPlugin];
 }
 
 // Mainly to enforce types / DX.