@ecopages/core 0.2.0-beta.13 → 0.2.0-beta.15

package/README.md

@@ -227,7 +227,7 @@ import { defineApiHandler, defineGroupHandler, eco } from '@ecopages/core';
 ```
 
 > [!NOTE]
-> `createApp` is the recommended entrypoint over `EcopagesApp`.
+> Use `createApp()` from `@ecopages/core/create-app` as the application entrypoint.
 
 ### Runtime Escape Hatches
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.13",
+  "version": "0.2.0-beta.15",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.13",
+    "@ecopages/file-system": "0.2.0-beta.15",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",
@@ -62,6 +62,10 @@
       "types": "./src/route-renderer/orchestration/foreign-subtree-execution.service.d.ts",
       "default": "./src/route-renderer/orchestration/foreign-subtree-execution.service.js"
     },
+    "./route-renderer/orchestration/document-shell-render.service": {
+      "types": "./src/route-renderer/orchestration/document-shell-render.service.d.ts",
+      "default": "./src/route-renderer/orchestration/document-shell-render.service.js"
+    },
     "./router/navigation-coordinator": {
       "types": "./src/router/client/navigation-coordinator.d.ts",
       "default": "./src/router/client/navigation-coordinator.js"
@@ -75,6 +79,10 @@
       "types": "./src/eco/eco.d.ts",
       "default": "./src/eco/eco.js"
     },
+    "./eco/page-layout-normalization": {
+      "types": "./src/eco/page-layout-normalization.d.ts",
+      "default": "./src/eco/page-layout-normalization.js"
+    },
     "./declarations": {
       "types": "./src/declarations.d.ts"
     },
@@ -243,6 +251,10 @@
       "types": "./src/route-renderer/orchestration/foreign-subtree-execution.service.d.ts",
       "default": "./src/route-renderer/orchestration/foreign-subtree-execution.service.js"
     },
+    "./route-renderer/orchestration/document-shell-render.service.ts": {
+      "types": "./src/route-renderer/orchestration/document-shell-render.service.d.ts",
+      "default": "./src/route-renderer/orchestration/document-shell-render.service.js"
+    },
     "./router/navigation-coordinator.ts": {
       "types": "./src/router/client/navigation-coordinator.d.ts",
       "default": "./src/router/client/navigation-coordinator.js"
@@ -256,6 +268,10 @@
       "types": "./src/eco/eco.d.ts",
       "default": "./src/eco/eco.js"
     },
+    "./eco/page-layout-normalization.ts": {
+      "types": "./src/eco/page-layout-normalization.d.ts",
+      "default": "./src/eco/page-layout-normalization.js"
+    },
     "./declarations.ts": {
       "types": "./src/declarations.d.ts"
     },

package/src/adapters/abstract/application-adapter.d.ts

@@ -10,6 +10,7 @@ import type { SourceModuleLoader } from '../../services/module-loading/module-lo
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader } from '../../types/public-types.js';
 import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
+import { type EcopagesRuntimeLabel } from '../../dev/runtime-server-started-message.js';
 import { type ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
 /**
  * Runtime bootstrap options layered on top of the app config.
@@ -49,6 +50,18 @@ export interface ApplicationRuntimeOptions {
      */
     hostModuleLoader?: SourceModuleLoader;
 }
+export interface AppStartInfo {
+    origin: string;
+}
+export type OnAppStartCallback = (info: AppStartInfo) => void;
+/** @deprecated Use {@link AppStartInfo}. */
+export type ApplicationListeningInfo = AppStartInfo;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type StartCallback = OnAppStartCallback;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type ListenCallback = OnAppStartCallback;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type ApplicationListeningCallback = OnAppStartCallback;
 /**
  * Configuration options for application adapters
  */
@@ -66,7 +79,10 @@ export interface ApplicationAdapterOptions {
  * Common interface for application adapters
  */
 export interface ApplicationAdapter<T = any> extends AsyncDisposable {
-    start(): Promise<T | void>;
+    /** Boot the server. Pass a callback to run when the runtime is ready (optional). */
+    start(onAppStart?: OnAppStartCallback): Promise<T | void>;
+    /** Invoked by embedded hosts once the app can take traffic. */
+    handleListening(origin: string): void;
     stop(force?: boolean): Promise<void>;
 }
 /**
@@ -94,7 +110,9 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
      * Both Bun and Node adapters read this map to register upgrade routes.
      */
     protected websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
-    constructor(options: TOptions);
+    private onAppStartCallback?;
+    protected readonly runtimeLabel: EcopagesRuntimeLabel;
+    constructor(options: TOptions, runtimeLabel: EcopagesRuntimeLabel);
     private clearDistFolder;
     /**
      * Register a GET route handler.
@@ -244,9 +262,18 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
      */
     protected abstract initializeServerAdapter(): Promise<any>;
     /**
-     * Start the application server
+     * Boot the server. When `onAppStart` is passed, it runs once the runtime can take traffic.
+     * Embedded apps only register the callback — the host (for example Vite) boots the port.
+     */
+    start(onAppStart?: OnAppStartCallback): Promise<TServer | void>;
+    /** Runtime-specific server boot (dev, preview, build). */
+    protected abstract bootServer(): Promise<TServer | void>;
+    protected logServerStarted(origin: string): void;
+    /**
+     * Invoked by embedded hosts (for example Vite) once the app can take traffic.
      */
-    abstract start(): Promise<TServer | void>;
+    handleListening(origin: string): void;
+    protected notifyListening(origin: string): void;
     /**
      * Stops the application server and releases runtime resources.
      *

package/src/adapters/abstract/application-adapter.js

@@ -6,6 +6,9 @@ import {
 import { getHostModuleLoader } from "../../services/module-loading/host-module-loader-registry.js";
 import { invariant } from "../../utils/invariant.js";
 import { fileSystem } from "@ecopages/file-system";
+import {
+  formatRuntimeServerStartedMessage
+} from "../../dev/runtime-server-started-message.js";
 import { parseCliArgs } from "../../utils/parse-cli-args.js";
 class AbstractApplicationAdapter {
   appConfig;
@@ -20,7 +23,10 @@ class AbstractApplicationAdapter {
    * Both Bun and Node adapters read this map to register upgrade routes.
    */
   websocketHandlers = /* @__PURE__ */ new Map();
-  constructor(options) {
+  onAppStartCallback;
+  runtimeLabel;
+  constructor(options, runtimeLabel) {
+    this.runtimeLabel = runtimeLabel;
     this.appConfig = options.appConfig;
     this.serverOptions = options.serverOptions || {};
     this.runtimeOptions = options.runtime ?? {};
@@ -191,6 +197,35 @@ class AbstractApplicationAdapter {
   getErrorHandler() {
     return this.errorHandler;
   }
+  /**
+   * Boot the server. When `onAppStart` is passed, it runs once the runtime can take traffic.
+   * Embedded apps only register the callback — the host (for example Vite) boots the port.
+   */
+  async start(onAppStart) {
+    if (onAppStart) {
+      this.onAppStartCallback = onAppStart;
+    }
+    if (this.runtimeOptions.embedded) {
+      return;
+    }
+    return this.bootServer();
+  }
+  logServerStarted(origin) {
+    appLogger.info(formatRuntimeServerStartedMessage(this.runtimeLabel, origin));
+  }
+  /**
+   * Invoked by embedded hosts (for example Vite) once the app can take traffic.
+   */
+  handleListening(origin) {
+    this.notifyListening(origin);
+  }
+  notifyListening(origin) {
+    const normalizedOrigin = origin.replace(/\/$/, "");
+    if (!this.onAppStartCallback) {
+      this.logServerStarted(normalizedOrigin);
+    }
+    this.onAppStartCallback?.({ origin: normalizedOrigin });
+  }
   /**
    * Stops the application server and releases runtime resources.
    *

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

@@ -32,7 +32,8 @@ export interface ServerAdapterResult {
     buildStatic: (options?: {
         preview?: boolean;
         force?: boolean;
-    }) => Promise<void>;
+    }) => Promise<string | undefined>;
+    servePreviewOnly: () => Promise<string | undefined>;
     dispose(): Promise<void>;
 }
 /**
@@ -60,7 +61,7 @@ export declare abstract class AbstractServerAdapter<TOptions extends ServerAdapt
     abstract buildStatic(options?: {
         preview?: boolean;
         force?: boolean;
-    }): Promise<void>;
+    }): Promise<string | undefined>;
     /**
      * Factory method to create a server adapter with runtime-specific functionality
      */

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

@@ -53,7 +53,7 @@ export declare class BunEcopagesApp<WebSocketData = undefined> extends SharedApp
      * @param options Optional settings
      * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
      */
-    start(): Promise<Server<WebSocketData> | void>;
+    protected bootServer(): Promise<Server<WebSocketData> | void>;
     stop(force?: boolean): Promise<void>;
 }
 /**

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

@@ -10,7 +10,7 @@ class BunEcopagesApp extends SharedApplicationAdapter {
   stopped = false;
   runtimeHost;
   constructor(options, dependencies) {
-    super(options);
+    super(options, "Bun");
     this.runtimeHost = dependencies.runtimeHost;
   }
   async fetch(request) {
@@ -66,7 +66,7 @@ class BunEcopagesApp extends SharedApplicationAdapter {
    * @param options Optional settings
    * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
    */
-  async start() {
+  async bootServer() {
     if (this.stopped) {
       this.serverAdapter = void 0;
       this.stopped = false;
@@ -74,15 +74,25 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     if (!this.serverAdapter) {
       this.serverAdapter = await this.initializeServerAdapter();
     }
-    const { dev, preview, build, force } = this.cliArgs;
+    const { dev, preview, build, force, serveOnly } = this.cliArgs;
     const staticRuntimeMode = resolveStaticRuntimeMode({
       appConfig: this.appConfig,
       cliArgs: this.cliArgs
     });
+    if (preview && serveOnly) {
+      const previewOrigin2 = await this.serverAdapter.servePreviewOnly();
+      if (previewOrigin2) {
+        this.notifyListening(previewOrigin2);
+      }
+      return;
+    }
     if (staticRuntimeMode.canBuildWithoutRuntimeServer) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview, force });
+      const previewOrigin2 = await this.serverAdapter.buildStatic({ preview, force });
       appLogger.debugTimeEnd("Building static pages");
+      if (preview && previewOrigin2) {
+        this.notifyListening(previewOrigin2);
+      }
       if (build) {
         process.exit(0);
       }
@@ -103,12 +113,14 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     if (!this.server) {
       throw new Error("Server failed to start");
     }
-    appLogger.info(
-      `Server running at ${this.runtimeHost.getOrigin(this.server, runtimeServerOptions)}`
+    const runtimeOrigin = this.runtimeHost.getOrigin(
+      this.server,
+      runtimeServerOptions
     );
+    let previewOrigin;
     if (build || preview) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview, force });
+      previewOrigin = await this.serverAdapter.buildStatic({ preview, force });
       const buildRuntimeServer = this.server;
       this.server = null;
       await this.runtimeHost.stop(buildRuntimeServer, { force: true });
@@ -116,6 +128,11 @@ class BunEcopagesApp extends SharedApplicationAdapter {
       if (build) {
         process.exit(0);
       }
+    } else {
+      this.notifyListening(runtimeOrigin);
+    }
+    if (preview && previewOrigin) {
+      this.notifyListening(previewOrigin);
     }
     return this.server ?? void 0;
   }

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

@@ -52,7 +52,8 @@ export interface BunServerAdapterResult extends ServerAdapterResult {
     buildStatic: (options?: {
         preview?: boolean;
         force?: boolean;
-    }) => Promise<void>;
+    }) => Promise<string | undefined>;
+    servePreviewOnly: () => Promise<string | undefined>;
     completeInitialization: (server?: BunServerInstance | null) => Promise<void>;
     handleRequest: (request: Request) => Promise<Response>;
     attachUserWebSocketUpgrades: (server: NodeHttpServer, options?: {
@@ -216,7 +217,13 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
     buildStatic(options?: {
         preview?: boolean;
         force?: boolean;
-    }): Promise<void>;
+    }): Promise<string | undefined>;
+    /**
+     * Serves an existing static export without running SSG. Used by e2e preview
+     * launchers after a shared prewarm build.
+     */
+    servePreviewOnly(): Promise<string | undefined>;
+    private startPreviewServer;
     /**
      * Initializes the server with dynamic routes after server creation.
      * Must be called before handling any requests.

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

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
 import { appLogger } from "../../global/app-logger.js";
 import { HttpError } from "../../errors/http-error.js";
@@ -433,8 +434,30 @@ class BunServerAdapter extends SharedServerAdapter {
       }
     );
     if (!options?.preview) {
-      return;
+      return void 0;
     }
+    return this.startPreviewServer();
+  }
+  /**
+   * Serves an existing static export without running SSG. Used by e2e preview
+   * launchers after a shared prewarm build.
+   */
+  async servePreviewOnly() {
+    if (!this.fullyInitialized) {
+      await this.initializeSharedRouteHandling({
+        staticRoutes: this.staticRoutes,
+        hmrManager: this.hmrManager
+      });
+    }
+    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 previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
     const previewPort = Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT);
     const activePreviewPort = await this.previewHost.start({
@@ -443,10 +466,10 @@ class BunServerAdapter extends SharedServerAdapter {
       port: previewPort,
       allowPortFallback: this.allowPortFallback
     });
-    if (activePreviewPort) {
-      appLogger.info(`Preview running at http://${previewHostname}:${activePreviewPort}`);
-      return;
+    if (!activePreviewPort) {
+      return void 0;
     }
