@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.27

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

@@ -0,0 +1,320 @@
+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 { NodeHmrManager } from './node-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('NodeHmrManager shares one in-flight entrypoint registration across concurrent callers', async () => {
+	const rootDir = createTempRoot('ecopages-node-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 NodeHmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+		} 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('NodeHmrManager does not broadcast HMR events for initial entrypoint registration builds', async () => {
+	const rootDir = createTempRoot('ecopages-node-hmr-silent-register');
+	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 broadcast = vi.fn();
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new NodeHmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 1,
+			broadcast,
+		} 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 (_filePath, _options) => {
+		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fs.writeFileSync(outputPath, 'export default 1;', 'utf8');
+	});
+
+	const outputUrl = await manager.registerEntrypoint(entrypointPath);
+
+	assert.equal(outputUrl, '/assets/_hmr/pages/react-content.js');
+	assert.equal(broadcast.mock.calls.length, 0);
+
+	manager.stop();
+});
+
+test('NodeHmrManager clears timed-out entrypoint registrations so later requests can retry', async () => {
+	const rootDir = createTempRoot('ecopages-node-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 NodeHmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+		} 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('NodeHmrManager fails strict entrypoint registration when the owning integration emits no output', async () => {
+	const rootDir = createTempRoot('ecopages-node-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 NodeHmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+		} 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('NodeHmrManager uses the generic build path for script entrypoints when no strategy emits output', async () => {
+	const rootDir = createTempRoot('ecopages-node-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 NodeHmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+		} as any,
+	});
+
+	const relativePathJs = path
+		.relative(config.absolutePaths.srcDir, entrypointPath)
+		.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+	const outputPath = path.join(resolveInternalWorkDir(config), 'assets', '_hmr', relativePathJs);
+
+	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('NodeHmrManager disables HMR instead of throwing when runtime bundle generation crashes', async () => {
+	const rootDir = createTempRoot('ecopages-node-hmr-runtime-failure');
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new NodeHmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+		} as any,
+	});
+	const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+	vi.spyOn(
+		(manager as unknown as { browserBundleService: { bundle: () => Promise<unknown> } }).browserBundleService,
+		'bundle',
+	).mockRejectedValueOnce(new Error('Unexpected end of JSON input'));
+
+	await assert.doesNotReject(() => manager.buildRuntime());
+	assert.equal(manager.isEnabled(), false);
+
+	manager.stop();
+	errorSpy.mockRestore();
+});
+
+test('NodeHmrManager stop clears retained registration state', async () => {
+	const rootDir = createTempRoot('ecopages-node-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 NodeHmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+		} 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');
+	});
+
+	await manager.registerEntrypoint(entrypointPath);
+
+	manager.stop();
+
+	assert.equal(manager.getWatchedFiles().size, 0);
+	assert.equal(config.runtime?.entrypointDependencyGraph?.getDependencyEntrypoints(entrypointPath).size, 0);
+});
+
+test('NodeHmrManager keeps internal browser and server-module outputs out of distDir', async () => {
+	const rootDir = createTempRoot('ecopages-node-hmr-internal-paths');
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new NodeHmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+		} 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/node/node-hmr-manager.ts

@@ -0,0 +1,355 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { RESOLVED_ASSETS_DIR } from '../../config/constants.ts';
+import { getAppBuildExecutor } from '../../build/build-adapter.ts';
+import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge } from '../../types/internal-types.ts';
+import type { EcoBuildPlugin } from '../../build/build-types.ts';
+import { fileSystem } from '@ecopages/file-system';
+import { HmrStrategyType, type HmrStrategy } from '../../hmr/hmr-strategy.ts';
+import { DefaultHmrStrategy } from '../../hmr/strategies/default-hmr-strategy.ts';
+import { JsHmrStrategy } from '../../hmr/strategies/js-hmr-strategy.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import type { ClientBridgeEvent } from '../../types/public-types.ts';
+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.ts';
+import {
+	getAppEntrypointDependencyGraph,
+	InMemoryEntrypointDependencyGraph,
+	setAppEntrypointDependencyGraph,
+	type EntrypointDependencyGraph,
+} from '../../services/runtime-state/entrypoint-dependency-graph.service.ts';
+import type { ServerModuleTranspiler } from '../../services/module-loading/server-module-transpiler.service.ts';
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from '../../utils/resolve-work-dir.ts';
+
+export interface NodeHmrManagerParams {
+	appConfig: EcoPagesAppConfig;
+	bridge: IClientBridge;
+}
+
+type HandleFileChangeOptions = {
+	broadcast?: boolean;
+};
+
+/**
+ * Node development HMR manager.
+ *
+ * @remarks
+ * This manager owns three separate concerns:
+ * - runtime websocket event fanout
+ * - entrypoint registration and dedupe
+ * - strategy coordination for rebuilds and invalidation
+ *
+ * The strict page-entrypoint contract lives here: `registerEntrypoint()` is
+ * reserved for integration-owned page bundles, while generic script assets must
+ * go through `registerScriptEntrypoint()`.
+ */
+export class NodeHmrManager implements IHmrManager {
+	private static readonly entrypointRegistrationTimeoutMs = 4000;
+	public readonly appConfig: EcoPagesAppConfig;
+	private readonly bridge: IClientBridge;
+	private watchers = new Map<string, fs.FSWatcher>();
+	private watchedFiles = 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: EntrypointDependencyGraph;
+	private readonly serverModuleTranspiler: ServerModuleTranspiler;
+
+	constructor({ appConfig, bridge }: NodeHmrManagerParams) {
+		this.appConfig = appConfig;
+		this.bridge = bridge;
+		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: NodeHmrManager.entrypointRegistrationTimeoutMs,
+		});
+		this.browserBundleService = new BrowserBundleService(appConfig);
+		const existingEntrypointDependencyGraph = getAppEntrypointDependencyGraph(appConfig);
+		this.entrypointDependencyGraph =
+			existingEntrypointDependencyGraph instanceof InMemoryEntrypointDependencyGraph
+				? existingEntrypointDependencyGraph
+				: new InMemoryEntrypointDependencyGraph();
+		setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
+		this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
+		this.cleanDistDir();
+		this.initializeStrategies();
+	}
+
+	/**
+	 * Ensures the HMR output directory exists.
+	 *
+	 * This must not remove the directory because multiple app processes
+	 * can share the same dist path during e2e runs.
+	 */
+	private cleanDistDir(): void {
+		fileSystem.ensureDir(this.distDir);
+	}
+
+	/**
+	 * Returns whether the generic JS strategy is allowed to rebuild an entrypoint.
+	 *
+	 * @remarks
+	 * Higher-priority integration strategies own framework page entrypoints. When
+	 * one of them matches, the generic JS strategy must stay out of the way so a
+	 * shared dependency invalidation does not overwrite framework-specific output.
+	 */
+	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;
+			}
+		});
+	}
+
+	private initializeStrategies(): void {
+		const jsContext = {
+			getWatchedFiles: () => this.watchedFiles,
+			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()];
+	}
+
+	public registerStrategy(strategy: HmrStrategy): void {
+		this.strategies.push(strategy);
+	}
+
+	public setPlugins(plugins: EcoBuildPlugin[]): void {
+		this.plugins = [...plugins];
+	}
+
+	public setEnabled(enabled: boolean): void {
+		this.enabled = enabled;
+	}
+
+	public isEnabled(): boolean {
+		return this.enabled;
+	}
+
+	public async buildRuntime(): Promise<void> {
+		const runtimeSource = path.resolve(import.meta.dirname, '../../hmr/client/hmr-runtime.ts');
+
+		try {
+			const result = await this.browserBundleService.bundle({
+				profile: 'hmr-runtime',
+				entrypoints: [runtimeSource],
+				outdir: this.distDir,
+				naming: '_hmr_runtime.js',
+				minify: false,
+				plugins: this.plugins,
+			});
+
+			if (!result.success) {
+				this.enabled = false;
+				appLogger.error('[HMR] Failed to build runtime script; continuing with HMR disabled.', result.logs);
+			}
+		} catch (error) {
+			this.enabled = false;
+			appLogger.error('[HMR] Failed to build runtime script; continuing with HMR disabled.', error);
+		}
+	}
+
+	public getRuntimePath(): string {
+		return path.join(this.distDir, '_hmr_runtime.js');
+	}
+
+	public broadcast(event: ClientBridgeEvent) {
+		appLogger.debug(
+			`[HMR] Broadcasting ${event.type} event, path=${event.path || 'all'}, subscribers=${this.bridge.subscriberCount}`,
+		);
+		this.bridge.broadcast(event);
+	}
+
+	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(err);
+				return false;
+			}
+		});
+
+		if (!strategy) {
+			appLogger.warn(`[HMR] No strategy found for ${filePath}`);
+			return;
+		}
+
+		appLogger.debug(`[NodeHmrManager] Selected strategy: ${strategy.constructor.name}`);
+
+		const action = await strategy.process(filePath);
+		const shouldBroadcast = options.broadcast ?? true;
+
+		if (shouldBroadcast && action.type === 'broadcast') {
+			if (action.events) {
+				for (const event of action.events) {
+					this.broadcast(event);
+				}
+			}
+		}
+	}
+
+	public getOutputUrl(entrypointPath: string): string | undefined {
+		return this.watchedFiles.get(entrypointPath);
+	}
+
+	public getWatchedFiles(): Map<string, string> {
+		return this.watchedFiles;
+	}
+
+	public getDistDir(): string {
+		return this.distDir;
+	}
+
+	public getPlugins(): EcoBuildPlugin[] {
+		return this.plugins;
+	}
+
+	public getDefaultContext(): DefaultHmrContext {
+		return {
+			getWatchedFiles: () => this.watchedFiles,
+			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);
+		this.entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath);
+	}
+
+	/**
+	 * Registers one integration-owned page entrypoint.
+	 *
+	 * @remarks
+	 * Concurrent callers share one in-flight registration. The registration is
+	 * removed from the dedupe map once it resolves or fails so later requests do
+	 * not inherit stale state.
+	 */
+	public async registerEntrypoint(entrypointPath: string): Promise<string> {
+		return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+			emit: async (normalizedEntrypoint) => await this.emitStrictEntrypoint(normalizedEntrypoint),
+			getMissingOutputError: (normalizedEntrypoint, outputPath) =>
+				new Error(
+					`[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`,
+				),
+		});
+	}
+
+	/**
+	 * Registers one generic script entrypoint.
+	 *
+	 * @remarks
+	 * This path is intentionally separate from page entrypoints so non-framework
+	 * scripts can still use the generic build fallback without weakening the page
+	 * ownership contract.
+	 */
+	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}`),
+		});
+	}
+
+	/**
+	 * Performs strict integration-owned entrypoint registration for one normalized source path.
+	 *
+	 * @remarks
+	 * The flow is:
+	 * 1. Reserve the output URL in the watched map.
+	 * 2. Remove any stale emitted file from an earlier process or failed build.
+	 * 3. Let the strategy chain try to emit the entrypoint without broadcasting.
+	 * 4. Fail if the owning integration did not emit the expected output.
+	 */
+	private async emitStrictEntrypoint(entrypointPath: string): Promise<void> {
+		await this.handleFileChange(entrypointPath, { broadcast: false });
+	}
+
+	/**
+	 * Performs registration for a generic script asset.
+	 *
+	 * @remarks
+	 * This path performs a targeted browser bundle for the requested script
+	 * entrypoint only. The resulting dependency graph is retained so later file
+	 * changes can invalidate just the affected script entrypoints.
+	 */
+	private async emitScriptEntrypoint(entrypointPath: string, outputPath: string): Promise<void> {
+		const naming = path.relative(this.distDir, outputPath).split(path.sep).join('/');
+		const buildResult = await this.browserBundleService.bundle({
+			profile: 'hmr-entrypoint',
+			entrypoints: [entrypointPath],
+			outdir: this.distDir,
+			naming,
+			minify: false,
+			plugins: this.plugins,
+		});
+
+		if (!buildResult.success) {
+			appLogger.error(`[HMR] Generic script entrypoint build failed for ${entrypointPath}:`, buildResult.logs);
+			return;
+		}
+
+		const entrypointDependencies = buildResult.dependencyGraph?.entrypoints?.[entrypointPath];
+		if (entrypointDependencies) {
+			this.entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, entrypointDependencies);
+		}
+	}
+
+	/**
+	 * Stops active watchers and releases retained registration state.
+	 *
+	 * @remarks
+	 * The manager intentionally does not remove emitted `_hmr` files from disk
+	 * because multiple app processes may share the same dist directory during test
+	 * runs. It does clear in-memory indexes so old entrypoints and dependencies
+	 * cannot leak across a reused manager instance.
+	 */
+	public stop() {
+		this.entrypointRegistrations.clear();
+		for (const watcher of this.watchers.values()) {
+			watcher.close();
+		}
+		this.watchers.clear();
+		this.watchedFiles.clear();
+		this.entrypointDependencyGraph.reset();
+		this.plugins = [];
+	}
+}