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

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

@@ -1,23 +1,26 @@
-import { createServer } from "node:http";
+import {} from "node:http";
 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 { setupAppRuntimePlugins } from "../../build/build-adapter.js";
+import { installBuildRuntime } from "../../build/runtime/build-runtime.js";
 import { appLogger } from "../../global/app-logger.js";
 import { NodeClientBridge } from "./node-client-bridge.js";
 import { NodeHmrManager } from "./node-hmr-manager.js";
 import { ProjectWatcher } from "../../watchers/project-watcher.js";
+import {
+  attachNodeHttpWebSocketUpgrades
+} from "../shared/ws/node-http-websocket-upgrades.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 { SharedServerAdapter } from "../shared/runtime/server-adapter.js";
+import { ServerStaticBuilder } from "../shared/runtime/server-static-builder.js";
 import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
 import {
-  injectHmrRuntimeIntoHtmlResponse,
-  isHtmlResponse,
-  shouldInjectHmrHtmlResponse
-} from "../shared/hmr-html-response.js";
-import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
+  attachHmrToIntegrations,
+  disposeDevResources,
+  prepareRuntimePublicDir,
+  startConfiguredIntegrationRuntimePrewarm
+} from "../shared/runtime/runtime-server-lifecycle.js";
+import { resolveServeRuntimeOrigin } from "../shared/runtime/runtime-app-bootstrap.js";
 import { NodeClientAbortError, NodeHttpRequestBridge } from "./http-request-bridge.js";
 import { NodeStaticPreviewHost } from "./static-preview-host.js";
 import { DefaultNodeServerDevRuntimeFactory } from "./server-adapter-dependencies.js";
