@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.9

package/src/adapters/shared/file-route-middleware-pipeline.d.ts

@@ -0,0 +1,65 @@
+import type { Middleware, ApiHandlerContext, RequestLocals } from '../../public-types.js';
+import type { PageCacheService } from '../../services/cache/page-cache-service.js';
+export declare const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS: {
+    readonly CTX_RENDER_UNAVAILABLE: "[ecopages] ctx.render is not available in file-route middleware";
+    readonly CTX_RENDER_PARTIAL_UNAVAILABLE: "[ecopages] ctx.renderPartial is not available in file-route middleware";
+    readonly middlewareRequiresDynamic: (filePath: string) => string;
+};
+/**
+ * Executes middleware for file-based page routes.
+ *
+ * This pipeline owns the middleware-specific rules that are distinct from route
+ * matching and rendering, including request-local storage, the middleware
+ * execution context, and the invariant that page middleware only runs for
+ * request-time dynamic rendering.
+ */
+export declare class FileRouteMiddlewarePipeline {
+    private cacheService;
+    constructor(cacheService: PageCacheService | null);
+    /**
+     * Enforces the current middleware contract for file-routed pages.
+     *
+     * Middleware depends on request-scoped locals and therefore must not run when
+     * the page is treated as statically cacheable.
+     *
+     * @param input Middleware list, effective cache strategy, and page path.
+     * @throws LocalsAccessError When middleware is configured for a non-dynamic page.
+     */
+    assertValidConfiguration(input: {
+        middleware: Middleware[];
+        pageCacheStrategy: 'static' | 'dynamic' | {
+            revalidate: number;
+            tags?: string[];
+        };
+        filePath: string;
+    }): void;
+    /**
+     * Creates the request-scoped middleware context used by page middleware.
+     *
+     * The context intentionally disables `render()` and `renderPartial()` inside
+     * file-route middleware because rendering is owned by the page route pipeline,
+     * not by middleware stages.
+     *
+     * @param input Request details and the mutable locals store.
+     * @returns Middleware execution context.
+     */
+    createContext(input: {
+        request: Request;
+        params: Record<string, string>;
+        locals: RequestLocals;
+    }): ApiHandlerContext;
+    /**
+     * Runs the middleware chain and eventually delegates to the render callback.
+     *
+     * Middleware may short-circuit by returning a response directly. If the chain
+     * completes, the supplied `renderResponse` callback is executed exactly once.
+     *
+     * @param input Middleware context, chain, and terminal render callback.
+     * @returns Response from middleware or final render stage.
+     */
+    run(input: {
+        middleware: Middleware[];
+        context: ApiHandlerContext;
+        renderResponse: () => Promise<Response>;
+    }): Promise<Response>;
+}

package/src/adapters/shared/file-route-middleware-pipeline.js

