@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.6

package/src/adapters/bun/hmr-manager.test.ts

@@ -0,0 +1,267 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, test, vi } from 'vitest';
+import { ConfigBuilder } from '../../config/config-builder.ts';
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from '../../utils/resolve-work-dir.ts';
+import { HmrManager } from './hmr-manager.ts';
+
+const tempRoots: string[] = [];
+
+function createTempRoot(prefix: string): string {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+	tempRoots.push(root);
+	return root;
+}
+
+afterEach(() => {
+	for (const root of tempRoots.splice(0)) {
+		fs.rmSync(root, { recursive: true, force: true });
+	}
+	vi.restoreAllMocks();
+});
+
+test('HmrManager shares one in-flight entrypoint registration across concurrent callers', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-register');
+	const srcDir = path.join(rootDir, 'src');
+	const pagesDir = path.join(srcDir, 'pages');
+	fs.mkdirSync(pagesDir, { recursive: true });
+
+	const entrypointPath = path.join(pagesDir, 'react-lab.tsx');
+	fs.writeFileSync(entrypointPath, 'export default function Page() { return null; }', 'utf8');
+
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	const relativePathJs = path
+		.relative(config.absolutePaths.srcDir, entrypointPath)
+		.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+	const encodedPathJs = relativePathJs.replace(/\[([^\]]+)\]/g, '_$1_');
+	const outputPath = path.join(resolveInternalWorkDir(config), 'assets', '_hmr', encodedPathJs);
+
+	const handleFileChange = vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {
+		await new Promise((resolve) => setTimeout(resolve, 25));
+		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fs.writeFileSync(outputPath, 'export default 1;', 'utf8');
+	});
+
+	const [firstUrl, secondUrl] = await Promise.all([
+		manager.registerEntrypoint(entrypointPath),
+		manager.registerEntrypoint(entrypointPath),
+	]);
+
+	assert.equal(firstUrl, '/assets/_hmr/pages/react-lab.js');
+	assert.equal(secondUrl, '/assets/_hmr/pages/react-lab.js');
+	assert.equal(handleFileChange.mock.calls.length, 1);
+	assert.equal(fs.existsSync(outputPath), true);
+
+	manager.stop();
+});
+
+test('HmrManager clears timed-out entrypoint registrations so later requests can retry', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-timeout-register');
+	const srcDir = path.join(rootDir, 'src');
+	const pagesDir = path.join(srcDir, 'pages');
+	fs.mkdirSync(pagesDir, { recursive: true });
+
+	const entrypointPath = path.join(pagesDir, 'stuck-page.tsx');
+	fs.writeFileSync(entrypointPath, 'export default function Page() { return null; }', 'utf8');
+
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	const previousNodeEnv = process.env.NODE_ENV;
+	process.env.NODE_ENV = 'development';
+
+	const handleFileChange = vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {
+		await new Promise(() => undefined);
+	});
+
+	try {
+		await assert.rejects(() => manager.registerEntrypoint(entrypointPath), /Timed out registering entrypoint/);
+
+		const registrations = (manager as unknown as { entrypointRegistrations: Map<string, Promise<string>> })
+			.entrypointRegistrations;
+		const watchedFiles = manager.getWatchedFiles();
+		assert.equal(registrations.size, 0);
+		assert.equal(watchedFiles.has(entrypointPath), false);
+
+		handleFileChange.mockImplementationOnce(async () => {
+			const relativePathJs = path
+				.relative(config.absolutePaths.srcDir, entrypointPath)
+				.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+			const encodedPathJs = relativePathJs.replace(/\[([^\]]+)\]/g, '_$1_');
+			const outputPath = path.join(resolveInternalWorkDir(config), 'assets', '_hmr', encodedPathJs);
+			fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+			fs.writeFileSync(outputPath, 'export default 2;', 'utf8');
+		});
+
+		const retriedUrl = await manager.registerEntrypoint(entrypointPath);
+		assert.equal(retriedUrl, '/assets/_hmr/pages/stuck-page.js');
+		assert.equal(watchedFiles.get(entrypointPath), retriedUrl);
+	} finally {
+		process.env.NODE_ENV = previousNodeEnv;
+		manager.stop();
+	}
+});
+
+test('HmrManager fails strict entrypoint registration when the owning integration emits no output', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-strict-fail');
+	const srcDir = path.join(rootDir, 'src');
+	const pagesDir = path.join(srcDir, 'pages');
+	fs.mkdirSync(pagesDir, { recursive: true });
+
+	const entrypointPath = path.join(pagesDir, 'react-content.mdx');
+	fs.writeFileSync(entrypointPath, '# Hello', 'utf8');
+
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {});
+
+	await assert.rejects(() => manager.registerEntrypoint(entrypointPath), /Integration failed to emit entrypoint/);
+	assert.equal(manager.getWatchedFiles().has(path.resolve(entrypointPath)), false);
+
+	manager.stop();
+});
+
+test('HmrManager uses the generic build path for script entrypoints when no strategy emits output', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-script-fallback');
+	const srcDir = path.join(rootDir, 'src');
+	fs.mkdirSync(srcDir, { recursive: true });
+
+	const entrypointPath = path.join(srcDir, 'script.ts');
+	fs.writeFileSync(entrypointPath, 'console.log("hello");', 'utf8');
+
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	const outputPath = path.join(resolveInternalWorkDir(config), 'assets', '_hmr', 'script.js');
+	const buildCalls: string[] = [];
+	config.runtime!.buildExecutor = {
+		build: vi.fn(async (options) => {
+			buildCalls.push(options.entrypoints[0] as string);
+			fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+			fs.writeFileSync(outputPath, 'fresh-output', 'utf8');
+
+			return {
+				success: true,
+				logs: [],
+				outputs: [{ path: outputPath }],
+			};
+		}),
+	};
+
+	vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {});
+
+	const outputUrl = await manager.registerScriptEntrypoint(entrypointPath);
+
+	assert.equal(outputUrl, '/assets/_hmr/script.js');
+	assert.deepEqual(buildCalls, [entrypointPath]);
+	assert.equal(fs.readFileSync(outputPath, 'utf8'), 'fresh-output');
+
+	manager.stop();
+});
+
+test('HmrManager stop clears retained registration state', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-stop-cleanup');
+	const srcDir = path.join(rootDir, 'src');
+	const pagesDir = path.join(srcDir, 'pages');
+	fs.mkdirSync(pagesDir, { recursive: true });
+
+	const entrypointPath = path.join(pagesDir, 'react-content.tsx');
+	fs.writeFileSync(entrypointPath, 'export default function Page() { return null; }', 'utf8');
+
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	const relativePathJs = path
+		.relative(config.absolutePaths.srcDir, entrypointPath)
+		.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+	const encodedPathJs = relativePathJs.replace(/\[([^\]]+)\]/g, '_$1_');
+	const outputPath = path.join(resolveInternalWorkDir(config), 'assets', '_hmr', encodedPathJs);
+
+	vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {
+		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fs.writeFileSync(outputPath, 'export default 1;', 'utf8');
+	});
+
+	manager.registerSpecifierMap({ react: '/assets/vendors/react.js' });
+	await manager.registerEntrypoint(entrypointPath);
+
+	manager.stop();
+
+	assert.equal(manager.getWatchedFiles().size, 0);
+	assert.equal(manager.getSpecifierMap().size, 0);
+});
+
+test('HmrManager keeps internal browser and server-module outputs out of distDir', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-internal-paths');
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	assert.equal(manager.getDistDir(), path.join(resolveInternalWorkDir(config), 'assets', '_hmr'));
+
+	const importModule = vi.fn(async (_options: { outdir: string }) => ({}));
+	(manager as unknown as { serverModuleTranspiler: { importModule: typeof importModule } }).serverModuleTranspiler = {
+		importModule,
+	};
+
+	await manager.getDefaultContext().importServerModule(path.join(config.absolutePaths.srcDir, 'pages', 'index.tsx'));
+
+	assert.equal(
+		importModule.mock.calls[0]?.[0]?.outdir,
+		path.join(resolveInternalExecutionDir(config), '.server-modules'),
+	);
+
+	manager.stop();
+});

