@ecopages/core 0.2.0-alpha.39 → 0.2.0-alpha.40

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

@@ -1,36 +1,44 @@
+import path from "node:path";
 import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
 import { appLogger } from "../../global/app-logger.js";
 import { HttpError } from "../../errors/http-error.js";
 import { createRequire } from "../../utils/locals-utils.js";
 import { fileSystem } from "@ecopages/file-system";
+import { getAppBrowserBuildPlugins, setupAppRuntimePlugins } from "../../build/build-adapter.js";
+import { installAppRuntimeBuildExecutor } from "../../build/runtime-build-executor.js";
+import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator.js";
+import { ProjectWatcher } from "../../watchers/project-watcher.js";
 import { SharedServerAdapter } from "../shared/server-adapter.js";
 import { ApiResponseBuilder } from "../shared/api-response.js";
-import { installSharedRuntimeBuildExecutor } from "../shared/runtime-bootstrap.js";
-import { StaticContentServer } from "../../dev/sc-server.js";
-import { ServerRouteHandler } from "../shared/server-route-handler.js";
 import { ServerStaticBuilder } from "../shared/server-static-builder.js";
 import {
   injectHmrRuntimeIntoHtmlResponse,
   isHtmlResponse,
   shouldInjectHmrHtmlResponse
 } from "../shared/hmr-html-response.js";
+import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
 import { ClientBridge } from "./client-bridge.js";
 import { HmrManager } from "./hmr-manager.js";
