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

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

@@ -1,24 +1,30 @@
 import path from "node:path";
 import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
-import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
 import { appLogger } from "../../global/app-logger.js";
 import { HttpError } from "../../errors/http-error.js";
 import { createRequire } from "../../utils/locals-utils.js";
+import { findWebSocketRoute } from "../abstract/ws-pattern-matcher.js";
 import { fileSystem } from "@ecopages/file-system";
-import { getAppBrowserBuildPlugins, setupAppRuntimePlugins } from "../../build/build-adapter.js";
-import { installAppRuntimeBuildExecutor } from "../../build/runtime-build-executor.js";
+import { setupAppRuntimePlugins } from "../../build/build-adapter.js";
+import { installBuildRuntime } from "../../build/runtime/build-runtime.js";
 import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator.js";
 import { ProjectWatcher } from "../../watchers/project-watcher.js";
-import { SharedServerAdapter } from "../shared/server-adapter.js";
-import { ApiResponseBuilder } from "../shared/api-response.js";
-import { ServerStaticBuilder } from "../shared/server-static-builder.js";
+import { SharedServerAdapter } from "../shared/runtime/server-adapter.js";
+import { ApiResponseBuilder } from "../shared/http/api-response.js";
+import { ServerStaticBuilder } from "../shared/runtime/server-static-builder.js";
+import { attachNodeHttpWebSocketUpgrades } from "../shared/ws/node-http-websocket-upgrades.js";
+import { createBunUserWebSocketLifecycle } from "./bun-user-websocket-lifecycle.js";
+import { createEcopagesSocket } from "../shared/ws/websocket-lifecycle.js";
+import { resolveServeRuntimeOrigin } from "../shared/runtime/runtime-app-bootstrap.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 { ClientBridge } from "./client-bridge.js";
+import { setAppDevClientBridge } from "../../dev/client-bridge-registry.js";
+import { setAppHmrManager } from "../../dev/hmr-manager-registry.js";
 import { HmrManager } from "./hmr-manager.js";
 import { BunStaticPreviewHost } from "./static-preview-host.js";
 class BunServerAdapter extends SharedServerAdapter {
@@ -29,7 +35,59 @@ class BunServerAdapter extends SharedServerAdapter {
   hmrManager;
   initializationPromise = null;
   fullyInitialized = false;
+  projectWatcher = null;
+  adapterDisposed = false;
+  deferRuntimeAssetSetup;
+  allowPortFallback;
   previewHost;
+  /**
+   * 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 Bun adapter reads from it to wire
+   * WebSocket upgrades for user-registered patterns.
+   */
+  websocketHandlers = /* @__PURE__ */ new Map();
+  registerBunRuntimePlugin(plugin) {
+    Bun.plugin(plugin);
+  }
+  adaptBunWebSocket(ws, kind, params, search, context) {
+    return createEcopagesSocket(
+      {
+        send: (data) => ws.send(data),
+        close: (code, reason) => ws.close(code, reason)
+      },
+      { kind, params, search, context }
+    );
+  }
+  /**
+   * Resolves the per-connection context for a Bun user connection.
+   *
+   * @remarks
+   * `context()` is invoked exactly once per accepted connection. Its
+   * resolved value is shared by all subsequent lifecycle hooks. If
+   * `context()` throws, the connection is closed immediately with code
+   * 1011 (server error) and the error is logged.
+   *
+   * @param request - The original upgrade request (best-effort reconstructed)
+   * @param handler - The registered handler
+   * @param kind - The registered route pattern
+   * @param params - Dynamic path parameters
+   * @param search - Query string parameters
+   * @returns The resolved per-connection context
+   */
+  async resolveBunContext(request, handler, kind, params, search) {
+    if (!handler.context) {
+      return void 0;
+    }
+    try {
+      return await handler.context({ request, kind, params, search });
+    } catch (error) {
+      appLogger.error(`[WS:${kind}] context() failed; closing connection.`, error);
+      throw error;
+    }
+  }
   /**
    * Creates a Bun server adapter with already-resolved runtime collaborators.
    *
@@ -46,74 +104,64 @@ class BunServerAdapter extends SharedServerAdapter {
     apiHandlers,
     staticRoutes,
     errorHandler,
+    websocketHandlers,
     options,
+    hostOwnsDevClient,
+    deferRuntimeAssetSetup,
+    allowPortFallback,
     hmrManager,
     bridge,
     previewHost
   }) {
     super({ appConfig, runtimeOrigin, serveOptions, options });
+    this.deferRuntimeAssetSetup = deferRuntimeAssetSetup === true;
+    this.allowPortFallback = allowPortFallback !== false;
     this.apiHandlers = apiHandlers || [];
     this.staticRoutes = staticRoutes || [];
     this.errorHandler = errorHandler;
     this.bridge = bridge;
     this.hmrManager = hmrManager;
     this.previewHost = previewHost;
+    this.hostOwnsDevClient = hostOwnsDevClient === true;
+    if (websocketHandlers) {
+      this.websocketHandlers = websocketHandlers;
+    }
   }
   /**
-   * Returns whether adapter-level HTML responses still need HMR runtime injection.
-   *
-   * @remarks
-   * Filesystem-routed pages are wrapped later in the shared route layer. This
-   * adapter-level check exists for explicit API handlers that return HTML and
-   * would otherwise bypass the route wrapper entirely.
-   */
-  shouldInjectHmrScript() {
-    return shouldInjectHmrHtmlResponse(this.options?.watch === true, this.hmrManager);
-  }
-  /**
-   * Delegates the HTML-response test to the shared response helper used by both
-   * adapters.
-   */
-  isHtmlResponse(response) {
-    return isHtmlResponse(response);
-  }
-  /**
-   * Injects HMR script into HTML responses in development mode.
-   * Ensures explicit API handlers that return HTML get auto-reload capability.
+   * Wires user WebSocket routes onto a Node HTTP server used by host integrations.
    */
-  async maybeInjectHmrScript(response) {
-    if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
-      return injectHmrRuntimeIntoHtmlResponse(response);
-    }
-    return response;
+  attachUserWebSocketUpgrades(server, options) {
+    attachNodeHttpWebSocketUpgrades(server, {
+      runtimeOrigin: this.runtimeOrigin,
+      websocketHandlers: this.websocketHandlers,
+      passthroughUnmatched: options?.passthroughUnmatched
+    });
   }
   /**
    * Initializes the server adapter's core runtime components.
    */
   async initialize() {
-    installAppRuntimeBuildExecutor(this.appConfig);
+    installBuildRuntime(this.appConfig);
     this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
-    await this.hmrManager.buildRuntime();
-    this.prepareRuntimePublicDir();
+    prepareRuntimePublicDir(this.appConfig);
     const staticBuilderOptions = {
       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,
+      onRuntimePlugin: (plugin) => {
+        this.registerBunRuntimePlugin(plugin);
+      }
     };
     this.staticBuilder = new ServerStaticBuilder(staticBuilderOptions);
-    await this.initializeRuntimePlugins({ watch: this.options?.watch });
-  }
-  /**
-   * Copies the source `public` directory into the runtime output and ensures the
-   * HMR assets directory exists before any runtime bundles are emitted.
-   */
-  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));
+    if (!this.deferRuntimeAssetSetup) {
+      await this.initializeRuntimePlugins({ watch: this.options?.watch });
+    }
+    if (this.options?.watch) {
+      await this.hmrManager.ensureRuntimeReady();
     }