package/src/adapters/bun/hmr-manager.ts

@@ -2,17 +2,27 @@ import fs from 'node:fs';
 import path from 'node:path';
 import type { ServerWebSocket, WebSocketHandler } from 'bun';
 import { RESOLVED_ASSETS_DIR } from '../../constants';
-import { defaultBuildAdapter } from '../../build/build-adapter.ts';
+import { getAppBuildExecutor } from '../../build/build-adapter.ts';
 import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager } from '../../internal-types';
 import type { EcoBuildPlugin } from '../../build/build-types.ts';
 import { fileSystem } from '@ecopages/file-system';
-import type { HmrStrategy } from '../../hmr/hmr-strategy';
-import { HmrStrategyType } from '../../hmr/hmr-strategy';
+import { HmrStrategyType, type HmrStrategy } from '../../hmr/hmr-strategy';
 import { DefaultHmrStrategy } from '../../hmr/strategies/default-hmr-strategy';
 import { JsHmrStrategy } from '../../hmr/strategies/js-hmr-strategy';
 import { appLogger } from '../../global/app-logger';
 import type { ClientBridge } from './client-bridge';
 import type { ClientBridgeEvent } from '../../public-types';
+import { HmrEntrypointRegistrar } from '../shared/hmr-entrypoint-registrar.ts';
+import { BrowserBundleService } from '../../services/assets/browser-bundle.service.ts';
+import { getAppServerModuleTranspiler } from '../../services/module-loading/app-server-module-transpiler.service';
+import {
+	getAppEntrypointDependencyGraph,
+	NoopEntrypointDependencyGraph,
+	setAppEntrypointDependencyGraph,
+} from '../../services/runtime-state/entrypoint-dependency-graph.service.ts';
+import { getAppRuntimeSpecifierRegistry } from '../../services/runtime-state/runtime-specifier-registry.service.ts';
+import type { ServerModuleTranspiler } from '../../services/module-loading/server-module-transpiler.service';
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from '../../utils/resolve-work-dir.ts';
 
 type BunSocket = ServerWebSocket<unknown>;
 type BunSocketHandler = WebSocketHandler<unknown>;
