@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.40

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

@@ -1,313 +1,362 @@
-import { createServer } 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 { 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 { 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 { 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";
-import { NodeClientAbortError, NodeHttpRequestBridge } from "./http-request-bridge.js";
-import { NodeStaticPreviewHost } from "./static-preview-host.js";
-import { DefaultNodeServerDevRuntimeFactory } from "./server-adapter-dependencies.js";
-class NodeServerAdapter extends SharedServerAdapter {
-  serverInstance = null;
-  initialized = false;
-  apiHandlers;
-  staticRoutes;
-  errorHandler;
-  bridge = null;
-  hmrManager = null;
-  previewHost;
-  requestBridge;
-  devRuntimeFactory;
-  shouldInjectHmrScript() {
-    return shouldInjectHmrHtmlResponse(this.options?.watch === true, this.hmrManager ?? void 0);
-  }
-  isHtmlResponse(response) {
-    return isHtmlResponse(response);
-  }
-  async maybeInjectHmrScript(response) {
-    if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
-      return injectHmrRuntimeIntoHtmlResponse(response);
+import {} from 'node:http';
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+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/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 { attachHmrToIntegrations, disposeDevResources, prepareRuntimePublicDir, startDevWarmup, } 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';
+/**
+ * Node.js HTTP server adapter for the Ecopages runtime.
+ *
+ * `NodeServerAdapter` bridges the Node.js `http` module and the Ecopages
+ * `SharedServerAdapter` abstraction, translating between Node's
+ * `IncomingMessage`/`ServerResponse` API and the platform-agnostic Web
+ * `Request`/`Response` model.
+ *
+ * Lifecycle:
+ * 1. `createAdapter()` — calls `initialize()` and returns the public adapter result.
+ * 2. `completeInitialization(server)` — called once the HTTP server is listening.
+ *    Conditionally wires HMR, WebSocket upgrades, and the file watcher when
+ *    `options.watch` is `true`.
+ * 3. `handleRequest(request)` — delegates to `handleSharedRequest` for routing;
+ *    intercepts `ClientAbortError` to return 499 instead of 500.
+ * 4. `buildStatic()` — spins up an ephemeral runtime server, generates all static
+ *    pages against it, then tears it down.
+ *
+ * @see SharedServerAdapter for routing, caching and response handler logic.
+ */
+export class NodeServerAdapter extends SharedServerAdapter {
+    serverInstance = null;
+    initialized = false;
+    apiHandlers;
+    staticRoutes;
+    errorHandler;
+    bridge = null;
+    hmrManager = null;
+    projectWatcher = null;
+    adapterDisposed = false;
+    deferRuntimeAssetSetup;
+    allowPortFallback;
+    previewHost;
+    requestBridge;
+    devRuntimeFactory;
+    /**
+     * 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 = 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,
+        });
     }
-    return response;
-  }
-  constructor(options) {
-    super(options);
-    this.apiHandlers = options.apiHandlers || [];
-    this.staticRoutes = options.staticRoutes || [];
-    this.errorHandler = options.errorHandler;
-    this.previewHost = options.previewHost;
-    this.requestBridge = options.requestBridge;
-    this.devRuntimeFactory = options.devRuntimeFactory;
-  }
-  /**
-   * Prepares the adapter for use.
-   *
-   * Order is intentional:
-   * 1. **Loaders** are registered first so processors and integrations can
-   *    reference loader-provided file types in their own plugins.
-   * 2. **Public dir** is copied before any build so static assets are in `distDir`
-   *    before the first request arrives.
-   * 3. **Plugins** (processors, then integrations) are set up after the public dir
-   *    is in place so they can safely reference dist-relative paths.
-   * 4. **Router** is initialised last because it may depend on files written by
-   *    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
-    });
-    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,
-      apiHandlers: this.apiHandlers
-    });
-    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));
+    wireUserWebSocketUpgrades(server, preflight) {
+        attachNodeHttpWebSocketUpgrades(server, {
+            runtimeOrigin: this.runtimeOrigin,
+            websocketHandlers: this.websocketHandlers,
+            passthroughUnmatched: false,
+            preflight,
+        });
     }
-    fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
-  }
-  getServerOptions() {
-    return {
-      ...this.serveOptions
-    };
-  }
-  async buildStatic(options) {
-    if (!this.initialized) {
-      await this.initialize();
+    /**
+     * @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;
     }
-    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
+    /**
+     * Prepares the adapter for use.
+     *
+     * Order is intentional:
+     * 1. **Loaders** are registered first so processors and integrations can
+     *    reference loader-provided file types in their own plugins.
+     * 2. **Public dir** is copied before any build so static assets are in `distDir`
+     *    before the first request arrives.
+     * 3. **Plugins** (processors, then integrations) are set up after the public dir
+     *    is in place so they can safely reference dist-relative paths.
+     * 4. **Router** is initialised last because it may depend on files written by
+     *    processors during their `setup()` calls.
+     */
+    async initialize() {
+        installBuildRuntime(this.appConfig);
+        prepareRuntimePublicDir(this.appConfig);
+        if (!this.deferRuntimeAssetSetup) {
+            await setupAppRuntimePlugins({
+                appConfig: this.appConfig,
+                runtimeOrigin: this.runtimeOrigin,
+            });
         }
-      );
-    } finally {
-      await this.stopBuildRuntimeServer(buildServer);
+        await this.initializeSharedRouteHandling({
+            staticRoutes: this.staticRoutes,
+            hmrManager: this.hmrManager ?? undefined,
+        });
+        this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
+        this.staticBuilder = new ServerStaticBuilder({
+            appConfig: this.appConfig,
+            staticSiteGenerator: this.staticSiteGenerator,
+            serveOptions: this.serveOptions,
+            runtimeOrigin: this.runtimeOrigin,
+            needsServerBundle: this.apiHandlers.length > 0 || this.websocketHandlers.size > 0,
+            hmrManager: this.hmrManager ?? undefined,
+        });
+        this.initialized = true;
     }
-    if (!options?.preview) {
-      return;
+    getServerOptions() {
+        return {
+            ...this.serveOptions,
+        };
     }
-    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;
+    async buildStatic(options) {
+        if (!this.initialized) {
+            await this.initialize();
         }
-        appLogger.error("Node static build runtime request failed", error);
-        res.statusCode = 500;
-        res.end("Internal Server Error");
-      }
-    });
-    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");
+        const baseUrl = resolveServeRuntimeOrigin(this.serveOptions);
+        await this.staticBuilder.build({ baseUrl, force: options?.force }, {
+            router: this.router,
+            routeRendererFactory: this.routeRendererFactory,
+            staticRoutes: this.staticRoutes,
+        });
+        if (!options?.preview) {
+            return undefined;
+        }
+        return this.startPreviewServer();
     }
-    return `http://${hostname}:${address.port}`;
-  }
-  /**
-   * 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.
-   */
-  async stopBuildRuntimeServer(server) {
-    await new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error) {
-          reject(error);
-          return;
+    /**
+     * Serves an existing static export without running SSG. Used by e2e preview
+     * launchers after a shared prewarm build.
+     */
+    async servePreviewOnly() {
+        if (!this.initialized) {
+            await this.initialize();
         }
-        resolve();
-      });
-      server.closeAllConnections();
-    });
-    if (this.serverInstance === server) {
-      this.serverInstance = null;
+        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();
     }
