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

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

@@ -1,22 +1,25 @@
-import { createServer } from "node:http";
+import {} from "node:http";
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
-import { getAppBrowserBuildPlugins, setupAppRuntimePlugins } from "../../build/build-adapter.js";
+import { setupAppRuntimePlugins } from "../../build/build-adapter.js";
 import { installAppRuntimeBuildExecutor } from "../../build/runtime-build-executor.js";
-import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
 import { appLogger } from "../../global/app-logger.js";
 import { NodeClientBridge } from "./node-client-bridge.js";
 import { NodeHmrManager } from "./node-hmr-manager.js";
 import { ProjectWatcher } from "../../watchers/project-watcher.js";
+import {
+  attachNodeHttpWebSocketUpgrades
+} from "../shared/node-http-websocket-upgrades.js";
 import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator.js";
 import { SharedServerAdapter } from "../shared/server-adapter.js";
 import { ServerStaticBuilder } from "../shared/server-static-builder.js";
 import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
 import {
-  injectHmrRuntimeIntoHtmlResponse,
-  isHtmlResponse,
-  shouldInjectHmrHtmlResponse
-} from "../shared/hmr-html-response.js";
+  maybeInjectAdapterHmrHtmlResponse,
+  prepareRuntimePublicDir,
+  wireIntegrationHmrManagers,
+  disposeDevResources
+} from "../shared/runtime-server-lifecycle.js";
 import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
 import { NodeClientAbortError, NodeHttpRequestBridge } from "./http-request-bridge.js";
 import { NodeStaticPreviewHost } from "./static-preview-host.js";