@@ -29,29 +32,66 @@ class NodeServerAdapter extends SharedServerAdapter {
   errorHandler;
   bridge = null;
   hmrManager = null;
+  projectWatcher = null;
+  adapterDisposed = false;
+  deferRuntimeAssetSetup;
+  allowPortFallback;
   previewHost;
   requestBridge;
   devRuntimeFactory;
-  shouldInjectHmrScript() {
-    return shouldInjectHmrHtmlResponse(this.options?.watch === true, this.hmrManager ?? void 0);
-  }
-  isHtmlResponse(response) {
-    return isHtmlResponse(response);
+  /**
+   * Reference to the application-level WebSocket handlers map.
+   *
+   * @remarks
+   * This is a reference to the map owned by `AbstractApplicationAdapter`,
+   * passed in via the constructor. The Node adapter reads from it to wire
+   * WebSocket upgrades for user-registered patterns.
+   */
+  websocketHandlers = /* @__PURE__ */ new Map();
+  /**
+   * Wires user WebSocket routes onto a foreign Node HTTP server.
+   *
+   * Host integrations such as the Vite plugin call this so `app.websocket()`
+   * handlers work while HTTP is still served by the host dev server.
+   */
+  attachUserWebSocketUpgrades(server, options) {
+    attachNodeHttpWebSocketUpgrades(server, {
+      runtimeOrigin: this.runtimeOrigin,
+      websocketHandlers: this.websocketHandlers,
+      passthroughUnmatched: options?.passthroughUnmatched
+    });
   }
-  async maybeInjectHmrScript(response) {
-    if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
-      return injectHmrRuntimeIntoHtmlResponse(response);
-    }
-    return response;
+  wireUserWebSocketUpgrades(server, preflight) {
+    attachNodeHttpWebSocketUpgrades(server, {
+      runtimeOrigin: this.runtimeOrigin,
+      websocketHandlers: this.websocketHandlers,
+      passthroughUnmatched: false,
+      preflight
+    });
   }
+  /**
+   * @remarks
+   * `previewHost`, `requestBridge`, and `devRuntimeFactory` are optional on the
+   * public {@link NodeServerAdapterParams} so factory callers can omit them, but
+   * they are mandatory by the time the concrete adapter is constructed —
+   * {@link createNodeServerAdapter} fills in Node-specific defaults first. The
+   * constructor signature makes that invariant explicit instead of relying on
+   * non-null assertions.
+   */
   constructor(options) {
     super(options);
+    this.deferRuntimeAssetSetup = options.deferRuntimeAssetSetup === true;
+    this.allowPortFallback = options.allowPortFallback !== false;
     this.apiHandlers = options.apiHandlers || [];
     this.staticRoutes = options.staticRoutes || [];
     this.errorHandler = options.errorHandler;
     this.previewHost = options.previewHost;
     this.requestBridge = options.requestBridge;
     this.devRuntimeFactory = options.devRuntimeFactory;
+    if (options.websocketHandlers) {
+      this.websocketHandlers = options.websocketHandlers;
+    }
+    this.hostOwnsDevClient = options.hostOwnsDevClient === true;
   }
   /**
    * Prepares the adapter for use.
@@ -67,13 +107,14 @@ class NodeServerAdapter extends SharedServerAdapter {
    *    processors during their `setup()` calls.
    */
   async initialize() {
-    installAppRuntimeBuildExecutor(this.appConfig);
-    this.prepareRuntimePublicDir();
-    await setupAppRuntimePlugins({
-      appConfig: this.appConfig,
-      runtimeOrigin: this.runtimeOrigin,
-      hmrManager: this.hmrManager ?? void 0
-    });
+    installBuildRuntime(this.appConfig);
+    prepareRuntimePublicDir(this.appConfig);
+    if (!this.deferRuntimeAssetSetup) {
+      await setupAppRuntimePlugins({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin
+      });
+    }
     await this.initializeSharedRouteHandling({
       staticRoutes: this.staticRoutes,
       hmrManager: this.hmrManager ?? void 0
@@ -83,17 +124,12 @@ class NodeServerAdapter extends SharedServerAdapter {
       appConfig: this.appConfig,
       staticSiteGenerator: this.staticSiteGenerator,
       serveOptions: this.serveOptions,
-      apiHandlers: this.apiHandlers
+      runtimeOrigin: this.runtimeOrigin,
+      needsServerBundle: this.apiHandlers.length > 0 || this.websocketHandlers.size > 0,
+      hmrManager: this.hmrManager ?? void 0
     });
     this.initialized = true;
   }
-  prepareRuntimePublicDir() {
-    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));
-  }
   getServerOptions() {
     return {
       ...this.serveOptions
@@ -103,106 +139,85 @@ class NodeServerAdapter extends SharedServerAdapter {
     if (!this.initialized) {
       await this.initialize();
     }
-    const buildServer = await this.startBuildRuntimeServer();
-    const buildRuntimeOrigin = this.getListeningServerOrigin(buildServer);
-    try {
-      await this.staticBuilder.build(
-        { preview: false, baseUrl: buildRuntimeOrigin },
-        {
-          router: this.router,
-          routeRendererFactory: this.routeRendererFactory,
-          staticRoutes: this.staticRoutes
-        }
-      );
-    } finally {
-      await this.stopBuildRuntimeServer(buildServer);
-    }
-    if (!options?.preview) {
-      return;
-    }
-    await this.previewHost.start({
-      appConfig: this.appConfig,
-      hostname: String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME),
-      port: Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT)
-    });
-    const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
-    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
-    appLogger.info(`Preview running at http://${previewHostname}:${previewPort}`);
-  }
-  async startBuildRuntimeServer() {
-    const hostname = String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME);
-    const port = 0;
-    const server = createServer(async (req, res) => {
-      try {
-        const webRequest = this.requestBridge.createWebRequest(req, this.runtimeOrigin);
-        const response = await this.handleRequest(webRequest);
-        await this.requestBridge.sendNodeResponse(res, response);
-      } catch (error) {
-        if (error instanceof NodeClientAbortError) {
-          return;
-        }
-        appLogger.error("Node static build runtime request failed", error);
-        res.statusCode = 500;
-        res.end("Internal Server Error");
+    const baseUrl = resolveServeRuntimeOrigin(this.serveOptions);
+    await this.staticBuilder.build(
+      { baseUrl, force: options?.force },
+      {
+        router: this.router,
+        routeRendererFactory: this.routeRendererFactory,
+        staticRoutes: this.staticRoutes
       }
-    });
-    await new Promise((resolve, reject) => {
-      server.once("error", reject);
-      server.listen(port, hostname, () => {
-        server.off("error", reject);
-        resolve();
-      });
-    });
-    this.serverInstance = server;
-    appLogger.info(`Server running at ${this.getListeningServerOrigin(server)}`);
-    return server;
-  }
-  getListeningServerOrigin(server) {
-    const address = server.address();
-    const hostname = String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME);
-    if (!address || typeof address === "string") {
-      throw new Error("Build runtime server did not expose a numeric listening port");
+    );
+    if (!options?.preview) {
+      return void 0;
     }
-    return `http://${hostname}:${address.port}`;
+    return this.startPreviewServer();
   }
   /**
-   * Gracefully shuts down the ephemeral build runtime server.
-   *
-   * `closeAllConnections()` is called *before* `close()` because `server.close()`
-   * only stops accepting new connections — it waits for existing keep-alive
-   * connections to finish naturally, which can stall the build indefinitely.
-   * `closeAllConnections()` force-closes any lingering sockets immediately so
-   * the `close()` callback fires promptly.
-   *
-   * The `NodeClientBridge` heartbeat is also destroyed here so its `setInterval`
-   * does not prevent the Node.js process from exiting cleanly after the build.
+   * Serves an existing static export without running SSG. Used by e2e preview
+   * launchers after a shared prewarm build.
    */
-  async stopBuildRuntimeServer(server) {
-    await new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve();
-      });
-      server.closeAllConnections();
+  async servePreviewOnly() {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    const distPath = path.join(this.appConfig.rootDir, this.appConfig.distDir);
+    if (!fileSystem.exists(distPath)) {
+      throw new Error(
+        `Cannot serve preview without building first: dist directory "${this.appConfig.distDir}" not found in "${this.appConfig.rootDir}".`
+      );
+    }
+    return this.startPreviewServer();
+  }
+  async startPreviewServer() {
+    const activePreviewPort = await this.previewHost.start({
+      appConfig: this.appConfig,
+      hostname: String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME),
+      port: Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT),
+      allowPortFallback: this.allowPortFallback
     });
