@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/adapters/node/static-content-server.d.ts

@@ -1,24 +1,60 @@
 import { type Server as NodeHttpServer } from 'node:http';
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 type NodeStaticContentServerOptions = {
     hostname?: string;
     port?: number;
 };
+/**
+ * Serves prebuilt static Ecopages output through Node's HTTP server.
+ *
+ * @remarks
+ * This server is used by the Node preview/build path once the app has already
+ * emitted its static output. It intentionally stays small: path sanitization,
+ * content-type selection, optional gzip serving, and 404 handling.
+ */
 export declare class NodeStaticContentServer {
     private readonly appConfig;
     private readonly options;
     private server;
+    /**
+     * Creates the Node static-content server for one built app output directory.
+     */
     constructor({ appConfig, options }: {
         appConfig: EcoPagesAppConfig;
         options?: NodeStaticContentServerOptions;
     });
+    /**
+     * Returns whether the given content type should be served from a pre-gzipped
+     * companion file when available.
+     */
     private shouldServeGzip;
+    /**
+     * Normalizes a request pathname and rejects directory traversal attempts.
+     */
     private sanitizePath;
+    /**
+     * Writes one HTTP response with the provided headers and optional body.
+     */
     private sendResponse;
+    /**
+     * Serves the generated 404 page when present, or a plain-text fallback.
+     */
     private sendNotFoundPage;
+    /**
+     * Serves one concrete file path, honoring gzip and HEAD semantics.
+     */
     private serveFile;
+    /**
+     * Handles one incoming Node HTTP request against the built static output tree.
+     */
     private handleRequest;
+    /**
+     * Starts the static preview server.
+     */
     start(): Promise<NodeHttpServer>;
+    /**
+     * Stops the static preview server and optionally closes active connections.
+     */
     stop(force?: boolean): Promise<void>;
 }
 export {};

package/src/adapters/node/static-content-server.js