@@ -29,29 +32,73 @@ class NodeServerAdapter extends SharedServerAdapter {
   errorHandler;
   bridge = null;
   hmrManager = null;
+  projectWatcher = null;
+  adapterDisposed = false;
+  deferRuntimeAssetSetup;
+  allowPortFallback;
   previewHost;
   requestBridge;
   devRuntimeFactory;
-  shouldInjectHmrScript() {
-    return shouldInjectHmrHtmlResponse(this.options?.watch === true, this.hmrManager ?? void 0);
+  /**
+   * 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 Node adapter reads from it to wire
+   * WebSocket upgrades for user-registered patterns.
+   */
+  websocketHandlers = /* @__PURE__ */ new Map();
+  /**
+   * Wires user WebSocket routes onto a foreign Node HTTP server.
+   *
+   * Host integrations such as the Vite plugin call this so `app.websocket()`
+   * handlers work while HTTP is still served by the host dev server.
+   */
+  attachUserWebSocketUpgrades(server, options) {
+    attachNodeHttpWebSocketUpgrades(server, {
+      runtimeOrigin: this.runtimeOrigin,
+      websocketHandlers: this.websocketHandlers,
+      passthroughUnmatched: options?.passthroughUnmatched
+    });
   }
-  isHtmlResponse(response) {
-    return isHtmlResponse(response);
+  wireUserWebSocketUpgrades(server, preflight) {
+    attachNodeHttpWebSocketUpgrades(server, {
+      runtimeOrigin: this.runtimeOrigin,
+      websocketHandlers: this.websocketHandlers,
+      passthroughUnmatched: false,
+      preflight
+    });
   }
   async maybeInjectHmrScript(response) {
-    if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
-      return injectHmrRuntimeIntoHtmlResponse(response);
-    }
-    return response;
+    return maybeInjectAdapterHmrHtmlResponse(response, {
+      watch: this.options?.watch === true,
+      hmrManager: this.hmrManager ?? void 0,
+      hostOwnsDevClient: this.hostOwnsDevClient
+    });
   }
+  /**
+   * @remarks
+   * `previewHost`, `requestBridge`, and `devRuntimeFactory` are optional on the
+   * public {@link NodeServerAdapterParams} so factory callers can omit them, but
+   * they are mandatory by the time the concrete adapter is constructed —
+   * {@link createNodeServerAdapter} fills in Node-specific defaults first. The
+   * constructor signature makes that invariant explicit instead of relying on
+   * non-null assertions.
+   */
   constructor(options) {
     super(options);
+    this.deferRuntimeAssetSetup = options.deferRuntimeAssetSetup === true;
+    this.allowPortFallback = options.allowPortFallback !== false;
     this.apiHandlers = options.apiHandlers || [];
     this.staticRoutes = options.staticRoutes || [];
     this.errorHandler = options.errorHandler;
     this.previewHost = options.previewHost;
     this.requestBridge = options.requestBridge;
     this.devRuntimeFactory = options.devRuntimeFactory;
+    if (options.websocketHandlers) {
+      this.websocketHandlers = options.websocketHandlers;
+    }
+    this.hostOwnsDevClient = options.hostOwnsDevClient === true;
   }
   /**
    * Prepares the adapter for use.
@@ -68,12 +115,14 @@ class NodeServerAdapter extends SharedServerAdapter {
    */
   async initialize() {
     installAppRuntimeBuildExecutor(this.appConfig);
-    this.prepareRuntimePublicDir();
-    await setupAppRuntimePlugins({
-      appConfig: this.appConfig,
-      runtimeOrigin: this.runtimeOrigin,
-      hmrManager: this.hmrManager ?? void 0
-    });
+    prepareRuntimePublicDir(this.appConfig);
+    if (!this.deferRuntimeAssetSetup) {
+      await setupAppRuntimePlugins({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin,
+        hmrManager: this.hmrManager ?? void 0
+      });
+    }
     await this.initializeSharedRouteHandling({
       staticRoutes: this.staticRoutes,
       hmrManager: this.hmrManager ?? void 0
@@ -83,17 +132,12 @@ class NodeServerAdapter extends SharedServerAdapter {
       appConfig: this.appConfig,
       staticSiteGenerator: this.staticSiteGenerator,
       serveOptions: this.serveOptions,
-      apiHandlers: this.apiHandlers
+      runtimeOrigin: this.runtimeOrigin,
+      needsServerBundle: this.apiHandlers.length > 0 || this.websocketHandlers.size > 0,
+      hmrManager: this.hmrManager ?? void 0
     });
     this.initialized = true;
   }
-  prepareRuntimePublicDir() {
-    const srcPublicDir = path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.publicDir);
-    if (fileSystem.exists(srcPublicDir)) {
-      fileSystem.copyDir(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
-    }
-    fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
-  }
   getServerOptions() {
     return {
       ...this.serveOptions
@@ -103,106 +147,84 @@ class NodeServerAdapter extends SharedServerAdapter {
     if (!this.initialized) {
       await this.initialize();
     }
-    const buildServer = await this.startBuildRuntimeServer();
-    const buildRuntimeOrigin = this.getListeningServerOrigin(buildServer);
-    try {
-      await this.staticBuilder.build(
-        { preview: false, baseUrl: buildRuntimeOrigin },
-        {
-          router: this.router,
-          routeRendererFactory: this.routeRendererFactory,
-          staticRoutes: this.staticRoutes
-        }
-      );
-    } finally {
-      await this.stopBuildRuntimeServer(buildServer);
-    }
-    if (!options?.preview) {
-      return;
-    }
-    await this.previewHost.start({
-      appConfig: this.appConfig,
-      hostname: String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME),
-      port: Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT)
-    });
-    const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
-    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
-    appLogger.info(`Preview running at http://${previewHostname}:${previewPort}`);
-  }
-  async startBuildRuntimeServer() {
-    const hostname = String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME);
-    const port = 0;
-    const server = createServer(async (req, res) => {
-      try {
-        const webRequest = this.requestBridge.createWebRequest(req, this.runtimeOrigin);
-        const response = await this.handleRequest(webRequest);
-        await this.requestBridge.sendNodeResponse(res, response);
-      } catch (error) {
-        if (error instanceof NodeClientAbortError) {
-          return;
-        }
-        appLogger.error("Node static build runtime request failed", error);
-        res.statusCode = 500;
-        res.end("Internal Server Error");
+    const baseUrl = resolveServeRuntimeOrigin(this.serveOptions);
+    await this.staticBuilder.build(
+      { baseUrl, force: options?.force },
+      {
+        router: this.router,
+        routeRendererFactory: this.routeRendererFactory,
+        staticRoutes: this.staticRoutes
       }
-    });
-    await new Promise((resolve, reject) => {
-      server.once("error", reject);
-      server.listen(port, hostname, () => {
-        server.off("error", reject);
-        resolve();
-      });
-    });
-    this.serverInstance = server;
-    appLogger.info(`Server running at ${this.getListeningServerOrigin(server)}`);
-    return server;
-  }
-  getListeningServerOrigin(server) {
-    const address = server.address();
-    const hostname = String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME);
-    if (!address || typeof address === "string") {
-      throw new Error("Build runtime server did not expose a numeric listening port");
+    );
+    if (!options?.preview) {
+      return void 0;
     }
-    return `http://${hostname}:${address.port}`;
+    return this.startPreviewServer();
   }
   /**
-   * Gracefully shuts down the ephemeral build runtime server.
-   *
-   * `closeAllConnections()` is called *before* `close()` because `server.close()`
-   * only stops accepting new connections — it waits for existing keep-alive
-   * connections to finish naturally, which can stall the build indefinitely.
-   * `closeAllConnections()` force-closes any lingering sockets immediately so
-   * the `close()` callback fires promptly.
-   *
-   * The `NodeClientBridge` heartbeat is also destroyed here so its `setInterval`
-   * does not prevent the Node.js process from exiting cleanly after the build.
+   * Serves an existing static export without running SSG. Used by e2e preview
+   * launchers after a shared prewarm build.
    */
-  async stopBuildRuntimeServer(server) {
-    await new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve();
-      });
-      server.closeAllConnections();
+  async servePreviewOnly() {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    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();
+  }
+  async startPreviewServer() {
+    const activePreviewPort = await this.previewHost.start({
+      appConfig: this.appConfig,
+      hostname: String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME),
+      port: Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT),
+      allowPortFallback: this.allowPortFallback
     });
-    if (this.serverInstance === server) {
-      this.serverInstance = null;
+    if (!activePreviewPort) {
+      return void 0;
     }
-    this.bridge?.destroy();
-    this.bridge = null;
+    const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
+    return `http://${previewHostname}:${activePreviewPort}`;
   }
   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)
