@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.31

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

@@ -1,19 +1,23 @@
-import type { EcoPagesAppConfig, FileSystemServerOptions } from '../../internal-types.js';
-import type { RouteRendererBody } from '../../public-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+import type { FileSystemServerOptions } from '../../types/internal-types.js';
+import type { RouteRendererBody } from '../../types/public-types.js';
+/**
+ * Builds HTTP responses for static files and shared file-system fallbacks.
+ */
 export declare class FileSystemServerResponseFactory {
-    private appConfig;
-    private routeRendererFactory;
     private options;
-    constructor({ appConfig, routeRendererFactory, options, }: {
-        appConfig: EcoPagesAppConfig;
-        routeRendererFactory: RouteRendererFactory;
+    constructor({ options }: {
         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>;
+    /**
+     * Wraps already-rendered HTML in a 404 response envelope.
+     */
+    createHtmlNotFoundResponse(body: RouteRendererBody): Promise<Response>;
+    /**
+     * Reads a static file response, returning `null` when the file is missing.
+     */
+    createFileResponse(filePath: string, contentType: string): Promise<Response | null>;
 }

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

@@ -1,17 +1,9 @@
-import { STATUS_MESSAGE } from "../../constants.js";
+import { STATUS_MESSAGE } from "../../config/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;
+  constructor({ options }) {
     this.options = options;
   }
   isHtml(contentType) {
@@ -34,22 +26,11 @@ class FileSystemServerResponseFactory {
       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, {
+  /**
+   * Wraps already-rendered HTML in a 404 response envelope.
+   */
+  async createHtmlNotFoundResponse(body) {
+    return await this.createResponseWithBody(body, {
       status: 404,
       statusText: STATUS_MESSAGE[404],
       headers: {
@@ -57,6 +38,9 @@ class FileSystemServerResponseFactory {
       }
     });
   }
+  /**
+   * Reads a static file response, returning `null` when the file is missing.
+   */
   async createFileResponse(filePath, contentType) {
     try {
       let file;
@@ -88,7 +72,7 @@ class FileSystemServerResponseFactory {
       } else {
         appLogger.error("Error reading file", filePath, err);
       }
-      return this.createCustomNotFoundResponse();
+      return null;
     }
   }
 }

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

@@ -1,16 +1,14 @@
-import type { MatchResult } from '../../internal-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
-import type { FSRouter } from '../../router/fs-router.js';
+import type { EcoPagesAppConfig, MatchResult } from '../../types/internal-types.js';
+import type { PageRendererResolver } from '../../route-renderer/route-renderer.js';
+import type { RouteRegistry } from '../../router/server/route-registry.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 {
-    router: FSRouter;
-    routeRendererFactory: RouteRendererFactory;
+    appConfig: EcoPagesAppConfig;
+    assetPrefix: string;
+    router: RouteRegistry;
+    routeRendererFactory: PageRendererResolver;
     fileSystemResponseFactory: FileSystemServerResponseFactory;
     /** Optional cache service. When null, caching is disabled. */
     cacheService?: PageCacheService | null;
@@ -20,23 +18,22 @@ export interface FileSystemResponseMatcherOptions {
 /**
  * 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,
+ * This render pipeline coordinates page module inspection, request-local policy,
  * renderer invocation, middleware execution, cache integration, and fallback
  * error translation.
  */
 export declare class FileSystemResponseMatcher {
+    private appConfig;
+    private assetPrefix;
     private router;
     private routeRendererFactory;
     private fileSystemResponseFactory;
-    private pageModuleImportService;
     private pageRequestCacheCoordinator;
     private fileRouteMiddlewarePipeline;
-    constructor({ router, routeRendererFactory, fileSystemResponseFactory, cacheService, defaultCacheStrategy, }: FileSystemResponseMatcherOptions);
+    constructor({ appConfig, assetPrefix, 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.
      */
@@ -53,12 +50,19 @@ export declare class FileSystemResponseMatcher {
      * @returns Final response for the matched route.
      */
     handleMatch(match: MatchResult, request?: Request): Promise<Response>;
+    /**
+     * Renders the app-owned custom 404 page, falling back to the default text 404
+     * when the page template cannot be resolved.
+     */
+    private renderCustomNotFoundResponse;
+    private createExecutionPlan;
     /**
      * 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.
+     * `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.

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

@@ -1,52 +1,51 @@
 import path from "node:path";
 import { appLogger } from "../../global/app-logger.js";
-import { PageModuleImportService } from "../../services/page-module-import.service.js";
-import { PageRequestCacheCoordinator } from "../../services/page-request-cache-coordinator.service.js";
+import { PageRequestCacheCoordinator } from "../../services/cache/page-request-cache-coordinator.service.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;
+  assetPrefix;
   router;
   routeRendererFactory;
   fileSystemResponseFactory;
-  pageModuleImportService;
   pageRequestCacheCoordinator;
   fileRouteMiddlewarePipeline;
   constructor({
+    appConfig,
+    assetPrefix,
     router,
     routeRendererFactory,
     fileSystemResponseFactory,
     cacheService = null,
     defaultCacheStrategy = "static"
   }) {
+    this.appConfig = appConfig;
+    this.assetPrefix = assetPrefix;
     this.router = router;
     this.routeRendererFactory = routeRendererFactory;
     this.fileSystemResponseFactory = fileSystemResponseFactory;
-    this.pageModuleImportService = new PageModuleImportService();
     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();
+      return this.renderCustomNotFoundResponse();
     }
     const relativeUrl = requestUrl.startsWith("/") ? requestUrl.slice(1) : requestUrl;
-    const filePath = path.join(this.router.assetPrefix, relativeUrl);
+    const filePath = path.join(this.assetPrefix, relativeUrl);
     const contentType = ServerUtils.getContentType(filePath);
-    return this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
+    const response = await this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
+    return response ?? this.renderCustomNotFoundResponse();
   }
   /**
    * Handles a matched file-system page route.
@@ -60,34 +59,25 @@ class FileSystemResponseMatcher {
    * @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;
+      const executionPlan = await this.createExecutionPlan(match, request);
       this.fileRouteMiddlewarePipeline.assertValidConfiguration({
-        middleware: pageMiddleware,
-        pageCacheStrategy,
-        filePath: match.filePath
+        middleware: executionPlan.pageMiddleware,
+        pageCacheStrategy: executionPlan.pageCacheStrategy,
+        filePath: executionPlan.pageFilePath
       });
-      const routeRenderer = this.routeRendererFactory.createRenderer(match.filePath);
+      const routeRenderer = this.routeRendererFactory.getPageRenderer(executionPlan.pageFilePath);
       const middlewareContext = this.fileRouteMiddlewarePipeline.createContext({
-        request: resolvedRequest,
+        request: executionPlan.request,
         params: match.params,
-        locals: localsStore
+        locals: executionPlan.localsStore
       });
       const renderFn = async () => {
-        const result = await routeRenderer.createRoute({
-          file: match.filePath,
+        const result = await routeRenderer.execute({
+          file: executionPlan.pageFilePath,
           params: match.params,
           query: match.query,
-          locals: localsForRender
+          locals: executionPlan.localsForRender
         });
         const html = await this.pageRequestCacheCoordinator.bodyToString(result.body);
         const strategy = result.cacheStrategy ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
@@ -95,13 +85,13 @@ class FileSystemResponseMatcher {
       };
       const renderResponse = async () => {
         return this.pageRequestCacheCoordinator.render({
-          cacheKey,
-          pageCacheStrategy,
+          cacheKey: executionPlan.cacheKey,
+          pageCacheStrategy: executionPlan.pageCacheStrategy,
           renderFn
         });
       };
       return await this.fileRouteMiddlewarePipeline.run({
-        middleware: pageMiddleware,
+        middleware: executionPlan.pageMiddleware,
         context: middlewareContext,
         renderResponse
       });
@@ -117,29 +107,71 @@ class FileSystemResponseMatcher {
       }
       if (error instanceof Error) {
         if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
-          appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.pathname}`);
+          appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.requestedPathname}`);
         }
       }
-      return this.fileSystemResponseFactory.createCustomNotFoundResponse();
+      return this.renderCustomNotFoundResponse();
+    }
+  }
+  /**
+   * Renders the app-owned custom 404 page, falling back to the default text 404
+   * when the page template cannot be resolved.
+   */
+  async renderCustomNotFoundResponse() {
+    const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
+    try {
+      const routeRenderer = this.routeRendererFactory.getPageRenderer(error404TemplatePath);
+      const result = await routeRenderer.execute({
+        file: error404TemplatePath
+      });
+      return this.fileSystemResponseFactory.createHtmlNotFoundResponse(result.body);
+    } catch {
+      appLogger.debug(
+        "Custom 404 template not found, falling back to default 404 response",
+        error404TemplatePath
+      );
+      return this.fileSystemResponseFactory.createDefaultNotFoundResponse();
     }
   }
+  async createExecutionPlan(match, request) {
+    const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey({
+      pathname: match.requestedPathname,
+      query: match.query
+    });
+    const resolvedRequest = request ?? new Request(new URL(cacheKey, this.router.origin).toString(), {
+      method: "GET"
+    });
+    const localsStore = {};
+    const pageFilePath = match.templateRoute.filePath;
+    const pageModule = await this.importPageModule(pageFilePath);
+    const Page = pageModule?.default;
+    const pageMiddleware = Page?.middleware ?? [];
+    const pageCacheStrategy = Page?.cache ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
+    return {
+      cacheKey,
+      request: resolvedRequest,
+      pageFilePath,
+      pageMiddleware,
+      pageCacheStrategy,
+      localsStore,
+      localsForRender: pageCacheStrategy === "dynamic" ? localsStore : void 0
+    };
+  }
   /**
    * 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.
+   * `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.
    */
   async importPageModule(filePath) {
-    return this.pageModuleImportService.importModule({
-      filePath,
-      rootDir: path.dirname(this.router.assetPrefix),
-      outdir: path.join(this.router.assetPrefix, ".server-modules-meta"),
-      transpileErrorMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.transpilePageModuleFailed,
-      noOutputMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.noTranspiledOutputForPageModule
+    const routeRenderer = this.routeRendererFactory.getPageRenderer(filePath);
+    return routeRenderer.loadPageModule(filePath, {
+      cacheScope: "request-metadata"
     });
   }
   /**
@@ -150,6 +182,5 @@ class FileSystemResponseMatcher {
   }
 }
 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 "../../config/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 '../../types/public-types.js';
+/**
+ * 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>;

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

@@ -0,0 +1,32 @@
+const HMR_RUNTIME_IMPORT = "import '/_hmr_runtime.js'";
+const HMR_RUNTIME_SCRIPT = `<script type="module">${HMR_RUNTIME_IMPORT};<\/script>`;
+function isHtmlResponse(response) {
+  const contentType = response.headers.get("Content-Type");
+  return contentType !== null && contentType.startsWith("text/html");
+}
+function shouldInjectHmrHtmlResponse(watch, hmrManager) {
+  return watch && hmrManager?.isEnabled() === true;
+}
+async function injectHmrRuntimeIntoHtmlResponse(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
+  });
+}
+export {
+  injectHmrRuntimeIntoHtmlResponse,
+  isHtmlResponse,
+  shouldInjectHmrHtmlResponse
+};

package/src/adapters/shared/render-context.d.ts

@@ -1,7 +1,8 @@
-import type { RenderContext } from '../../public-types.js';
-import type { IntegrationPlugin } from '../../plugins/integration-plugin.js';
+import type { RenderContext } from '../../types/public-types.js';
+import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.js';
 export interface CreateRenderContextOptions {
-    integrations: IntegrationPlugin[];
+    integrations: AnyIntegrationPlugin[];
+    rendererModules?: unknown;
 }
 /**
  * Creates a render context for route handlers.

package/src/adapters/shared/render-context.js

@@ -15,12 +15,14 @@ function createRenderContext(options) {
     );
     const integration = integrations.find((i) => i.name === integrationName);
     invariant(!!integration, `No integration found for: ${integrationName}`);
-    return integration.initializeRenderer();
+    return integration.initializeRenderer({
+      rendererModules: options.rendererModules
+    });
   };
-  return {
+  const renderContext = {
     async render(view, props, renderOptions) {
       const locals = this?.locals;
-      const mergedProps = mergePropsWithLocals(props, locals);
+      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
       const renderer = getRendererForView(view);
       const ctx = {
         partial: false,
@@ -63,6 +65,7 @@ function createRenderContext(options) {
       });
     }
   };
+  return renderContext;
 }
 export {
   createRenderContext

package/src/adapters/shared/runtime-bootstrap.d.ts

@@ -0,0 +1,38 @@
+import { type BuildExecutor } from '../../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoPagesAppConfig, IClientBridge, IHmrManager } from '../../types/internal-types.js';
+/**
+ * Installs and returns the app-owned runtime build executor used by adapter
+ * startup and follow-up runtime work.
+ */
+export declare function installSharedRuntimeBuildExecutor(appConfig: EcoPagesAppConfig, options: {
+    development: boolean;
+}): BuildExecutor;
+/**
+ * Copies app public assets into dist and ensures the resolved assets directory
+ * exists before request handling begins.
+ */
+export declare function prepareSharedRuntimePublicDir(appConfig: EcoPagesAppConfig): void;
+/**
+ * Runs runtime plugin setup against app-owned config/runtime state and optional
+ * host plugin registration hooks.
+ */
+export declare function initializeSharedRuntimePlugins(options: {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    hmrManager?: IHmrManager;
+    onRuntimePlugin?: (plugin: unknown) => void;
+}): Promise<void>;
+/**
+ * Starts shared project watching for runtime adapters.
+ */
+export declare function startSharedProjectWatching(options: {
+    appConfig: EcoPagesAppConfig;
+    refreshRouterRoutesCallback: () => Promise<void>;
+    hmrManager: IHmrManager;
+    bridge: IClientBridge;
+}): Promise<void>;
+/**
+ * Binds a runtime HMR manager to app-owned plugin and integration state.
+ */
+export declare function bindSharedRuntimeHmrManager(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): EcoBuildPlugin[];