@@ -0,0 +1,99 @@
+import { createRequire } from "../../utils/locals-utils.js";
+import { ApiResponseBuilder } from "./api-response.js";
+import { LocalsAccessError } from "../../errors/locals-access-error.js";
+const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS = {
+  CTX_RENDER_UNAVAILABLE: "[ecopages] ctx.render is not available in file-route middleware",
+  CTX_RENDER_PARTIAL_UNAVAILABLE: "[ecopages] ctx.renderPartial is not available in file-route middleware",
+  middlewareRequiresDynamic: (filePath) => `[ecopages] Page middleware requires cache: 'dynamic'. Page: ${filePath}`
+};
+class FileRouteMiddlewarePipeline {
+  cacheService;
+  constructor(cacheService) {
+    this.cacheService = cacheService;
+  }
+  /**
+   * Enforces the current middleware contract for file-routed pages.
+   *
+   * Middleware depends on request-scoped locals and therefore must not run when
+   * the page is treated as statically cacheable.
+   *
+   * @param input Middleware list, effective cache strategy, and page path.
+   * @throws LocalsAccessError When middleware is configured for a non-dynamic page.
+   */
+  assertValidConfiguration(input) {
+    if (input.middleware.length > 0 && input.pageCacheStrategy !== "dynamic") {
+      throw new LocalsAccessError(
+        FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.middlewareRequiresDynamic(input.filePath)
+      );
+    }
+  }
+  /**
+   * Creates the request-scoped middleware context used by page middleware.
+   *
+   * The context intentionally disables `render()` and `renderPartial()` inside
+   * file-route middleware because rendering is owned by the page route pipeline,
+   * not by middleware stages.
+   *
+   * @param input Request details and the mutable locals store.
+   * @returns Middleware execution context.
+   */
+  createContext(input) {
+    const context = {
+      request: input.request,
+      params: input.params,
+      response: new ApiResponseBuilder(),
+      server: null,
+      services: {
+        cache: this.cacheService
+      },
+      locals: input.locals,
+      require: createRequire(() => context.locals),
+      render: async () => {
+        throw new Error(FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.CTX_RENDER_UNAVAILABLE);
+      },
+      renderPartial: async () => {
+        throw new Error(FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.CTX_RENDER_PARTIAL_UNAVAILABLE);
+      },
+      json: (data, options) => {
+        const builder = new ApiResponseBuilder();
+        if (options?.status) builder.status(options.status);
+        if (options?.headers) builder.headers(options.headers);
+        return builder.json(data);
+      },
+      html: (content, options) => {
+        const builder = new ApiResponseBuilder();
+        if (options?.status) builder.status(options.status);
+        if (options?.headers) builder.headers(options.headers);
+        return builder.html(content);
+      }
+    };
+    return context;
+  }
+  /**
+   * Runs the middleware chain and eventually delegates to the render callback.
+   *
+   * Middleware may short-circuit by returning a response directly. If the chain
+   * completes, the supplied `renderResponse` callback is executed exactly once.
+   *
+   * @param input Middleware context, chain, and terminal render callback.
+   * @returns Response from middleware or final render stage.
+   */
+  async run(input) {
+    if (input.middleware.length === 0) {
+      return input.renderResponse();
+    }
+    let index = 0;
+    const executeNext = async () => {
+      if (index < input.middleware.length) {
+        const current = input.middleware[index++];
+        return current(input.context, executeNext);
+      }
+      return input.renderResponse();
+    };
+    return executeNext();
+  }
+}
+export {
+  FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS,
+  FileRouteMiddlewarePipeline
+};

package/src/adapters/shared/fs-server-response-factory.d.ts

@@ -0,0 +1,19 @@
+import type { EcoPagesAppConfig, FileSystemServerOptions } from '../../internal-types.js';
+import type { RouteRendererBody } from '../../public-types.js';
+import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+export declare class FileSystemServerResponseFactory {
+    private appConfig;
+    private routeRendererFactory;
+    private options;
+    constructor({ appConfig, routeRendererFactory, options, }: {
+        appConfig: EcoPagesAppConfig;
+        routeRendererFactory: RouteRendererFactory;
+        options: FileSystemServerOptions;
+    });
+    isHtml(contentType: string): contentType is "text/html";
+    shouldEnableGzip(contentType: string): boolean;
+    createResponseWithBody(body: RouteRendererBody, init?: ResponseInit): Promise<Response>;
+    createDefaultNotFoundResponse(): Promise<Response>;
+    createCustomNotFoundResponse(): Promise<Response>;
+    createFileResponse(filePath: string, contentType: string): Promise<Response>;
+}

package/src/adapters/shared/fs-server-response-factory.js

