@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.50

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

@@ -1,37 +1,58 @@
 import { createServer } from "node:http";
 import path from "node:path";
+import { WebSocketServer } from "ws";
 import { fileSystem } from "@ecopages/file-system";
-import { RESOLVED_ASSETS_DIR } from "../../constants.js";
-import { defaultBuildAdapter } from "../../build/build-adapter.js";
+import { getAppBrowserBuildPlugins, 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 { ProjectWatcher } from "../../watchers/project-watcher.js";
 import { NodeClientBridge } from "./node-client-bridge.js";
 import { NodeHmrManager } from "./node-hmr-manager.js";
+import { ProjectWatcher } from "../../watchers/project-watcher.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 { NodeStaticContentServer } from "./static-content-server.js";
-class ClientAbortError extends Error {
-  constructor() {
-    super("Client closed the request");
-    this.name = "ClientAbortError";
-  }
-}
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+import {
+  injectHmrRuntimeIntoHtmlResponse,
+  isHtmlResponse,
+  shouldInjectHmrHtmlResponse
+} from "../shared/hmr-html-response.js";
+import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
+import { NodeClientAbortError, NodeHttpRequestBridge } from "./http-request-bridge.js";
+import { NodeStaticPreviewHost } from "./static-preview-host.js";
+import { DefaultNodeServerDevRuntimeFactory } from "./server-adapter-dependencies.js";
 class NodeServerAdapter extends SharedServerAdapter {
   serverInstance = null;
   initialized = false;
   apiHandlers;
   staticRoutes;
   errorHandler;
-  previewServer = null;
   bridge = null;
   hmrManager = null;
-  processorBuildPlugins = [];
+  previewHost;
+  requestBridge;
+  devRuntimeFactory;
+  shouldInjectHmrScript() {
+    return shouldInjectHmrHtmlResponse(this.options?.watch === true, this.hmrManager ?? void 0);
+  }
+  isHtmlResponse(response) {
+    return isHtmlResponse(response);
+  }
+  async maybeInjectHmrScript(response) {
+    if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
+      return injectHmrRuntimeIntoHtmlResponse(response);
+    }
+    return response;
+  }
   constructor(options) {
     super(options);
     this.apiHandlers = options.apiHandlers || [];
     this.staticRoutes = options.staticRoutes || [];
     this.errorHandler = options.errorHandler;
+    this.previewHost = options.previewHost;
+    this.requestBridge = options.requestBridge;
+    this.devRuntimeFactory = options.devRuntimeFactory;
   }
   /**
    * Prepares the adapter for use.
@@ -47,85 +68,35 @@ class NodeServerAdapter extends SharedServerAdapter {
    *    processors during their `setup()` calls.
    */
   async initialize() {
-    this.setupLoaders();
-    this.copyPublicDir();
-    await this.initializePlugins();
-    await this.initSharedRouter();
-    this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager ?? void 0);
+    installAppRuntimeBuildExecutor(this.appConfig, {
+      development: this.options?.watch === true
+    });
+    this.prepareRuntimePublicDir();
+    await setupAppRuntimePlugins({
+      appConfig: this.appConfig,
+      runtimeOrigin: this.runtimeOrigin,
+      hmrManager: this.hmrManager ?? void 0
+    });
+    await this.initializeSharedRouteHandling({
+      staticRoutes: this.staticRoutes,
+      hmrManager: this.hmrManager ?? void 0
+    });
     this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
     this.staticBuilder = new ServerStaticBuilder({
       appConfig: this.appConfig,
       staticSiteGenerator: this.staticSiteGenerator,
-      serveOptions: this.serveOptions
+      serveOptions: this.serveOptions,
+      apiHandlers: this.apiHandlers
     });
     this.initialized = true;
   }
-  /**
-   * Registers every configured file loader as a build plugin on the shared
-   * `defaultBuildAdapter`.
-   *
-   * Loaders are registered on the *shared* adapter (not on a per-build instance)
-   * because they must be available globally to both the SSR build and any dynamic
-   * transpile passes that happen outside of a top-level `build()` call (e.g. HMR
-   * incremental rebuilds).
-   */
-  setupLoaders() {
-    for (const loader of this.appConfig.loaders.values()) {
-      defaultBuildAdapter.registerPlugin(loader);
-    }
-  }
-  copyPublicDir() {
+  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));
   }