-    if (this.serverInstance === server) {
-      this.serverInstance = null;
+    if (!activePreviewPort) {
+      return void 0;
     }
-    this.bridge?.destroy();
-    this.bridge = null;
+    const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
+    return `http://${previewHostname}:${activePreviewPort}`;
   }
   async createAdapter() {
     await this.initialize();
     return {
       getServerOptions: this.getServerOptions.bind(this),
       buildStatic: this.buildStatic.bind(this),
+      servePreviewOnly: this.servePreviewOnly.bind(this),
       completeInitialization: this.completeInitialization.bind(this),
-      handleRequest: this.handleRequest.bind(this)
+      handleRequest: this.handleRequest.bind(this),
+      attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this),
+      listStaticGenerationRoutes: (input) => this.router.listStaticGenerationRoutes(input),
+      dispose: this.dispose.bind(this)
     };
   }
+  /**
+   * Releases dev-time resources owned by the adapter.
+   *
+   * @remarks
+   * Safe to call multiple times. Does not stop the bound HTTP server — callers
+   * should shut down transport through the runtime host before disposing.
+   */
+  async dispose() {
+    if (this.adapterDisposed) {
+      return;
+    }
+    this.adapterDisposed = true;
+    await disposeDevResources({
+      projectWatcher: this.projectWatcher,
+      appConfig: this.appConfig,
+      hmrManager: this.hmrManager,
+      bridge: this.bridge,
+      previewHost: this.previewHost
+    });
+    this.projectWatcher = null;
+    this.hmrManager = null;
+    this.bridge = null;
+  }
   /**
    * Handles a single incoming Web `Request` and returns a Web `Response`.
    *
@@ -221,9 +236,9 @@ class NodeServerAdapter extends SharedServerAdapter {
         apiHandlers: this.apiHandlers,
         errorHandler: this.errorHandler,
         serverInstance: this.serverInstance,
-        hmrManager: this.hmrManager
+        hmrManager: this.hmrManager ?? void 0
       });
-      return await this.maybeInjectHmrScript(response);
+      return response;
     } catch (error) {
       if (error instanceof NodeClientAbortError) {
         return new Response(null, { status: 499 });
@@ -244,46 +259,58 @@ class NodeServerAdapter extends SharedServerAdapter {
    * - 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
+   * WebSocket upgrade requests that do not match a known path are rejected with an
    * immediate socket destroy to prevent unhandled upgrade leaks.
    */
   async completeInitialization(server) {
     this.serverInstance = server;
+    const hasUserWs = this.websocketHandlers.size > 0;
     if (this.options?.watch) {
       const devRuntime = this.devRuntimeFactory.create({ appConfig: this.appConfig });
       const wss = devRuntime.websocketServer;
       this.bridge = devRuntime.bridge;
       this.hmrManager = devRuntime.hmrManager;
       this.hmrManager.setEnabled(true);
-      await this.hmrManager.buildRuntime();
-      server.on("upgrade", (req, socket, head) => {
+      await this.hmrManager.ensureRuntimeReady();
+      const hmrPreflight = (req, socket, head) => {
         const url = new URL(req.url ?? "/", this.runtimeOrigin);
-        if (url.pathname === "/_hmr") {
-          wss.handleUpgrade(req, socket, head, (ws) => {
-            this.bridge.subscribe(ws);
-            ws.on("close", () => this.bridge.unsubscribe(ws));
-            ws.on("error", (err) => appLogger.error("[HMR] WebSocket error:", err));
-          });
-        } else {
-          socket.destroy();
-        }
-      });
-      const browserBuildPlugins = getAppBrowserBuildPlugins(this.appConfig);
-      this.hmrManager.setPlugins(browserBuildPlugins);
-      for (const integration of this.appConfig.integrations) {
-        integration.setHmrManager(this.hmrManager);
+        if (url.pathname !== "/_hmr") return false;
+        wss.handleUpgrade(req, socket, head, (ws) => {
+          this.bridge.subscribe(ws);
+          ws.on("close", () => this.bridge.unsubscribe(ws));
+          ws.on("error", (err) => appLogger.error("[HMR] WebSocket error:", err));
+        });
+        return true;
+      };
+      if (hasUserWs) {
+        this.wireUserWebSocketUpgrades(server, hmrPreflight);
+      } else {
+        server.on("upgrade", (req, socket, head) => {
+          if (!hmrPreflight(req, socket, head)) {
+            socket.destroy();
+          }
+        });
       }
+      attachHmrToIntegrations(this.appConfig, this.hmrManager);
+      startConfiguredIntegrationRuntimePrewarm({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin
+      });
       this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
       const watcher = new ProjectWatcher({
         config: this.appConfig,
         refreshRouterRoutesCallback: this.createSharedWatchRefreshCallback({
           staticRoutes: this.staticRoutes,
-          hmrManager: this.hmrManager
+          hmrManager: this.hmrManager ?? void 0
         }),
-        hmrManager: this.hmrManager,
-        bridge: this.bridge
+        hmrManager: this.hmrManager ?? void 0,
+        bridge: this.bridge,
+        hostOwnsDevClient: this.hostOwnsDevClient
       });
+      this.projectWatcher = watcher;
       await watcher.createWatcherSubscription();
+    } else if (hasUserWs) {
+      this.wireUserWebSocketUpgrades(server);
     }
     appLogger.debug("Node server adapter initialization completed", {
       apiHandlers: this.apiHandlers.length,

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

@@ -56,5 +56,6 @@ export declare class NodeStaticContentServer {
      * Stops the static preview server and optionally closes active connections.
      */
     stop(force?: boolean): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
 }
 export {};

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

@@ -161,8 +161,13 @@ class NodeStaticContentServer {
     this.server = createServer(this.handleRequest.bind(this));
     const hostname = this.options.hostname ?? DEFAULT_ECOPAGES_HOSTNAME;
     const port = this.options.port ?? DEFAULT_ECOPAGES_PORT;
-    await new Promise((resolve) => {
-      this.server.listen(port, hostname, () => resolve());
+    await new Promise((resolve, reject) => {
+      const activeServer = this.server;
+      activeServer.once("error", reject);
+      activeServer.listen(port, hostname, () => {
+        activeServer.off("error", reject);
+        resolve();
+      });
     });
     return this.server;
   }
@@ -188,6 +193,9 @@ class NodeStaticContentServer {
       }
     });
   }
+  async [Symbol.asyncDispose]() {
+    await this.stop();
+  }
 }
 export {
   NodeStaticContentServer

package/src/adapters/node/static-preview-host.d.ts

@@ -1,6 +1,6 @@
 import type { AddressInfo } from 'node:net';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { StaticPreviewHost, StaticPreviewHostStartOptions } from '../shared/static-preview-host.js';
+import type { StaticPreviewHost, StaticPreviewHostStartOptions } from '../shared/runtime/static-preview-host.js';
 type NodeStaticPreviewServer = {
     start(): Promise<{
         address(): AddressInfo | string | null;

package/src/adapters/node/static-preview-host.js

@@ -1,3 +1,5 @@
+import { appLogger } from "../../global/app-logger.js";
+import { PortManager } from "../shared/runtime/port-manager.js";
 import { NodeStaticContentServer } from "./static-content-server.js";
 class NodeStaticPreviewHost {
   /**
@@ -20,20 +22,33 @@ class NodeStaticPreviewHost {
    */
   async start(options) {
     await this.stop();
-    const previewServer = new this.previewServerFactory({
-      appConfig: options.appConfig,
-      options: {
-        hostname: options.hostname,
-        port: options.port
-      }
+    const portManager = new PortManager({
+      startOnPort: async (port) => {
+        const previewServer = new this.previewServerFactory({
+          appConfig: options.appConfig,
+          options: {
+            hostname: options.hostname,
+            port
+          }
+        });
+        const server = await previewServer.start();
+        this.previewServer = previewServer;
+        const address = server.address();
+        if (address && typeof address === "object") {
+          return address.port;
+        }
+        return port;
+      },
+      warn: (message) => appLogger.warn(message)
+    });
+    const previewPort = await portManager.bind({
+      preferredPort: options.port,
+      allowPortFallback: options.allowPortFallback === true
     });
-    const server = await previewServer.start();
-    this.previewServer = previewServer;
-    const address = server.address();
-    if (address && typeof address === "object") {
-      return address.port;
+    if (!previewPort) {
+      this.previewServer = null;
     }
-    return options.port;
+    return previewPort;
   }
   /**
    * Stops the active preview server and coalesces overlapping stop requests onto

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

@@ -1,20 +1,4 @@
-/**
- * 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;
-}
+import { type ResolvedHmrEntrypoint } from '../../../hmr/hmr-entrypoint-output.js';
 /**
  * Runtime-specific hooks required to materialize a single HMR entrypoint.
  */
@@ -28,28 +12,45 @@ export interface HmrEntrypointRegistrationOptions {
      */
     getMissingOutputError(entrypointPath: string, outputPath: string): Error;
 }
+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;
+    /** Runtime-specific cleanup invoked when an entrypoint registration fails. */
+    clearFailedRegistration?: (entrypointPath: string) => void;
+}
 /**
  * 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.
+ * @remarks
+ * The registrar owns in-flight deduplication and the registered entrypoint table.
+ * A source path is committed only after emit succeeds and the expected output exists on disk.
  */
 export declare class HmrEntrypointRegistrar {
     private readonly options;
+    private readonly inFlight;
+    private readonly registered;
     constructor(options: HmrEntrypointRegistrarOptions);
+    getRegistered(): ReadonlyMap<string, ResolvedHmrEntrypoint>;
+    getWatchedFiles(): Map<string, string>;
+    clearRegistration(entrypointPath: string): void;
+    /**
+     * Registers an already-materialized HMR entrypoint without running the emit hook.
+     *
+     * @remarks
+     * Cold dev batches build entrypoints in grouped Rolldown passes and then seed
+     * the registrar so the first SSR can resolve the artifact without rebuilding.
+     * The source path is committed verbatim so `getResolvedScriptOutput()` and the
+     * file watcher see it as a regular watched entrypoint.
+     */
+    seedResolvedEntrypoint(resolved: ResolvedHmrEntrypoint): void;
+    clearAll(): void;
     /**
-     * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
+     * Registers a single source entrypoint and returns its verified HMR artifact.
      *
-     * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
-     * integration only builds once per registration cycle.
+     * Concurrent requests for the same normalized entrypoint share the same in-flight promise.
      */
-    registerEntrypoint(entrypointPath: string, registrationOptions: HmrEntrypointRegistrationOptions): Promise<string>;
+    registerEntrypoint(entrypointPath: string, registrationOptions: HmrEntrypointRegistrationOptions): Promise<ResolvedHmrEntrypoint>;
     private registerEntrypointInternal;
-    private awaitEntrypointRegistration;
-    private getEntrypointOutput;
-    private removeStaleEntrypointOutput;
-    private encodeDynamicSegments;
 }