@@ -22,19 +32,36 @@ export interface HmrManagerParams {
 	bridge: ClientBridge;
 }
 
+type HandleFileChangeOptions = {
+	broadcast?: boolean;
+};
+
+/**
+ * Bun development HMR manager.
+ *
+ * @remarks
+ * Bun shares the same public contract as the Node manager: page entrypoints are
+ * strict integration-owned registrations, while generic script assets use their
+ * own explicit registration path.
+ */
 export class HmrManager implements IHmrManager {
+	private static readonly entrypointRegistrationTimeoutMs = 4000;
 	public readonly appConfig: EcoPagesAppConfig;
 	private readonly bridge: ClientBridge;
 	/** Keep track of watchers */
 	private watchers = new Map<string, fs.FSWatcher>();
 	/** entrypoint -> output path */
 	private watchedFiles = new Map<string, string>();
-	/** bare specifier -> runtime URL (e.g., 'react' -> '/assets/vendors/react.js') */
-	private specifierMap = new Map<string, string>();
+	private entrypointRegistrations = new Map<string, Promise<string>>();
 	private distDir: string;
 	private plugins: EcoBuildPlugin[] = [];
 	private enabled = true;
 	private strategies: HmrStrategy[] = [];
+	private readonly entrypointRegistrar: HmrEntrypointRegistrar;
+	private readonly browserBundleService: BrowserBundleService;
+	private readonly entrypointDependencyGraph: ReturnType<typeof getAppEntrypointDependencyGraph>;
+	private readonly runtimeSpecifierRegistry: ReturnType<typeof getAppRuntimeSpecifierRegistry>;
+	private readonly serverModuleTranspiler: ServerModuleTranspiler;
 	private wsHandler!: {
 		open: (ws: BunSocket) => void;
 		close: (ws: BunSocket) => void;
@@ -43,7 +70,24 @@ export class HmrManager implements IHmrManager {
 	constructor({ appConfig, bridge }: HmrManagerParams) {
 		this.appConfig = appConfig;
 		this.bridge = bridge;
-		this.distDir = path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR, '_hmr');
+		this.distDir = path.join(resolveInternalWorkDir(this.appConfig), RESOLVED_ASSETS_DIR, '_hmr');
+		this.entrypointRegistrar = new HmrEntrypointRegistrar({
+			srcDir: this.appConfig.absolutePaths.srcDir,
+			distDir: this.distDir,
+			entrypointRegistrations: this.entrypointRegistrations,
+			watchedFiles: this.watchedFiles,
+			clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath),
+			registrationTimeoutMs: HmrManager.entrypointRegistrationTimeoutMs,
+		});
+		this.browserBundleService = new BrowserBundleService(appConfig);
+		const existingEntrypointDependencyGraph = getAppEntrypointDependencyGraph(appConfig);
+		this.entrypointDependencyGraph =
+			existingEntrypointDependencyGraph instanceof NoopEntrypointDependencyGraph
+				? existingEntrypointDependencyGraph
+				: new NoopEntrypointDependencyGraph();
+		setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
+		this.runtimeSpecifierRegistry = getAppRuntimeSpecifierRegistry(this.appConfig);
+		this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
 		this.cleanDistDir();
 		this.initializeStrategies();
 	}
@@ -58,6 +102,29 @@ export class HmrManager implements IHmrManager {
 		fileSystem.ensureDir(this.distDir);
 	}
 
+	/**
+	 * Returns whether the generic JS strategy may rebuild an entrypoint.
+	 *
+	 * @remarks
+	 * Integration-owned page entrypoints are excluded so a shared dependency
+	 * invalidation cannot replace framework-owned browser output with a generic JS
+	 * rebuild.
+	 */
+	private shouldJsStrategyProcessEntrypoint(entrypointPath: string): boolean {
+		return !this.strategies.some((strategy) => {
+			if (strategy.type !== HmrStrategyType.INTEGRATION || strategy.priority <= HmrStrategyType.SCRIPT) {
+				return false;
+			}
+
+			try {
+				return strategy.matches(entrypointPath);
+			} catch (error) {
+				appLogger.error(error);
+				return false;
+			}
+		});
+	}
+
 	/**
 	 * Initializes core HMR strategies.
 	 * Strategies are evaluated in priority order (highest first).
@@ -65,10 +132,16 @@ export class HmrManager implements IHmrManager {
 	private initializeStrategies(): void {
 		const jsContext = {
 			getWatchedFiles: () => this.watchedFiles,
-			getSpecifierMap: () => this.specifierMap,
+			getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
 			getDistDir: () => this.distDir,
 			getPlugins: () => this.plugins,
 			getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+			getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+			getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+			getTemplateExtensions: () => this.appConfig.templatesExt,
+			getBrowserBundleService: () => this.browserBundleService,
+			getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+			shouldProcessEntrypoint: (entrypointPath: string) => this.shouldJsStrategyProcessEntrypoint(entrypointPath),
 		};
 
 		this.strategies = [new JsHmrStrategy(jsContext), new DefaultHmrStrategy()];
@@ -96,14 +169,16 @@ export class HmrManager implements IHmrManager {
 	}
 
 	/**
-	 * Registers a mapping from bare specifiers to vendor URLs.
-	 * Used by integrations to provide their module resolution mappings.
-	 * @param map - Object mapping bare specifiers to vendor URLs
+	 * Registers runtime bare-specifier mappings exposed by integrations.
+	 *
+	 * @remarks
+	 * These mappings are consumed by framework-owned HMR strategies that preserve
+	 * shared runtime imports in browser bundles. The registry stays generic so
+	 * these mappings can later support broader import-map-style runtime features
+	 * without moving integration semantics into core.
 	 */
 	public registerSpecifierMap(map: Record<string, string>): void {
-		for (const [specifier, url] of Object.entries(map)) {
-			this.specifierMap.set(specifier, url);
-		}
+		this.runtimeSpecifierRegistry.register(map);
 	}
 
 	public getWebSocketHandler(): BunSocketHandler {
@@ -134,12 +209,12 @@ export class HmrManager implements IHmrManager {
 	public async buildRuntime(): Promise<void> {
 		const runtimeSource = path.resolve(import.meta.dirname, '../../hmr/client/hmr-runtime.ts');
 
-		const result = await defaultBuildAdapter.build({
+		const result = await this.browserBundleService.bundle({
+			profile: 'hmr-runtime',
 			entrypoints: [runtimeSource],
 			outdir: this.distDir,
 			naming: '_hmr_runtime.js',
 			minify: false,
-			...defaultBuildAdapter.getTranspileOptions('hmr-runtime'),
 			plugins: this.plugins,
 		});
 
@@ -159,32 +234,13 @@ export class HmrManager implements IHmrManager {
 		this.bridge.broadcast(event);
 	}
 
-	public canHandleFileChange(filePath: string): boolean {
-		const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
-		const strategy = sorted.find((candidate) => {
-			try {
-				return candidate.matches(filePath);
-			} catch (err) {
-				appLogger.error(`[HmrManager] Error checking match for ${candidate.constructor.name}:`, err as Error);
-				return false;
-			}
-		});
-
-		return strategy !== undefined && strategy.type !== HmrStrategyType.FALLBACK;
-	}
-
-	/**
-	 * Handles file changes using registered HMR strategies.
-	 * Strategies are evaluated in priority order until one matches.
-	 * @param filePath - Absolute path to the changed file
-	 */
-	public async handleFileChange(filePath: string): Promise<void> {
+	public async handleFileChange(filePath: string, options: HandleFileChangeOptions = {}): Promise<void> {
 		const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
 		const strategy = sorted.find((s) => {
 			try {
 				return s.matches(filePath);
 			} catch (err) {
-				appLogger.error(`[HmrManager] Error checking match for ${s.constructor.name}:`, err as Error);
+				appLogger.error(err);
 				return false;
 			}
 		});
@@ -197,8 +253,9 @@ export class HmrManager implements IHmrManager {
 		appLogger.debug(`[HmrManager] Selected strategy: ${strategy.constructor.name}`);
 
 		const action = await strategy.process(filePath);
+		const shouldBroadcast = options.broadcast ?? true;
 
-		if (action.type === 'broadcast') {
+		if (shouldBroadcast && action.type === 'broadcast') {
 			if (action.events) {
 				for (const event of action.events) {
 					this.broadcast(event);
@@ -207,9 +264,6 @@ export class HmrManager implements IHmrManager {
 		}
 	}
 
-	/**
-	 * Registers a client entrypoint to be built and watched by Bun.
-	 */
 	public getOutputUrl(entrypointPath: string): string | undefined {
 		return this.watchedFiles.get(entrypointPath);
 	}
@@ -219,7 +273,7 @@ export class HmrManager implements IHmrManager {
 	}
 
 	public getSpecifierMap(): Map<string, string> {
-		return this.specifierMap;
+		return this.runtimeSpecifierRegistry.getAll();
 	}
 
 	public getDistDir(): string {
@@ -233,64 +287,123 @@ export class HmrManager implements IHmrManager {
 	public getDefaultContext(): DefaultHmrContext {
 		return {
 			getWatchedFiles: () => this.watchedFiles,
-			getSpecifierMap: () => this.specifierMap,
+			getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
 			getDistDir: () => this.distDir,
 			getPlugins: () => this.plugins,
 			getSrcDir: () => this.appConfig.absolutePaths.srcDir,
 			getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
 			getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+			getBuildExecutor: () => getAppBuildExecutor(this.appConfig),
+			getBrowserBundleService: () => this.browserBundleService,
+			importServerModule: async <T>(filePath: string) =>
+				await this.serverModuleTranspiler.importModule<T>({
+					filePath,
+					outdir: path.join(resolveInternalExecutionDir(this.appConfig), '.server-modules'),
+					externalPackages: true,
+				}),
 		};
 	}
 
+	private clearFailedEntrypointRegistration(entrypointPath: string): void {
+		this.watchedFiles.delete(entrypointPath);
+	}
+
+	/**
+	 * Registers one integration-owned page entrypoint.
+	 *
+	 * @remarks
+	 * Concurrent callers share one in-flight registration. The registration is
+	 * cleared from the dedupe map when it settles so later callers cannot inherit a
+	 * stale promise.
+	 */
 	public async registerEntrypoint(entrypointPath: string): Promise<string> {
-		if (this.watchedFiles.has(entrypointPath)) {
-			return this.watchedFiles.get(entrypointPath)!;
-		}
+		return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+			emit: async (normalizedEntrypoint, outputPath) =>
+				await this.emitStrictEntrypoint(normalizedEntrypoint, outputPath),
+			getMissingOutputError: (normalizedEntrypoint, outputPath) =>
+				new Error(
+					`[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`,
+				),
+		});
+	}
 
-		const srcDir = this.appConfig.absolutePaths.srcDir;
-		const relativePath = path.relative(srcDir, entrypointPath);
-		const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
-		const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
+	/**
+	 * Registers one generic script entrypoint.
+	 *
+	 * @remarks
+	 * This explicit path keeps the page-entrypoint contract strict while still
+	 * allowing generic script assets to use the fallback build path.
+	 */
+	public async registerScriptEntrypoint(entrypointPath: string): Promise<string> {
+		return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+			emit: async (normalizedEntrypoint, outputPath) =>
+				await this.emitScriptEntrypoint(normalizedEntrypoint, outputPath),
+			getMissingOutputError: (normalizedEntrypoint) =>
+				new Error(`[HMR] Failed to register script entrypoint: ${normalizedEntrypoint}`),
+		});
+	}
 
-		const urlPath = encodedPathJs.split(path.sep).join('/');
-		const outputUrl = `/${path.join(RESOLVED_ASSETS_DIR, '_hmr', urlPath)}`;
-		const outputPath = path.join(this.distDir, urlPath);
+	/**
+	 * Performs strict integration-owned registration for one normalized path.
+	 *
+	 * @remarks
+	 * The manager reserves the output URL, removes any stale emitted file, runs
+	 * strategy processing without broadcasting, and then verifies that the owning
+	 * integration emitted the expected file.
+	 */
+	private async emitStrictEntrypoint(entrypointPath: string, _outputPath: string): Promise<void> {
+		await this.handleFileChange(entrypointPath, { broadcast: false });
+	}
 
-		this.watchedFiles.set(entrypointPath, outputUrl);
+	/**
+	 * Performs registration for a generic script asset.
+	 *
+	 * @remarks
+	 * Strategies get the first chance to emit output. If no output exists after
+	 * that pass, Bun falls back to the generic browser build for this explicit
+	 * script-only path.
+	 */
+	private async emitScriptEntrypoint(entrypointPath: string, outputPath: string): Promise<void> {
+		const naming = path.relative(this.distDir, outputPath).split(path.sep).join('/');
 
-		await this.handleFileChange(entrypointPath);
+		await this.handleFileChange(entrypointPath, { broadcast: false });
 
 		if (!fileSystem.exists(outputPath)) {
-			const fallback = await defaultBuildAdapter.build({
+			const buildResult = await this.browserBundleService.bundle({
+				profile: 'hmr-entrypoint',
 				entrypoints: [entrypointPath],
 				outdir: this.distDir,
-				naming: encodedPathJs,
+				naming,
 				minify: false,
-				external: Array.from(this.specifierMap.keys()),
-				...defaultBuildAdapter.getTranspileOptions('hmr-entrypoint'),
 				plugins: this.plugins,
 			});
 
-			if (!fallback.success) {
-				appLogger.error(`[HMR] Fallback build failed for ${entrypointPath}:`, fallback.logs);
+			if (!buildResult.success) {
+				appLogger.error(
+					`[HMR] Generic script entrypoint build failed for ${entrypointPath}:`,
+					buildResult.logs,
+				);
 			}
 		}
-
-		return outputUrl;
 	}
 
 	/**
-	 * Encodes dynamic route segments (brackets) in file paths.
-	 * Converts `[slug]` to `_slug_` to avoid filesystem/URL issues.
+	 * Stops active watchers and releases retained registration state.
+	 *
+	 * @remarks
+	 * Emitted `_hmr` files remain on disk because parallel app processes may share
+	 * the same dist directory. The in-memory indexes are cleared so stale
+	 * entrypoints and specifier maps cannot leak through a reused manager object.
 	 */
-	private encodeDynamicSegments(filepath: string): string {
-		return filepath.replace(/\[([^\]]+)\]/g, '_$1_');
-	}
-
 	public stop() {
+		this.entrypointRegistrations.clear();
 		for (const watcher of this.watchers.values()) {
 			watcher.close();
 		}
 		this.watchers.clear();
+		this.watchedFiles.clear();
+		this.runtimeSpecifierRegistry.clear();
+		this.entrypointDependencyGraph.reset();
+		this.plugins = [];
 	}
 }

package/src/adapters/bun/index.ts

@@ -1,3 +1,2 @@
 export { EcopagesApp, createApp } from './create-app.ts';
-export { defineApiHandler, defineGroupHandler } from './define-api-handler.ts';
-export type { GroupHandler } from './define-api-handler.ts';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from '../shared/define-api-handler.ts';