+      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 HTTP 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;
+    this.hmrManager = null;
+    this.bridge = null;
+  }
   /**
    * Handles a single incoming Web `Request` and returns a Web `Response`.
    *
@@ -244,35 +266,39 @@ class NodeServerAdapter extends SharedServerAdapter {
    * - Shared watcher bootstrapping listens for route-level file changes and
    *   refreshes the router and response handlers when pages are added or removed.
    *
-   * WebSocket upgrade requests that do not target `/_hmr` are rejected with an
+   * WebSocket upgrade requests that do not match a known path are rejected with an
    * immediate socket destroy to prevent unhandled upgrade leaks.
    */
   async completeInitialization(server) {
     this.serverInstance = server;
+    const hasUserWs = this.websocketHandlers.size > 0;
     if (this.options?.watch) {
       const devRuntime = this.devRuntimeFactory.create({ appConfig: this.appConfig });
       const wss = devRuntime.websocketServer;
       this.bridge = devRuntime.bridge;
       this.hmrManager = devRuntime.hmrManager;
       this.hmrManager.setEnabled(true);
-      await this.hmrManager.buildRuntime();
-      server.on("upgrade", (req, socket, head) => {
+      await this.hmrManager.ensureRuntimeReady();
+      const hmrPreflight = (req, socket, head) => {
         const url = new URL(req.url ?? "/", this.runtimeOrigin);
-        if (url.pathname === "/_hmr") {
-          wss.handleUpgrade(req, socket, head, (ws) => {
-            this.bridge.subscribe(ws);
-            ws.on("close", () => this.bridge.unsubscribe(ws));
-            ws.on("error", (err) => appLogger.error("[HMR] WebSocket error:", err));
-          });
-        } else {
-          socket.destroy();
-        }
-      });
-      const browserBuildPlugins = getAppBrowserBuildPlugins(this.appConfig);
-      this.hmrManager.setPlugins(browserBuildPlugins);
-      for (const integration of this.appConfig.integrations) {
-        integration.setHmrManager(this.hmrManager);
+        if (url.pathname !== "/_hmr") return false;
+        wss.handleUpgrade(req, socket, head, (ws) => {
+          this.bridge.subscribe(ws);
+          ws.on("close", () => this.bridge.unsubscribe(ws));
+          ws.on("error", (err) => appLogger.error("[HMR] WebSocket error:", err));
+        });
+        return true;
+      };
+      if (hasUserWs) {
+        this.wireUserWebSocketUpgrades(server, hmrPreflight);
+      } else {
+        server.on("upgrade", (req, socket, head) => {
+          if (!hmrPreflight(req, socket, head)) {
+            socket.destroy();
+          }
+        });
       }
+      wireIntegrationHmrManagers(this.appConfig, this.hmrManager);
       this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
       const watcher = new ProjectWatcher({
         config: this.appConfig,
@@ -281,9 +307,13 @@ class NodeServerAdapter extends SharedServerAdapter {
           hmrManager: this.hmrManager
         }),
         hmrManager: this.hmrManager,
-        bridge: this.bridge
+        bridge: this.bridge,
+        hostOwnsDevClient: this.hostOwnsDevClient
       });
+      this.projectWatcher = watcher;
       await watcher.createWatcherSubscription();
+    } else if (hasUserWs) {
+      this.wireUserWebSocketUpgrades(server);
     }
     appLogger.debug("Node server adapter initialization completed", {
       apiHandlers: this.apiHandlers.length,

package/src/adapters/node/static-content-server.d.ts

@@ -56,5 +56,6 @@ export declare class NodeStaticContentServer {
      * Stops the static preview server and optionally closes active connections.
      */
     stop(force?: boolean): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
 }
 export {};

package/src/adapters/node/static-content-server.js

@@ -161,8 +161,13 @@ class NodeStaticContentServer {
     this.server = createServer(this.handleRequest.bind(this));
     const hostname = this.options.hostname ?? DEFAULT_ECOPAGES_HOSTNAME;
     const port = this.options.port ?? DEFAULT_ECOPAGES_PORT;
-    await new Promise((resolve) => {
-      this.server.listen(port, hostname, () => resolve());
+    await new Promise((resolve, reject) => {
+      const activeServer = this.server;
+      activeServer.once("error", reject);
+      activeServer.listen(port, hostname, () => {
+        activeServer.off("error", reject);
+        resolve();
+      });
     });
     return this.server;
   }
@@ -188,6 +193,9 @@ class NodeStaticContentServer {
       }
     });
   }
+  async [Symbol.asyncDispose]() {
+    await this.stop();
+  }
 }
 export {
   NodeStaticContentServer

package/src/adapters/node/static-preview-host.js

@@ -1,3 +1,5 @@
+import { appLogger } from "../../global/app-logger.js";
+import { PortManager } from "../shared/port-manager.js";
 import { NodeStaticContentServer } from "./static-content-server.js";
 class NodeStaticPreviewHost {
   /**
@@ -20,20 +22,33 @@ class NodeStaticPreviewHost {
    */
   async start(options) {
     await this.stop();
-    const previewServer = new this.previewServerFactory({
-      appConfig: options.appConfig,
-      options: {
-        hostname: options.hostname,
-        port: options.port
-      }
+    const portManager = new PortManager({
+      startOnPort: async (port) => {
+        const previewServer = new this.previewServerFactory({
+          appConfig: options.appConfig,
+          options: {
+            hostname: options.hostname,
+            port
+          }
+        });
+        const server = await previewServer.start();
+        this.previewServer = previewServer;
+        const address = server.address();
+        if (address && typeof address === "object") {
+          return address.port;
+        }
+        return port;
+      },
+      warn: (message) => appLogger.warn(message)
+    });
+    const previewPort = await portManager.bind({
+      preferredPort: options.port,
+      allowPortFallback: options.allowPortFallback === true
     });
-    const server = await previewServer.start();
-    this.previewServer = previewServer;
-    const address = server.address();
-    if (address && typeof address === "object") {
-      return address.port;
+    if (!previewPort) {
+      this.previewServer = null;
     }
-    return options.port;
+    return previewPort;
   }
   /**
    * Stops the active preview server and coalesces overlapping stop requests onto

package/src/adapters/shared/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;
+};

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

@@ -0,0 +1,96 @@
+import { appLogger } from "../../global/app-logger.js";
+import { invokeWebSocketHandlerHook, toWebSocketCloseInfo } from "./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/shared/copy-runtime-public-dir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copies a source public directory into the runtime dist dir, skipping unchanged files.
+ *
+ * Dev restarts call this on every boot; byte comparison avoids rewriting identical assets.
+ */
+export declare function copyRuntimePublicDirIfChanged(sourceDir: string, destinationDir: string): void;

package/src/adapters/shared/copy-runtime-public-dir.js

@@ -0,0 +1,24 @@
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+function copyRuntimePublicDirIfChanged(sourceDir, destinationDir) {
+  fileSystem.ensureDir(destinationDir);
+  for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const destinationPath = path.join(destinationDir, entry.name);
+    if (entry.isDirectory()) {
+      copyRuntimePublicDirIfChanged(sourcePath, destinationPath);
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    if (fileSystem.exists(destinationPath) && Buffer.compare(fileSystem.readFileAsBuffer(sourcePath), fileSystem.readFileAsBuffer(destinationPath)) === 0) {
+      continue;
+    }
+    fileSystem.copyFile(sourcePath, destinationPath);
+  }
+}
+export {
+  copyRuntimePublicDirIfChanged
+};

package/src/adapters/shared/fs-server-response-matcher.d.ts

@@ -55,6 +55,8 @@ export declare class FileSystemResponseMatcher {
      * when the page template cannot be resolved.
      */
     private renderCustomNotFoundResponse;
+    private renderCustomNotFoundResponseOrServerError;
+    private createInternalServerErrorResponse;
     private createExecutionPlan;
     /**
      * Loads the matched page module for request-time inspection.