-    fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
   }
   /**
    * Registers runtime plugins and propagates the final HMR manager into each
@@ -130,15 +178,12 @@ class BunServerAdapter extends SharedServerAdapter {
       await setupAppRuntimePlugins({
         appConfig: this.appConfig,
         runtimeOrigin: this.runtimeOrigin,
-        hmrManager: this.hmrManager,
         onRuntimePlugin: (plugin) => {
-          Bun.plugin(plugin);
+          this.registerBunRuntimePlugin(plugin);
         }
       });
-      const browserBuildPlugins = getAppBrowserBuildPlugins(this.appConfig);
-      this.hmrManager.setPlugins(browserBuildPlugins);
-      for (const integration of this.appConfig.integrations) {
-        integration.setHmrManager(this.hmrManager);
+      if (options?.watch) {
+        attachHmrToIntegrations(this.appConfig, this.hmrManager);
       }
     } catch (error) {
       appLogger.error(`Failed to initialize plugins: ${error instanceof Error ? error.message : String(error)}`);
@@ -173,70 +218,109 @@ class BunServerAdapter extends SharedServerAdapter {
       config: this.appConfig,
       refreshRouterRoutesCallback: this.refreshRouterRoutes.bind(this),
       hmrManager: this.hmrManager,
-      bridge: this.bridge
+      bridge: this.bridge,
+      hostOwnsDevClient: this.hostOwnsDevClient
     });
+    this.projectWatcher = watcher;
     await watcher.createWatcherSubscription();
   }
   /**
    * Builds the `Bun.serve()` options for the current adapter state.
    *
    * @remarks
-   * The HMR-enabled variant wraps the base fetch handler so one Bun server can
-   * serve normal requests, accept HMR websocket upgrades, and expose the HMR
-   * runtime asset without splitting responsibility across separate listeners.
+   * When HMR is enabled the websocket dispatcher merges HMR and user handlers,
+   * routing by the `kind` field embedded in socket data at upgrade time.
+   * This prevents user-registered websocket handlers from being silently overwritten
+   * by the HMR handler in development mode.
+   *
+   * User WebSocket paths are intercepted in the fetch handler via the pattern matcher.
+   * The upgrade happens implicitly — no manual GET route registration needed.
    */
   getServerOptions({ enableHmr = false } = {}) {
     appLogger.debug(`[BunServerAdapter] getServerOptions called with enableHmr: ${enableHmr}`);
     const serverOptions = this.buildServerSettings();
+    const hasUserWs = this.websocketHandlers.size > 0;
+    if (!enableHmr && !hasUserWs) {
+      return serverOptions;
+    }
+    const userLifecycle = this.createBunUserLifecycle();
     if (enableHmr) {
-      const originalFetch = serverOptions.fetch;
-      const hmrHandler = this.hmrManager.getWebSocketHandler();
-      const hmrManager = this.hmrManager;
       serverOptions.development = true;
-      serverOptions.websocket = hmrHandler;
-      serverOptions.fetch = async function(request, _server) {
-        const url = new URL(request.url);
-        appLogger.debug(`[HMR] Request: ${url.pathname}`);
-        if (url.pathname === "/_hmr") {
-          const success = this.upgrade(request, {
-            data: void 0
-          });
-          if (success) return;
-          return new Response("WebSocket upgrade failed", { status: 400 });
-        }
-        if (url.pathname === "/_hmr_runtime.js") {
-          appLogger.debug(`[HMR] Serving runtime from ${hmrManager.getRuntimePath()}`);
-          return new Response(fileSystem.readFileAsBuffer(hmrManager.getRuntimePath()), {
-            headers: { "Content-Type": "application/javascript" }
-          });
-        }
-        let response;
-        if (originalFetch) {
-          const res = await originalFetch.call(this, request, this);
-          response = res instanceof Response ? res : new Response("Not Found", { status: 404 });
-        } else {
-          response = new Response("Not Found", { status: 404 });
-        }
-        return response;
-      };
+      serverOptions.websocket = this.createHmrAwareWebSocketHandler(userLifecycle);
+    } else {
+      serverOptions.websocket = userLifecycle;
     }
+    serverOptions.fetch = this.wrapFetchWithWebSocketUpgrades(serverOptions.fetch, {
+      serveHmrEndpoints: enableHmr
+    });
     return serverOptions;
   }