-import { ServerLifecycle } from "./server-lifecycle.js";
+import { BunStaticPreviewHost } from "./static-preview-host.js";
 class BunServerAdapter extends SharedServerAdapter {
   apiHandlers;
   staticRoutes;
   errorHandler;
   bridge;
-  lifecycle;
   hmrManager;
   initializationPromise = null;
   fullyInitialized = false;
-  lifecycleFactory;
-  staticBuilderFactory;
-  routeHandlerFactory;
-  hmrManagerFactory;
-  bridgeFactory;
+  previewHost;
+  /**
+   * Creates a Bun server adapter with already-resolved runtime collaborators.
+   *
+   * @remarks
+   * The public params interface keeps `hmrManager`, `bridge`, and `previewHost`
+   * optional so factory callers can omit them. By the time the concrete adapter
+   * is constructed, those collaborators are mandatory because the adapter cannot
+   * initialize Bun HMR or preview flows without them.
+   */
   constructor({
     appConfig,
     runtimeOrigin,
@@ -39,31 +47,32 @@ class BunServerAdapter extends SharedServerAdapter {
     staticRoutes,
     errorHandler,
     options,
-    lifecycle,
-    staticBuilderFactory,
-    routeHandlerFactory,
     hmrManager,
-    bridge
+    bridge,
+    previewHost
   }) {
     super({ appConfig, runtimeOrigin, serveOptions, options });
     this.apiHandlers = apiHandlers || [];
     this.staticRoutes = staticRoutes || [];
     this.errorHandler = errorHandler;
-    this.lifecycleFactory = lifecycle;
-    this.staticBuilderFactory = staticBuilderFactory;
-    this.routeHandlerFactory = routeHandlerFactory;
-    this.hmrManagerFactory = hmrManager;
-    this.bridgeFactory = bridge;
+    this.bridge = bridge;
+    this.hmrManager = hmrManager;
+    this.previewHost = previewHost;
   }
   /**
-   * Determines if HMR script should be injected.
-   * Only injects in watch mode when HMR manager is enabled.
+   * 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.
    */
   shouldInjectHmrScript() {
     return shouldInjectHmrHtmlResponse(this.options?.watch === true, this.hmrManager);
   }
   /**
-   * Checks if a response contains HTML content.
+   * Delegates the HTML-response test to the shared response helper used by both
+   * adapters.
    */
   isHtmlResponse(response) {
     return isHtmlResponse(response);
@@ -79,33 +88,68 @@ class BunServerAdapter extends SharedServerAdapter {
     return response;
   }
   /**
-   * Initializes the server adapter's core components.
-   * Delegates to ServerLifecycle for setup.
+   * Initializes the server adapter's core runtime components.
    */
   async initialize() {
-    installSharedRuntimeBuildExecutor(this.appConfig, {
+    installAppRuntimeBuildExecutor(this.appConfig, {
       development: this.options?.watch === true
     });
-    this.bridge = this.bridgeFactory ?? new ClientBridge();
-    this.hmrManager = this.hmrManagerFactory ?? new HmrManager({ appConfig: this.appConfig, bridge: this.bridge });
-    this.lifecycle = this.lifecycleFactory ?? new ServerLifecycle({
-      appConfig: this.appConfig,
-      runtimeOrigin: this.runtimeOrigin,
-      hmrManager: this.hmrManager,
-      bridge: this.bridge
-    });
-    this.staticSiteGenerator = await this.lifecycle.initialize();
+    this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
+    await this.hmrManager.buildRuntime();
+    this.prepareRuntimePublicDir();
     const staticBuilderOptions = {
       appConfig: this.appConfig,
       staticSiteGenerator: this.staticSiteGenerator,
       serveOptions: this.serveOptions,
       apiHandlers: this.apiHandlers
     };
-    this.staticBuilder = this.staticBuilderFactory ? this.staticBuilderFactory(staticBuilderOptions) : new ServerStaticBuilder(staticBuilderOptions);
-    await this.lifecycle.initializePlugins({ watch: this.options?.watch });
+    this.staticBuilder = new ServerStaticBuilder(staticBuilderOptions);
+    await this.initializeRuntimePlugins({ watch: this.options?.watch });
+  }
+  /**
+   * Copies the source `public` directory into the runtime output and ensures the
+   * HMR assets directory exists before any runtime bundles are emitted.
+   */
+  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));
   }
   /**
-   * Refreshes the router routes during watch mode.
+   * Registers runtime plugins and propagates the final HMR manager into each
+   * integration.
+   *
+   * @remarks
+   * This is where Bun's runtime-plugin registration path meets the integration
+   * lifecycle. A failure here leaves the runtime partially bootstrapped, so the
+   * method logs the underlying error and rethrows instead of trying to limp on.
+   */
+  async initializeRuntimePlugins(options) {
+    try {
+      this.hmrManager.setEnabled(Boolean(options?.watch));
+      await setupAppRuntimePlugins({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin,
+        hmrManager: this.hmrManager,
+        onRuntimePlugin: (plugin) => {
+          Bun.plugin(plugin);
+        }
+      });
+      const browserBuildPlugins = getAppBrowserBuildPlugins(this.appConfig);
+      this.hmrManager.setPlugins(browserBuildPlugins);
+      for (const integration of this.appConfig.integrations) {
+        integration.setHmrManager(this.hmrManager);
+      }
+    } catch (error) {
+      appLogger.error(`Failed to initialize plugins: ${error instanceof Error ? error.message : String(error)}`);
+      throw error;
+    }
+  }
+  /**
+   * Rebuilds the shared routing state and hot-reloads the live Bun server when a
+   * watched route file changes.
    */
   async refreshRouterRoutes() {
     if (!this.serverInstance || typeof this.serverInstance.reload !== "function") {
@@ -127,15 +171,21 @@ class BunServerAdapter extends SharedServerAdapter {
     })();
   }
   async watch() {
-    await this.lifecycle.startWatching({
-      refreshRouterRoutesCallback: this.refreshRouterRoutes.bind(this)
+    const watcher = new ProjectWatcher({
+      config: this.appConfig,
+      refreshRouterRoutesCallback: this.refreshRouterRoutes.bind(this),
+      hmrManager: this.hmrManager,
+      bridge: this.bridge
     });
+    await watcher.createWatcherSubscription();
   }
   /**
-   * Retrieves the current server options, optionally enabling HMR.
-   * If HMR is enabled, modifies fetch to handle WebSocket upgrades and serve HMR runtime.
-   * Ensures original fetch logic is preserved and called for non-HMR requests.
-   * @param options.enableHmr Whether to enable Hot Module Replacement
+   * 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.
    */
   getServerOptions({ enableHmr = false } = {}) {
     appLogger.debug(`[BunServerAdapter] getServerOptions called with enableHmr: ${enableHmr}`);
@@ -191,8 +241,12 @@ class BunServerAdapter extends SharedServerAdapter {
     return void 0;
   }
   /**
-   * Creates complete server configuration with request handling.
-   * @returns Server options ready for Bun.serve()
+   * Composes the base Bun server settings that all runtime modes build from.
+   *
+   * @remarks
+   * This method centralizes the Bun-specific error boundary. It preserves the
+   * shared route pipeline while still allowing adapter-level custom error-handler
+   * execution and `HttpError` passthrough.
    */
   buildServerSettings() {
     const serverOptions = { ...this.serveOptions };
@@ -268,15 +322,15 @@ class BunServerAdapter extends SharedServerAdapter {
     }
     const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
     const previewPort = Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT);
-    const previewServer = StaticContentServer.createServer({
+    const activePreviewPort = await this.previewHost.start({
       appConfig: this.appConfig,
-      options: { port: previewPort }
+      hostname: String(previewHostname),
+      port: previewPort
     });
-    if (previewServer.server?.port) {
-      appLogger.info(`Preview running at http://${previewHostname}:${previewServer.server.port}`);
+    if (activePreviewPort) {
+      appLogger.info(`Preview running at http://${previewHostname}:${activePreviewPort}`);
       return;
     }
-    appLogger.error("Failed to start preview server");
   }
   /**
    * Initializes the server with dynamic routes after server creation.
@@ -296,7 +350,12 @@ class BunServerAdapter extends SharedServerAdapter {
     return this.initializationPromise;
   }
   /**
-   * Performs complete server setup including routing, watchers, and HMR.
+   * Performs the one-time post-bind initialization path for Bun servers.
+   *
+   * @remarks
+   * This is intentionally split from `initialize()` because shared route handling
+   * and file watching need the live server instance to exist before Bun can
+   * reload updated route handlers in place.
    */
   async _performInitialization(server) {
     this.serverInstance = server;
@@ -367,23 +426,16 @@ class BunServerAdapter extends SharedServerAdapter {
   }
 }
 async function createBunServerAdapter(params) {
-  const runtimeOrigin = params.runtimeOrigin ?? `http://${params.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${params.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
+  const runtimeOrigin = params.runtimeOrigin ?? resolveServeRuntimeOrigin(params.serveOptions);
   const bridge = params.bridge ?? new ClientBridge();
   const hmrManager = params.hmrManager ?? new HmrManager({ appConfig: params.appConfig, bridge });
-  const lifecycle = params.lifecycle ?? new ServerLifecycle({
-    appConfig: params.appConfig,
-    runtimeOrigin,
-    hmrManager,
-    bridge
-  });
+  const previewHost = params.previewHost ?? new BunStaticPreviewHost();
   const adapter = new BunServerAdapter({
     ...params,
     runtimeOrigin,
     bridge,
     hmrManager,
-    lifecycle,
-    staticBuilderFactory: params.staticBuilderFactory ?? ((opts) => new ServerStaticBuilder(opts)),
-    routeHandlerFactory: params.routeHandlerFactory ?? ((p) => new ServerRouteHandler(p))
+    previewHost
   });
   return adapter.createAdapter();
 }

package/src/adapters/bun/static-preview-host.d.ts

@@ -0,0 +1,28 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { StaticPreviewHost, StaticPreviewHostStartOptions } from '../shared/static-preview-host.js';
+type BunStaticPreviewServer = {
+    server: {
+        port?: number;
+    } | null;
+    stop(): void;
+};
+type BunStaticPreviewServerFactory = {
+    createServer(args: {
+        appConfig: EcoPagesAppConfig;
+        options: {
+            port: number;
+        };
+    }): BunStaticPreviewServer;
+};
+type BunStaticPreviewLogger = {
+    error(message: string): unknown;
+};
+export declare class BunStaticPreviewHost implements StaticPreviewHost {
+    private readonly previewServerFactory;
+    private readonly logger;
+    private previewServer;
+    constructor(previewServerFactory?: BunStaticPreviewServerFactory, logger?: BunStaticPreviewLogger);
+    start(options: StaticPreviewHostStartOptions): Promise<number | null>;
+    stop(): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,45 @@
+import { StaticContentServer } from "../../dev/sc-server.js";
+import { appLogger } from "../../global/app-logger.js";
+class BunStaticPreviewHost {
+  constructor(previewServerFactory = StaticContentServer, logger = appLogger) {
+    this.previewServerFactory = previewServerFactory;
+    this.logger = logger;
+  }
+  previewServerFactory;
+  logger;
+  previewServer = null;
+  async start(options) {
+    await this.stop();
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      try {
+        this.previewServer = this.previewServerFactory.createServer({
+          appConfig: options.appConfig,
+          options: { port: options.port }
+        });
+        const previewPort = this.previewServer.server?.port;
+        if (previewPort) {
+          return previewPort;
+        }
+        break;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorCode = typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
+        const isPortReleaseRace = errorCode === "EADDRINUSE" || errorMessage.includes("EADDRINUSE");
+        if (!isPortReleaseRace || attempt === 19) {
+          throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+    }
+    this.logger.error("Failed to start preview server");
+    return null;
+  }
+  async stop() {
+    this.previewServer?.stop();
+    this.previewServer = null;
+  }
+}
+export {
+  BunStaticPreviewHost
+};

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

@@ -1,17 +1,23 @@
-import { type Server as NodeServerInstance } from 'node:http';
 import { SharedApplicationAdapter } from '../shared/application-adapter.js';
+import type { RuntimeHost } from '../shared/runtime-host.js';
 import type { EcopagesAppOptions } from '../create-app.js';
 import { type NodeServerAdapterResult, createNodeServerAdapter } from './server-adapter.js';
+import type { NodeServerInstance } from './server-adapter.js';
 export declare class NodeEcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, NodeServerInstance, Request> {
     serverAdapter: NodeServerAdapterResult | undefined;
     private server;
     private runtimeOrigin;
+    private readonly runtimeHost;
+    constructor(options: EcopagesAppOptions, dependencies: {
+        runtimeHost: RuntimeHost<NodeServerInstance, {
+            port?: number;
+            hostname?: string;
+        }>;
+    });
     protected createServerAdapter(params: Parameters<typeof createNodeServerAdapter>[0]): Promise<NodeServerAdapterResult>;
     stop(force?: boolean): Promise<void>;
     protected initializeServerAdapter(): Promise<NodeServerAdapterResult>;
     start(): Promise<NodeServerInstance | void>;
-    private createWebRequest;
-    private sendNodeResponse;
     fetch(request: Request): Promise<Response>;
 }
 export declare function createNodeApp(options: EcopagesAppOptions): Promise<NodeEcopagesApp>;

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

@@ -1,13 +1,18 @@
-import { createServer } from "node:http";
-import { Readable } from "node:stream";
-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 } from "../shared/runtime-app-bootstrap.js";
 import { createNodeServerAdapter } from "./server-adapter.js";
+import { NodeHttpRequestBridge } from "./http-request-bridge.js";
+import { NodeRuntimeHost } from "./runtime-host.js";
 class NodeEcopagesApp extends SharedApplicationAdapter {
   serverAdapter;
   server = null;
   runtimeOrigin = "";
+  runtimeHost;
+  constructor(options, dependencies) {
+    super(options);
+    this.runtimeHost = dependencies.runtimeHost;
+  }
   createServerAdapter(params) {
     return createNodeServerAdapter(params);
   }
@@ -17,39 +22,22 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
     }
     const activeServer = this.server;
     this.server = null;
-    await new Promise((resolve, reject) => {
-      activeServer.close((error) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve();
-      });
-      if (force) {
-        activeServer.closeAllConnections();
-      }
-    });
+    await this.runtimeHost.stop(activeServer, { force });
   }
   async initializeServerAdapter() {
-    const { dev } = this.cliArgs;
-    const { port: cliPort, hostname: cliHostname } = this.cliArgs;
-    const envPort = process.env.ECOPAGES_PORT;
-    const envHostname = process.env.ECOPAGES_HOSTNAME;
-    const preferredPort = cliPort ?? (envPort ? Number(envPort) : void 0) ?? DEFAULT_ECOPAGES_PORT;
-    const preferredHostname = cliHostname ?? envHostname ?? DEFAULT_ECOPAGES_HOSTNAME;
-    this.runtimeOrigin = `http://${preferredHostname}:${preferredPort}`;
+    const binding = resolveRuntimeBinding({
+      cliArgs: this.cliArgs,
+      serverOptions: this.serverOptions
+    });
+    this.runtimeOrigin = binding.runtimeOrigin;
     return this.createServerAdapter({
       runtimeOrigin: this.runtimeOrigin,
       appConfig: this.appConfig,
       apiHandlers: this.apiHandlers,
       staticRoutes: this.staticRoutes,
       errorHandler: this.errorHandler,
-      options: { watch: dev },
-      serveOptions: {
-        port: preferredPort,
-        hostname: preferredHostname,
-        ...this.serverOptions
-      }
+      options: { watch: binding.watch },
+      serveOptions: binding.serveOptions
     });
   }
   async start() {
@@ -71,64 +59,17 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
       return;
     }
     const serveOptions = this.serverAdapter.getServerOptions();
-    const hostname = String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME);
-    const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
-    this.runtimeOrigin = `http://${hostname}:${port}`;
-    this.server = createServer(async (req, res) => {
-      try {
-        const webRequest = this.createWebRequest(req);
-        const response = await this.serverAdapter.handleRequest(webRequest);
-        await this.sendNodeResponse(res, response);
-      } catch (error) {
-        appLogger.error("Node server adapter request failed", error);
-        res.statusCode = 500;
-        res.end("Internal Server Error");
+    this.server = await this.runtimeHost.start({
+      serveOptions,
+      handleRequest: async (request) => await this.serverAdapter.handleRequest(request),
+      onError: async () => {
       }
     });
-    await new Promise((resolve) => {
-      this.server.listen(port, hostname, () => resolve());
-    });
+    this.runtimeOrigin = this.runtimeHost.getOrigin(this.server, serveOptions);
     await this.serverAdapter.completeInitialization(this.server);
     appLogger.info(`Node server running at ${this.runtimeOrigin}`);
     return this.server;
   }
-  createWebRequest(req) {
-    const url = new URL(req.url ?? "/", this.runtimeOrigin);
-    const headers = new Headers();
-    for (const [key, value] of Object.entries(req.headers)) {
-      if (Array.isArray(value)) {
-        for (const item of value) {
-          headers.append(key, item);
-        }
-        continue;
-      }
-      if (value !== void 0) {
-        headers.set(key, value);
-      }
-    }
-    const method = (req.method ?? "GET").toUpperCase();
-    const requestInit = {
-      method,
-      headers
-    };
-    if (method !== "GET" && method !== "HEAD") {
-      requestInit.body = Readable.toWeb(req);
-      requestInit.duplex = "half";
-    }
-    return new Request(url, requestInit);
-  }
-  async sendNodeResponse(res, response) {
-    res.statusCode = response.status;
-    response.headers.forEach((value, key) => {
-      res.setHeader(key, value);
-    });
-    if (!response.body) {
-      res.end();
-      return;
-    }
-    const body = Buffer.from(await response.arrayBuffer());
-    res.end(body);
-  }
   async fetch(request) {
     if (!this.serverAdapter) {
       this.serverAdapter = await this.initializeServerAdapter();
@@ -137,7 +78,9 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
   }
 }
 async function createNodeApp(options) {
-  return new NodeEcopagesApp(options);
+  return new NodeEcopagesApp(options, {
+    runtimeHost: new NodeRuntimeHost(new NodeHttpRequestBridge())
+  });
 }
 async function createApp(options) {
   return createNodeApp(options);

package/src/adapters/node/http-request-bridge.d.ts

@@ -0,0 +1,57 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * Signals that the remote client closed the HTTP exchange before the Node
+ * adapter finished reading or writing the body.
+ *
+ * @remarks
+ * This error represents a transport-level disconnect, not an application
+ * failure. Higher layers may safely suppress logging for this error when the
+ * client socket is already gone and no meaningful response can still be sent.
+ */
+export declare class NodeClientAbortError extends Error {
+    /**
+     * Creates the canonical Node transport abort error used across request-body
+     * reads and response-body writes.
+     */
+    constructor();
+}
+/**
+ * Type guard for the canonical client-abort error used by the Node adapter.
+ *
+ * @remarks
+ * Runtime hosts use this guard before logging so only explicitly classified
+ * client disconnects are muted. All other failures continue through the normal
+ * error-reporting path.
+ */
+export declare function isNodeClientAbortError(error: unknown): error is NodeClientAbortError;
+/**
+ * Bridges Node's `IncomingMessage` / `ServerResponse` pair to the Web
+ * `Request` / `Response` contract used by the shared routing pipeline.
+ *
+ * @remarks
+ * This class is the Node transport boundary. It owns the translation of request
+ * headers and bodies into Web primitives and the reverse translation of Web
+ * responses back onto Node streams, including client-abort normalization.
+ */
+export declare class NodeHttpRequestBridge {
+    /**
+     * Converts one incoming Node request into the Web `Request` shape consumed by
+     * the shared server adapter.
+     *
+     * @remarks
+     * Non-GET/HEAD requests retain streaming semantics via a `ReadableStream` so
+     * large request bodies do not need to be buffered before route handling begins.
+     */
+    createWebRequest(req: IncomingMessage, runtimeOrigin: string): Request;
+    /**
+     * Sends a Web `Response` through Node's `ServerResponse` without buffering the
+     * full body in memory first.
+     *
+     * @remarks
+     * Streaming responses matter for large payloads and long-lived transports such
+     * as server-sent events. The bridge therefore forwards the `ReadableStream`
+     * directly into the Node writable response instead of materializing an
+     * intermediate `ArrayBuffer`.
+     */
+    sendNodeResponse(res: ServerResponse, response: Response): Promise<void>;
+}