-    this.bridge?.destroy();
-    this.bridge = null;
-  }
-  async createAdapter() {
-    await this.initialize();
-    return {
-      getServerOptions: this.getServerOptions.bind(this),
-      buildStatic: this.buildStatic.bind(this),
-      completeInitialization: this.completeInitialization.bind(this),
-      handleRequest: this.handleRequest.bind(this)
-    };
-  }
-  /**
-   * Handles a single incoming Web `Request` and returns a Web `Response`.
-   *
-   * Delegates to `handleSharedRequest` for all routing, caching, and response
-   * handler logic. The only Node-specific concern here is translating a
-   * `ClientAbortError` — which the body `ReadableStream` raises when the
-   * underlying socket closes early — into a 499 response so it does not
-   * incorrectly surface as a 500 in application logs.
-   */
-  async handleRequest(request) {
-    if (!this.initialized) {
-      throw new Error("Node server adapter is not initialized. Call createAdapter() first.");
+    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 (!activePreviewPort) {
+            return undefined;
+        }
+        const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
+        return `http://${previewHostname}:${activePreviewPort}`;
     }
-    try {
-      const response = await this.handleSharedRequest(request, {
-        apiHandlers: this.apiHandlers,
-        errorHandler: this.errorHandler,
-        serverInstance: this.serverInstance,
-        hmrManager: this.hmrManager
-      });
-      return await this.maybeInjectHmrScript(response);
-    } catch (error) {
-      if (error instanceof NodeClientAbortError) {
-        return new Response(null, { status: 499 });
-      }
-      throw error;
+    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),
+            attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this),
+            listStaticGenerationRoutes: (input) => this.router.listStaticGenerationRoutes(input),
+            dispose: this.dispose.bind(this),
+        };
     }
