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

package/src/adapters/bun/bun-user-websocket-lifecycle.js

@@ -0,0 +1,96 @@
+import { appLogger } from "../../global/app-logger.js";
+import { invokeWebSocketHandlerHook, toWebSocketCloseInfo } from "../shared/ws/websocket-lifecycle.js";
+function toUpgradeRequest(ws, runtimeOrigin) {
+  const upgradeUrl = ws.data?.upgradeUrl;
+  if (upgradeUrl) {
+    return new Request(upgradeUrl);
+  }
+  return new Request(runtimeOrigin);
+}
+async function runUserWebSocketOpen(ws, kind, deps) {
+  const handler = deps.userHandlers.get(kind);
+  if (!handler) {
+    return;
+  }
+  const params = ws.data?.params ?? {};
+  const search = ws.data?.search ?? {};
+  const request = toUpgradeRequest(ws, deps.runtimeOrigin);
+  let context;
+  try {
+    context = await deps.resolveContext(request, handler, kind, params, search);
+  } catch {
+    ws.close(1011, "context initialization failed");
+    return;
+  }
+  ws.data.context = context;
+  const socket = deps.adaptSocket(ws, kind, params, search, context);
+  try {
+    await handler.onConnect?.(socket);
+  } catch (error) {
+    appLogger.error(`[WS:${kind}] onConnect failed:`, error);
+    ws.close(1011, "onConnect failed");
+  }
+}
+function createBunUserWebSocketLifecycle(deps) {
+  const resolveSocketForEvent = (ws) => {
+    const kind = ws.data?.kind;
+    if (!kind) {
+      return void 0;
+    }
+    const handler = deps.userHandlers.get(kind);
+    if (!handler) {
+      return void 0;
+    }
+    const params = ws.data?.params ?? {};
+    const search = ws.data?.search ?? {};
+    const socket = deps.adaptSocket(ws, kind, params, search, ws.data?.context);
+    return { kind, handler, socket };
+  };
+  return {
+    open(ws) {
+      const kind = ws.data?.kind;
+      if (!kind) {
+        return;
+      }
+      void runUserWebSocketOpen(ws, kind, deps).catch((error) => {
+        appLogger.error(`[WS:${kind}] open failed:`, error);
+        ws.close(1011, "internal error");
+      });
+    },
+    message(ws, msg) {
+      const resolved = resolveSocketForEvent(ws);
+      if (!resolved) {
+        return;
+      }
+      if (ws.data?.context === void 0 && resolved.handler.context) {
+        appLogger.warn(`[WS:${resolved.kind}] message received before context resolved; dropping.`);
+        return;
+      }
+      const message = typeof msg === "string" ? { kind: "text", text: msg } : { kind: "binary", data: new Uint8Array(msg.buffer, msg.byteOffset, msg.byteLength) };
+      invokeWebSocketHandlerHook(
+        resolved.kind,
+        "onMessage",
+        resolved.handler.onMessage?.(resolved.socket, message)
+      );
+    },
+    close(ws, code, reason) {
+      const resolved = resolveSocketForEvent(ws);
+      if (!resolved) {
+        return;
+      }
+      const event = toWebSocketCloseInfo(code, reason);
+      invokeWebSocketHandlerHook(resolved.kind, "onClose", resolved.handler.onClose?.(resolved.socket, event));
+    },
+    error(ws, error) {
+      const resolved = resolveSocketForEvent(ws);
+      if (!resolved) {
+        return;
+      }
+      appLogger.error(`[WS:${resolved.kind}] error:`, error);
+      invokeWebSocketHandlerHook(resolved.kind, "onError", resolved.handler.onError?.(resolved.socket, error));
+    }
+  };
+}
+export {
+  createBunUserWebSocketLifecycle
+};

package/src/adapters/bun/client-bridge.d.ts

@@ -30,5 +30,6 @@ export declare class ClientBridge implements IClientBridge {
      */
     error(message: string): void;
     get subscriberCount(): number;
+    destroy(): void;
 }
 export {};

package/src/adapters/bun/client-bridge.js