+  createBunUserLifecycle() {
+    return createBunUserWebSocketLifecycle({
+      runtimeOrigin: this.runtimeOrigin,
+      userHandlers: this.websocketHandlers,
+      resolveContext: this.resolveBunContext.bind(this),
+      adaptSocket: (ws, kind, params, search, context) => this.adaptBunWebSocket(ws, kind, params, search, context)
+    });
+  }
   /**
-   * Helper method to retrieve and parse the request body.
-   * Handles JSON and plain text content types.
-   * For FormData (multipart/form-data, x-www-form-urlencoded), use ctx.request.formData() directly.
-   * Returns undefined for unsupported content types.
+   * @remarks
+   * HMR and user sockets share one Bun `websocket` handler. Upgrade tags HMR
+   * connections with `kind: '__hmr__'`; everything else routes to the user lifecycle.
    */
-  async retrieveBodyFromRequest(request) {
-    const contentType = request.headers.get("Content-Type") || "";
-    if (contentType.includes("application/json")) {
-      return await request.json();
-    }
-    if (contentType.includes("text/plain")) {
-      return await request.text();
-    }
-    return void 0;
+  createHmrAwareWebSocketHandler(userLifecycle) {
+    const hmrHandler = this.hmrManager.getWebSocketHandler();
+    const isHmrSocket = (ws) => (ws.data?.kind ?? "__hmr__") === "__hmr__";
+    return {
+      open(ws) {
+        if (isHmrSocket(ws)) return void hmrHandler.open?.(ws);
+        userLifecycle.open(ws);
+      },
+      message(ws, msg) {
+        if (isHmrSocket(ws)) return void hmrHandler.message?.(ws, msg);
+        userLifecycle.message(ws, msg);
+      },
+      close(ws, code, reason) {
+        if (isHmrSocket(ws)) return void hmrHandler.close?.(ws, code, reason);
+        userLifecycle.close(ws, code, reason);
+      },
+      error(ws, error) {
+        if (isHmrSocket(ws)) return void appLogger.error("[HMR] WebSocket error:", error);
+        userLifecycle.error(ws, error);
+      }
+    };
+  }
+  /**
+   * @remarks
+   * When `serveHmrEndpoints` is set, `/_hmr` is checked before user websocket
+   * patterns so HMR upgrades are never captured by app routes. Runtime assets are
+   * served by `SharedServerAdapter.handleSharedRequest` via `tryHandleAssetRequest`.
+   * Production mode with only user handlers skips the HMR branch entirely.
+   */
+  wrapFetchWithWebSocketUpgrades(originalFetch, { serveHmrEndpoints }) {
+    const matchRoute = (pathname) => findWebSocketRoute(this.websocketHandlers, pathname);
+    return async function(request, server) {
+      const url = new URL(request.url);
+      if (serveHmrEndpoints) {
+        if (url.pathname === "/_hmr") {
+          const success = this.upgrade(request, { data: { kind: "__hmr__", params: {}, search: {} } });
+          return success ? void 0 : new Response("WebSocket upgrade failed", { status: 400 });
+        }
+      }
+      const wsMatch = matchRoute(url.pathname);
+      if (wsMatch && request.headers.get("upgrade")?.toLowerCase() === "websocket") {
+        const search = Object.fromEntries(url.searchParams.entries());
+        const success = this.upgrade(request, {
+          data: { kind: wsMatch.kind, params: wsMatch.params, search, upgradeUrl: request.url }
+        });
+        return success ? void 0 : new Response("WebSocket upgrade failed", { status: 400 });
+      }
+      if (!originalFetch) {
+        return new Response("Not Found", { status: 404 });
+      }
+      const res = await originalFetch.call(this, request, server);
+      return res instanceof Response ? res : new Response("Not Found", { status: 404 });
+    };
   }
   /**
    * Composes the base Bun server settings that all runtime modes build from.
@@ -306,9 +390,9 @@ class BunServerAdapter extends SharedServerAdapter {
         hmrManager: this.hmrManager
       });
     }
-    const buildRuntimeOrigin = this.serverInstance ? `http://${this.serverInstance.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serverInstance.port || DEFAULT_ECOPAGES_PORT}` : void 0;
+    const buildRuntimeOrigin = resolveServeRuntimeOrigin(this.serveOptions);
     await this.staticBuilder.build(
-      { ...options, preview: false, baseUrl: buildRuntimeOrigin },
+      { baseUrl: buildRuntimeOrigin, force: options?.force },
       {
         router: this.router,
         routeRendererFactory: this.routeRendererFactory,
@@ -316,19 +400,42 @@ class BunServerAdapter extends SharedServerAdapter {
       }
     );
     if (!options?.preview) {
-      return;
+      return void 0;
+    }
+    return this.startPreviewServer();
+  }
+  /**
+   * Serves an existing static export without running SSG. Used by e2e preview
+   * launchers after a shared prewarm build.
+   */
+  async servePreviewOnly() {
+    if (!this.fullyInitialized) {
+      await this.initializeSharedRouteHandling({
+        staticRoutes: this.staticRoutes,
+        hmrManager: this.hmrManager
+      });
     }
+    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 previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
     const previewPort = Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT);
     const activePreviewPort = await this.previewHost.start({
       appConfig: this.appConfig,
       hostname: String(previewHostname),
-      port: previewPort
+      port: previewPort,
+      allowPortFallback: this.allowPortFallback
     });
-    if (activePreviewPort) {
-      appLogger.info(`Preview running at http://${previewHostname}:${activePreviewPort}`);
-      return;
+    if (!activePreviewPort) {
+      return void 0;
     }
+    return `http://${previewHostname}:${activePreviewPort}`;
   }
   /**
    * Initializes the server with dynamic routes after server creation.
@@ -362,6 +469,13 @@ class BunServerAdapter extends SharedServerAdapter {
       staticRoutes: this.staticRoutes,
       hmrManager: this.hmrManager
     });
+    if (this.options?.watch) {
+      await this.hmrManager.ensureRuntimeReady();
+      startConfiguredIntegrationRuntimePrewarm({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin
+      });
+    }
     this.fullyInitialized = true;
     if (this.options?.watch) await this.watch();
     if (server && typeof server.reload === "function") {
@@ -379,19 +493,42 @@ class BunServerAdapter extends SharedServerAdapter {
     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 Bun 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;
+  }
   /**
    * Handles HTTP requests by passing them securely to the shared core router adapter.
    *
    * @remarks
-   * Filesystem page responses are wrapped by `ServerRouteHandler`. This
-   * adapter-level pass only covers HTML returned by explicit API handlers,
-   * which bypass that route-layer wrapper and would otherwise miss the
-   * dev HMR runtime — so the HMR script injection happens here, after
-   * the shared handler runs.
+   * HMR HTML injection for API and page responses is owned by
+   * `SharedServerAdapter.handleSharedRequest`. This method only maps the
+   * request into the shared pipeline.
    */
   async handleRequest(request) {
     const response = await this.handleSharedRequest(request, {
@@ -400,7 +537,7 @@ class BunServerAdapter extends SharedServerAdapter {
       serverInstance: this.serverInstance,
       hmrManager: this.hmrManager
     });
-    return await this.maybeInjectHmrScript(response);
+    return response;
   }
   /**
    * Ensures server initialization completes before request handling.
@@ -434,6 +571,8 @@ async function createBunServerAdapter(params) {
   const runtimeOrigin = params.runtimeOrigin ?? resolveServeRuntimeOrigin(params.serveOptions);
   const bridge = params.bridge ?? new ClientBridge();
   const hmrManager = params.hmrManager ?? new HmrManager({ appConfig: params.appConfig, bridge });
+  setAppDevClientBridge(params.appConfig, bridge);
+  setAppHmrManager(params.appConfig, hmrManager);
   const previewHost = params.previewHost ?? new BunStaticPreviewHost();
   const adapter = new BunServerAdapter({
     ...params,

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

@@ -1,5 +1,5 @@
 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 BunStaticPreviewServer = {
     server: {
         port?: number;

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

@@ -1,5 +1,6 @@
 import { StaticContentServer } from "../../dev/sc-server.js";
 import { appLogger } from "../../global/app-logger.js";
+import { PortManager } from "../shared/runtime/port-manager.js";
 class BunStaticPreviewHost {
   constructor(previewServerFactory = StaticContentServer, logger = appLogger) {
     this.previewServerFactory = previewServerFactory;
@@ -10,30 +11,34 @@ class BunStaticPreviewHost {
   previewServer = null;
   async start(options) {
     await this.stop();
-    await new Promise((resolve) => setTimeout(resolve, 100));
-    for (let attempt = 0; attempt < 20; attempt += 1) {
-      try {
-        this.previewServer = this.previewServerFactory.createServer({
+    let previewServer = null;
+    const portManager = new PortManager({
+      startOnPort: async (port) => {
+        const candidate = this.previewServerFactory.createServer({
           appConfig: options.appConfig,
-          options: { port: options.port }
+          options: { port }
         });
-        const previewPort = this.previewServer.server?.port;
-        if (previewPort) {
-          return previewPort;
+        const boundPort = candidate.server?.port ?? null;
+        if (!boundPort) {
+          candidate.stop();
+          return null;
         }
-        break;
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        const errorCode = typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
-        const isPortReleaseRace = errorCode === "EADDRINUSE" || errorMessage.includes("EADDRINUSE");
-        if (!isPortReleaseRace || attempt === 19) {
-          throw error;
-        }
-        await new Promise((resolve) => setTimeout(resolve, 100));
-      }
+        previewServer = candidate;
+        return boundPort;
+      },
+      warn: (message) => appLogger.warn(message)
+    });
+    const previewPort = await portManager.bind({
+      preferredPort: options.port,
+      allowPortFallback: options.allowPortFallback === true
+    });
+    if (!previewPort) {
+      this.previewServer = null;
+      this.logger.error("Failed to start preview server");
+      return null;
     }
-    this.logger.error("Failed to start preview server");
-    return null;
+    this.previewServer = previewServer;
+    return previewPort;
   }
   async stop() {
     this.previewServer?.stop();

package/src/adapters/create-app.d.ts

@@ -1,20 +1,22 @@
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
 import { AbstractApplicationAdapter } from './abstract/application-adapter.js';
 import type { ApplicationAdapterOptions } from './abstract/application-adapter.js';
-import { SharedApplicationAdapter } from './shared/application-adapter.js';
+export type { OnAppStartCallback, AppStartInfo, StartCallback, ListenCallback, ApplicationListeningCallback, ApplicationListeningInfo, } from './abstract/application-adapter.js';
+export type EcopagesRuntimeAdapter = 'auto' | 'node' | 'bun';
 export interface EcopagesAppOptions extends ApplicationAdapterOptions {
     appConfig: EcoPagesAppConfig;
+    /**
+     * Selects the runtime adapter used by the universal `createApp()` entrypoint.
+     *
+     * @default 'auto'
+     *
+     * @remarks
+     * This is separate from `runtime`, which configures embedded host behavior.
+     * Use `auto` to select Bun when the current process exposes `globalThis.Bun`
+     * and Node otherwise.
+     */
+    adapter?: EcopagesRuntimeAdapter;
     serverOptions?: Record<string, any>;
 }
 export type UniversalEcopagesApp = AbstractApplicationAdapter<EcopagesAppOptions, unknown, Request>;
 export declare function createApp<WebSocketData = undefined>(options: EcopagesAppOptions): Promise<UniversalEcopagesApp>;
-export declare class EcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, unknown, Request> {
-    private readonly appOptions;
-    private runtimeApp;
-    private runtimeAppPromise;
-    constructor(options: EcopagesAppOptions);
-    private getRuntimeApp;
-    protected initializeServerAdapter(): Promise<UniversalEcopagesApp>;
-    start(): Promise<unknown>;
-    fetch(request: Request): Promise<Response>;
-}