-  /**
-   * Sets up all configured processors and integrations in two distinct phases.
-   *
-   * **Phase 1 — Processors:**
-   * Each processor's `setup()` is called first. A processor may expose two
-   * plugin lists:
-   * - `plugins` — transform plugins used during SSR rendering (e.g. PostCSS).
-   * - `buildPlugins` — esbuild plugins used during the client bundle step.
-   * Both are registered on `defaultBuildAdapter` so later build calls pick them up.
-   *
-   * **Phase 2 — Integrations:**
-   * Integrations receive the fully-resolved app config, the runtime origin, and
-   * (if already initialised) the HMR manager before their own `setup()` is called.
-   * This ordering ensures integrations can query config values that processors
-   * may have mutated during phase 1.
-   */
-  async initializePlugins() {
-    const processorBuildPlugins = [];
-    for (const processor of this.appConfig.processors.values()) {
-      await processor.setup();
-      if (processor.plugins) {
-        for (const plugin of processor.plugins) {
-          defaultBuildAdapter.registerPlugin(plugin);
-        }
-      }
-      if (processor.buildPlugins) {
-        processorBuildPlugins.push(...processor.buildPlugins);
-        for (const plugin of processor.buildPlugins) {
-          defaultBuildAdapter.registerPlugin(plugin);
-        }
-      }
-    }
-    for (const integration of this.appConfig.integrations) {
-      integration.setConfig(this.appConfig);
-      integration.setRuntimeOrigin(this.runtimeOrigin);
-      if (this.hmrManager) {
-        integration.setHmrManager(this.hmrManager);
-      }
-      await integration.setup();
-      for (const plugin of integration.plugins) {
-        defaultBuildAdapter.registerPlugin(plugin);
-      }
-    }
-    this.processorBuildPlugins = processorBuildPlugins;
-  }
   getServerOptions() {
     return {
       ...this.serveOptions
@@ -136,9 +107,10 @@ class NodeServerAdapter extends SharedServerAdapter {
       await this.initialize();
     }
     const buildServer = await this.startBuildRuntimeServer();
+    const buildRuntimeOrigin = this.getListeningServerOrigin(buildServer);
     try {
       await this.staticBuilder.build(
-        { preview: false },
+        { preview: false, baseUrl: buildRuntimeOrigin },
         {
           router: this.router,
           routeRendererFactory: this.routeRendererFactory,
@@ -151,117 +123,27 @@ class NodeServerAdapter extends SharedServerAdapter {
     if (!options?.preview) {
       return;
     }
-    if (this.previewServer) {
-      await this.previewServer.stop();
-    }
-    this.previewServer = new NodeStaticContentServer({
+    await this.previewHost.start({
       appConfig: this.appConfig,
-      options: {
-        hostname: this.serveOptions.hostname,
-        port: Number(this.serveOptions.port || 3e3)
-      }
+      hostname: String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME),
+      port: Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT)
     });
-    await this.previewServer.start();
-    const previewHostname = this.serveOptions.hostname || "localhost";
-    const previewPort = this.serveOptions.port || 3e3;
+    const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
+    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
     appLogger.info(`Preview running at http://${previewHostname}:${previewPort}`);
   }
-  /**
-   * Converts a Node.js `IncomingMessage` into a Web API `Request`.
-   *
-   * Multi-value headers (e.g. `set-cookie`) are appended individually so no
-   * value is silently dropped.
-   *
-   * For methods that carry a body (`POST`, `PUT`, `PATCH`, …), the raw
-   * `IncomingMessage` stream is wrapped in a `ReadableStream` rather than
-   * cast directly to `BodyInit`. See the inline doc block inside the `if`
-   * branch for the rationale (client-abort handling).
-   *
-   * `duplex: 'half'` is required by the `fetch` spec when a streaming body is
-   * provided — without it Node.js 18+ throws a `TypeError`.
-   */
-  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") {
-      const body = new ReadableStream({
-        start(controller) {
-          req.on("data", (chunk) => controller.enqueue(chunk));
-          req.once("end", () => controller.close());
-          req.once("aborted", () => {
-            controller.error(new ClientAbortError());
-          });
-          req.once("error", (err) => {
-            const isClientAbort = err.code === "ECONNRESET";
-            controller.error(isClientAbort ? new ClientAbortError() : err);
-          });
-        },
-        cancel() {
-          req.destroy();
-        }
-      });
-      requestInit.body = body;
-      requestInit.duplex = "half";
-    }
-    return new Request(url, requestInit);
-  }
-  /**
-   * Writes a Web `Response` back to a Node.js `ServerResponse`.
-   *
-   * The entire body is buffered via `arrayBuffer()` before writing. This is
-   * intentional for the current use-case (SSR pages and API routes), where
-   * responses are typically small and fully materialised. Streaming responses
-   * are not yet supported.
-   */
-  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);
-  }
-  /**
-   * Starts an ephemeral HTTP server used *only* during a static site generation
-   * run.
-   *
-   * Static generation works by having the `StaticSiteGenerator` issue real HTTP
-   * requests to a live server for each route, capturing the rendered HTML. This
-   * approach reuses the normal request pipeline (middleware, caching, API
-   * handlers) without any special-casing for the build path.
-   *
-   * The server is torn down immediately after generation completes via
-   * `stopBuildRuntimeServer`, so it never overlaps with the actual dev/prod server.
-   */
   async startBuildRuntimeServer() {
-    const hostname = String(this.serveOptions.hostname || "localhost");
-    const port = Number(this.serveOptions.port || 3e3);
+    const hostname = String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME);
+    const port = 0;
     const server = createServer(async (req, res) => {
       try {
-        const webRequest = this.createWebRequest(req);
+        const webRequest = this.requestBridge.createWebRequest(req, this.runtimeOrigin);
         const response = await this.handleRequest(webRequest);
-        await this.sendNodeResponse(res, response);
+        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");
@@ -275,9 +157,17 @@ class NodeServerAdapter extends SharedServerAdapter {
       });
     });
     this.serverInstance = server;
-    appLogger.info(`Server running at http://${hostname}:${port}`);
+    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");
+    }
+    return `http://${hostname}:${address.port}`;
+  }
   /**
    * Gracefully shuts down the ephemeral build runtime server.
    *
@@ -325,19 +215,20 @@ class NodeServerAdapter extends SharedServerAdapter {
    * underlying socket closes early — into a 499 response so it does not
    * incorrectly surface as a 500 in application logs.
    */
