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

package/src/adapters/abstract/application-adapter.d.ts

@@ -8,7 +8,9 @@
  */
 import type { SourceModuleLoader } from '../../services/module-loading/module-loading-types.js';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader } from '../../types/public-types.js';
+import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader, EcopagesRouteInfo } from '../../types/public-types.js';
+import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
+import { type EcopagesRuntimeLabel } from '../../dev/runtime-server-started-message.js';
 import { type ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
 /**
  * Runtime bootstrap options layered on top of the app config.
@@ -25,6 +27,21 @@ export interface ApplicationRuntimeOptions {
      * adapter auto-detects a host module loader from the global scope.
      */
     embedded?: boolean;
+    /**
+     * When true, full-page reload signaling is owned by the host dev server
+     * (for example Vite's `full-reload` websocket event) instead of the Ecopages
+     * client bridge.
+     *
+     * @deprecated Prefer `devClientOwner: 'host'`.
+     */
+    delegateBrowserReloadToHost?: boolean;
+    /**
+     * Selects which layer injects browser dev-client bootstrap (HMR runtime, reload).
+     *
+     * `host` disables core injection and reload signaling so embedded hosts like
+     * Vite own the full dev-client surface.
+     */
+    devClientOwner?: 'core' | 'host';
     /**
      * Explicit source module loader for request-time imports.
      *
@@ -33,6 +50,27 @@ export interface ApplicationRuntimeOptions {
      */
     hostModuleLoader?: SourceModuleLoader;
 }
+export interface AppStartInfo {
+    origin: string;
+    /**
+     * Static-generation routes available when the runtime becomes ready.
+     *
+     * @remarks
+     * Empty when the server adapter has no route registry yet, or when route
+     * resolution fails (failures never block startup). Route resolution completes
+     * before the `onAppStart` callback runs.
+     */
+    routes: EcopagesRouteInfo[];
+}
+export type OnAppStartCallback = (info: AppStartInfo) => void;
+/** @deprecated Use {@link AppStartInfo}. */
+export type ApplicationListeningInfo = AppStartInfo;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type StartCallback = OnAppStartCallback;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type ListenCallback = OnAppStartCallback;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type ApplicationListeningCallback = OnAppStartCallback;
 /**
  * Configuration options for application adapters
  */