@@ -42,6 +42,9 @@ class ClientBridge {
   get subscriberCount() {
     return this.subscribers.size;
   }
+  destroy() {
+    this.subscribers.clear();
+  }
 }
 export {
   ClientBridge

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

@@ -9,9 +9,8 @@
  */
 import type { Server } from 'bun';
 import type { ApiHandlerContext, RouteGroupBuilder } from '../../types/public-types.js';
-import { SharedApplicationAdapter } from '../shared/application-adapter.js';
-import type { RuntimeHost } from '../shared/runtime-host.js';
-import type { StaticPreviewHost } from '../shared/static-preview-host.js';
+import { SharedApplicationAdapter } from '../shared/runtime/application-adapter.js';
+import type { RuntimeHost } from '../shared/runtime/runtime-host.js';
 import type { EcopagesAppOptions } from '../create-app.js';
 import { type BunServerAdapterResult } from './server-adapter.js';
 /**
@@ -31,13 +30,15 @@ export type BunRouteGroupBuilder<WebSocketData = undefined, TContext extends Api
 export declare class BunEcopagesApp<WebSocketData = undefined> extends SharedApplicationAdapter<EcopagesAppOptions, Server<WebSocketData>, Request> {
     serverAdapter: BunServerAdapterResult | undefined;
     private server;
+    private stopped;
     private readonly runtimeHost;
-    private readonly previewHost;
     constructor(options: EcopagesAppOptions, dependencies: {
         runtimeHost: RuntimeHost<Server<WebSocketData>, Bun.Serve.Options<WebSocketData>>;
-        previewHost: StaticPreviewHost;
     });
     fetch(request: Request): Promise<Response>;
+    attachWebSocketUpgrades(httpServer: import('node:http').Server, options?: {
+        passthroughUnmatched?: boolean;
+    }): Promise<void>;
     /**
      * Complete the initialization of the server adapter by processing dynamic routes
      * @param server The Bun server instance
@@ -52,7 +53,9 @@ export declare class BunEcopagesApp<WebSocketData = undefined> extends SharedApp
      * @param options Optional settings
      * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
      */
-    start(): Promise<Server<WebSocketData> | void>;
+    protected bootServer(): Promise<Server<WebSocketData> | void>;
+    stop(force?: boolean): Promise<void>;
+    protected resolveAppRoutes(): Promise<import("../../index.browser.js").EcopagesRouteInfo[]>;
 }
 /**
  * Factory function to create a Bun application

package/src/adapters/bun/create-app.js

@@ -1,19 +1,19 @@
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
 import { appLogger } from "../../global/app-logger.js";
-import { SharedApplicationAdapter } from "../shared/application-adapter.js";
-import { resolveRuntimeBinding, resolveStaticRuntimeMode } from "../shared/runtime-app-bootstrap.js";
+import { SharedApplicationAdapter } from "../shared/runtime/application-adapter.js";
+import { resolveRuntimeBinding, resolveStaticRuntimeMode } from "../shared/runtime/runtime-app-bootstrap.js";
+import { startupTrace } from "../../diagnostics/startup-trace.js";
 import { createBunServerAdapter } from "./server-adapter.js";
-import { BunStaticPreviewHost } from "./static-preview-host.js";
 import { BunRuntimeHost } from "./runtime-host.js";
+import { hostOwnsDevClient } from "../../dev/dev-client-ownership.js";
+import { resolveAppStartRoutes } from "../../utils/ecopages-route-info.js";
 class BunEcopagesApp extends SharedApplicationAdapter {
   serverAdapter;
   server = null;
+  stopped = false;
   runtimeHost;
-  previewHost;
   constructor(options, dependencies) {
-    super(options);
+    super(options, "Bun");
     this.runtimeHost = dependencies.runtimeHost;
-    this.previewHost = dependencies.previewHost;
   }
   async fetch(request) {
     if (!this.serverAdapter) {
@@ -22,6 +22,12 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     await this.serverAdapter.completeInitialization(this.server);
     return this.serverAdapter.handleRequest(request);
   }
+  async attachWebSocketUpgrades(httpServer, options) {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    this.serverAdapter.attachUserWebSocketUpgrades(httpServer, options);
+  }
   /**
    * Complete the initialization of the server adapter by processing dynamic routes
    * @param server The Bun server instance
@@ -40,24 +46,21 @@ class BunEcopagesApp extends SharedApplicationAdapter {
       cliArgs: this.cliArgs,
       serverOptions: this.serverOptions
     });
-    appLogger.debug("initializeServerAdapter", {
-      dev: this.cliArgs.dev,
-      cliPort: this.cliArgs.port,
-      cliHostname: this.cliArgs.hostname,
-      envPort: process.env.ECOPAGES_PORT,
-      envHostname: process.env.ECOPAGES_HOSTNAME,
-      preferredPort: binding.preferredPort,
-      preferredHostname: binding.preferredHostname,
-      composedUrl: binding.runtimeOrigin
-    });
-    return await createBunServerAdapter({
+    return createBunServerAdapter({
       runtimeOrigin: binding.runtimeOrigin,
       appConfig: this.appConfig,
       apiHandlers: this.apiHandlers,
       staticRoutes: this.staticRoutes,
       errorHandler: this.errorHandler,
+      websocketHandlers: this.websocketHandlers.size > 0 ? this.websocketHandlers : void 0,
       options: { watch: binding.watch },
-      serveOptions: binding.serveOptions
+      serveOptions: binding.serveOptions,
+      hostOwnsDevClient: hostOwnsDevClient(this.runtimeOptions),
+      deferRuntimeAssetSetup: resolveStaticRuntimeMode({
+        appConfig: this.appConfig,
+        cliArgs: this.cliArgs
+      }).canBuildWithoutRuntimeServer,
+      allowPortFallback: binding.allowPortFallback
     });
   }
   /**
@@ -65,19 +68,33 @@ class BunEcopagesApp extends SharedApplicationAdapter {
    * @param options Optional settings
    * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
    */