-  async handleRequest(_request) {
+  async handleRequest(request) {
     if (!this.initialized) {
       throw new Error("Node server adapter is not initialized. Call createAdapter() first.");
     }
     try {
-      return await this.handleSharedRequest(_request, {
+      const response = await this.handleSharedRequest(request, {
         apiHandlers: this.apiHandlers,
         errorHandler: this.errorHandler,
         serverInstance: this.serverInstance,
         hmrManager: this.hmrManager
       });
+      return await this.maybeInjectHmrScript(response);
     } catch (error) {
-      if (error instanceof ClientAbortError) {
+      if (error instanceof NodeClientAbortError) {
         return new Response(null, { status: 499 });
       }
       throw error;
@@ -353,22 +244,22 @@ class NodeServerAdapter extends SharedServerAdapter {
    *   broadcast + heartbeat cleanup.
    * - `NodeHmrManager` watches the filesystem and triggers incremental esbuild
    *   rebuilds, notifying connected clients via the bridge.
-   * - `ProjectWatcher` listens for route-level file changes and refreshes the
-   *   router and response handlers when pages are added or removed.
+   * - 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
    * immediate socket destroy to prevent unhandled upgrade leaks.
    */
-  async completeInitialization(_server) {
-    this.serverInstance = _server;
+  async completeInitialization(server) {
+    this.serverInstance = server;
     if (this.options?.watch) {
-      const { WebSocketServer } = await import("ws");
-      const wss = new WebSocketServer({ noServer: true });
-      this.bridge = new NodeClientBridge();
-      this.hmrManager = new NodeHmrManager({ appConfig: this.appConfig, bridge: this.bridge });
+      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) => {
+      server.on("upgrade", (req, socket, head) => {
         const url = new URL(req.url ?? "/", this.runtimeOrigin);
         if (url.pathname === "/_hmr") {
           wss.handleUpgrade(req, socket, head, (ws) => {
@@ -380,19 +271,18 @@ class NodeServerAdapter extends SharedServerAdapter {
           socket.destroy();
         }
       });
-      const loaderPlugins = Array.from(this.appConfig.loaders.values());
-      const hmrBuildPlugins = [...loaderPlugins, ...this.processorBuildPlugins];
-      this.hmrManager.setPlugins(hmrBuildPlugins);
+      const browserBuildPlugins = getAppBrowserBuildPlugins(this.appConfig);
+      this.hmrManager.setPlugins(browserBuildPlugins);
       for (const integration of this.appConfig.integrations) {
         integration.setHmrManager(this.hmrManager);
       }
       this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
       const watcher = new ProjectWatcher({
         config: this.appConfig,
-        refreshRouterRoutesCallback: async () => {
-          await this.initSharedRouter();
-          this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
-        },
+        refreshRouterRoutesCallback: this.createSharedWatchRefreshCallback({
+          staticRoutes: this.staticRoutes,
+          hmrManager: this.hmrManager
+        }),
         hmrManager: this.hmrManager,
         bridge: this.bridge
       });
@@ -407,10 +297,16 @@ class NodeServerAdapter extends SharedServerAdapter {
   }
 }
 async function createNodeServerAdapter(params) {
-  const runtimeOrigin = params.runtimeOrigin ?? `http://${params.serveOptions.hostname || "localhost"}:${params.serveOptions.port || 3e3}`;
+  const runtimeOrigin = params.runtimeOrigin ?? resolveServeRuntimeOrigin(params.serveOptions);
+  const previewHost = params.previewHost ?? new NodeStaticPreviewHost();
+  const requestBridge = params.requestBridge ?? new NodeHttpRequestBridge();
+  const devRuntimeFactory = params.devRuntimeFactory ?? new DefaultNodeServerDevRuntimeFactory();
   const adapter = new NodeServerAdapter({
     ...params,
-    runtimeOrigin
+    runtimeOrigin,
+    previewHost,
+    requestBridge,
+    devRuntimeFactory
   });
   return adapter.createAdapter();
 }

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

@@ -1,24 +1,60 @@
 import { type Server as NodeHttpServer } from 'node:http';
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 type NodeStaticContentServerOptions = {
     hostname?: string;
     port?: number;
 };
+/**
+ * Serves prebuilt static Ecopages output through Node's HTTP server.
+ *
+ * @remarks
+ * This server is used by the Node preview/build path once the app has already
+ * emitted its static output. It intentionally stays small: path sanitization,
+ * content-type selection, optional gzip serving, and 404 handling.
+ */
 export declare class NodeStaticContentServer {
     private readonly appConfig;
     private readonly options;
     private server;
+    /**
+     * Creates the Node static-content server for one built app output directory.
+     */
     constructor({ appConfig, options }: {
         appConfig: EcoPagesAppConfig;
         options?: NodeStaticContentServerOptions;
     });
+    /**
+     * Returns whether the given content type should be served from a pre-gzipped
+     * companion file when available.
+     */
     private shouldServeGzip;
+    /**
+     * Normalizes a request pathname and rejects directory traversal attempts.
+     */
     private sanitizePath;
+    /**
+     * Writes one HTTP response with the provided headers and optional body.
+     */
     private sendResponse;
+    /**
+     * Serves the generated 404 page when present, or a plain-text fallback.
+     */
     private sendNotFoundPage;
+    /**
+     * Serves one concrete file path, honoring gzip and HEAD semantics.
+     */
     private serveFile;
+    /**
+     * Handles one incoming Node HTTP request against the built static output tree.
+     */
     private handleRequest;
+    /**
+     * Starts the static preview server.
+     */
     start(): Promise<NodeHttpServer>;
+    /**
+     * Stops the static preview server and optionally closes active connections.
+     */
     stop(force?: boolean): Promise<void>;
 }
 export {};

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

@@ -1,12 +1,15 @@
 import { createServer } from "node:http";
 import { extname, join, normalize, sep } from "node:path";
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, STATUS_MESSAGE } from "../../constants.js";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, STATUS_MESSAGE } from "../../config/constants.js";
 import { fileSystem } from "@ecopages/file-system";
 import { ServerUtils } from "../../utils/server-utils.module.js";
 class NodeStaticContentServer {
   appConfig;
   options;
   server = null;
+  /**
+   * Creates the Node static-content server for one built app output directory.
+   */
   constructor({ appConfig, options }) {
     this.appConfig = appConfig;
     this.options = {
@@ -14,9 +17,16 @@ class NodeStaticContentServer {
       port: options?.port ?? DEFAULT_ECOPAGES_PORT
     };
   }
+  /**
+   * Returns whether the given content type should be served from a pre-gzipped
+   * companion file when available.
+   */
   shouldServeGzip(contentType) {
     return ["text/javascript", "text/css"].includes(contentType);
   }
+  /**
+   * Normalizes a request pathname and rejects directory traversal attempts.
+   */
   sanitizePath(pathname) {
     const withoutLeadingSlash = pathname.replace(/^\/+/, "");
     const normalizedPath = normalize(withoutLeadingSlash);
@@ -25,6 +35,9 @@ class NodeStaticContentServer {
     }
     return normalizedPath;
   }
+  /**
+   * Writes one HTTP response with the provided headers and optional body.
+   */
   sendResponse(res, status, headers, body) {
     res.statusCode = status;
     for (const [key, value] of Object.entries(headers)) {
@@ -36,6 +49,9 @@ class NodeStaticContentServer {
     }
     res.end(body);
   }
+  /**
+   * Serves the generated 404 page when present, or a plain-text fallback.
+   */
   sendNotFoundPage(req, res) {
     const error404TemplatePath = join(this.appConfig.absolutePaths.distDir, "404.html");
     const isHead = (req.method ?? "GET").toUpperCase() === "HEAD";
@@ -51,6 +67,9 @@ class NodeStaticContentServer {
     const file = fileSystem.readFileAsBuffer(error404TemplatePath);
     this.sendResponse(res, 404, { "Content-Type": "text/html" }, isHead ? void 0 : file);
   }
+  /**
+   * Serves one concrete file path, honoring gzip and HEAD semantics.
+   */
   serveFile(req, res, filePath, status = 200) {
     const contentType = ServerUtils.getContentType(extname(filePath));
     const acceptsGzip = req.headers["accept-encoding"]?.includes("gzip");
@@ -79,6 +98,9 @@ class NodeStaticContentServer {
     const file = fileSystem.readFileAsBuffer(filePath);
     this.sendResponse(res, status, { "Content-Type": contentType }, isHead ? void 0 : file);
   }
+  /**
+   * Handles one incoming Node HTTP request against the built static output tree.
+   */
   handleRequest(req, res) {
     const method = (req.method ?? "GET").toUpperCase();
     const isHead = method === "HEAD";
@@ -129,6 +151,9 @@ class NodeStaticContentServer {
     }
     this.sendNotFoundPage(req, res);
   }
+  /**
+   * Starts the static preview server.
+   */
   async start() {
     if (this.server) {
       return this.server;
@@ -141,6 +166,9 @@ class NodeStaticContentServer {
     });
     return this.server;
   }
+  /**
+   * Stops the static preview server and optionally closes active connections.
+   */
   async stop(force = true) {
     if (!this.server) {
       return;

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

@@ -0,0 +1,55 @@
+import type { AddressInfo } from 'node:net';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { StaticPreviewHost, StaticPreviewHostStartOptions } from '../shared/static-preview-host.js';
+type NodeStaticPreviewServer = {
+    start(): Promise<{
+        address(): AddressInfo | string | null;
+    }>;
+    stop(force?: boolean): Promise<void>;
+};
+type NodeStaticPreviewServerFactory = new (args: {
+    appConfig: EcoPagesAppConfig;
+    options?: {
+        hostname?: string;
+        port?: number;
+    };
+}) => NodeStaticPreviewServer;
+/**
+ * Node preview-host wrapper that manages the lifecycle of the static preview
+ * server used after a build.
+ *
+ * @remarks
+ * The host separates preview-server construction from lifecycle control so the
+ * Node server adapter can restart preview serving safely across repeated build
+ * and preview flows.
+ */
+export declare class NodeStaticPreviewHost implements StaticPreviewHost {
+    private readonly previewServerFactory;
+    private previewServer;
+    private stopPromise;
+    /**
+     * Creates the preview host with an injectable preview-server constructor.
+     */
+    constructor(previewServerFactory?: NodeStaticPreviewServerFactory);
+    /**
+     * Starts the Node preview host after fully draining any previous preview server
+     * shutdown that may still be in flight.
+     *
+     * @remarks
+     * The host only publishes a new preview server after `start()` succeeds. That
+     * keeps failed startup attempts from replacing the last known-good server with a
+     * half-initialized instance.
+     */
+    start(options: StaticPreviewHostStartOptions): Promise<number | null>;
+    /**
+     * Stops the active preview server and coalesces overlapping stop requests onto
+     * the same shutdown promise.
+     *
+     * @remarks
+     * The host keeps the server reference until shutdown succeeds. If shutdown
+     * fails, callers can still retry `stop()` or inspect the same live instance
+     * instead of losing the handle during a rejected async stop.
+     */
+    stop(force?: boolean): Promise<void>;
+}
+export {};