@@ -49,8 +87,12 @@ export interface ApplicationAdapterOptions {
 /**
  * Common interface for application adapters
  */
-export interface ApplicationAdapter<T = any> {
-    start(): Promise<T | void>;
+export interface ApplicationAdapter<T = any> extends AsyncDisposable {
+    /** Boot the server. Pass a callback to run when the runtime is ready (optional). */
+    start(onAppStart?: OnAppStartCallback): Promise<T | void>;
+    /** Invoked by embedded hosts once the app can take traffic. */
+    handleListening(origin: string): void | Promise<void>;
+    stop(force?: boolean): Promise<void>;
 }
 /**
  * Handler function type for route handlers
@@ -72,7 +114,14 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
     protected apiHandlers: ApiHandler[];
     protected staticRoutes: StaticRoute[];
     protected errorHandler?: ErrorHandler;
-    constructor(options: TOptions);
+    /**
+     * App-level WebSocket handlers keyed by URL path pattern (e.g. '/ws/chat/:id').
+     * Both Bun and Node adapters read this map to register upgrade routes.
+     */
+    protected websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    private onAppStartCallback?;
+    protected readonly runtimeLabel: EcopagesRuntimeLabel;
+    constructor(options: TOptions, runtimeLabel: EcopagesRuntimeLabel);
     private clearDistFolder;
     /**
      * Register a GET route handler.
@@ -160,6 +209,46 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
      * Get all registered static routes
      */
     getStaticRoutes(): StaticRoute[];
+    /**
+     * Register a WebSocket handler for the given path pattern.
+     *
+     * The runtime adapter handles the HTTP→WebSocket upgrade for this path
+     * and routes lifecycle events to `handler`.
+     *
+     * Supports dynamic segments via `:param` syntax. The handler receives
+     * typed `params` and `search` fields, and a typed `context` produced by
+     * the optional `context()` factory.
+     *
+     * One pattern registration matches infinite path variations. For example,
+     * `app.websocket('/ws/chat/:roomId', handler)` matches `/ws/chat/abc`,
+     * `/ws/chat/xyz`, etc. Each connection receives its own `params.roomId`.
+     *
+     * Works across both Bun and Node runtimes — no runtime-specific imports needed.
+     *
+     * @example
+     * ```typescript
+     * app.websocket<ChatContext, { roomId: string }>('/ws/chat/:roomId', {
+     *   async context({ params, search }) {
+     *     return { username: search.username ?? 'anonymous', roomId: params.roomId };
+     *   },
+     *   onConnect(socket) {
+     *     socket.send(`Welcome to room ${socket.context.roomId}`);
+     *   },
+     *   onMessage(socket, message) {
+     *     if (message.kind === 'text') {
+     *       socket.send(message.text);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    websocket<TContext = unknown, TParams extends Record<string, string> = Record<string, string>>(path: string, handler: EcopagesWebSocketHandler<TContext, TParams>): this;
+    /**
+     * Get the registered WebSocket handlers map.
+     *
+     * @returns The map of WebSocket route patterns to handlers
+     */
+    getWebsocketHandlers(): Map<string, EcopagesWebSocketHandler<any, any>>;
     /**
      * Register a global error handler for all routes.
      * Useful for logging, monitoring integration, and custom error formatting.
@@ -182,9 +271,37 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
      */
     protected abstract initializeServerAdapter(): Promise<any>;
     /**
-     * Start the application server
+     * Boot the server. When `onAppStart` is passed, it runs once the runtime can take traffic.
+     * Embedded apps only register the callback — the host (for example Vite) boots the port.
+     */
+    start(onAppStart?: OnAppStartCallback): Promise<TServer | void>;
+    /** Runtime-specific server boot (dev, preview, build). */
+    protected abstract bootServer(): Promise<TServer | void>;
+    protected logServerStarted(origin: string): void;
+    /**
+     * Invoked by embedded hosts (for example Vite) once the app can take traffic.
+     */
+    handleListening(origin: string): Promise<void>;
+    protected notifyListening(origin: string): Promise<void>;
+    /**
+     * Resolves routes exposed on {@link AppStartInfo}.
+     *
+     * @remarks
+     * Default is empty. Runtime adapters override this to read from the
+     * initialized server route registry.
+     */
+    protected resolveAppRoutes(): Promise<EcopagesRouteInfo[]>;
+    private invokeAppStartCallback;
+    /**
+     * Stops the application server and releases runtime resources.
+     *
+     * @remarks
+     * Subclasses override this to shut down bound servers, watchers, and other
+     * dev-time resources. The default implementation is a no-op so embedded
+     * adapters that never call `start()` can still be used with `await using`.
      */
-    abstract start(): Promise<TServer | void>;
+    stop(_force?: boolean): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Handles a standard Web request without requiring a bound network server.
      * This is the primary interoperability surface for embedding Ecopages inside

package/src/adapters/abstract/application-adapter.js

@@ -6,7 +6,11 @@ import {
 import { getHostModuleLoader } from "../../services/module-loading/host-module-loader-registry.js";
 import { invariant } from "../../utils/invariant.js";
 import { fileSystem } from "@ecopages/file-system";
+import {
+  formatRuntimeServerStartedMessage
+} from "../../dev/runtime-server-started-message.js";
 import { parseCliArgs } from "../../utils/parse-cli-args.js";
+import { startupTrace } from "../../diagnostics/startup-trace.js";
 class AbstractApplicationAdapter {
   appConfig;
   serverOptions;
@@ -15,16 +19,31 @@ class AbstractApplicationAdapter {
   apiHandlers = [];
   staticRoutes = [];
   errorHandler;
-  constructor(options) {
+  /**
+   * App-level WebSocket handlers keyed by URL path pattern (e.g. '/ws/chat/:id').
+   * Both Bun and Node adapters read this map to register upgrade routes.
+   */
+  websocketHandlers = /* @__PURE__ */ new Map();
+  onAppStartCallback;
+  runtimeLabel;
+  constructor(options, runtimeLabel) {
+    this.runtimeLabel = runtimeLabel;
     this.appConfig = options.appConfig;
     this.serverOptions = options.serverOptions || {};
     this.runtimeOptions = options.runtime ?? {};
+    if (options.runtime) {
+      this.appConfig.runtime = {
+        ...this.appConfig.runtime ?? {},
+        ...options.runtime
+      };
+    }
     this.cliArgs = parseCliArgs({ embeddedRuntime: this.runtimeOptions.embedded });
     const hostModuleLoader = this.runtimeOptions.hostModuleLoader ?? (this.runtimeOptions.embedded ? getHostModuleLoader() : void 0);
     if (hostModuleLoader) {
       setAppHostModuleLoader(this.appConfig, hostModuleLoader);
     }
     getAppModuleLoader(this.appConfig);
+    startupTrace.markConfigReady();
     if (options.clearOutput) {
       this.clearDistFolder().catch((error) => {
         appLogger.error("Error clearing dist folder", error);
@@ -93,6 +112,71 @@ class AbstractApplicationAdapter {
   getStaticRoutes() {
     return this.staticRoutes;
   }
+  /**
+   * Register a WebSocket handler for the given path pattern.
+   *
+   * The runtime adapter handles the HTTP→WebSocket upgrade for this path
+   * and routes lifecycle events to `handler`.
+   *
+   * Supports dynamic segments via `:param` syntax. The handler receives
+   * typed `params` and `search` fields, and a typed `context` produced by
+   * the optional `context()` factory.
+   *
+   * One pattern registration matches infinite path variations. For example,
+   * `app.websocket('/ws/chat/:roomId', handler)` matches `/ws/chat/abc`,
+   * `/ws/chat/xyz`, etc. Each connection receives its own `params.roomId`.
+   *
+   * Works across both Bun and Node runtimes — no runtime-specific imports needed.
+   *
+   * @example
+   * ```typescript
+   * app.websocket<ChatContext, { roomId: string }>('/ws/chat/:roomId', {
+   *   async context({ params, search }) {
+   *     return { username: search.username ?? 'anonymous', roomId: params.roomId };
+   *   },
+   *   onConnect(socket) {
+   *     socket.send(`Welcome to room ${socket.context.roomId}`);
+   *   },
+   *   onMessage(socket, message) {
+   *     if (message.kind === 'text') {
+   *       socket.send(message.text);
+   *     }
+   *   },
+   * });
+   * ```
+   */
+  websocket(path, handler) {
+    invariant(
+      typeof path === "string" && path.startsWith("/"),
+      `app.websocket(): path must be a string starting with "/", got "${path}".`
+    );
+    const segments = path.split("/").filter(Boolean);
+    const paramNames = /* @__PURE__ */ new Set();
+    for (const segment of segments) {
+      if (segment.startsWith(":")) {
+        const paramName = segment.slice(1);
+        invariant(
+          paramName.length > 0,
+          `app.websocket(): invalid pattern "${path}" \u2014 empty param name in segment ":${paramName}".`
+        );
+        invariant(
+          !paramNames.has(paramName),
+          `app.websocket(): invalid pattern "${path}" \u2014 duplicate param name ":${paramName}".`
+        );
+        paramNames.add(paramName);
+      }
+    }
+    this.websocketHandlers.set(path, handler);
+    return this;
+  }
+  /**
+   * Get the registered WebSocket handlers map.
+   *
+   * @returns The map of WebSocket route patterns to handlers
+   */
+  getWebsocketHandlers() {
+    return this.websocketHandlers;
+  }
   /**
    * Register a global error handler for all routes.
    * Useful for logging, monitoring integration, and custom error formatting.
@@ -115,6 +199,72 @@ class AbstractApplicationAdapter {
   getErrorHandler() {
     return this.errorHandler;
   }
+  /**
+   * Boot the server. When `onAppStart` is passed, it runs once the runtime can take traffic.
+   * Embedded apps only register the callback — the host (for example Vite) boots the port.
+   */
+  async start(onAppStart) {
+    if (onAppStart) {
+      this.onAppStartCallback = onAppStart;
+    }
+    if (this.runtimeOptions.embedded) {
+      return;
+    }
+    return this.bootServer();
+  }
+  logServerStarted(origin) {
+    appLogger.info(formatRuntimeServerStartedMessage(this.runtimeLabel, origin));
+  }
+  /**
+   * Invoked by embedded hosts (for example Vite) once the app can take traffic.
+   */
+  async handleListening(origin) {
+    await this.notifyListening(origin);
+  }
+  async notifyListening(origin) {
+    const normalizedOrigin = origin.replace(/\/$/, "");
+    startupTrace.markServerListening();
+    if (!this.onAppStartCallback) {
+      this.logServerStarted(normalizedOrigin);
+      return;
+    }
+    await this.invokeAppStartCallback(normalizedOrigin);
+  }
+  /**
+   * Resolves routes exposed on {@link AppStartInfo}.
+   *
+   * @remarks
+   * Default is empty. Runtime adapters override this to read from the
+   * initialized server route registry.
+   */
+  async resolveAppRoutes() {
+    return [];
+  }
+  async invokeAppStartCallback(origin) {
+    let routes = [];
+    try {
+      routes = await this.resolveAppRoutes();
+    } catch (error) {
+      appLogger.debug(
+        "Failed to resolve app start routes; continuing with empty routes",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+    this.onAppStartCallback?.({ origin, routes });
+  }
+  /**
+   * Stops the application server and releases runtime resources.
+   *
+   * @remarks
+   * Subclasses override this to shut down bound servers, watchers, and other
+   * dev-time resources. The default implementation is a no-op so embedded
+   * adapters that never call `start()` can still be used with `await using`.
+   */
+  async stop(_force = true) {
+  }
+  async [Symbol.asyncDispose]() {
+    await this.stop(true);
+  }
 }
 export {
   AbstractApplicationAdapter

package/src/adapters/abstract/segment-path-matcher.d.ts

@@ -0,0 +1,6 @@
+export declare function normalizeSegmentPath(pathname: string): string;
+export declare function matchApiPathPattern(pattern: string, pathname: string): Record<string, string | string[]> | null;
+export declare function scoreApiPathPattern(pattern: string): number;
+export declare function matchExplicitStaticPathPattern(pattern: string, pathname: string): Record<string, string> | null;
+export declare function matchColonSegmentPath(pattern: string, pathname: string): Record<string, string> | null;
+export declare function scoreColonSegmentPath(pattern: string): number;

package/src/adapters/abstract/segment-path-matcher.js

@@ -0,0 +1,149 @@
+function normalizeSegmentPath(pathname) {
+  if (pathname.length > 1 && pathname.endsWith("/")) {
+    return pathname.slice(0, -1);
+  }
+  return pathname;
+}
+function matchApiPathPattern(pattern, pathname) {
+  const normalizedPattern = normalizeSegmentPath(pattern);
+  const normalizedPathname = normalizeSegmentPath(pathname);
+  const patternSegments = normalizedPattern.split("/").filter(Boolean);
+  const pathSegments = normalizedPathname.split("/").filter(Boolean);
+  const params = {};
+  let patternIndex = 0;
+  let pathIndex = 0;
+  while (patternIndex < patternSegments.length && pathIndex < pathSegments.length) {
+    const patternSegment = patternSegments[patternIndex];
+    const pathSegment = pathSegments[pathIndex];
+    if (patternSegment === "*") {
+      return params;
+    }
+    if (patternSegment.startsWith("[...") && patternSegment.endsWith("]")) {
+      const paramName = patternSegment.slice(4, -1);
+      params[paramName] = pathSegments.slice(pathIndex);
+      return params;
+    }
+    if (patternSegment.startsWith(":")) {
+      params[patternSegment.slice(1)] = pathSegment;
+      patternIndex++;
+      pathIndex++;
+      continue;
+    }
+    if (patternSegment.startsWith("[") && patternSegment.endsWith("]")) {
+      params[patternSegment.slice(1, -1)] = pathSegment;
+      patternIndex++;
+      pathIndex++;
+      continue;
+    }
+    if (patternSegment !== pathSegment) {
+      return null;
+    }
+    patternIndex++;
+    pathIndex++;
+  }
+  if (patternIndex < patternSegments.length) {
+    const remaining = patternSegments.slice(patternIndex);
+    const catchAll = remaining[0];
+    if (remaining.length === 1 && (catchAll === "*" || catchAll.startsWith("[...") && catchAll.endsWith("]"))) {
+      if (catchAll.startsWith("[...")) {
+        const paramName = catchAll.slice(4, -1);
+        params[paramName] = [];
+      }
+      return params;
+    }
+    return null;
+  }
+  if (pathIndex < pathSegments.length) {
+    return null;
+  }
+  return params;
+}
+function scoreApiPathPattern(pattern) {
+  const segments = normalizeSegmentPath(pattern).split("/").filter(Boolean);
+  let score = 0;
+  for (const segment of segments) {
+    if (segment === "*" || segment.startsWith("[...") && segment.endsWith("]")) {
+      score += 10;
+    } else if (segment.startsWith(":") || segment.startsWith("[") && segment.endsWith("]")) {
+      score += 50;
+    } else {
+      score += 100;
+    }
+  }
+  return score;
+}
+function matchExplicitStaticPathPattern(pattern, pathname) {
+  const patternSegments = normalizeSegmentPath(pattern).split("/").filter(Boolean);
+  const pathSegments = normalizeSegmentPath(pathname).split("/").filter(Boolean);
+  if (patternSegments.length !== pathSegments.length) {
+    const lastPattern = patternSegments[patternSegments.length - 1];
+    const isCatchAll = lastPattern?.startsWith("[...") || lastPattern?.startsWith(":...");
+    if (!isCatchAll) {
+      return null;
+    }
+  }
+  const params = {};
+  for (let i = 0; i < patternSegments.length; i++) {
+    const patternPart = patternSegments[i];
+    const pathPart = pathSegments[i];
+    if (patternPart.startsWith(":...") || patternPart.startsWith("[...")) {
+      const paramName = patternPart.replace(/^(:\.\.\.|\[\.\.\.)/, "").replace(/\]$/, "");
+      params[paramName] = pathSegments.slice(i).join("/");
+      return params;
+    }
+    if (patternPart.startsWith(":")) {
+      params[patternPart.slice(1)] = pathPart;
+    } else if (patternPart.startsWith("[") && patternPart.endsWith("]")) {
+      params[patternPart.slice(1, -1)] = pathPart;
+    } else if (patternPart !== pathPart) {
+      return null;
+    }
+  }
+  return params;
+}
+function matchColonSegmentPath(pattern, pathname) {
+  const patternSegments = pattern.split("/").filter(Boolean);
+  const pathSegments = pathname.split("/").filter(Boolean);
+  if (patternSegments.length !== pathSegments.length) {
+    return null;
+  }
+  const params = {};
+  for (let i = 0; i < patternSegments.length; i++) {
+    const patternSegment = patternSegments[i];
+    const pathSegment = pathSegments[i];
+    if (!patternSegment || !pathSegment) {
+      return null;
+    }
+    if (patternSegment.startsWith(":")) {
+      const paramName = patternSegment.slice(1);
+      if (!paramName) {
+        return null;
+      }
+      params[paramName] = pathSegment;
+    } else if (patternSegment !== pathSegment) {
+      return null;
+    }
+  }
+  return params;
+}
+function scoreColonSegmentPath(pattern) {
+  const segments = pattern.split("/").filter(Boolean);
+  let literals = 0;
+  let dynamics = 0;
+  for (const segment of segments) {
+    if (segment.startsWith(":")) {
+      dynamics += 1;
+    } else {
+      literals += 1;
+    }
+  }
+  return literals * 100 - dynamics * 10 + segments.length;
+}
+export {
+  matchApiPathPattern,
+  matchColonSegmentPath,
+  matchExplicitStaticPathPattern,
+  normalizeSegmentPath,
+  scoreApiPathPattern,
+  scoreColonSegmentPath
+};

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

@@ -8,6 +8,7 @@
  */
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { ApiHandler } from '../../types/public-types.js';
+import type { StaticGenerationRoute } from '../../router/server/route-registry.js';
 /**
  * Configuration options for all server adapters
  */
@@ -31,7 +32,19 @@ export interface ServerAdapterResult {
     }) => any;
     buildStatic: (options?: {
         preview?: boolean;
-    }) => Promise<void>;
+        force?: boolean;
+    }) => Promise<string | undefined>;
+    servePreviewOnly: () => Promise<string | undefined>;
+    dispose(): Promise<void>;
+    /**
+     * Lists static-generation routes for app-start consumers.
+     *
+     * @remarks
+     * Optional so lightweight adapter stubs in tests need not implement routing.
+     */
+    listStaticGenerationRoutes?: (input: {
+        runtimeOrigin: string;
+    }) => Promise<readonly StaticGenerationRoute[]>;
 }
 /**
  * Abstract base class for server adapters across different runtimes
@@ -57,7 +70,8 @@ export declare abstract class AbstractServerAdapter<TOptions extends ServerAdapt
      */
     abstract buildStatic(options?: {
         preview?: boolean;
-    }): Promise<void>;
+        force?: boolean;
+    }): Promise<string | undefined>;
     /**
      * Factory method to create a server adapter with runtime-specific functionality
      */

package/src/adapters/abstract/ws-pattern-matcher.d.ts

@@ -0,0 +1,12 @@
+import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
+export type WebSocketRouteMatch = {
+    handler: EcopagesWebSocketHandler<any, any>;
+    params: Record<string, string>;
+    kind: string;
+};
+/**
+ * Pattern matcher for WebSocket route paths.
+ */
+export declare function matchWebSocketPath(pattern: string, pathname: string): Record<string, string> | null;
+export declare function scoreWebSocketPattern(pattern: string): number;
+export declare function findWebSocketRoute(handlers: Map<string, EcopagesWebSocketHandler<any, any>>, pathname: string): WebSocketRouteMatch | null;

package/src/adapters/abstract/ws-pattern-matcher.js

@@ -0,0 +1,30 @@
+import { matchColonSegmentPath, scoreColonSegmentPath } from "./segment-path-matcher.js";
+function matchWebSocketPath(pattern, pathname) {
+  return matchColonSegmentPath(pattern, pathname);
+}
+function scoreWebSocketPattern(pattern) {
+  return scoreColonSegmentPath(pattern);
+}
+function findWebSocketRoute(handlers, pathname) {
+  let best = null;
+  let index = 0;
+  for (const [pattern, handler] of handlers) {
+    const params = matchColonSegmentPath(pattern, pathname);
+    if (params === null) {
+      index += 1;
+      continue;
+    }
+    const score = scoreColonSegmentPath(pattern);
+    const match = { handler, params, kind: pattern };
+    if (best === null || score > best.score || score === best.score && index < best.index) {
+      best = { score, match, index };
+    }
+    index += 1;
+  }
+  return best?.match ?? null;
+}
+export {
+  findWebSocketRoute,
+  matchWebSocketPath,
+  scoreWebSocketPattern
+};

package/src/adapters/bun/bun-user-websocket-lifecycle.d.ts

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