@ecopages/core 0.2.0-alpha.22 → 0.2.0-alpha.24

package/src/adapters/shared/fs-server-response-matcher.test.ts

@@ -0,0 +1,285 @@
+import { describe, expect, it, vi } from 'vitest';
+import path from 'node:path';
+import { APP_TEST_ROUTES, FIXTURE_APP_PROJECT_DIR, INDEX_TEMPLATE_FILE } from '../../../__fixtures__/constants.ts';
+import { ConfigBuilder } from '../../config/config-builder.ts';
+import type { MatchResult } from '../../types/internal-types.ts';
+import { RouteRendererFactory } from '../../route-renderer/route-renderer.ts';
+import { FSRouter } from '../../router/server/fs-router.ts';
+import { FSRouterScanner } from '../../router/server/fs-router-scanner.ts';
+import { MemoryCacheStore } from '../../services/cache/memory-cache-store.ts';
+import { PageCacheService } from '../../services/cache/page-cache-service.ts';
+import { FileSystemServerResponseFactory } from './fs-server-response-factory.ts';
+import { FileSystemResponseMatcher } from './fs-server-response-matcher.ts';
+
+const appConfig = await new ConfigBuilder().setRootDir(FIXTURE_APP_PROJECT_DIR).build();
+
+for (const integration of appConfig.integrations) {
+	integration.setConfig(appConfig);
+	integration.setRuntimeOrigin(appConfig.baseUrl);
+}
+
+const scanner = new FSRouterScanner({
+	dir: path.join(appConfig.rootDir, appConfig.srcDir, appConfig.pagesDir),
+	appConfig,
+	origin: appConfig.baseUrl,
+	templatesExt: appConfig.templatesExt,
+	options: {
+		buildMode: false,
+	},
+});
+
+const router = new FSRouter({
+	origin: appConfig.baseUrl,
+	assetPrefix: path.join(appConfig.rootDir, appConfig.distDir),
+	scanner,
+});
+
+const routeRendererFactory = new RouteRendererFactory({
+	appConfig,
+	runtimeOrigin: appConfig.baseUrl,
+});
+
+const fileSystemResponseFactory = new FileSystemServerResponseFactory({
+	appConfig,
+	routeRendererFactory,
+	options: {
+		watchMode: false,
+	},
+});
+
+describe('FileSystemResponseMatcher', () => {
+	describe('without cache service', () => {
+		const matcherWithoutCache = new FileSystemResponseMatcher({
+			appConfig,
+			router,
+			routeRendererFactory,
+			fileSystemResponseFactory,
+		});
+
+		it('should return custom 404 page for unmatched request URL', async () => {
+			const requestUrl = APP_TEST_ROUTES.nonExistentFile;
+			const response = await matcherWithoutCache.handleNoMatch(requestUrl);
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+
+		it('should handle match with disabled cache headers', async () => {
+			const match: MatchResult = {
+				kind: 'exact',
+				pathname: APP_TEST_ROUTES.index,
+				filePath: INDEX_TEMPLATE_FILE,
+				params: {},
+				query: {},
+			};
+			const response = await matcherWithoutCache.handleMatch(match);
+			expect(response.headers.get('Content-Type')).toBe('text/html');
+			expect(response.headers.get('X-Cache')).toBe('DISABLED');
+			expect(response.headers.get('Cache-Control')).toBe('no-store, must-revalidate');
+		});
+
+		it('should return null for getCacheService when not configured', () => {
+			expect(matcherWithoutCache.getCacheService()).toBeNull();
+		});
+	});
+
+	describe('with cache service', () => {
+		const cacheService = new PageCacheService({
+			store: new MemoryCacheStore(),
+			enabled: true,
+		});
+
+		const matcherWithCache = new FileSystemResponseMatcher({
+			appConfig,
+			router,
+			routeRendererFactory,
+			fileSystemResponseFactory,
+			cacheService,
+			defaultCacheStrategy: 'static',
+		});
+
+		it('should return cache service via getCacheService', () => {
+			expect(matcherWithCache.getCacheService()).toBe(cacheService);
+		});
+
+		it('should return X-Cache header on first request (MISS)', async () => {
+			const match: MatchResult = {
+				kind: 'exact',
+				pathname: '/cache-test-miss',
+				filePath: INDEX_TEMPLATE_FILE,
+				params: {},
+				query: {},
+			};
+			const response = await matcherWithCache.handleMatch(match);
+			expect(response.headers.get('X-Cache')).toBe('MISS');
+			expect(response.headers.get('Cache-Control')).toBe('public, max-age=31536000, immutable');
+		});
+
+		it('should return X-Cache HIT on second request to same path', async () => {
+			const uniquePath = `/cache-test-hit-${Date.now()}`;
+			const match: MatchResult = {
+				kind: 'exact',
+				pathname: uniquePath,
+				filePath: INDEX_TEMPLATE_FILE,
+				params: {},
+				query: {},
+			};
+
+			const response1 = await matcherWithCache.handleMatch(match);
+			const response2 = await matcherWithCache.handleMatch(match);
+
+			expect(response1.headers.get('X-Cache')).toBe('MISS');
+			expect(response2.headers.get('X-Cache')).toBe('HIT');
+		});
+
+		it('should cache different paths separately', async () => {
+			const match1: MatchResult = {
+				kind: 'exact',
+				pathname: '/path-a',
+				filePath: INDEX_TEMPLATE_FILE,
+				params: {},
+				query: {},
+			};
+			const match2: MatchResult = {
+				kind: 'exact',
+				pathname: '/path-b',
+				filePath: INDEX_TEMPLATE_FILE,
+				params: {},
+				query: {},
+			};
+
+			const response1 = await matcherWithCache.handleMatch(match1);
+			const response2 = await matcherWithCache.handleMatch(match2);
+
+			expect(response1.headers.get('X-Cache')).toBe('MISS');
+			expect(response2.headers.get('X-Cache')).toBe('MISS');
+		});
+
+		it('should include query params in cache key', async () => {
+			const basePath = `/search-${Date.now()}`;
+			const matchWithQuery: MatchResult = {
+				kind: 'exact',
+				pathname: basePath,
+				filePath: INDEX_TEMPLATE_FILE,
+				params: {},
+				query: { q: 'test' },
+			};
+			const matchWithDifferentQuery: MatchResult = {
+				kind: 'exact',
+				pathname: basePath,
+				filePath: INDEX_TEMPLATE_FILE,
+				params: {},
+				query: { q: 'other' },
+			};
+
+			const firstCall = await matcherWithCache.handleMatch(matchWithQuery);
+			const response1 = await matcherWithCache.handleMatch(matchWithQuery);
+			const response2 = await matcherWithCache.handleMatch(matchWithDifferentQuery);
+
+			expect(firstCall.headers.get('X-Cache')).toBe('MISS');
+			expect(response1.headers.get('X-Cache')).toBe('HIT');
+			expect(response2.headers.get('X-Cache')).toBe('MISS');
+		});
+	});
+
+	describe('with dynamic cache strategy', () => {
+		const cacheService = new PageCacheService({
+			store: new MemoryCacheStore(),
+			enabled: true,
+		});
+
+		const dynamicMatcher = new FileSystemResponseMatcher({
+			appConfig,
+			router,
+			routeRendererFactory,
+			fileSystemResponseFactory,
+			cacheService,
+			defaultCacheStrategy: 'dynamic',
+		});
+
+		it('should bypass cache entirely for dynamic strategy', async () => {
+			const match: MatchResult = {
+				kind: 'exact',
+				pathname: '/dynamic-page',
+				filePath: INDEX_TEMPLATE_FILE,
+				params: {},
+				query: {},
+			};
+
+			const response1 = await dynamicMatcher.handleMatch(match);
+			const response2 = await dynamicMatcher.handleMatch(match);
+
+			expect(response1.headers.get('X-Cache')).toBe('DISABLED');
+			expect(response2.headers.get('X-Cache')).toBe('DISABLED');
+			expect(response1.headers.get('Cache-Control')).toBe('no-store, must-revalidate');
+		});
+	});
+
+	describe('handleNoMatch content type behavior', () => {
+		const matcher = new FileSystemResponseMatcher({
+			appConfig,
+			router,
+			routeRendererFactory,
+			fileSystemResponseFactory,
+		});
+
+		it('should return custom 404 page for known extension like .html', async () => {
+			const response = await matcher.handleNoMatch('/non-existent-page.html');
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+
+		it('should return custom 404 page for page requests without extension', async () => {
+			const response = await matcher.handleNoMatch('/non-existent-page');
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+
+		it('should return custom 404 page for unknown extensions', async () => {
+			const response = await matcher.handleNoMatch('/page.xyz');
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+
+		it('should return custom 404 page for trailing dot', async () => {
+			const response = await matcher.handleNoMatch('/page.');
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+
+		it('should serve text/plain files from disk', async () => {
+			const response = await matcher.handleNoMatch('/robots.txt');
+			expect(response.headers.get('Content-Type')).toBe('text/plain');
+		});
+
+		it('should return custom 404 page for non-existent static files', async () => {
+			const response = await matcher.handleNoMatch('/non-existent.txt');
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+	});
+
+	describe('internal transpile output', () => {
+		it('should inspect page modules through the owning route renderer', async () => {
+			const matcher = new FileSystemResponseMatcher({
+				appConfig,
+				router,
+				routeRendererFactory,
+				fileSystemResponseFactory,
+			});
+
+			const loadPageModule = vi.fn(async () => ({}));
+			(matcher as any).routeRendererFactory = {
+				createRenderer: vi.fn(() => ({
+					loadPageModule,
+				})),
+			};
+
+			await (matcher as any).importPageModule(INDEX_TEMPLATE_FILE);
+
+			expect((matcher as any).routeRendererFactory.createRenderer).toHaveBeenCalledWith(INDEX_TEMPLATE_FILE);
+			expect(loadPageModule).toHaveBeenCalledWith(INDEX_TEMPLATE_FILE, {
+				cacheScope: 'request-metadata',
+			});
+		});
+	});
+});

package/src/adapters/shared/fs-server-response-matcher.ts

@@ -0,0 +1,189 @@
+import path from 'node:path';
+import { appLogger } from '../../global/app-logger.ts';
+import type { EcoPagesAppConfig, MatchResult } from '../../types/internal-types.ts';
+import type { RouteRendererFactory } from '../../route-renderer/route-renderer.ts';
+import type { FSRouter } from '../../router/server/fs-router.ts';
+import type { PageCacheService } from '../../services/cache/page-cache-service.ts';
+import type { CacheStrategy, RenderResult } from '../../services/cache/cache.types.ts';
+import { PageRequestCacheCoordinator } from '../../services/cache/page-request-cache-coordinator.service.ts';
+import { ServerUtils } from '../../utils/server-utils.module.ts';
+import type { Middleware, RequestLocals } from '../../types/public-types.ts';
+import { FileRouteMiddlewarePipeline } from './file-route-middleware-pipeline.ts';
+import { LocalsAccessError } from '../../errors/locals-access-error.ts';
+import { isDevelopmentRuntime } from '../../utils/runtime.ts';
+import type { FileSystemServerResponseFactory } from './fs-server-response-factory.ts';
+
+export interface FileSystemResponseMatcherOptions {
+	appConfig: EcoPagesAppConfig;
+	router: FSRouter;
+	routeRendererFactory: RouteRendererFactory;
+	fileSystemResponseFactory: FileSystemServerResponseFactory;
+	/** Optional cache service. When null, caching is disabled. */
+	cacheService?: PageCacheService | null;
+	/** Default cache strategy when caching is enabled. @default 'static' */
+	defaultCacheStrategy?: CacheStrategy;
+}
+
+/**
+ * Matches file-system routes to rendered HTML responses.
+ *
+ * render pipeline. It coordinates page module inspection, request-local policy,
+ * renderer invocation, middleware execution, cache integration, and fallback
+ * error translation.
+ */
+export class FileSystemResponseMatcher {
+	private appConfig: EcoPagesAppConfig;
+	private router: FSRouter;
+	private routeRendererFactory: RouteRendererFactory;
+	private fileSystemResponseFactory: FileSystemServerResponseFactory;
+	private pageRequestCacheCoordinator: PageRequestCacheCoordinator;
+	private fileRouteMiddlewarePipeline: FileRouteMiddlewarePipeline;
+
+	constructor({
+		appConfig,
+		router,
+		routeRendererFactory,
+		fileSystemResponseFactory,
+		cacheService = null,
+		defaultCacheStrategy = 'static',
+	}: FileSystemResponseMatcherOptions) {
+		this.appConfig = appConfig;
+		this.router = router;
+		this.routeRendererFactory = routeRendererFactory;
+		this.fileSystemResponseFactory = fileSystemResponseFactory;
+		this.pageRequestCacheCoordinator = new PageRequestCacheCoordinator(cacheService, defaultCacheStrategy);
+		this.fileRouteMiddlewarePipeline = new FileRouteMiddlewarePipeline(cacheService);
+	}
+
+	/**
+	 * Resolves unmatched paths either as static asset requests or as the custom
+	 * not-found page.
+	 * @param requestUrl Incoming pathname.
+	 * @returns Static file response or rendered 404 response.
+	 */
+	async handleNoMatch(requestUrl: string): Promise<Response> {
+		const isStaticFileRequest = ServerUtils.hasKnownExtension(requestUrl);
+
+		if (!isStaticFileRequest) {
+			return this.fileSystemResponseFactory.createCustomNotFoundResponse();
+		}
+
+		const relativeUrl = requestUrl.startsWith('/') ? requestUrl.slice(1) : requestUrl;
+		const filePath = path.join(this.router.assetPrefix, relativeUrl);
+		const contentType = ServerUtils.getContentType(filePath);
+
+		return this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
+	}
+
+	/**
+	 * Handles a matched file-system page route.
+	 *
+	 * The method inspects page metadata needed for request-time execution,
+	 * prepares the renderer invocation, validates middleware/cache constraints,
+	 * and delegates caching plus middleware execution to dedicated collaborators.
+	 *
+	 * @param match Router match result.
+	 * @param request Optional incoming request. A synthetic GET request is created when omitted.
+	 * @returns Final response for the matched route.
+	 */
+	async handleMatch(match: MatchResult, request?: Request): Promise<Response> {
+		const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey(match);
+
+		try {
+			const resolvedRequest =
+				request ??
+				new Request(new URL(cacheKey, this.router.origin).toString(), {
+					method: 'GET',
+				});
+
+			const localsStore: RequestLocals = {};
+			const pageModule = await this.importPageModule(match.filePath);
+			const Page = (pageModule as any)?.default;
+			const pageMiddleware = (Page?.middleware ?? []) as Middleware[];
+			const pageCacheStrategy =
+				(Page?.cache as CacheStrategy | undefined) ??
+				this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
+			const localsForRender: RequestLocals | undefined =
+				pageCacheStrategy === 'dynamic' ? localsStore : undefined;
+
+			this.fileRouteMiddlewarePipeline.assertValidConfiguration({
+				middleware: pageMiddleware,
+				pageCacheStrategy,
+				filePath: match.filePath,
+			});
+
+			const routeRenderer = this.routeRendererFactory.createRenderer(match.filePath);
+			const middlewareContext = this.fileRouteMiddlewarePipeline.createContext({
+				request: resolvedRequest,
+				params: match.params as Record<string, string>,
+				locals: localsStore,
+			});
+
+			const renderFn = async (): Promise<RenderResult> => {
+				const result = await routeRenderer.createRoute({
+					file: match.filePath,
+					params: match.params,
+					query: match.query,
+					locals: localsForRender,
+				});
+				const html = await this.pageRequestCacheCoordinator.bodyToString(result.body);
+				const strategy = result.cacheStrategy ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
+				return { html, strategy };
+			};
+			const renderResponse = async (): Promise<Response> => {
+				return this.pageRequestCacheCoordinator.render({
+					cacheKey,
+					pageCacheStrategy,
+					renderFn,
+				});
+			};
+
+			return await this.fileRouteMiddlewarePipeline.run({
+				middleware: pageMiddleware,
+				context: middlewareContext,
+				renderResponse,
+			});
+		} catch (error) {
+			if (error instanceof Response) {
+				return error;
+			}
+			if (error instanceof LocalsAccessError) {
+				return new Response(error.message, {
+					status: 500,
+					headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+				});
+			}
+			if (error instanceof Error) {
+				if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
+					appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.pathname}`);
+				}
+			}
+			return this.fileSystemResponseFactory.createCustomNotFoundResponse();
+		}
+	}
+
+	/**
+	 * Loads the matched page module for request-time inspection.
+	 *
+	 * The matcher needs access to page-level metadata such as `cache` and
+	 * `middleware` before full rendering starts, so it asks the owning route
+	 * renderer to load the page module. That preserves integration-specific page
+	 * import setup for request-time inspection as well as for full rendering.
+	 *
+	 * @param filePath Absolute page module path.
+	 * @returns Imported page module.
+	 */
+	private async importPageModule(filePath: string): Promise<unknown> {
+		const routeRenderer = this.routeRendererFactory.createRenderer(filePath);
+		return routeRenderer.loadPageModule(filePath, {
+			cacheScope: 'request-metadata',
+		});
+	}
+
+	/**
+	 * Get the underlying cache service for external invalidation.
+	 */
+	getCacheService(): PageCacheService | null {
+		return this.pageRequestCacheCoordinator.getCacheService();
+	}
+}

package/src/adapters/shared/hmr-entrypoint-registrar.ts

@@ -0,0 +1,149 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { appLogger } from '../../global/app-logger.ts';
+import { RESOLVED_ASSETS_DIR } from '../../config/constants.ts';
+
+/**
+ * Shared runtime state used while registering HMR-owned entrypoints.
+ */
+export interface HmrEntrypointRegistrarOptions {
+	/** Absolute source directory used to derive the emitted HMR path. */
+	srcDir: string;
+	/** Absolute distribution directory where HMR outputs are written. */
+	distDir: string;
+	/** In-flight registrations keyed by normalized absolute entrypoint path. */
+	entrypointRegistrations: Map<string, Promise<string>>;
+	/** Stable entrypoint-to-output mapping retained once an entrypoint is registered. */
+	watchedFiles: Map<string, string>;
+	/** Runtime-specific cleanup invoked when an entrypoint registration fails. */
+	clearFailedRegistration?: (entrypointPath: string) => void;
+	/** Development-only guardrail for integrations that never finish producing output. */
+	registrationTimeoutMs: number;
+}
+
+/**
+ * Runtime-specific hooks required to materialize a single HMR entrypoint.
+ */
+export interface HmrEntrypointRegistrationOptions {
+	/**
+	 * Emits the browser-consumable HMR artifact for an entrypoint.
+	 */
+	emit(entrypointPath: string, outputPath: string): Promise<void>;
+	/**
+	 * Creates the runtime-specific error raised when the emit hook completes without producing output.
+	 */
+	getMissingOutputError(entrypointPath: string, outputPath: string): Error;
+}
+
+/**
+ * Coordinates the shared HMR entrypoint registration lifecycle for both Node and Bun managers.
+ *
+ * The registrar owns the cross-runtime policy: normalize entrypoint identities, dedupe concurrent
+ * registrations, derive the emitted `_hmr` output path, clear stale output before rebuilding, and
+ * apply the development timeout that prevents unresolved registrations from hanging navigation.
+ * Runtime-specific managers remain responsible for the actual emit step and any cleanup outside
+ * this shared registration flow.
+ */
+export class HmrEntrypointRegistrar {
+	private readonly options: HmrEntrypointRegistrarOptions;
+
+	constructor(options: HmrEntrypointRegistrarOptions) {
+		this.options = options;
+	}
+
+	/**
+	 * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
+	 *
+	 * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
+	 * integration only builds once per registration cycle.
+	 */
+	async registerEntrypoint(
+		entrypointPath: string,
+		registrationOptions: HmrEntrypointRegistrationOptions,
+	): Promise<string> {
+		const normalizedEntrypoint = path.resolve(entrypointPath);
+		const existingRegistration = this.options.entrypointRegistrations.get(normalizedEntrypoint);
+		if (existingRegistration) {
+			return await this.awaitEntrypointRegistration(existingRegistration, normalizedEntrypoint);
+		}
+
+		const registration = this.registerEntrypointInternal(normalizedEntrypoint, registrationOptions);
+		this.options.entrypointRegistrations.set(normalizedEntrypoint, registration);
+
+		try {
+			return await this.awaitEntrypointRegistration(registration, normalizedEntrypoint);
+		} catch (error) {
+			this.options.clearFailedRegistration?.(normalizedEntrypoint);
+			throw error;
+		} finally {
+			this.options.entrypointRegistrations.delete(normalizedEntrypoint);
+		}
+	}
+
+	private async registerEntrypointInternal(
+		entrypointPath: string,
+		registrationOptions: HmrEntrypointRegistrationOptions,
+	): Promise<string> {
+		if (this.options.watchedFiles.has(entrypointPath)) {
+			return this.options.watchedFiles.get(entrypointPath)!;
+		}
+
+		const { outputPath, outputUrl } = this.getEntrypointOutput(entrypointPath);
+
+		this.options.watchedFiles.set(entrypointPath, outputUrl);
+		this.removeStaleEntrypointOutput(outputPath);
+
+		await registrationOptions.emit(entrypointPath, outputPath);
+
+		if (!fileSystem.exists(outputPath)) {
+			throw registrationOptions.getMissingOutputError(entrypointPath, outputPath);
+		}
+
+		return outputUrl;
+	}
+
+	private async awaitEntrypointRegistration(registration: Promise<string>, entrypointPath: string): Promise<string> {
+		if (process.env.NODE_ENV !== 'development') {
+			return await registration;
+		}
+
+		return await Promise.race([
+			registration,
+			new Promise<string>((_, reject) => {
+				setTimeout(() => {
+					reject(new Error(`[HMR] Timed out registering entrypoint: ${entrypointPath}`));
+				}, this.options.registrationTimeoutMs);
+			}),
+		]);
+	}
+
+	private getEntrypointOutput(entrypointPath: string): { outputPath: string; outputUrl: string } {
+		const relativePath = path.relative(this.options.srcDir, entrypointPath);
+		const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+		const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
+		const urlPath = encodedPathJs.split(path.sep).join('/');
+
+		return {
+			outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, '_hmr', urlPath)}`,
+			outputPath: path.join(this.options.distDir, urlPath),
+		};
+	}
+
+	private removeStaleEntrypointOutput(outputPath: string): void {
+		if (!fileSystem.exists(outputPath)) {
+			return;
+		}
+
+		try {
+			fileSystem.remove(outputPath);
+		} catch (error) {
+			appLogger.warn(
+				`[HMR] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
+	private encodeDynamicSegments(filepath: string): string {
+		return filepath.replace(/\[([^\]]+)\]/g, '_$1_');
+	}
+}

package/src/adapters/shared/hmr-html-response.ts

@@ -0,0 +1,52 @@
+import type { IHmrManager } from '../../types/public-types.ts';
+
+const HMR_RUNTIME_IMPORT = "import '/_hmr_runtime.js'";
+const HMR_RUNTIME_SCRIPT = `<script type="module">${HMR_RUNTIME_IMPORT};</script>`;
+
+/**
+ * Returns whether a response is HTML and therefore eligible for development HMR
+ * runtime injection.
+ */
+export function isHtmlResponse(response: Response): boolean {
+	const contentType = response.headers.get('Content-Type');
+	return contentType !== null && contentType.startsWith('text/html');
+}
+
+/**
+ * Returns whether HTML responses should receive the HMR runtime bootstrap.
+ *
+ * This is shared because filesystem page responses and adapter-level HTML
+ * responses flow through different layers, but both need identical injection
+ * behavior in watch mode.
+ */
+export function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>): boolean {
+	return watch && hmrManager?.isEnabled() === true;
+}
+
+/**
+ * Injects the development HMR runtime script into an HTML response if it is not
+ * already present.
+ *
+ * The check is intentionally idempotent because an HTML response can pass
+ * through more than one development-layer wrapper before reaching the client.
+ */
+export async function injectHmrRuntimeIntoHtmlResponse(response: Response): Promise<Response> {
+	const html = await response.text();
+	if (html.includes(HMR_RUNTIME_IMPORT)) {
+		return new Response(html, {
+			status: response.status,
+			statusText: response.statusText,
+			headers: response.headers,
+		});
+	}
+
+	const updatedHtml = html.replace(/<\/html>/i, `${HMR_RUNTIME_SCRIPT}</html>`);
+	const headers = new Headers(response.headers);
+	headers.delete('Content-Length');
+
+	return new Response(updatedHtml, {
+		status: response.status,
+		statusText: response.statusText,
+		headers,
+	});
+}