@ecopages/core 0.2.0-alpha.2 → 0.2.0-alpha.21

package/src/adapters/node/server-adapter.js

@@ -1,16 +1,18 @@
 import { createServer } from "node:http";
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { RESOLVED_ASSETS_DIR } from "../../constants.js";
-import { defaultBuildAdapter } from "../../build/build-adapter.js";
 import { appLogger } from "../../global/app-logger.js";
-import { ProjectWatcher } from "../../watchers/project-watcher.js";
 import { NodeClientBridge } from "./node-client-bridge.js";
-import { NodeHmrManager } from "./node-hmr-manager.js";
 import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator.js";
 import { SharedServerAdapter } from "../shared/server-adapter.js";
 import { ServerStaticBuilder } from "../shared/server-static-builder.js";
+import {
+  bindSharedRuntimeHmrManager,
+  initializeSharedRuntimePlugins,
+  installSharedRuntimeBuildExecutor,
+  prepareSharedRuntimePublicDir,
+  startSharedProjectWatching
+} from "../shared/runtime-bootstrap.js";
 import { NodeStaticContentServer } from "./static-content-server.js";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
 class ClientAbortError extends Error {
   constructor() {
     super("Client closed the request");
@@ -26,7 +28,6 @@ class NodeServerAdapter extends SharedServerAdapter {
   previewServer = null;
   bridge = null;
   hmrManager = null;
-  processorBuildPlugins = [];
   constructor(options) {
     super(options);
     this.apiHandlers = options.apiHandlers || [];
@@ -47,85 +48,28 @@ class NodeServerAdapter extends SharedServerAdapter {
    *    processors during their `setup()` calls.
    */
   async initialize() {
-    this.setupLoaders();
-    this.copyPublicDir();
-    await this.initializePlugins();
-    await this.initSharedRouter();
-    this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager ?? void 0);
+    installSharedRuntimeBuildExecutor(this.appConfig, {
+      development: this.options?.watch === true
+    });
+    prepareSharedRuntimePublicDir(this.appConfig);
+    await initializeSharedRuntimePlugins({
+      appConfig: this.appConfig,
+      runtimeOrigin: this.runtimeOrigin,
+      hmrManager: this.hmrManager ?? void 0
+    });
+    await this.initializeSharedRouteHandling({
+      staticRoutes: this.staticRoutes,
+      hmrManager: this.hmrManager ?? void 0
+    });
     this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
     this.staticBuilder = new ServerStaticBuilder({
       appConfig: this.appConfig,
       staticSiteGenerator: this.staticSiteGenerator,
-      serveOptions: this.serveOptions
+      serveOptions: this.serveOptions,
+      apiHandlers: this.apiHandlers
     });
     this.initialized = true;
   }
-  /**
-   * Registers every configured file loader as a build plugin on the shared
-   * `defaultBuildAdapter`.
-   *
-   * Loaders are registered on the *shared* adapter (not on a per-build instance)
-   * because they must be available globally to both the SSR build and any dynamic
-   * transpile passes that happen outside of a top-level `build()` call (e.g. HMR
-   * incremental rebuilds).
-   */
-  setupLoaders() {
-    for (const loader of this.appConfig.loaders.values()) {
-      defaultBuildAdapter.registerPlugin(loader);
-    }
-  }
-  copyPublicDir() {
-    const srcPublicDir = path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.publicDir);
-    if (fileSystem.exists(srcPublicDir)) {
-      fileSystem.copyDir(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
-    }
-    fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
-  }
-  /**
-   * Sets up all configured processors and integrations in two distinct phases.
-   *
-   * **Phase 1 — Processors:**
-   * Each processor's `setup()` is called first. A processor may expose two
-   * plugin lists:
-   * - `plugins` — transform plugins used during SSR rendering (e.g. PostCSS).
-   * - `buildPlugins` — esbuild plugins used during the client bundle step.
-   * Both are registered on `defaultBuildAdapter` so later build calls pick them up.
-   *
-   * **Phase 2 — Integrations:**
-   * Integrations receive the fully-resolved app config, the runtime origin, and
-   * (if already initialised) the HMR manager before their own `setup()` is called.
-   * This ordering ensures integrations can query config values that processors
-   * may have mutated during phase 1.
-   */
-  async initializePlugins() {
-    const processorBuildPlugins = [];
-    for (const processor of this.appConfig.processors.values()) {
-      await processor.setup();
-      if (processor.plugins) {
-        for (const plugin of processor.plugins) {
-          defaultBuildAdapter.registerPlugin(plugin);
-        }
-      }
-      if (processor.buildPlugins) {
-        processorBuildPlugins.push(...processor.buildPlugins);
-        for (const plugin of processor.buildPlugins) {
-          defaultBuildAdapter.registerPlugin(plugin);
-        }
-      }
-    }
-    for (const integration of this.appConfig.integrations) {
-      integration.setConfig(this.appConfig);
-      integration.setRuntimeOrigin(this.runtimeOrigin);
-      if (this.hmrManager) {
-        integration.setHmrManager(this.hmrManager);
-      }
-      await integration.setup();
-      for (const plugin of integration.plugins) {
-        defaultBuildAdapter.registerPlugin(plugin);
-      }
-    }
-    this.processorBuildPlugins = processorBuildPlugins;
-  }
   getServerOptions() {
     return {
       ...this.serveOptions
@@ -158,12 +102,12 @@ class NodeServerAdapter extends SharedServerAdapter {
       appConfig: this.appConfig,
       options: {
         hostname: this.serveOptions.hostname,
-        port: Number(this.serveOptions.port || 3e3)
+        port: Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT)
       }
     });
     await this.previewServer.start();
-    const previewHostname = this.serveOptions.hostname || "localhost";
-    const previewPort = this.serveOptions.port || 3e3;
+    const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
+    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
     appLogger.info(`Preview running at http://${previewHostname}:${previewPort}`);
   }
   /**
@@ -254,8 +198,8 @@ class NodeServerAdapter extends SharedServerAdapter {
    * `stopBuildRuntimeServer`, so it never overlaps with the actual dev/prod server.
    */
   async startBuildRuntimeServer() {
-    const hostname = String(this.serveOptions.hostname || "localhost");
-    const port = Number(this.serveOptions.port || 3e3);
+    const hostname = String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME);
+    const port = Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT);
     const server = createServer(async (req, res) => {
       try {
         const webRequest = this.createWebRequest(req);
@@ -325,12 +269,12 @@ class NodeServerAdapter extends SharedServerAdapter {
    * underlying socket closes early — into a 499 response so it does not
    * incorrectly surface as a 500 in application logs.
    */
-  async handleRequest(_request) {
+  async handleRequest(request) {
     if (!this.initialized) {
       throw new Error("Node server adapter is not initialized. Call createAdapter() first.");
     }
     try {
-      return await this.handleSharedRequest(_request, {
+      return await this.handleSharedRequest(request, {
         apiHandlers: this.apiHandlers,
         errorHandler: this.errorHandler,
         serverInstance: this.serverInstance,
@@ -353,22 +297,23 @@ class NodeServerAdapter extends SharedServerAdapter {
    *   broadcast + heartbeat cleanup.
    * - `NodeHmrManager` watches the filesystem and triggers incremental esbuild
    *   rebuilds, notifying connected clients via the bridge.
-   * - `ProjectWatcher` listens for route-level file changes and refreshes the
-   *   router and response handlers when pages are added or removed.
+   * - Shared watcher bootstrapping listens for route-level file changes and
+   *   refreshes the router and response handlers when pages are added or removed.
    *
    * WebSocket upgrade requests that do not target `/_hmr` are rejected with an
    * immediate socket destroy to prevent unhandled upgrade leaks.
    */
-  async completeInitialization(_server) {
-    this.serverInstance = _server;
+  async completeInitialization(server) {
+    this.serverInstance = server;
     if (this.options?.watch) {
+      const { NodeHmrManager } = await import("./node-hmr-manager.js");
       const { WebSocketServer } = await import("ws");
       const wss = new WebSocketServer({ noServer: true });
       this.bridge = new NodeClientBridge();
       this.hmrManager = new NodeHmrManager({ appConfig: this.appConfig, bridge: this.bridge });
       this.hmrManager.setEnabled(true);
       await this.hmrManager.buildRuntime();
-      _server.on("upgrade", (req, socket, head) => {
+      server.on("upgrade", (req, socket, head) => {
         const url = new URL(req.url ?? "/", this.runtimeOrigin);
         if (url.pathname === "/_hmr") {
           wss.handleUpgrade(req, socket, head, (ws) => {
@@ -380,23 +325,17 @@ class NodeServerAdapter extends SharedServerAdapter {
           socket.destroy();
         }
       });
-      const loaderPlugins = Array.from(this.appConfig.loaders.values());
-      const hmrBuildPlugins = [...loaderPlugins, ...this.processorBuildPlugins];
-      this.hmrManager.setPlugins(hmrBuildPlugins);
-      for (const integration of this.appConfig.integrations) {
-        integration.setHmrManager(this.hmrManager);
-      }
+      bindSharedRuntimeHmrManager(this.appConfig, this.hmrManager);
       this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
-      const watcher = new ProjectWatcher({
-        config: this.appConfig,
-        refreshRouterRoutesCallback: async () => {
-          await this.initSharedRouter();
-          this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
-        },
+      await startSharedProjectWatching({
+        appConfig: this.appConfig,
+        refreshRouterRoutesCallback: this.createSharedWatchRefreshCallback({
+          staticRoutes: this.staticRoutes,
+          hmrManager: this.hmrManager
+        }),
         hmrManager: this.hmrManager,
         bridge: this.bridge
       });
-      await watcher.createWatcherSubscription();
     }
     appLogger.debug("Node server adapter initialization completed", {
       apiHandlers: this.apiHandlers.length,
@@ -407,7 +346,7 @@ class NodeServerAdapter extends SharedServerAdapter {
   }
 }
 async function createNodeServerAdapter(params) {
-  const runtimeOrigin = params.runtimeOrigin ?? `http://${params.serveOptions.hostname || "localhost"}:${params.serveOptions.port || 3e3}`;
+  const runtimeOrigin = params.runtimeOrigin ?? `http://${params.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${params.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
   const adapter = new NodeServerAdapter({
     ...params,
     runtimeOrigin

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,14 +1,11 @@
-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';
-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;
@@ -20,23 +17,21 @@ 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,
  * renderer invocation, middleware execution, cache integration, and fallback
  * error translation.
  */
 export declare class FileSystemResponseMatcher {
+    private appConfig;
     private router;
     private routeRendererFactory;
     private fileSystemResponseFactory;
-    private pageModuleImportService;
     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.
-     *
      * @param requestUrl Incoming pathname.
      * @returns Static file response or rendered 404 response.
      */
@@ -57,8 +52,9 @@ export declare class FileSystemResponseMatcher {
      * 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,40 +1,35 @@
 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;
   router;
   routeRendererFactory;
   fileSystemResponseFactory;
-  pageModuleImportService;
   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.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.
    */
@@ -127,19 +122,17 @@ class FileSystemResponseMatcher {
    * 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.createRenderer(filePath);
+    return routeRenderer.loadPageModule(filePath, {
+      cacheScope: "request-metadata"
     });
   }
   /**
@@ -150,6 +143,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;
+}