-  }
-  /**
-   * Called once the HTTP server is bound and listening.
-   *
-   * When `options.watch` is `true` this method wires the full HMR pipeline:
-   * - A `WebSocketServer` is attached to the existing HTTP server via the
-   *   `upgrade` event (no separate port needed).
-   * - `NodeClientBridge` tracks active WebSocket connections and handles
-   *   broadcast + heartbeat cleanup.
-   * - `NodeHmrManager` watches the filesystem and triggers incremental
-   *   rebuilds, notifying connected clients via the bridge.
-   * - 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;
-    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) => {
-        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();
+    /**
+     * 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;
         }
-      });
-      const browserBuildPlugins = getAppBrowserBuildPlugins(this.appConfig);
-      this.hmrManager.setPlugins(browserBuildPlugins);
-      for (const integration of this.appConfig.integrations) {
-        integration.setHmrManager(this.hmrManager);
-      }
-      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,
-        bridge: this.bridge
-      });
-      await watcher.createWatcherSubscription();
+        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`.
+     *
+     * Delegates to `handleSharedRequest` for all routing, caching, and response
+     * handler logic. The only Node-specific concern here is translating a
+     * `ClientAbortError` — which the body `ReadableStream` raises when the
+     * underlying socket closes early — into a 499 response so it does not
+     * incorrectly surface as a 500 in application logs.
+     */
+    async handleRequest(request) {
+        if (!this.initialized) {
+            throw new Error('Node server adapter is not initialized. Call createAdapter() first.');
+        }
+        try {
+            const response = await this.handleSharedRequest(request, {
+                apiHandlers: this.apiHandlers,
+                errorHandler: this.errorHandler,
+                serverInstance: this.serverInstance,
+                hmrManager: this.hmrManager ?? undefined,
+            });
+            return response;
+        }
+        catch (error) {
+            if (error instanceof NodeClientAbortError) {
+                /**
+                 * The client disconnected before the response was sent (killed tab,
+                 * network drop, or programmatic abort). This is a normal browser behaviour,
+                 * not a server fault. Return 499 (Client Closed Request) silently so the
+                 * error does not surface in application logs as a 500.
+                 */
+                return new Response(null, { status: 499 });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Called once the HTTP server is bound and listening.
+     *
+     * When `options.watch` is `true` this method wires the full HMR pipeline:
+     * - A `WebSocketServer` is attached to the existing HTTP server via the
+     *   `upgrade` event (no separate port needed).
+     * - `NodeClientBridge` tracks active WebSocket connections and handles
+     *   broadcast + heartbeat cleanup.
+     * - `NodeHmrManager` watches the filesystem and triggers incremental
+     *   rebuilds, notifying connected clients via the bridge.
+     * - 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 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.ensureRuntimeReady();
+            const hmrPreflight = (req, socket, head) => {
+                const url = new URL(req.url ?? '/', this.runtimeOrigin);
+                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);
+            startDevWarmup({
+                appConfig: this.appConfig,
+                runtimeOrigin: this.runtimeOrigin,
+            });
+            this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
+            await this.startDevStaticRoutePrewarmWhenReady();
+            const watcher = new ProjectWatcher({
+                config: this.appConfig,
+                refreshRouterRoutesCallback: this.createSharedWatchRefreshCallback({
+                    staticRoutes: this.staticRoutes,
+                    hmrManager: this.hmrManager ?? undefined,
+                }),
+                hmrManager: this.hmrManager ?? undefined,
+                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,
+            staticRoutes: this.staticRoutes.length,
+            hasErrorHandler: !!this.errorHandler,
+            hmrEnabled: !!this.hmrManager?.isEnabled(),
+        });
     }
-    appLogger.debug("Node server adapter initialization completed", {
-      apiHandlers: this.apiHandlers.length,
-      staticRoutes: this.staticRoutes.length,
-      hasErrorHandler: !!this.errorHandler,
-      hmrEnabled: !!this.hmrManager?.isEnabled()
-    });
-  }
 }
-async function createNodeServerAdapter(params) {
-  const runtimeOrigin = params.runtimeOrigin ?? resolveServeRuntimeOrigin(params.serveOptions);
-  const previewHost = params.previewHost ?? new NodeStaticPreviewHost();
-  const requestBridge = params.requestBridge ?? new NodeHttpRequestBridge();
-  const devRuntimeFactory = params.devRuntimeFactory ?? new DefaultNodeServerDevRuntimeFactory();
-  const adapter = new NodeServerAdapter({
-    ...params,
-    runtimeOrigin,
-    previewHost,
-    requestBridge,
-    devRuntimeFactory
-  });
-  return adapter.createAdapter();
+/**
+ * Factory function that creates and fully initialises a `NodeServerAdapter`.
+ *
+ * `runtimeOrigin` is derived from `serveOptions` when not explicitly provided,
+ * so callers only need to set it when the server is behind a reverse proxy that
+ * changes the effective host or port.
+ */
+export async function createNodeServerAdapter(params) {
+    const runtimeOrigin = params.runtimeOrigin ?? resolveServeRuntimeOrigin(params.serveOptions);
+    const previewHost = params.previewHost ?? new NodeStaticPreviewHost();
+    const requestBridge = params.requestBridge ?? new NodeHttpRequestBridge();
+    const devRuntimeFactory = params.devRuntimeFactory ?? new DefaultNodeServerDevRuntimeFactory();
+    const adapter = new NodeServerAdapter({
+        ...params,
+        runtimeOrigin,
+        previewHost,
+        requestBridge,
+        devRuntimeFactory,
+    });
+    return adapter.createAdapter();
 }
-export {
-  NodeServerAdapter,
-  createNodeServerAdapter
-};