@ecopages/core 0.2.0-beta.8 → 0.2.0-rc.0

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

@@ -1,670 +1,590 @@
-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 { 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 {
-  injectHmrRuntimeIntoHtmlResponse,
-  isHtmlResponse,
-  shouldInjectHmrHtmlResponse
-} from "../shared/hmr-html-response.js";
-import { attachNodeHttpWebSocketUpgrades } from "../shared/node-http-websocket-upgrades.js";
-import { createBunUserWebSocketLifecycle } from "../shared/bun-user-websocket-lifecycle.js";
-import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
-import { copyRuntimePublicDirIfChanged } from "../shared/copy-runtime-public-dir.js";
-import { ClientBridge } from "./client-bridge.js";
-import { HmrManager } from "./hmr-manager.js";
-import { BunStaticPreviewHost } from "./static-preview-host.js";
-class BunServerAdapter extends SharedServerAdapter {
-  apiHandlers;
-  staticRoutes;
-  errorHandler;
-  bridge;
-  hmrManager;
-  initializationPromise = null;
-  fullyInitialized = false;
-  projectWatcher = null;
-  adapterDisposed = false;
-  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();
-  /**
-   * Adapts a Bun ServerWebSocket to the public EcopagesSocket interface.
-   *
-   * @remarks
-   * This is the single source of truth for the Bun→public type adaptation.
-   * Both the HMR and production branches use this helper to ensure consistency.
-   *
-   * @param ws - The raw Bun ServerWebSocket
-   * @param kind - The registered route pattern
-   * @param params - Dynamic path parameters
-   * @param search - Query string parameters
-   * @param context - The resolved per-connection context
-   * @returns An EcopagesSocket view
-   */
-  adaptBunWebSocket(ws, kind, params, search, context) {
-    return {
-      kind,
-      params,
-      search,
-      context,
-      send: (message) => {
-        if (typeof message === "string") {
-          ws.send(message);
-        } else if (message instanceof Blob) {
-          void message.arrayBuffer().then((buf) => ws.send(new Uint8Array(buf)));
-        } else if (message instanceof ArrayBuffer) {
-          ws.send(new Uint8Array(message));
-        } else if (ArrayBuffer.isView(message)) {
-          ws.send(new Uint8Array(message.buffer, message.byteOffset, message.byteLength));
-        } else {
-          ws.send(message);
+import path from 'node:path';
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } 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 { 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/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 { attachHmrToIntegrations, disposeDevResources, prepareRuntimePublicDir, startDevWarmup, } 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';
+/**
+ * Bun transport adapter that wires shared Ecopages request handling onto a live
+ * `Bun.serve()` runtime.
+ *
+ * @remarks
+ * The adapter owns Bun-specific concerns that do not exist in the shared server
+ * abstraction: websocket-backed HMR transport, runtime plugin registration, and
+ * preview-host startup for static builds. Routing, rendering, and response
+ * composition still delegate to the shared server adapter base.
+ */
+export class BunServerAdapter extends SharedServerAdapter {
+    apiHandlers;
+    staticRoutes;
+    errorHandler;
+    bridge;
+    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 = 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 undefined;
         }
-      },
-      sendStream: async (stream) => {
-        const reader = stream.getReader();
         try {
-          while (true) {
-            const { value, done } = await reader.read();
-            if (done) break;
-            if (value) ws.send(value);
-          }
-        } finally {
-          reader.releaseLock();
+            return (await handler.context({ request, kind, params, search }));
+        }
+        catch (error) {
+            appLogger.error(`[WS:${kind}] context() failed; closing connection.`, error);
+            throw error;
         }
-      },
-      close: (code, reason) => ws.close(code, reason)
-    };
-  }
-  /**
-   * 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.
-   *
-   * @remarks
-   * The public params interface keeps `hmrManager`, `bridge`, and `previewHost`
-   * optional so factory callers can omit them. By the time the concrete adapter
-   * is constructed, those collaborators are mandatory because the adapter cannot
-   * initialize Bun HMR or preview flows without them.
-   */
-  constructor({
-    appConfig,
-    runtimeOrigin,
-    serveOptions,
-    apiHandlers,
-    staticRoutes,
-    errorHandler,
-    websocketHandlers,
-    options,
-    hmrManager,
-    bridge,
-    previewHost
-  }) {
-    super({ appConfig, runtimeOrigin, serveOptions, options });
-    this.apiHandlers = apiHandlers || [];
-    this.staticRoutes = staticRoutes || [];
-    this.errorHandler = errorHandler;
-    this.bridge = bridge;
-    this.hmrManager = hmrManager;
-    this.previewHost = previewHost;
-    if (websocketHandlers) {
-      this.websocketHandlers = websocketHandlers;
+    /**
+     * Creates a Bun server adapter with already-resolved runtime collaborators.
+     *
+     * @remarks
+     * The public params interface keeps `hmrManager`, `bridge`, and `previewHost`
+     * optional so factory callers can omit them. By the time the concrete adapter
+     * is constructed, those collaborators are mandatory because the adapter cannot
+     * initialize Bun HMR or preview flows without them.
+     */
+    constructor({ appConfig, runtimeOrigin, serveOptions, 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;
+        }
     }
-  }
-  /**
-   * Wires user WebSocket routes onto a Node HTTP server used by host integrations.
-   */
-  attachUserWebSocketUpgrades(server, options) {
-    attachNodeHttpWebSocketUpgrades(server, {
-      runtimeOrigin: this.runtimeOrigin,
-      websocketHandlers: this.websocketHandlers,
-      passthroughUnmatched: options?.passthroughUnmatched
-    });
-  }
-  /**
-   * 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.
-   */
-  async maybeInjectHmrScript(response) {
-    if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
-      return injectHmrRuntimeIntoHtmlResponse(response);
+    /**
+     * Wires user WebSocket routes onto a Node HTTP server used by host integrations.
+     */
+    attachUserWebSocketUpgrades(server, options) {
+        attachNodeHttpWebSocketUpgrades(server, {
+            runtimeOrigin: this.runtimeOrigin,
+            websocketHandlers: this.websocketHandlers,
+            passthroughUnmatched: options?.passthroughUnmatched,
+        });
     }
-    return response;
-  }
-  /**
-   * Initializes the server adapter's core runtime components.
-   */
-  async initialize() {
-    installAppRuntimeBuildExecutor(this.appConfig);
-    this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
-    if (this.options?.watch) {
-      await this.hmrManager.buildRuntime();
+    /**
+     * Initializes the server adapter's core runtime components.
+     */
+    async initialize() {
+        installBuildRuntime(this.appConfig);
+        this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
+        prepareRuntimePublicDir(this.appConfig);
+        const staticBuilderOptions = {
+            appConfig: this.appConfig,
+            staticSiteGenerator: this.staticSiteGenerator,
+            serveOptions: this.serveOptions,
+            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);
+        if (!this.deferRuntimeAssetSetup) {
+            await this.initializeRuntimePlugins({ watch: this.options?.watch });
+        }
+        if (this.options?.watch) {
+            await this.hmrManager.ensureRuntimeReady();
+        }
     }
-    this.prepareRuntimePublicDir();
-    const staticBuilderOptions = {
-      appConfig: this.appConfig,
-      staticSiteGenerator: this.staticSiteGenerator,
-      serveOptions: this.serveOptions,
-      apiHandlers: this.apiHandlers
-    };
-    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)) {
-      copyRuntimePublicDirIfChanged(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
+    /**
+     * Registers runtime plugins and propagates the final HMR manager into each
+     * integration.
+     *
+     * @remarks
+     * This is where Bun's runtime-plugin registration path meets the integration
+     * lifecycle. A failure here leaves the runtime partially bootstrapped, so the
+     * method logs the underlying error and rethrows instead of trying to limp on.
+     */
+    async initializeRuntimePlugins(options) {
+        try {
+            this.hmrManager.setEnabled(Boolean(options?.watch));
+            await setupAppRuntimePlugins({
+                appConfig: this.appConfig,
+                runtimeOrigin: this.runtimeOrigin,
+                onRuntimePlugin: (plugin) => {
+                    this.registerBunRuntimePlugin(plugin);
+                },
+            });
+            if (options?.watch) {
+                attachHmrToIntegrations(this.appConfig, this.hmrManager);
+            }
+        }
+        catch (error) {
+            appLogger.error(`Failed to initialize plugins: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
+        }
     }
-    fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
-  }
-  /**
-   * Registers runtime plugins and propagates the final HMR manager into each
-   * integration.
-   *
-   * @remarks
-   * This is where Bun's runtime-plugin registration path meets the integration
-   * lifecycle. A failure here leaves the runtime partially bootstrapped, so the
-   * method logs the underlying error and rethrows instead of trying to limp on.
-   */
-  async initializeRuntimePlugins(options) {
-    try {
-      this.hmrManager.setEnabled(Boolean(options?.watch));
-      await setupAppRuntimePlugins({
-        appConfig: this.appConfig,
-        runtimeOrigin: this.runtimeOrigin,
-        hmrManager: this.hmrManager,
-        onRuntimePlugin: (plugin) => {
-          Bun.plugin(plugin);
+    /**
+     * Rebuilds the shared routing state and hot-reloads the live Bun server when a
+     * watched route file changes.
+     */
+    async refreshRouterRoutes() {
+        if (!this.serverInstance || typeof this.serverInstance.reload !== 'function') {
+            appLogger.error('Server instance is not available for reloading');
+            return;
         }
-      });
-      const browserBuildPlugins = getAppBrowserBuildPlugins(this.appConfig);
-      this.hmrManager.setPlugins(browserBuildPlugins);
-      for (const integration of this.appConfig.integrations) {
-        integration.setHmrManager(this.hmrManager);
-      }
-    } catch (error) {
-      appLogger.error(`Failed to initialize plugins: ${error instanceof Error ? error.message : String(error)}`);
-      throw error;
+        await this.createSharedWatchRefreshCallback({
+            staticRoutes: this.staticRoutes,
+            hmrManager: this.hmrManager,
+            onRoutesReady: () => {
+                const options = this.getServerOptions({ enableHmr: true });
+                this.serverInstance.reload(options);
+                appLogger.debug('Server routes updated with dynamic routes');
+            },
+            onError: (error) => {
+                this.hmrManager.broadcast({ type: 'error', message: error.message });
+                appLogger.error('Failed to refresh router routes:', error);
+            },
+        })();
     }
-  }
-  /**
-   * Rebuilds the shared routing state and hot-reloads the live Bun server when a
-   * watched route file changes.
-   */
-  async refreshRouterRoutes() {
-    if (!this.serverInstance || typeof this.serverInstance.reload !== "function") {
-      appLogger.error("Server instance is not available for reloading");
-      return;
+    async watch() {
+        const watcher = new ProjectWatcher({
+            config: this.appConfig,
+            refreshRouterRoutesCallback: this.refreshRouterRoutes.bind(this),
+            hmrManager: this.hmrManager,
+            bridge: this.bridge,
+            hostOwnsDevClient: this.hostOwnsDevClient,
+        });
+        this.projectWatcher = watcher;
+        await watcher.createWatcherSubscription();
     }
-    await this.createSharedWatchRefreshCallback({
-      staticRoutes: this.staticRoutes,
-      hmrManager: this.hmrManager,
-      onRoutesReady: () => {
-        const options = this.getServerOptions({ enableHmr: true });
-        this.serverInstance.reload(options);
-        appLogger.debug("Server routes updated with dynamic routes");
-      },
-      onError: (error) => {
-        this.hmrManager.broadcast({ type: "error", message: error.message });
-        appLogger.error("Failed to refresh router routes:", error);
-      }
-    })();
-  }
-  async watch() {
-    const watcher = new ProjectWatcher({
-      config: this.appConfig,
-      refreshRouterRoutesCallback: this.refreshRouterRoutes.bind(this),
-      hmrManager: this.hmrManager,
-      bridge: this.bridge
-    });
-    this.projectWatcher = watcher;
-    await watcher.createWatcherSubscription();
-  }
-  /**
-   * Builds the `Bun.serve()` options for the current adapter state.
-   *
-   * @remarks
-   * 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();
-    if (enableHmr) {
-      const originalFetch = serverOptions.fetch;
-      const hmrHandler = this.hmrManager.getWebSocketHandler();
-      const hmrManager = this.hmrManager;
-      const matchRoute = (pathname) => findWebSocketRoute(this.websocketHandlers, pathname);
-      const userLifecycle = 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)
-      });
-      serverOptions.development = true;
-      serverOptions.websocket = {
-        open(ws) {
-          const kind = ws.data?.kind ?? "__hmr__";
-          if (kind === "__hmr__") {
-            hmrHandler.open?.(ws);
-            return;
-          }
-          userLifecycle.open(ws);
-        },
-        message(ws, msg) {
-          const kind = ws.data?.kind ?? "__hmr__";
-          if (kind === "__hmr__") {
-            hmrHandler.message?.(ws, msg);
-            return;
-          }
-          userLifecycle.message(ws, msg);
-        },
-        close(ws, code, reason) {
-          const kind = ws.data?.kind ?? "__hmr__";
-          if (kind === "__hmr__") {
-            hmrHandler.close?.(ws, code, reason);
-            return;
-          }
-          userLifecycle.close(ws, code, reason);
-        },
-        error(ws, error) {
-          const kind = ws.data?.kind ?? "__hmr__";
-          if (kind === "__hmr__") {
-            appLogger.error("[HMR] WebSocket error:", error);
-            return;
-          }
-          userLifecycle.error(ws, error);
+    /**
+     * Builds the `Bun.serve()` options for the current adapter state.
+     *
+     * @remarks
+     * 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;
         }
-      };
-      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: { kind: "__hmr__", params: {}, search: {} }
-          });
-          if (success) return;
-          return new Response("WebSocket upgrade failed", { status: 400 });
+        const userLifecycle = this.createBunUserLifecycle();
+        if (enableHmr) {
+            serverOptions.development = true;
+            serverOptions.websocket = this.createHmrAwareWebSocketHandler(userLifecycle);
         }
-        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" }
-          });
+        else {
+            serverOptions.websocket = userLifecycle;
         }
-        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
+        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),
+        });
+    }
+    /**
+     * @remarks
+     * HMR and user sockets share one Bun `websocket` handler. Upgrade tags HMR
+     * connections with `kind: '__hmr__'`; everything else routes to the user lifecycle.
+     */
+    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 ? undefined : new Response('WebSocket upgrade failed', { status: 400 });
+                }
             }
-          });
-          if (success) return;
-          return new Response("WebSocket upgrade failed", { status: 400 });
-        }
-        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;
-      };
-    } else if (this.websocketHandlers.size > 0) {
-      const matchRoute = (pathname) => findWebSocketRoute(this.websocketHandlers, pathname);
-      const userLifecycle = 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)
-      });
-      serverOptions.websocket = userLifecycle;
-      const originalFetch = serverOptions.fetch;
-      serverOptions.fetch = async function(request, _server) {
-        const url = new URL(request.url);
-        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
+            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 ? undefined : new Response('WebSocket upgrade failed', { status: 400 });
+            }
+            if (!originalFetch) {
+                return new Response('Not Found', { status: 404 });
             }
-          });
-          if (success) return;
-          return new Response("WebSocket upgrade failed", { status: 400 });
+            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.
+     *
+     * @remarks
+     * This method centralizes the Bun-specific error boundary. It preserves the
+     * shared route pipeline while still allowing adapter-level custom error-handler
+     * execution and `HttpError` passthrough.
+     */
+    buildServerSettings() {
+        const serverOptions = { ...this.serveOptions };
+        const handleNoMatch = this.handleNoMatch.bind(this);
+        const waitForInit = this.waitForInitialization.bind(this);
+        const handleReq = this.handleRequest.bind(this);
+        const errorHandler = this.errorHandler;
+        const getCacheService = () => this.getCacheService();
+        const getRenderContext = () => this.getRenderContext();
+        appLogger.debug(`[BunServerAdapter] Building server settings`);
+        const finalOptions = {
+            ...serverOptions,
+            async fetch(request, _server) {
+                try {
+                    await waitForInit();
+                    return await handleReq(request);
+                }
+                catch (error) {
+                    if (error instanceof Response)
+                        return error;
+                    if (errorHandler) {
+                        try {
+                            const locals = {};
+                            const context = {
+                                request,
+                                params: {},
+                                response: new ApiResponseBuilder(),
+                                server: _server,
+                                locals,
+                                require: createRequire(() => locals),
+                                services: {
+                                    cache: getCacheService(),
+                                },
+                                ...getRenderContext(),
+                            };
+                            return await errorHandler(error, context);
+                        }
+                        catch (handlerError) {
+                            appLogger.error(`[ecopages] Error in custom error handler: ${handlerError}`);
+                        }
+                    }
+                    if (error instanceof HttpError)
+                        return error.toResponse();
+                    appLogger.error(`[ecopages] Error handling request: ${error}`);
+                    return new Response('Internal Server Error', { status: 500 });
+                }
+            },
+            error(error) {
+                appLogger.error(`[ecopages] Error handling request: ${error}`);
+                return handleNoMatch(new Request('http://localhost'));
+            },
+        };
+        return finalOptions;
+    }
+    /**
+     * Generates a static build of the site for deployment.
+     * @param options.preview - If true, starts a preview server after build
+     */
+    async buildStatic(options) {
+        if (!this.fullyInitialized) {
+            await this.initializeSharedRouteHandling({
+                staticRoutes: this.staticRoutes,
+                hmrManager: this.hmrManager,
+            });
         }
-        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 });
+        const buildRuntimeOrigin = resolveServeRuntimeOrigin(this.serveOptions);
+        await this.staticBuilder.build({ baseUrl: buildRuntimeOrigin, force: options?.force }, {
+            router: this.router,
+            routeRendererFactory: this.routeRendererFactory,
+            staticRoutes: this.staticRoutes,
+        });
+        if (!options?.preview) {
+            return undefined;
         }
-        return response;
-      };
+        return this.startPreviewServer();
     }
-    return serverOptions;
-  }
-  /**
-   * 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.
-   */
-  async retrieveBodyFromRequest(request) {
-    const contentType = request.headers.get("Content-Type") || "";
-    if (contentType.includes("application/json")) {
-      return await request.json();
+    /**
+     * 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();
     }
-    if (contentType.includes("text/plain")) {
-      return await request.text();
+    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,
+            allowPortFallback: this.allowPortFallback,
+        });
+        if (!activePreviewPort) {
+            return undefined;
+        }
+        return `http://${previewHostname}:${activePreviewPort}`;
     }
-    return void 0;
-  }
-  /**
-   * Composes the base Bun server settings that all runtime modes build from.
-   *
-   * @remarks
-   * This method centralizes the Bun-specific error boundary. It preserves the
-   * shared route pipeline while still allowing adapter-level custom error-handler
-   * execution and `HttpError` passthrough.
-   */
-  buildServerSettings() {
-    const serverOptions = { ...this.serveOptions };
-    const handleNoMatch = this.handleNoMatch.bind(this);
-    const waitForInit = this.waitForInitialization.bind(this);
-    const handleReq = this.handleRequest.bind(this);
-    const errorHandler = this.errorHandler;
-    const getCacheService = () => this.getCacheService();
-    const getRenderContext = () => this.getRenderContext();
-    appLogger.debug(`[BunServerAdapter] Building server settings`);
-    const finalOptions = {
-      ...serverOptions,
-      async fetch(request, _server) {
-        try {
-          await waitForInit();
-          return await handleReq(request);
-        } catch (error) {
-          if (error instanceof Response) return error;
-          if (errorHandler) {
-            try {
-              const locals = {};
-              const context = {
-                request,
-                params: {},
-                response: new ApiResponseBuilder(),
-                server: _server,
-                locals,
-                require: createRequire(() => locals),
-                services: {
-                  cache: getCacheService()
-                },
-                ...getRenderContext()
-              };
-              return await errorHandler(error, context);
-            } catch (handlerError) {
-              appLogger.error(`[ecopages] Error in custom error handler: ${handlerError}`);
+    /**
+     * Initializes the server with dynamic routes after server creation.
+     * Must be called before handling any requests.
+     * @param server - The Bun server instance
+     */
+    async completeInitialization(server) {
+        if (this.fullyInitialized) {
+            if (server && !this.serverInstance) {
+                this.serverInstance = server;
             }
-          }
-          if (error instanceof HttpError) return error.toResponse();
-          appLogger.error(`[ecopages] Error handling request: ${error}`);
-          return new Response("Internal Server Error", { status: 500 });
+            return;
         }
-      },
-      error(error) {
-        appLogger.error(`[ecopages] Error handling request: ${error}`);
-        return handleNoMatch(new Request("http://localhost"));
-      }
-    };
-    return finalOptions;
-  }
-  /**
-   * Generates a static build of the site for deployment.
-   * @param options.preview - If true, starts a preview server after build
-   */
-  async buildStatic(options) {
-    if (!this.fullyInitialized) {
-      await this.initializeSharedRouteHandling({
-        staticRoutes: this.staticRoutes,
-        hmrManager: this.hmrManager
-      });
-    }
-    const buildRuntimeOrigin = resolveServeRuntimeOrigin(this.serveOptions);
-    await this.staticBuilder.build(
-      { ...options, preview: false, baseUrl: buildRuntimeOrigin },
-      {
-        router: this.router,
-        routeRendererFactory: this.routeRendererFactory,
-        staticRoutes: this.staticRoutes
-      }
-    );
-    if (!options?.preview) {
-      return;
-    }
-    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
-    });
-    if (activePreviewPort) {
-      appLogger.info(`Preview running at http://${previewHostname}:${activePreviewPort}`);
-      return;
+        if (!this.initializationPromise) {
+            this.initializationPromise = this._performInitialization(server ?? null);
+        }
+        return this.initializationPromise;
     }
-  }
-  /**
-   * Initializes the server with dynamic routes after server creation.
-   * Must be called before handling any requests.
-   * @param server - The Bun server instance
-   */
-  async completeInitialization(server) {
-    if (this.fullyInitialized) {
-      if (server && !this.serverInstance) {
+    /**
+     * Performs the one-time post-bind initialization path for Bun servers.
+     *
+     * @remarks
+     * This is intentionally split from `initialize()` because shared route handling
+     * and file watching need the live server instance to exist before Bun can
+     * reload updated route handlers in place.
+     */
+    async _performInitialization(server) {
         this.serverInstance = server;
-      }
-      return;
+        appLogger.debug('Completing server initialization with dynamic routes');
+        await this.initializeSharedRouteHandling({
+            staticRoutes: this.staticRoutes,
+            hmrManager: this.hmrManager,
+        });
+        if (this.options?.watch) {
+            await this.hmrManager.ensureRuntimeReady();
+            startDevWarmup({
+                appConfig: this.appConfig,
+                runtimeOrigin: this.runtimeOrigin,
+            });
+            await this.startDevStaticRoutePrewarmWhenReady();
+        }
+        this.fullyInitialized = true;
+        if (this.options?.watch)
+            await this.watch();
+        if (server && typeof server.reload === 'function') {
+            const updatedOptions = this.getServerOptions(this.options?.watch ? { enableHmr: true } : undefined);
+            server.reload(updatedOptions);
+            appLogger.debug('Server routes updated with dynamic routes');
+        }
     }
-    if (!this.initializationPromise) {
-      this.initializationPromise = this._performInitialization(server ?? null);
+    /**
+     * Creates and initializes the Bun server adapter.
+     * @returns Configured adapter with server methods
+     */
+    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),
+        };
     }
-    return this.initializationPromise;
-  }
-  /**
-   * Performs the one-time post-bind initialization path for Bun servers.
-   *
-   * @remarks
-   * This is intentionally split from `initialize()` because shared route handling
-   * and file watching need the live server instance to exist before Bun can
-   * reload updated route handlers in place.
-   */
-  async _performInitialization(server) {
-    this.serverInstance = server;
-    appLogger.debug("Completing server initialization with dynamic routes");
-    await this.initializeSharedRouteHandling({
-      staticRoutes: this.staticRoutes,
-      hmrManager: this.hmrManager
-    });
-    this.fullyInitialized = true;
-    if (this.options?.watch) await this.watch();
-    if (server && typeof server.reload === "function") {
-      const updatedOptions = this.getServerOptions(this.options?.watch ? { enableHmr: true } : void 0);
-      server.reload(updatedOptions);
-      appLogger.debug("Server routes updated with dynamic routes");
+    /**
+     * 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
+     * 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, {
+            apiHandlers: this.apiHandlers,
+            errorHandler: this.errorHandler,
+            serverInstance: this.serverInstance,
+            hmrManager: this.hmrManager,
+        });
+        return response;
     }
-  }
-  /**
-   * Creates and initializes the Bun server adapter.
-   * @returns Configured adapter with server methods
-   */
-  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),
-      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 Bun server — callers
-   * should shut down transport through the runtime host before disposing.
-   */
-  async dispose() {
-    if (this.adapterDisposed) {
-      return;
+    /**
+     * Ensures server initialization completes before request handling.
+     * Prevents race conditions during startup.
+     */
+    async waitForInitialization() {
+        if (this.fullyInitialized) {
+            return;
+        }
+        if (this.initializationPromise) {
+            return this.initializationPromise;
+        }
+        throw new Error('Server not initialized. Call completeInitialization() first.');
     }
-    this.adapterDisposed = true;
-    await this.projectWatcher?.close();
-    this.projectWatcher = null;
-    this.hmrManager?.stop();
-    this.bridge?.destroy();
-    await this.previewHost.stop();
-  }
-  /**
-   * 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.
-   */
-  async handleRequest(request) {
-    const response = await this.handleSharedRequest(request, {
-      apiHandlers: this.apiHandlers,
-      errorHandler: this.errorHandler,
-      serverInstance: this.serverInstance,
-      hmrManager: this.hmrManager
-    });
-    return await this.maybeInjectHmrScript(response);
-  }
-  /**
-   * Ensures server initialization completes before request handling.
-   * Prevents race conditions during startup.
-   */
-  async waitForInitialization() {
-    if (this.fullyInitialized) {
-      return;
+    /**
+     * Handles HTTP requests from the router adapter.
+     */
+    async handleResponse(request) {
+        await this.waitForInitialization();
+        return this.routeHandler.handleResponse(request);
     }
-    if (this.initializationPromise) {
-      return this.initializationPromise;
+    /**
+     * Handles requests that do not match any routes.
+     */
+    async handleNoMatch(request) {
+        await this.waitForInitialization();
+        return this.routeHandler.handleNoMatch(request);
     }
-    throw new Error("Server not initialized. Call completeInitialization() first.");
-  }
-  /**
-   * Handles HTTP requests from the router adapter.
-   */
-  async handleResponse(request) {
-    await this.waitForInitialization();
-    return this.routeHandler.handleResponse(request);
-  }
-  /**
-   * Handles requests that do not match any routes.
-   */
-  async handleNoMatch(request) {
-    await this.waitForInitialization();
-    return this.routeHandler.handleNoMatch(request);
-  }
 }
-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 });
-  const previewHost = params.previewHost ?? new BunStaticPreviewHost();
-  const adapter = new BunServerAdapter({
-    ...params,
-    runtimeOrigin,
-    bridge,
-    hmrManager,
-    previewHost
-  });
-  return adapter.createAdapter();
+/**
+ * Creates the Bun server adapter and fills in the runtime-specific collaborators
+ * that Bun callers usually leave implicit.
+ *
+ * @remarks
+ * This is the canonical entry point for Bun server-adapter construction. It
+ * guarantees that the concrete adapter receives a Bun websocket bridge, HMR
+ * manager, and preview host even though those dependencies are optional on the
+ * public params type.
+ */
+export 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,
+        runtimeOrigin,
+        bridge,
+        hmrManager,
+        previewHost,
+    });
+    return adapter.createAdapter();
 }
-export {
-  BunServerAdapter,
-  createBunServerAdapter
-};