@@ -0,0 +1,97 @@
+import { STATUS_MESSAGE } from "../../constants.js";
+import { appLogger } from "../../global/app-logger.js";
+import { fileSystem } from "@ecopages/file-system";
+class FileSystemServerResponseFactory {
+  appConfig;
+  routeRendererFactory;
+  options;
+  constructor({
+    appConfig,
+    routeRendererFactory,
+    options
+  }) {
+    this.appConfig = appConfig;
+    this.routeRendererFactory = routeRendererFactory;
+    this.options = options;
+  }
+  isHtml(contentType) {
+    return contentType === "text/html";
+  }
+  shouldEnableGzip(contentType) {
+    if (this.options.watchMode) return false;
+    const gzipEnabledExtensions = ["text/javascript", "text/css"];
+    return gzipEnabledExtensions.includes(contentType);
+  }
+  async createResponseWithBody(body, init = {
+    headers: {
+      "Content-Type": "text/html"
+    }
+  }) {
+    return new Response(body, init);
+  }
+  async createDefaultNotFoundResponse() {
+    return new Response(STATUS_MESSAGE[404], {
+      status: 404
+    });
+  }
+  async createCustomNotFoundResponse() {
+    const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
+    try {
+      fileSystem.verifyFileExists(error404TemplatePath);
+    } catch {
+      appLogger.debug(
+        "Custom 404 template not found, falling back to default 404 response",
+        error404TemplatePath
+      );
+      return this.createDefaultNotFoundResponse();
+    }
+    const routeRenderer = this.routeRendererFactory.createRenderer(error404TemplatePath);
+    const result = await routeRenderer.createRoute({
+      file: error404TemplatePath
+    });
+    return await this.createResponseWithBody(result.body, {
+      status: 404,
+      statusText: STATUS_MESSAGE[404],
+      headers: {
+        "Content-Type": "text/html"
+      }
+    });
+  }
+  async createFileResponse(filePath, contentType) {
+    try {
+      let file;
+      const contentEncodingHeader = {};
+      if (this.shouldEnableGzip(contentType)) {
+        const gzipPath = `${filePath}.gz`;
+        if (fileSystem.exists(gzipPath)) {
+          file = fileSystem.readFileAsBuffer(gzipPath);
+          contentEncodingHeader["Content-Encoding"] = "gzip";
+          contentEncodingHeader["Vary"] = "Accept-Encoding";
+        } else {
+          appLogger.debug("Gzip file not found, serving uncompressed", gzipPath);
+          file = fileSystem.readFileAsBuffer(filePath);
+        }
+      } else {
+        file = fileSystem.readFileAsBuffer(filePath);
+      }
+      return await this.createResponseWithBody(file, {
+        headers: {
+          "Content-Type": contentType,
+          ...contentEncodingHeader
+        }
+      });
+    } catch (error) {
+      const err = error;
+      const code = err.code || err.cause?.code;
+      if (code === "ENOENT") {
+        appLogger.debug("File not found", filePath);
+      } else {
+        appLogger.error("Error reading file", filePath, err);
+      }
+      return this.createCustomNotFoundResponse();
+    }
+  }
+}
+export {
+  FileSystemServerResponseFactory
+};

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

@@ -0,0 +1,75 @@
+import type { EcoPagesAppConfig, MatchResult } from '../../internal-types.js';
+import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+import type { FSRouter } from '../../router/server/fs-router.js';
+import type { PageCacheService } from '../../services/cache/page-cache-service.js';
+import type { CacheStrategy } from '../../services/cache/cache.types.js';
+import type { FileSystemServerResponseFactory } from './fs-server-response-factory.js';
+export declare const FILE_SYSTEM_RESPONSE_MATCHER_ERRORS: {
+    readonly transpilePageModuleFailed: (details: string) => string;
+    readonly noTranspiledOutputForPageModule: (filePath: string) => string;
+};
+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.
+ *
+ * This class sits at the request-time boundary between router matches and the
+ * render pipeline. It coordinates page module inspection, request-local policy,
+ * renderer invocation, middleware execution, cache integration, and fallback
+ * error translation.
+ */
+export declare class FileSystemResponseMatcher {
+    private appConfig;
+    private router;
+    private routeRendererFactory;
+    private fileSystemResponseFactory;
+    private serverModuleTranspiler;
+    private pageRequestCacheCoordinator;
+    private fileRouteMiddlewarePipeline;
+    constructor({ appConfig, router, routeRendererFactory, fileSystemResponseFactory, cacheService, defaultCacheStrategy, }: FileSystemResponseMatcherOptions);
+    /**
+     * 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.
+     */
+    handleNoMatch(requestUrl: string): Promise<Response>;
+    /**
+     * 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.
+     */
+    handleMatch(match: MatchResult, request?: Request): Promise<Response>;
+    /**
+     * 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 uses the shared module
+     * import service directly rather than going through route rendering. The
+     * app config is injected explicitly so build ownership stays at the adapter
+     * boundary instead of leaking through nested router collaborators.
+     *
+     * @param filePath Absolute page module path.
+     * @returns Imported page module.
+     */
+    private importPageModule;
+    /**
+     * Get the underlying cache service for external invalidation.
+     */
+    getCacheService(): PageCacheService | null;
+}

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

