@ecopages/core 0.2.0-beta.1 → 0.2.0-beta.10

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);
     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
     });
   }
   /**
@@ -66,17 +67,21 @@ class BunEcopagesApp extends SharedApplicationAdapter {
    * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
    */
   async start() {
+    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 } = this.cliArgs;
     const staticRuntimeMode = resolveStaticRuntimeMode({
       appConfig: this.appConfig,
       cliArgs: this.cliArgs
     });
     if (staticRuntimeMode.canBuildWithoutRuntimeServer) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview });
+      await this.serverAdapter.buildStatic({ preview, force });
       appLogger.debugTimeEnd("Building static pages");
       if (build) {
         process.exit(0);
@@ -85,12 +90,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 }),
@@ -108,30 +108,35 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     );
     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}`);
-        }
-      }
+      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);
       }
     }
-    return this.server;
+    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();
+    }
+    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/hmr-manager.d.ts

@@ -7,6 +7,7 @@ type BunSocketHandler = WebSocketHandler<unknown>;
 export interface HmrManagerParams {
     appConfig: EcoPagesAppConfig;
     bridge: ClientBridge;
+    registrationTimeoutMs?: number;
 }
 /**
  * Bun development HMR manager.
@@ -26,7 +27,7 @@ export declare class HmrManager extends SharedHmrManager {
      * generation to `SharedHmrManager`. The Bun subclass only supplies the
      * transport-specific dependency graph policy and websocket hook surface.
      */
-    constructor({ appConfig, bridge }: HmrManagerParams);
+    constructor({ appConfig, bridge, registrationTimeoutMs }: HmrManagerParams);
     /**
      * Reuses the shared in-memory dependency graph when possible and otherwise
      * creates the Bun-compatible default graph implementation.

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

@@ -13,8 +13,8 @@ class HmrManager extends SharedHmrManager {
    * generation to `SharedHmrManager`. The Bun subclass only supplies the
    * transport-specific dependency graph policy and websocket hook surface.
    */
-  constructor({ appConfig, bridge }) {
-    super({ appConfig, bridge });
+  constructor({ appConfig, bridge, registrationTimeoutMs }) {
+    super({ appConfig, bridge, registrationTimeoutMs });
   }
   /**
    * Reuses the shared in-memory dependency graph when possible and otherwise

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,14 @@ export interface BunServerAdapterResult extends ServerAdapterResult {
     }) => BunServeOptions;
     buildStatic: (options?: {
         preview?: boolean;
+        force?: boolean;
     }) => Promise<void>;
     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 +82,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 +124,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 +143,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 +168,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,6 +215,7 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      */
     buildStatic(options?: {
         preview?: boolean;
+        force?: boolean;
     }): Promise<void>;
     /**
      * Initializes the server with dynamic routes after server creation.
@@ -184,6 +237,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.
      *