@octanejs/vite-plugin 0.1.6 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/vite-plugin",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -47,16 +47,17 @@
   },
   "dependencies": {
     "@ripple-ts/adapter": "^0.3.86",
-    "@octanejs/app-core": "0.0.2"
+    "@octanejs/app-core": "0.0.5"
   },
   "peerDependencies": {
     "vite": "^8.0.16",
-    "octane": "0.1.6"
+    "octane": "0.1.9"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
+    "playwright": "^1.61.0",
     "type-fest": "^5.6.0",
     "vite": "^8.0.16",
-    "octane": "0.1.6"
+    "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/index.js

@@ -1,6 +1,6 @@
 // @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';
@@ -33,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';
 
@@ -168,12 +169,37 @@ function has_route_config(config) {
 	return (config?.router.routes.length ?? 0) > 0;
 }
 
+/**
+ * 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
@@ -188,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 = {}) {
@@ -204,6 +230,15 @@ 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) */
@@ -211,6 +246,25 @@ export function octane(inlineOptions = {}) {
 	/** @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 = {
 		name: '@octanejs/vite-plugin',
@@ -274,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,
+							},
+						};
 					}
 				}
 			}
@@ -291,16 +366,7 @@ export function octane(inlineOptions = {}) {
 		buildStart() {
 			if (!isBuild || isSSRBuild || !has_route_config(buildOctaneConfig)) return;
 			serverModuleModules.clear();
-			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);
-			entries.push(
-				get_route_entry_path(cfg.rootBoundary.pending),
-				get_route_entry_path(cfg.rootBoundary.catch),
-			);
-			staticEntries = [...new Set(entries.filter((e) => typeof e === 'string'))];
+			staticEntries = collect_hydrate_module_paths(buildOctaneConfig);
 		},
 
 		async configResolved(resolvedConfig) {
@@ -324,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');
@@ -365,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} */
@@ -537,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;
 
@@ -593,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'));
@@ -603,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.
@@ -752,11 +813,58 @@ export function octane(inlineOptions = {}) {
 	// `"octane": { "hookSlots": { "manual": ["src"] } }` in their own package.json and the
 	// 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.

package/src/load-config.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import fs from 'node:fs';
+
 import {
 	getOctaneConfigPath,
 	loadOctaneConfig as loadCoreOctaneConfig,
@@ -78,9 +80,7 @@ async function withDefaultViteRunner(projectRoot, options, loader) {
 	try {
 		return await loader(projectRoot, {
 			...options,
-			moduleRunner: {
-				loadModule: (/** @type {string} */ id) => tempVite.ssrLoadModule(id),
-			},
+			moduleRunner: viteConfigModuleRunner(tempVite),
 		});
 	} finally {
 		await tempVite.close();
@@ -93,8 +93,51 @@ function withViteModuleRunner(options) {
 	const { vite, ...rest } = options;
 	return {
 		...rest,
-		moduleRunner: {
-			loadModule: (/** @type {string} */ id) => vite.ssrLoadModule(id),
+		moduleRunner: viteConfigModuleRunner(vite),
+	};
+}
+
+/**
+ * Adapt Vite's SSR runner and module graph to app-core's config-loader
+ * contract. Config evaluation itself is not enough: integrations also need
+ * the transitive file set so edits to imported renderer rules/boundary tables
+ * invalidate the compiler snapshot.
+ *
+ * @param {import('vite').ViteDevServer} vite
+ * @returns {import('@octanejs/app-core').ConfigModuleRunner}
+ */
+function viteConfigModuleRunner(vite) {
+	return {
+		loadModule: (/** @type {string} */ id) => vite.ssrLoadModule(id),
+		getDependencies(id) {
+			const graph = vite.environments.ssr.moduleGraph;
+			const roots = new Set();
+			const candidates = new Set([id]);
+			try {
+				// Vite canonicalizes graph IDs through realpath. Preserve the
+				// config loader's lexical path in its own metadata, but use both
+				// forms to find the root (notably /var -> /private/var on macOS).
+				candidates.add(fs.realpathSync(id));
+			} catch {
+				// The config loader reports the useful missing-file error.
+			}
+			for (const candidate of candidates) {
+				const byId = graph.getModuleById(candidate);
+				if (byId) roots.add(byId);
+				for (const module of graph.getModulesByFile(candidate) ?? []) roots.add(module);
+			}
+
+			const seen = new Set();
+			const dependencies = new Set();
+			/** @param {import('vite').EnvironmentModuleNode} module */
+			function visit(module) {
+				if (seen.has(module)) return;
+				seen.add(module);
+				if (module.file) dependencies.add(module.file);
+				for (const imported of module.importedModules) visit(imported);
+			}
+			for (const root of roots) visit(root);
+			return [...dependencies];
 		},
 	};
 }

package/types/index.d.ts

@@ -1,6 +1,7 @@
 import type { Plugin, ViteDevServer } from 'vite';
 import type {
 	ConfigModuleRunner,
+	ExperimentalRendererConfigOptions,
 	LoadedOctaneConfig,
 	OctaneConfigOptions,
 	ResolvedOctaneConfig,
@@ -11,11 +12,32 @@ export * from '@octanejs/app-core';
 export interface OctanePluginOptions {
 	/** Override the client HMR default (on in serve mode, off for SSR). */
 	hmr?: boolean;
+	/** Enable component profiling in client transforms. */
+	profile?: boolean;
 	/**
 	 * Path fragments the compiler's plain `.ts`/`.js` hook-slotting pass must
 	 * skip. Prefer package manifest `octane.hookSlots.manual` declarations.
+	 * With `requireDirective`, excluded paths are exempt from Octane ownership
+	 * entirely — including `.tsrx`/`.tsx` — for projects routing those paths
+	 * through a different tsrx compiler (e.g. `@tsrx/react`).
 	 */
 	exclude?: string[];
+	/**
+	 * Mixed-toolchain ownership gate: when `true`, Octane compiles only
+	 * project modules that declare `'use octane'` in their directive prologue.
+	 * Undirected project `.tsx`/`.ts`/`.js` pass through to the host
+	 * framework's own pipeline (e.g. React's JSX transform); an undirected
+	 * project `.tsrx` is a build error. Installed and linked packages keep
+	 * their Octane package-manifest decision. The directive is always
+	 * tolerated and stripped from compiled output, even when this is off.
+	 * @default false
+	 */
+	requireDirective?: boolean;
+	/**
+	 * @experimental Full renderer-config override. When omitted, the compiler
+	 * reads `compiler.renderers` from `octane.config.ts` before transforming modules.
+	 */
+	renderers?: ExperimentalRendererConfigOptions;
 }
 
 /** The Octane compiler plugin plus Vite app/metaframework integration. */