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

package/src/adapters/node/node-hmr-manager.d.ts

@@ -4,6 +4,7 @@ import { SharedHmrManager } from '../shared/shared-hmr-manager.js';
 export interface NodeHmrManagerParams {
     appConfig: EcoPagesAppConfig;
     bridge: IClientBridge;
+    registrationTimeoutMs?: number;
 }
 /**
  * Node development HMR manager.
@@ -28,7 +29,7 @@ export declare class NodeHmrManager extends SharedHmrManager {
      * actually differs: dependency-graph storage, missing-file tolerance, and how
      * runtime bundle failures disable HMR.
      */
-    constructor({ appConfig, bridge }: NodeHmrManagerParams);
+    constructor({ appConfig, bridge, registrationTimeoutMs }: NodeHmrManagerParams);
     /**
      * Reuses the shared in-memory dependency graph when the app already has one and
      * otherwise creates the default Node development graph.

package/src/adapters/node/node-hmr-manager.js

@@ -13,8 +13,8 @@ class NodeHmrManager extends SharedHmrManager {
    * actually differs: dependency-graph storage, missing-file tolerance, and how
    * runtime bundle failures disable HMR.
    */
-  constructor({ appConfig, bridge }) {
-    super({ appConfig, bridge });
+  constructor({ appConfig, bridge, registrationTimeoutMs }) {
+    super({ appConfig, bridge, registrationTimeoutMs });
   }
   /**
    * Reuses the shared in-memory dependency graph when the app already has one and

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

@@ -1,4 +1,5 @@
 import { WebSocketServer } from "ws";
+import { setAppDevClientBridge } from "../../dev/client-bridge-registry.js";
 import { NodeClientBridge } from "./node-client-bridge.js";
 import { NodeHmrManager } from "./node-hmr-manager.js";
 class DefaultNodeServerDevRuntimeFactory {
@@ -6,6 +7,7 @@ class DefaultNodeServerDevRuntimeFactory {
     const websocketServer = new WebSocketServer({ noServer: true });
     const bridge = new NodeClientBridge();
     const hmrManager = new NodeHmrManager({ appConfig: options.appConfig, bridge });
+    setAppDevClientBridge(options.appConfig, bridge);
     return {
       websocketServer,
       bridge,

package/src/adapters/node/server-adapter.d.ts

@@ -1,6 +1,6 @@
 import { type Server as NodeHttpServer } from 'node:http';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ApiHandler, ErrorHandler, StaticRoute } from '../../types/public-types.js';
+import type { ApiHandler, ErrorHandler, StaticRoute, EcopagesWebSocketHandler } from '../../types/public-types.js';
 import { SharedServerAdapter } from '../shared/server-adapter.js';
 import type { ServerAdapterResult } from '../abstract/server-adapter.js';
 import { NodeHttpRequestBridge } from './http-request-bridge.js';
@@ -19,9 +19,14 @@ export interface NodeServerAdapterParams {
     apiHandlers?: ApiHandler[];
     staticRoutes?: StaticRoute[];
     errorHandler?: ErrorHandler;
+    websocketHandlers?: Map<string, EcopagesWebSocketHandler<any, any>>;
+    delegateBrowserReloadToHost?: boolean;
+    hostOwnsDevClient?: boolean;
     options?: {
         watch?: boolean;
     };
+    deferRuntimeAssetSetup?: boolean;
+    allowPortFallback?: boolean;
     previewHost?: StaticPreviewHost;
     requestBridge?: NodeHttpRequestBridge;
     devRuntimeFactory?: NodeServerDevRuntimeFactory;
@@ -29,6 +34,10 @@ export interface NodeServerAdapterParams {
 export interface NodeServerAdapterResult extends ServerAdapterResult {
     completeInitialization: (server: NodeServerInstance) => Promise<void>;
     handleRequest: (request: Request) => Promise<Response>;
+    attachUserWebSocketUpgrades: (server: NodeServerInstance, options?: {
+        passthroughUnmatched?: boolean;
+    }) => void;
+    dispose: () => Promise<void>;
 }
 /**
  * Node.js HTTP server adapter for the Ecopages runtime.
@@ -58,13 +67,47 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
     private errorHandler?;
     private bridge;
     private hmrManager;
+    private projectWatcher;
+    private adapterDisposed;
+    private readonly deferRuntimeAssetSetup;
+    private readonly allowPortFallback;
     private readonly previewHost;
     private readonly requestBridge;
     private readonly devRuntimeFactory;
-    private shouldInjectHmrScript;
-    private isHtmlResponse;
+    /**
+     * 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.
+     */
+    protected websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    /**
+     * 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: NodeServerInstance, options?: {
+        passthroughUnmatched?: boolean;
+    }): void;
+    private wireUserWebSocketUpgrades;
     private maybeInjectHmrScript;
-    constructor(options: NodeServerAdapterParams);
+    /**
+     * @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: NodeServerAdapterParams & {
+        previewHost: StaticPreviewHost;
+        requestBridge: NodeHttpRequestBridge;
+        devRuntimeFactory: NodeServerDevRuntimeFactory;
+    });
     /**
      * Prepares the adapter for use.
      *
@@ -79,27 +122,20 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      *    processors during their `setup()` calls.
      */
     initialize(): Promise<void>;
-    private prepareRuntimePublicDir;
     getServerOptions(): NodeServeAdapterServerOptions;
     buildStatic(options?: {
         preview?: boolean;
+        force?: boolean;
     }): Promise<void>;
-    private startBuildRuntimeServer;
-    private getListeningServerOrigin;
+    createAdapter(): Promise<NodeServerAdapterResult>;
     /**
-     * Gracefully shuts down the ephemeral build runtime server.
+     * Releases dev-time resources owned by the adapter.
      *
-     * `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.
+     * @remarks
+     * Safe to call multiple times. Does not stop the bound HTTP server — callers
+     * should shut down transport through the runtime host before disposing.
      */
-    private stopBuildRuntimeServer;
-    createAdapter(): Promise<NodeServerAdapterResult>;
+    dispose(): Promise<void>;
     /**
      * Handles a single incoming Web `Request` and returns a Web `Response`.
      *
@@ -123,7 +159,7 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      * - 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.
      */
     completeInitialization(server: NodeServerInstance): Promise<void>;

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

@@ -1,22 +1,23 @@
-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 {} from "node:http";
+import { 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 {
+  attachNodeHttpWebSocketUpgrades
+} from "../shared/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 { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
 import {
-  injectHmrRuntimeIntoHtmlResponse,
-  isHtmlResponse,
-  shouldInjectHmrHtmlResponse
-} from "../shared/hmr-html-response.js";
+  maybeInjectAdapterHmrHtmlResponse,
+  prepareRuntimePublicDir,
+  wireIntegrationHmrManagers,
+  disposeDevResources
+} from "../shared/runtime-server-lifecycle.js";
 import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
 import { NodeClientAbortError, NodeHttpRequestBridge } from "./http-request-bridge.js";
 import { NodeStaticPreviewHost } from "./static-preview-host.js";
@@ -29,29 +30,73 @@ 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);
+  /**
+   * 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
+    });
   }
-  isHtmlResponse(response) {
-    return isHtmlResponse(response);
+  wireUserWebSocketUpgrades(server, preflight) {
+    attachNodeHttpWebSocketUpgrades(server, {
+      runtimeOrigin: this.runtimeOrigin,
+      websocketHandlers: this.websocketHandlers,
+      passthroughUnmatched: false,
+      preflight
+    });
   }
   async maybeInjectHmrScript(response) {
-    if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
-      return injectHmrRuntimeIntoHtmlResponse(response);
-    }
-    return response;
+    return maybeInjectAdapterHmrHtmlResponse(response, {
+      watch: this.options?.watch === true,
+      hmrManager: this.hmrManager ?? void 0,
+      hostOwnsDevClient: this.hostOwnsDevClient
+    });
   }
+  /**
+   * @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.
@@ -68,12 +113,14 @@ class NodeServerAdapter extends SharedServerAdapter {
    */
   async initialize() {
     installAppRuntimeBuildExecutor(this.appConfig);
-    this.prepareRuntimePublicDir();
-    await setupAppRuntimePlugins({
-      appConfig: this.appConfig,
-      runtimeOrigin: this.runtimeOrigin,
-      hmrManager: this.hmrManager ?? void 0
-    });
+    prepareRuntimePublicDir(this.appConfig);
+    if (!this.deferRuntimeAssetSetup) {
+      await setupAppRuntimePlugins({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin,
+        hmrManager: this.hmrManager ?? void 0
+      });
+    }
     await this.initializeSharedRouteHandling({
       staticRoutes: this.staticRoutes,
       hmrManager: this.hmrManager ?? void 0
@@ -83,17 +130,12 @@ class NodeServerAdapter extends SharedServerAdapter {
       appConfig: this.appConfig,
       staticSiteGenerator: this.staticSiteGenerator,
       serveOptions: this.serveOptions,
-      apiHandlers: this.apiHandlers
+      runtimeOrigin: this.runtimeOrigin,
+      apiHandlers: this.apiHandlers,
+      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,96 +145,29 @@ 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);
-    }
+    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;
     }
-    await this.previewHost.start({
+    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)
+      port: Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT),
+      allowPortFallback: this.allowPortFallback
     });