@@ -0,0 +1,160 @@
+import path from "node:path";
+import { appLogger } from "../../global/app-logger.js";
+import { PageRequestCacheCoordinator } from "../../services/cache/page-request-cache-coordinator.service.js";
+import { getAppServerModuleTranspiler } from "../../services/module-loading/app-server-module-transpiler.service.js";
+import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
+import { ServerUtils } from "../../utils/server-utils.module.js";
+import { FileRouteMiddlewarePipeline } from "./file-route-middleware-pipeline.js";
+import { LocalsAccessError } from "../../errors/locals-access-error.js";
+import { isDevelopmentRuntime } from "../../utils/runtime.js";
+const FILE_SYSTEM_RESPONSE_MATCHER_ERRORS = {
+  transpilePageModuleFailed: (details) => `Error transpiling page module: ${details}`,
+  noTranspiledOutputForPageModule: (filePath) => `No transpiled output generated for page module: ${filePath}`
+};
+class FileSystemResponseMatcher {
+  appConfig;
+  router;
+  routeRendererFactory;
+  fileSystemResponseFactory;
+  serverModuleTranspiler;
+  pageRequestCacheCoordinator;
+  fileRouteMiddlewarePipeline;
+  constructor({
+    appConfig,
+    router,
+    routeRendererFactory,
+    fileSystemResponseFactory,
+    cacheService = null,
+    defaultCacheStrategy = "static"
+  }) {
+    this.appConfig = appConfig;
+    this.router = router;
+    this.routeRendererFactory = routeRendererFactory;
+    this.fileSystemResponseFactory = fileSystemResponseFactory;
+    this.serverModuleTranspiler = getAppServerModuleTranspiler(appConfig);
+    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) {
+    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, request) {
+    const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey(match);
+    try {
+      const resolvedRequest = request ?? new Request(new URL(cacheKey, this.router.origin).toString(), {
+        method: "GET"
+      });
+      const localsStore = {};
+      const pageModule = await this.importPageModule(match.filePath);
+      const Page = pageModule?.default;
+      const pageMiddleware = Page?.middleware ?? [];
+      const pageCacheStrategy = Page?.cache ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
+      const localsForRender = pageCacheStrategy === "dynamic" ? localsStore : void 0;
+      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,
+        locals: localsStore
+      });
+      const renderFn = async () => {
+        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 () => {
+        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 uses the shared module
+   * import service directly rather than going through route rendering. The
+   * app config is injected explicitly so build ownership stays at the adapter
+   * boundary instead of leaking through nested router collaborators.
+   *
+   * @param filePath Absolute page module path.
+   * @returns Imported page module.
+   */
+  async importPageModule(filePath) {
+    return this.serverModuleTranspiler.importModule({
+      filePath,
+      outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules-meta"),
+      transpileErrorMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.transpilePageModuleFailed,
+      noOutputMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.noTranspiledOutputForPageModule
+    });
+  }
+  /**
+   * Get the underlying cache service for external invalidation.
+   */
+  getCacheService() {
+    return this.pageRequestCacheCoordinator.getCacheService();
+  }
+}
+export {
+  FILE_SYSTEM_RESPONSE_MATCHER_ERRORS,
+  FileSystemResponseMatcher
+};

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

@@ -0,0 +1,55 @@
+/**
+ * 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 declare class HmrEntrypointRegistrar {
+    private readonly options;
+    constructor(options: HmrEntrypointRegistrarOptions);
+    /**
+     * 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.
+     */
+    registerEntrypoint(entrypointPath: string, registrationOptions: HmrEntrypointRegistrationOptions): Promise<string>;
+    private registerEntrypointInternal;
+    private awaitEntrypointRegistration;
+    private getEntrypointOutput;
+    private removeStaleEntrypointOutput;
+    private encodeDynamicSegments;
+}

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

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { appLogger } from "../../global/app-logger.js";
+import { RESOLVED_ASSETS_DIR } from "../../constants.js";
+class HmrEntrypointRegistrar {
+  options;
+  constructor(options) {
+    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, registrationOptions) {
+    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);
+    }
+  }
+  async registerEntrypointInternal(entrypointPath, registrationOptions) {
+    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;
+  }
+  async awaitEntrypointRegistration(registration, entrypointPath) {
+    if (process.env.NODE_ENV !== "development") {
+      return await registration;
+    }
+    return await Promise.race([
+      registration,
+      new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`[HMR] Timed out registering entrypoint: ${entrypointPath}`));
+        }, this.options.registrationTimeoutMs);
+      })
+    ]);
+  }
+  getEntrypointOutput(entrypointPath) {
+    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)
+    };
+  }
+  removeStaleEntrypointOutput(outputPath) {
+    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)}`
+      );
+    }
+  }
+  encodeDynamicSegments(filepath) {
+    return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
+  }
+}
+export {
+  HmrEntrypointRegistrar
+};

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

@@ -0,0 +1,22 @@
+import type { IHmrManager } from '../../public-types';
+/**
+ * Returns whether a response is HTML and therefore eligible for development HMR
+ * runtime injection.
+ */
+export declare function isHtmlResponse(response: Response): boolean;
+/**
+ * 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 declare function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>): boolean;
+/**
+ * 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 declare function injectHmrRuntimeIntoHtmlResponse(response: Response): Promise<Response>;