-  async start() {
+  async bootServer() {
+    if (this.stopped) {
+      this.serverAdapter = void 0;
+      this.stopped = false;
+    }
     if (!this.serverAdapter) {
       this.serverAdapter = await this.initializeServerAdapter();
     }
-    const { dev, preview, build } = this.cliArgs;
+    const { dev, preview, build, force, serveOnly } = this.cliArgs;
     const staticRuntimeMode = resolveStaticRuntimeMode({
       appConfig: this.appConfig,
       cliArgs: this.cliArgs
     });
+    if (preview && serveOnly) {
+      const previewOrigin2 = await this.serverAdapter.servePreviewOnly();
+      if (previewOrigin2) {
+        await this.notifyListening(previewOrigin2);
+      }
+      return;
+    }
     if (staticRuntimeMode.canBuildWithoutRuntimeServer) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview });
+      const previewOrigin2 = await this.serverAdapter.buildStatic({ preview, force });
       appLogger.debugTimeEnd("Building static pages");
+      if (preview && previewOrigin2) {
+        await this.notifyListening(previewOrigin2);
+      }
       if (build) {
         process.exit(0);
       }
@@ -85,12 +102,8 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     }
     const enableHmr = dev || !preview && !build;
     const serverOptions = this.serverAdapter.getServerOptions({ enableHmr });