-    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");
-      }
-    });
-    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");
-    }
-    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;
-        }
-        resolve();
-      });
-      server.closeAllConnections();
-    });
-    if (this.serverInstance === server) {
-      this.serverInstance = null;
+    if (!activePreviewPort) {
+      return;
     }
-    this.bridge?.destroy();
-    this.bridge = null;
+    const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
+    appLogger.info(`Preview running at http://${previewHostname}:${activePreviewPort}`);
   }
   async createAdapter() {
     await this.initialize();
@@ -200,9 +175,34 @@ class NodeServerAdapter extends SharedServerAdapter {
       getServerOptions: this.getServerOptions.bind(this),
       buildStatic: this.buildStatic.bind(this),
       completeInitialization: this.completeInitialization.bind(this),
-      handleRequest: this.handleRequest.bind(this)
+      handleRequest: this.handleRequest.bind(this),
+      attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this),
+      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`.
    *
@@ -244,11 +244,12 @@ 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;
@@ -256,23 +257,26 @@ class NodeServerAdapter extends SharedServerAdapter {
       this.hmrManager = devRuntime.hmrManager;
       this.hmrManager.setEnabled(true);
       await this.hmrManager.buildRuntime();
-      server.on("upgrade", (req, socket, head) => {
+      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();
+          }
+        });
       }
+      wireIntegrationHmrManagers(this.appConfig, this.hmrManager);
       this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
       const watcher = new ProjectWatcher({
         config: this.appConfig,
@@ -281,9 +285,13 @@ class NodeServerAdapter extends SharedServerAdapter {
           hmrManager: this.hmrManager
         }),
         hmrManager: this.hmrManager,
-        bridge: this.bridge
+        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.js

@@ -1,3 +1,5 @@
+import { appLogger } from "../../global/app-logger.js";
+import { PortManager } from "../shared/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/bun-user-websocket-lifecycle.d.ts

@@ -0,0 +1,22 @@
+import type { ServerWebSocket } from 'bun';
+import type { EcopagesSocket, EcopagesWebSocketHandler } from '../../types/public-types.js';
+export type BunUserWebSocketData = {
+    kind: string;
+    params: Record<string, string>;
+    search: Record<string, string>;
+    upgradeUrl?: string;
+    context?: unknown;
+    [key: string]: unknown;
+};
+export type BunUserWebSocketLifecycleDeps<TWsData extends BunUserWebSocketData> = {
+    runtimeOrigin: string;
+    userHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    resolveContext: <TContext, TParams extends Record<string, string>>(request: Request, handler: EcopagesWebSocketHandler<TContext, TParams>, kind: string, params: TParams, search: Record<string, string>) => Promise<TContext>;
+    adaptSocket: <TContext, TParams extends Record<string, string>>(ws: ServerWebSocket<TWsData>, kind: string, params: TParams, search: Record<string, string>, context: TContext) => EcopagesSocket<TContext, TParams>;
+};
+export declare function createBunUserWebSocketLifecycle<TWsData extends BunUserWebSocketData>(deps: BunUserWebSocketLifecycleDeps<TWsData>): {
+    open(ws: ServerWebSocket<TWsData>): void;
+    message(ws: ServerWebSocket<TWsData>, msg: string | Buffer): void;
+    close(ws: ServerWebSocket<TWsData>, code: number, reason: string): void;
+    error(ws: ServerWebSocket<TWsData>, error: Error): void;
+};