@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.21

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

@@ -0,0 +1,60 @@
+import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
+/**
+ * Pattern matcher for WebSocket route paths.
+ *
+ * Supports dynamic segments via `:param` syntax. Matches are exact on literal
+ * segments and capture dynamic segments into a params object.
+ *
+ * @example
+ * ```ts
+ * matchWebSocketPath('/ws/chat/:id', '/ws/chat/abc123')
+ * // Returns: { id: 'abc123' }
+ *
+ * matchWebSocketPath('/ws/chat/:id', '/ws/chat/abc123/messages')
+ * // Returns: null (length mismatch)
+ *
+ * matchWebSocketPath('/ws/chat', '/ws/chat')
+ * // Returns: {} (no params)
+ * ```
+ *
+ * @remarks
+ * This is a minimal segment-based matcher. It does not support wildcards,
+ * optional segments, or catch-all patterns. Those are future concerns.
+ *
+ * @param pattern - The registered route pattern (e.g. '/ws/chat/:id')
+ * @param pathname - The actual request pathname (e.g. '/ws/chat/abc123')
+ * @returns A params object if the pattern matches, or null if it does not
+ */
+export declare function matchWebSocketPath(pattern: string, pathname: string): Record<string, string> | null;
+/**
+ * Represents a matched WebSocket route.
+ */
+export type WebSocketRouteMatch = {
+    handler: EcopagesWebSocketHandler<any, any>;
+    params: Record<string, string>;
+    kind: string;
+};
+/**
+ * Scores a pattern for specificity ordering.
+ *
+ * Higher scores win. Rules, in order:
+ * 1. More literal segments beats more dynamic segments.
+ * 2. Fewer dynamic segments beats more dynamic segments.
+ * 3. Longer route (more segments) beats shorter route.
+ *
+ * @param pattern - The registered route pattern
+ * @returns A numeric specificity score
+ */
+export declare function scoreWebSocketPattern(pattern: string): number;
+/**
+ * Find the registered WebSocket handler that best matches a pathname.
+ *
+ * Iterates through the provided handlers map, computes each pattern's
+ * specificity score, and returns the highest-scoring match. Ties resolve
+ * to the earliest-registered pattern.
+ *
+ * @param handlers - The map of registered WebSocket handlers
+ * @param pathname - The actual request pathname
+ * @returns The best match, or null if no pattern matches
+ */
+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,61 @@
+function matchWebSocketPath(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 scoreWebSocketPattern(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;
+}
+function findWebSocketRoute(handlers, pathname) {
+  let best = null;
+  let index = 0;
+  for (const [pattern, handler] of handlers) {
+    const params = matchWebSocketPath(pattern, pathname);
+    if (params === null) {
+      index += 1;
+      continue;
+    }
+    const score = scoreWebSocketPattern(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/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

@@ -11,7 +11,6 @@ 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 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,8 @@ 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>;
 }
 /**
  * Factory function to create a Bun application

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

@@ -1,19 +1,17 @@
-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 { 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";
 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 +20,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 +44,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 +66,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) {
+        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) {
+        this.notifyListening(previewOrigin2);
+      }
       if (build) {
         process.exit(0);
       }
@@ -85,12 +100,7 @@ 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;
     this.server = await this.runtimeHost.start({
       serveOptions: runtimeServerOptions,
       handleRequest: async () => new Response(null, { status: 500 }),
@@ -103,35 +113,47 @@ 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 {
+      this.notifyListening(runtimeOrigin);
+    }
+    if (preview && previewOrigin) {
+      this.notifyListening(previewOrigin);
+    }
+    return this.server ?? void 0;
+  }
+  async stop(force = true) {
+    if (this.stopped) {
+      return;
+    }
+    if (this.server) {
+      const activeServer = this.server;
+      this.server = null;
+      await this.runtimeHost.stop(activeServer, { force });
+    }
+    if (this.serverAdapter) {
+      await this.serverAdapter.dispose();
     }
-    return this.server;
+    this.stopped = true;
   }
 }
 async function createApp(options) {
   return new BunEcopagesApp(options, {
-    runtimeHost: new BunRuntimeHost(),
-    previewHost: new BunStaticPreviewHost()
+    runtimeHost: new BunRuntimeHost()
   });
 }
 export {

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

@@ -1,6 +1,7 @@
+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 type { ApiHandler, ErrorHandler, StaticRoute, EcopagesWebSocketHandler } from '../../types/public-types.js';
 import { SharedServerAdapter } from '../shared/server-adapter.js';
 import type { ServerAdapterResult } from '../abstract/server-adapter.js';
 import type { StaticPreviewHost } from '../shared/static-preview-host.js';
@@ -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,11 +125,17 @@ 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;
     });
+    /**
+     * Wires user WebSocket routes onto a Node HTTP server used by host integrations.
+     */
+    attachUserWebSocketUpgrades(server: NodeHttpServer, options?: {
+        passthroughUnmatched?: boolean;
+    }): void;
     /**
      * Returns whether adapter-level HTML responses still need HMR runtime injection.
      *
@@ -94,26 +144,11 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      * 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.
-     */
     private maybeInjectHmrScript;
     /**
      * 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,13 +169,31 @@ 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;
+    /**
+     * @remarks
+     * When `serveHmrEndpoints` is set, `/_hmr` and `/_hmr_runtime.js` are checked
+     * before user websocket patterns so HMR upgrades are never captured by app routes.
+     * Production mode with only user handlers skips the HMR branch entirely.
+     */
+    private wrapFetchWithWebSocketUpgrades;
     /**
      * Helper method to retrieve and parse the request body.
      * Handles JSON and plain text content types.
@@ -163,7 +216,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,6 +244,14 @@ 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.
      *