-    const configuredHostname = String(serverOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME);
-    const configuredPort = Number(serverOptions.port ?? DEFAULT_ECOPAGES_PORT);
-    const runtimeServerOptions = (preview || build) && staticRuntimeMode.requiresFetchRuntime ? {
-      ...serverOptions,
-      port: 0
-    } : serverOptions;
+    const runtimeServerOptions = serverOptions;
+    startupTrace.beginServerListen();
     this.server = await this.runtimeHost.start({
       serveOptions: runtimeServerOptions,
       handleRequest: async () => new Response(null, { status: 500 }),
@@ -103,35 +116,53 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     if (!this.server) {
       throw new Error("Server failed to start");
     }
-    appLogger.info(
-      `Server running at ${this.runtimeHost.getOrigin(this.server, runtimeServerOptions)}`
+    const runtimeOrigin = this.runtimeHost.getOrigin(
+      this.server,
+      runtimeServerOptions
     );
+    let previewOrigin;
     if (build || preview) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview: false });
-      await this.runtimeHost.stop(this.server, { force: true });
-      if (preview) {
-        const previewPort = await this.previewHost.start({
-          appConfig: this.appConfig,
-          hostname: configuredHostname,
-          port: configuredPort
-        });
-        if (previewPort) {
-          appLogger.info(`Preview running at http://${configuredHostname}:${previewPort}`);
-        }
-      }
+      previewOrigin = await this.serverAdapter.buildStatic({ preview, force });
+      const buildRuntimeServer = this.server;
+      this.server = null;
+      await this.runtimeHost.stop(buildRuntimeServer, { force: true });
       appLogger.debugTimeEnd("Building static pages");
       if (build) {
         process.exit(0);
       }
+    } else {
+      await this.notifyListening(runtimeOrigin);
+    }
+    if (preview && previewOrigin) {
+      await this.notifyListening(previewOrigin);
+    }
+    return this.server ?? void 0;
+  }
+  async stop(force = true) {
+    if (this.stopped) {
+      return;
     }
-    return this.server;
+    if (this.server) {
+      const activeServer = this.server;
+      this.server = null;
+      await this.runtimeHost.stop(activeServer, { force });
+    }
+    if (this.serverAdapter) {
+      await this.serverAdapter.dispose();
+    }
+    this.stopped = true;
+  }
+  async resolveAppRoutes() {
+    return resolveAppStartRoutes({
+      listStaticGenerationRoutes: this.serverAdapter?.listStaticGenerationRoutes,
+      runtimeOrigin: this.appConfig.baseUrl
+    });
   }
 }
 async function createApp(options) {
   return new BunEcopagesApp(options, {
-    runtimeHost: new BunRuntimeHost(),
-    previewHost: new BunStaticPreviewHost()
+    runtimeHost: new BunRuntimeHost()
   });
 }
 export {

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

@@ -2,7 +2,7 @@ import type { WebSocketHandler } from 'bun';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { ClientBridge } from './client-bridge.js';
 import { InMemoryEntrypointDependencyGraph, type EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
-import { SharedHmrManager } from '../shared/shared-hmr-manager.js';
+import { SharedHmrManager } from '../shared/hmr/shared-hmr-manager.js';
 type BunSocketHandler = WebSocketHandler<unknown>;
 export interface HmrManagerParams {
     appConfig: EcoPagesAppConfig;

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

@@ -2,7 +2,7 @@ import { appLogger } from "../../global/app-logger.js";
 import {
   InMemoryEntrypointDependencyGraph
 } from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
-import { SharedHmrManager } from "../shared/shared-hmr-manager.js";
+import { SharedHmrManager } from "../shared/hmr/shared-hmr-manager.js";
 class HmrManager extends SharedHmrManager {
   wsHandler;
   /**

package/src/adapters/bun/index.d.ts

@@ -1,2 +1,2 @@
 export { BunEcopagesApp, createApp } from './create-app.js';
-export { defineApiHandler, defineGroupHandler, type GroupHandler } from '../shared/define-api-handler.js';
+export { defineApiHandler, defineGroupHandler, defineGet, definePost, definePut, defineDelete, definePatch, defineOptions, defineHead, json, html, redirect, type GroupHandler, } from '../shared/http/define-api-handler.js';

package/src/adapters/bun/index.js

@@ -1,8 +1,31 @@
 import { BunEcopagesApp, createApp } from "./create-app.js";
-import { defineApiHandler, defineGroupHandler } from "../shared/define-api-handler.js";
+import {
+  defineApiHandler,
+  defineGroupHandler,
+  defineGet,
+  definePost,
+  definePut,
+  defineDelete,
+  definePatch,
+  defineOptions,
+  defineHead,
+  json,
+  html,
+  redirect
+} from "../shared/http/define-api-handler.js";
 export {
   BunEcopagesApp,
   createApp,
   defineApiHandler,
-  defineGroupHandler
+  defineDelete,
+  defineGet,
+  defineGroupHandler,
+  defineHead,
+  defineOptions,
+  definePatch,
+  definePost,
+  definePut,
+  html,
+  json,
+  redirect
 };

package/src/adapters/bun/runtime-host.d.ts

@@ -1,5 +1,5 @@
 import type { Server } from 'bun';
-import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime-host.js';
+import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime/runtime-host.js';
 type BunRuntimeProvider = {
     serve(options: Bun.Serve.Options<unknown>): Server<unknown>;
 };

package/src/adapters/bun/runtime-host.js

@@ -1,5 +1,5 @@
 import { getBunRuntime } from "../../utils/runtime.js";
-import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
+import { resolveServeRuntimeOrigin } from "../shared/runtime/runtime-app-bootstrap.js";
 class BunRuntimeHost {
   /**
    * Creates a Bun runtime host with an injectable runtime lookup.

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

@@ -1,9 +1,10 @@
+import type { Server as NodeHttpServer } from 'node:http';
 import type { Server, WebSocketHandler } from 'bun';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ApiHandler, ErrorHandler, StaticRoute } from '../../types/public-types.js';
-import { SharedServerAdapter } from '../shared/server-adapter.js';
+import type { ApiHandler, ErrorHandler, StaticRoute, EcopagesWebSocketHandler } from '../../types/public-types.js';
+import { SharedServerAdapter } from '../shared/runtime/server-adapter.js';
 import type { ServerAdapterResult } from '../abstract/server-adapter.js';
-import type { StaticPreviewHost } from '../shared/static-preview-host.js';
+import type { StaticPreviewHost } from '../shared/runtime/static-preview-host.js';
 import { ClientBridge } from './client-bridge.js';
 import { HmrManager } from './hmr-manager.js';
 type BunServerInstance = Server<unknown>;
@@ -32,9 +33,14 @@ export interface BunServerAdapterParams {
     apiHandlers?: ApiHandler<string, Request, BunServerInstance>[];
     staticRoutes?: StaticRoute[];
     errorHandler?: ErrorHandler;
+    websocketHandlers?: Map<string, EcopagesWebSocketHandler<any, any>>;
     options?: {
         watch?: boolean;
     };
+    delegateBrowserReloadToHost?: boolean;
+    hostOwnsDevClient?: boolean;
+    deferRuntimeAssetSetup?: boolean;
+    allowPortFallback?: boolean;
     hmrManager?: HmrManager;
     bridge?: ClientBridge;
     previewHost?: StaticPreviewHost;
@@ -45,9 +51,15 @@ export interface BunServerAdapterResult extends ServerAdapterResult {
     }) => BunServeOptions;
     buildStatic: (options?: {
         preview?: boolean;
-    }) => Promise<void>;
+        force?: boolean;
+    }) => Promise<string | undefined>;
+    servePreviewOnly: () => Promise<string | undefined>;
     completeInitialization: (server?: BunServerInstance | null) => Promise<void>;
     handleRequest: (request: Request) => Promise<Response>;
+    attachUserWebSocketUpgrades: (server: NodeHttpServer, options?: {
+        passthroughUnmatched?: boolean;
+    }) => void;
+    dispose: () => Promise<void>;
 }
 /**
  * Bun transport adapter that wires shared Ecopages request handling onto a live
@@ -71,7 +83,39 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
     private initializationPromise;
     private fullyInitialized;
     serverInstance: BunServerInstance | null;
+    private projectWatcher;
+    private adapterDisposed;
+    private readonly deferRuntimeAssetSetup;
+    private readonly allowPortFallback;
     private readonly 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.
+     */
+    protected websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    private registerBunRuntimePlugin;
+    private adaptBunWebSocket;
+    /**
+     * 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
+     */
+    private resolveBunContext;
     /**
      * Creates a Bun server adapter with already-resolved runtime collaborators.
      *
@@ -81,39 +125,21 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      * 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, options, hmrManager, bridge, previewHost, }: BunServerAdapterParams & {
+    constructor({ appConfig, runtimeOrigin, serveOptions, apiHandlers, staticRoutes, errorHandler, websocketHandlers, options, hostOwnsDevClient, deferRuntimeAssetSetup, allowPortFallback, hmrManager, bridge, previewHost, }: BunServerAdapterParams & {
         hmrManager: HmrManager;
         bridge: ClientBridge;
         previewHost: StaticPreviewHost;
     });
     /**
-     * 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.
-     */
-    private shouldInjectHmrScript;
-    /**
-     * Delegates the HTML-response test to the shared response helper used by both
-     * adapters.
-     */
-    private isHtmlResponse;
-    /**
-     * 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.
      */
-    private maybeInjectHmrScript;
+    attachUserWebSocketUpgrades(server: NodeHttpServer, options?: {
+        passthroughUnmatched?: boolean;
+    }): void;
     /**
      * Initializes the server adapter's core runtime components.
      */
     initialize(): Promise<void>;
-    /**
-     * Copies the source `public` directory into the runtime output and ensures the
-     * HMR assets directory exists before any runtime bundles are emitted.
-     */
-    private prepareRuntimePublicDir;
     /**
      * Registers runtime plugins and propagates the final HMR manager into each
      * integration.
@@ -134,20 +160,32 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      * 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 }?: {
         enableHmr?: boolean | undefined;
     }): BunServeOptions;
+    private createBunUserLifecycle;
+    /**
+     * @remarks
+     * HMR and user sockets share one Bun `websocket` handler. Upgrade tags HMR
+     * connections with `kind: '__hmr__'`; everything else routes to the user lifecycle.
+     */
+    private createHmrAwareWebSocketHandler;
     /**
-     * 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
+     * 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.
      */
-    private retrieveBodyFromRequest;
+    private wrapFetchWithWebSocketUpgrades;
     /**
      * Composes the base Bun server settings that all runtime modes build from.
      *
@@ -163,7 +201,14 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      */
     buildStatic(options?: {
         preview?: boolean;
-    }): Promise<void>;
+        force?: boolean;
+    }): Promise<string | undefined>;
+    /**
+     * Serves an existing static export without running SSG. Used by e2e preview
+     * launchers after a shared prewarm build.
+     */
+    servePreviewOnly(): Promise<string | undefined>;
+    private startPreviewServer;
     /**
      * Initializes the server with dynamic routes after server creation.
      * Must be called before handling any requests.
@@ -184,15 +229,21 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      * @returns Configured adapter with server methods
      */
     createAdapter(): Promise<BunServerAdapterResult>;
+    /**
+     * 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.
+     */
+    dispose(): Promise<void>;
     /**
      * 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.
      */
     handleRequest(request: Request): Promise<Response>;
     /**