@@ -1,12 +1,15 @@
 import { createServer } from "node:http";
 import { extname, join, normalize, sep } from "node:path";
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, STATUS_MESSAGE } from "../../constants.js";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, STATUS_MESSAGE } from "../../config/constants.js";
 import { fileSystem } from "@ecopages/file-system";
 import { ServerUtils } from "../../utils/server-utils.module.js";
 class NodeStaticContentServer {
   appConfig;
   options;
   server = null;
+  /**
+   * Creates the Node static-content server for one built app output directory.
+   */
   constructor({ appConfig, options }) {
     this.appConfig = appConfig;
     this.options = {
@@ -14,9 +17,16 @@ class NodeStaticContentServer {
       port: options?.port ?? DEFAULT_ECOPAGES_PORT
     };
   }
+  /**
+   * Returns whether the given content type should be served from a pre-gzipped
+   * companion file when available.
+   */
   shouldServeGzip(contentType) {
     return ["text/javascript", "text/css"].includes(contentType);
   }
+  /**
+   * Normalizes a request pathname and rejects directory traversal attempts.
+   */
   sanitizePath(pathname) {
     const withoutLeadingSlash = pathname.replace(/^\/+/, "");
     const normalizedPath = normalize(withoutLeadingSlash);
@@ -25,6 +35,9 @@ class NodeStaticContentServer {
     }
     return normalizedPath;
   }
+  /**
+   * Writes one HTTP response with the provided headers and optional body.
+   */
   sendResponse(res, status, headers, body) {
     res.statusCode = status;
     for (const [key, value] of Object.entries(headers)) {
@@ -36,6 +49,9 @@ class NodeStaticContentServer {
     }
     res.end(body);
   }
+  /**
+   * Serves the generated 404 page when present, or a plain-text fallback.
+   */
   sendNotFoundPage(req, res) {
     const error404TemplatePath = join(this.appConfig.absolutePaths.distDir, "404.html");
     const isHead = (req.method ?? "GET").toUpperCase() === "HEAD";
@@ -51,6 +67,9 @@ class NodeStaticContentServer {
     const file = fileSystem.readFileAsBuffer(error404TemplatePath);
     this.sendResponse(res, 404, { "Content-Type": "text/html" }, isHead ? void 0 : file);
   }
+  /**
+   * Serves one concrete file path, honoring gzip and HEAD semantics.
+   */
   serveFile(req, res, filePath, status = 200) {
     const contentType = ServerUtils.getContentType(extname(filePath));
     const acceptsGzip = req.headers["accept-encoding"]?.includes("gzip");
@@ -79,6 +98,9 @@ class NodeStaticContentServer {
     const file = fileSystem.readFileAsBuffer(filePath);
     this.sendResponse(res, status, { "Content-Type": contentType }, isHead ? void 0 : file);
   }
+  /**
+   * Handles one incoming Node HTTP request against the built static output tree.
+   */
   handleRequest(req, res) {
     const method = (req.method ?? "GET").toUpperCase();
     const isHead = method === "HEAD";
@@ -129,6 +151,9 @@ class NodeStaticContentServer {
     }
     this.sendNotFoundPage(req, res);
   }
+  /**
+   * Starts the static preview server.
+   */
   async start() {
     if (this.server) {
       return this.server;
@@ -141,6 +166,9 @@ class NodeStaticContentServer {
     });
     return this.server;
   }
+  /**
+   * Stops the static preview server and optionally closes active connections.
+   */
   async stop(force = true) {
     if (!this.server) {
       return;

package/src/adapters/shared/application-adapter.d.ts

@@ -1,4 +1,4 @@
-import type { ApiHandler, ApiHandlerContext, Middleware, RouteGroupBuilder, RouteOptions } from '../../public-types.js';
+import type { ApiHandler, ApiHandlerContext, Middleware, RouteGroupBuilder, RouteOptions } from '../../types/public-types.js';
 import { AbstractApplicationAdapter, type ApplicationAdapterOptions, type RouteGroupDefinition, type RouteHandler } from '../abstract/application-adapter.js';
 export declare abstract class SharedApplicationAdapter<TOptions extends ApplicationAdapterOptions = ApplicationAdapterOptions, TServer = any, TRequest extends Request = Request> extends AbstractApplicationAdapter<TOptions, TServer, TRequest> {
     protected register<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, method: ApiHandler['method'], handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;

package/src/{define-api-handler.d.ts → adapters/shared/define-api-handler.d.ts}

@@ -1,4 +1,4 @@
-import type { ApiHandler, ApiHandlerContext, Middleware, RouteSchema, TypedGroupHandlerContext } from './public-types.js';
+import type { ApiHandler, ApiHandlerContext, Middleware, RouteSchema, TypedGroupHandlerContext } from '../../types/public-types.js';
 type UniversalContext = ApiHandlerContext<Request, unknown>;
 type SchemaHandlerContext<TSchema extends RouteSchema | undefined, TContext extends UniversalContext> = TSchema extends RouteSchema ? TypedGroupHandlerContext<TSchema, TContext> : TContext;
 export declare function defineApiHandler<TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, 'handler' | 'middleware' | 'schema'> & {

package/src/adapters/shared/explicit-static-route-matcher.d.ts

@@ -1,5 +1,5 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { StaticRoute } from '../../public-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { StaticRoute } from '../../types/public-types.js';
 import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
 export declare const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS: {
     readonly missingIntegration: (routePath: string) => string;

package/src/adapters/shared/explicit-static-route-matcher.js

@@ -3,6 +3,9 @@ const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS = {
   missingIntegration: (routePath) => `View at ${routePath} is missing __eco.integration. Ensure it's defined with eco.page() and exported as default.`,
   noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`
 };
+function getViewIntegrationName(view) {
+  return view.config?.integration ?? view.config?.__eco?.integration;
+}
 class ExplicitStaticRouteMatcher {
   appConfig;
   routeRendererFactory;
@@ -71,7 +74,7 @@ class ExplicitStaticRouteMatcher {
     try {
       const mod = await route.loader();
       const view = mod.default;
-      const integrationName = view.config?.__eco?.integration;
+      const integrationName = getViewIntegrationName(view);
       if (!integrationName) {
         throw new Error(EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS.missingIntegration(route.path));
       }

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

@@ -1,4 +1,4 @@
-import type { Middleware, ApiHandlerContext, RequestLocals } from '../../public-types.js';
+import type { Middleware, ApiHandlerContext, RequestLocals } from '../../types/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";

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

@@ -7,6 +7,7 @@ const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS = {
   middlewareRequiresDynamic: (filePath) => `[ecopages] Page middleware requires cache: 'dynamic'. Page: ${filePath}`
 };
 class FileRouteMiddlewarePipeline {
+  cacheService;
   constructor(cacheService) {
     this.cacheService = cacheService;
   }

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

@@ -1,5 +1,5 @@
-import type { EcoPagesAppConfig, FileSystemServerOptions } from '../../internal-types.js';
-import type { RouteRendererBody } from '../../public-types.js';
+import type { EcoPagesAppConfig, FileSystemServerOptions } from '../../types/internal-types.js';
+import type { RouteRendererBody } from '../../types/public-types.js';
 import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
 export declare class FileSystemServerResponseFactory {
     private appConfig;

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

@@ -1,4 +1,4 @@
-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 {

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

@@ -1,6 +1,6 @@
-import type { MatchResult } from '../../internal-types.js';
+import type { EcoPagesAppConfig, MatchResult } from '../../types/internal-types.js';
 import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
-import type { FSRouter } from '../../router/fs-router.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';
@@ -9,6 +9,7 @@ export declare const FILE_SYSTEM_RESPONSE_MATCHER_ERRORS: {
     readonly noTranspiledOutputForPageModule: (filePath: string) => string;
 };
 export interface FileSystemResponseMatcherOptions {
+    appConfig: EcoPagesAppConfig;
     router: FSRouter;
     routeRendererFactory: RouteRendererFactory;
     fileSystemResponseFactory: FileSystemServerResponseFactory;
@@ -26,13 +27,14 @@ export interface FileSystemResponseMatcherOptions {
  * error translation.
  */
 export declare class FileSystemResponseMatcher {
+    private appConfig;
     private router;
     private routeRendererFactory;
     private fileSystemResponseFactory;
-    private pageModuleImportService;
+    private serverModuleTranspiler;
     private pageRequestCacheCoordinator;
     private fileRouteMiddlewarePipeline;
-    constructor({ router, routeRendererFactory, fileSystemResponseFactory, cacheService, defaultCacheStrategy, }: FileSystemResponseMatcherOptions);
+    constructor({ appConfig, router, routeRendererFactory, fileSystemResponseFactory, cacheService, defaultCacheStrategy, }: FileSystemResponseMatcherOptions);
     /**
      * Resolves unmatched paths either as static asset requests or as the custom
      * not-found page.
@@ -58,7 +60,9 @@ export declare class FileSystemResponseMatcher {
      *
      * 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.
+     * 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.

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

@@ -1,7 +1,8 @@
 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 { 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";
@@ -11,23 +12,26 @@ const FILE_SYSTEM_RESPONSE_MATCHER_ERRORS = {
   noTranspiledOutputForPageModule: (filePath) => `No transpiled output generated for page module: ${filePath}`
 };
 class FileSystemResponseMatcher {
+  appConfig;
   router;
   routeRendererFactory;
   fileSystemResponseFactory;
-  pageModuleImportService;
+  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.pageModuleImportService = new PageModuleImportService();
+    this.serverModuleTranspiler = getAppServerModuleTranspiler(appConfig);
     this.pageRequestCacheCoordinator = new PageRequestCacheCoordinator(cacheService, defaultCacheStrategy);
     this.fileRouteMiddlewarePipeline = new FileRouteMiddlewarePipeline(cacheService);
   }
@@ -128,16 +132,17 @@ class FileSystemResponseMatcher {
    *
    * 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.
+   * 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.pageModuleImportService.importModule({
+    return this.serverModuleTranspiler.importModule({
       filePath,
-      rootDir: path.dirname(this.router.assetPrefix),
-      outdir: path.join(this.router.assetPrefix, ".server-modules-meta"),
+      outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules-meta"),
       transpileErrorMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.transpilePageModuleFailed,
       noOutputMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.noTranspiledOutputForPageModule
     });

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 { RenderContext } from '../../types/public-types.js';
 import type { IntegrationPlugin } from '../../plugins/integration-plugin.js';
 export interface CreateRenderContextOptions {
     integrations: IntegrationPlugin[];
+    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[];

package/src/adapters/shared/runtime-bootstrap.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { getAppBrowserBuildPlugins, setupAppRuntimePlugins } from "../../build/build-adapter.js";
+import { installAppRuntimeBuildExecutor } from "../../build/runtime-build-executor.js";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+import { ProjectWatcher } from "../../watchers/project-watcher.js";
+function installSharedRuntimeBuildExecutor(appConfig, options) {
+  return installAppRuntimeBuildExecutor(appConfig, options);
+}
+function prepareSharedRuntimePublicDir(appConfig) {
+  const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
+  if (fileSystem.exists(srcPublicDir)) {
+    fileSystem.copyDir(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
+  }
+  fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+}
+async function initializeSharedRuntimePlugins(options) {
+  await setupAppRuntimePlugins(options);
+}
+async function startSharedProjectWatching(options) {
+  const watcher = new ProjectWatcher({
+    config: options.appConfig,
+    refreshRouterRoutesCallback: options.refreshRouterRoutesCallback,
+    hmrManager: options.hmrManager,
+    bridge: options.bridge
+  });
+  await watcher.createWatcherSubscription();
+}
+function bindSharedRuntimeHmrManager(appConfig, hmrManager) {
+  const browserBuildPlugins = getAppBrowserBuildPlugins(appConfig);
+  hmrManager.setPlugins(browserBuildPlugins);
+  for (const integration of appConfig.integrations) {
+    integration.setHmrManager(hmrManager);
+  }
+  return browserBuildPlugins;
+}
+export {
+  bindSharedRuntimeHmrManager,
+  initializeSharedRuntimePlugins,
+  installSharedRuntimeBuildExecutor,
+  prepareSharedRuntimePublicDir,
+  startSharedProjectWatching
+};