+    return `http://${previewHostname}:${activePreviewPort}`;
   }
   /**
    * Initializes the server with dynamic routes after server creation.
@@ -497,6 +520,7 @@ class BunServerAdapter extends SharedServerAdapter {
     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),
       attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this),

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

@@ -1,7 +1,7 @@
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
 import { AbstractApplicationAdapter } from './abstract/application-adapter.js';
 import type { ApplicationAdapterOptions } from './abstract/application-adapter.js';
-import { SharedApplicationAdapter } from './shared/application-adapter.js';
+export type { OnAppStartCallback, AppStartInfo, StartCallback, ListenCallback, ApplicationListeningCallback, ApplicationListeningInfo, } from './abstract/application-adapter.js';
 export type EcopagesRuntimeAdapter = 'auto' | 'node' | 'bun';
 export interface EcopagesAppOptions extends ApplicationAdapterOptions {
     appConfig: EcoPagesAppConfig;
@@ -20,14 +20,3 @@ export interface EcopagesAppOptions extends ApplicationAdapterOptions {
 }
 export type UniversalEcopagesApp = AbstractApplicationAdapter<EcopagesAppOptions, unknown, Request>;
 export declare function createApp<WebSocketData = undefined>(options: EcopagesAppOptions): Promise<UniversalEcopagesApp>;
-export declare class EcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, unknown, Request> {
-    private readonly appOptions;
-    private runtimeApp;
-    private runtimeAppPromise;
-    constructor(options: EcopagesAppOptions);
-    private getRuntimeApp;
-    protected initializeServerAdapter(): Promise<UniversalEcopagesApp>;
-    start(): Promise<unknown>;
-    fetch(request: Request): Promise<Response>;
-    stop(force?: boolean): Promise<void>;
-}

package/src/adapters/create-app.js

@@ -1,5 +1,4 @@
 import { AbstractApplicationAdapter } from "./abstract/application-adapter.js";
-import { SharedApplicationAdapter } from "./shared/application-adapter.js";
 import { createApp as createBunApp } from "./bun/create-app.js";
 import { createNodeApp } from "./node/create-app.js";
 async function createRuntimeApp(options) {
@@ -13,63 +12,6 @@ async function createRuntimeApp(options) {
 async function createApp(options) {
   return createRuntimeApp(options);
 }
-class EcopagesApp extends SharedApplicationAdapter {
-  appOptions;
-  runtimeApp = null;
-  runtimeAppPromise = null;
-  constructor(options) {
-    super(options);
-    this.appOptions = options;
-  }
-  async getRuntimeApp() {
-    if (this.runtimeApp) {
-      return this.runtimeApp;
-    }
-    if (!this.runtimeAppPromise) {
-      this.runtimeAppPromise = createRuntimeApp({
-        ...this.appOptions,
-        clearOutput: false
-      }).then((app) => {
-        for (const handler of this.apiHandlers) {
-          app.add(handler);
-        }
-        for (const route of this.staticRoutes) {
-          app.static(route.path, route.loader);
-        }
-        if (this.errorHandler) {
-          app.onError(this.errorHandler);
-        }
-        this.runtimeApp = app;
-        return app;
-      });
-    }
-    return this.runtimeAppPromise;
-  }
-  async initializeServerAdapter() {
-    return this.getRuntimeApp();
-  }
-  async start() {
-    const runtimeApp = await this.getRuntimeApp();
-    return runtimeApp.start();
-  }
-  async fetch(request) {
-    const runtimeApp = await this.getRuntimeApp();
-    const candidate = runtimeApp;
-    if (!candidate.fetch) {
-      throw new Error("The selected runtime adapter does not expose fetch()");
-    }
-    return candidate.fetch(request);
-  }
-  async stop(force = true) {
-    const runtimeApp = this.runtimeApp ?? (this.runtimeAppPromise ? await this.runtimeAppPromise : null);
-    if (runtimeApp) {
-      await runtimeApp.stop(force);
-    }
-    this.runtimeApp = null;
-    this.runtimeAppPromise = null;
-  }
-}
 export {
-  EcopagesApp,
   createApp
 };

package/src/adapters/index.d.ts

@@ -1,2 +1,2 @@
-export { EcopagesApp, createApp } from './create-app.js';
+export { createApp } from './create-app.js';
 export { defineApiHandler, defineGroupHandler, type GroupHandler } from './shared/define-api-handler.js';

package/src/adapters/index.js

@@ -1,7 +1,6 @@
-import { EcopagesApp, createApp } from "./create-app.js";
+import { createApp } from "./create-app.js";
 import { defineApiHandler, defineGroupHandler } from "./shared/define-api-handler.js";
 export {
-  EcopagesApp,
   createApp,
   defineApiHandler,
   defineGroupHandler

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

@@ -18,7 +18,7 @@ export declare class NodeEcopagesApp extends SharedApplicationAdapter<EcopagesAp
     protected createServerAdapter(params: Parameters<typeof createNodeServerAdapter>[0]): Promise<NodeServerAdapterResult>;
     stop(force?: boolean): Promise<void>;
     protected initializeServerAdapter(): Promise<NodeServerAdapterResult>;
-    start(): Promise<NodeServerInstance | void>;
+    protected bootServer(): Promise<NodeServerInstance | void>;
     fetch(request: Request): Promise<Response>;
     attachWebSocketUpgrades(httpServer: import('node:http').Server, options?: {
         passthroughUnmatched?: boolean;

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

@@ -12,7 +12,7 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
   stopped = false;
   runtimeHost;
   constructor(options, dependencies) {
-    super(options);
+    super(options, "Node");
     this.runtimeHost = dependencies.runtimeHost;
   }
   createServerAdapter(params) {
@@ -55,7 +55,7 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
       allowPortFallback: binding.allowPortFallback
     });
   }
-  async start() {
+  async bootServer() {
     if (this.stopped) {
       this.serverAdapter = void 0;
       this.stopped = false;
@@ -66,11 +66,21 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
     if (this.server) {
       return this.server;
     }
-    const { build, preview, force } = this.cliArgs;
+    const { build, preview, force, serveOnly } = this.cliArgs;
+    if (preview && serveOnly) {
+      const previewOrigin = await this.serverAdapter.servePreviewOnly();
+      if (previewOrigin) {
+        this.notifyListening(previewOrigin);
+      }
+      return;
+    }
     if (build || preview) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview, force });
+      const previewOrigin = await this.serverAdapter.buildStatic({ preview, force });
       appLogger.debugTimeEnd("Building static pages");
+      if (preview && previewOrigin) {
+        this.notifyListening(previewOrigin);
+      }
       if (build) {
         process.exit(0);
       }
@@ -85,7 +95,7 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
     });
     this.runtimeOrigin = this.runtimeHost.getOrigin(this.server, serveOptions);
     await this.serverAdapter.completeInitialization(this.server);
-    appLogger.info(`Node server running at ${this.runtimeOrigin}`);
+    this.notifyListening(this.runtimeOrigin);
     return this.server;
   }
   async fetch(request) {

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

@@ -126,7 +126,13 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
     buildStatic(options?: {
         preview?: boolean;
         force?: boolean;
-    }): Promise<void>;
+    }): Promise<string | undefined>;
+    /**
+     * Serves an existing static export without running SSG. Used by e2e preview
+     * launchers after a shared prewarm build.
+     */
+    servePreviewOnly(): Promise<string | undefined>;
+    private startPreviewServer;
     createAdapter(): Promise<NodeServerAdapterResult>;
     /**
      * Releases dev-time resources owned by the adapter.

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

@@ -1,4 +1,6 @@
 import {} from "node:http";
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
 import { setupAppRuntimePlugins } from "../../build/build-adapter.js";
 import { installAppRuntimeBuildExecutor } from "../../build/runtime-build-executor.js";
 import { appLogger } from "../../global/app-logger.js";
@@ -155,8 +157,27 @@ class NodeServerAdapter extends SharedServerAdapter {
       }
     );
     if (!options?.preview) {
-      return;
+      return void 0;
+    }
+    return this.startPreviewServer();
+  }
+  /**
+   * Serves an existing static export without running SSG. Used by e2e preview
+   * launchers after a shared prewarm build.
+   */
+  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),
@@ -164,16 +185,17 @@ class NodeServerAdapter extends SharedServerAdapter {
       allowPortFallback: this.allowPortFallback
     });
     if (!activePreviewPort) {
-      return;
+      return void 0;
     }
     const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
-    appLogger.info(`Preview running at http://${previewHostname}:${activePreviewPort}`);
+    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),
       attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this),

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.