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

package/src/adapters/shared/hmr-entrypoint-registrar.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { appLogger } from "../../global/app-logger.js";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+class HmrEntrypointRegistrar {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
+   *
+   * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
+   * integration only builds once per registration cycle.
+   */
+  async registerEntrypoint(entrypointPath, registrationOptions) {
+    const normalizedEntrypoint = path.resolve(entrypointPath);
+    const existingRegistration = this.options.entrypointRegistrations.get(normalizedEntrypoint);
+    if (existingRegistration) {
+      return await this.awaitEntrypointRegistration(existingRegistration, normalizedEntrypoint);
+    }
+    const registration = this.registerEntrypointInternal(normalizedEntrypoint, registrationOptions);
+    this.options.entrypointRegistrations.set(normalizedEntrypoint, registration);
+    try {
+      return await this.awaitEntrypointRegistration(registration, normalizedEntrypoint);
+    } catch (error) {
+      this.options.clearFailedRegistration?.(normalizedEntrypoint);
+      throw error;
+    } finally {
+      this.options.entrypointRegistrations.delete(normalizedEntrypoint);
+    }
+  }
+  async registerEntrypointInternal(entrypointPath, registrationOptions) {
+    if (this.options.watchedFiles.has(entrypointPath)) {
+      return this.options.watchedFiles.get(entrypointPath);
+    }
+    const { outputPath, outputUrl } = this.getEntrypointOutput(entrypointPath);
+    this.options.watchedFiles.set(entrypointPath, outputUrl);
+    this.removeStaleEntrypointOutput(outputPath);
+    await registrationOptions.emit(entrypointPath, outputPath);
+    if (!fileSystem.exists(outputPath)) {
+      throw registrationOptions.getMissingOutputError(entrypointPath, outputPath);
+    }
+    return outputUrl;
+  }
+  async awaitEntrypointRegistration(registration, entrypointPath) {
+    if (process.env.NODE_ENV !== "development") {
+      return await registration;
+    }
+    return await Promise.race([
+      registration,
+      new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`[HMR] Timed out registering entrypoint: ${entrypointPath}`));
+        }, this.options.registrationTimeoutMs);
+      })
+    ]);
+  }
+  getEntrypointOutput(entrypointPath) {
+    const relativePath = path.relative(this.options.srcDir, entrypointPath);
+    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
+    const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
+    const urlPath = encodedPathJs.split(path.sep).join("/");
+    return {
+      outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath)}`,
+      outputPath: path.join(this.options.distDir, urlPath)
+    };
+  }
+  removeStaleEntrypointOutput(outputPath) {
+    if (!fileSystem.exists(outputPath)) {
+      return;
+    }
+    try {
+      fileSystem.remove(outputPath);
+    } catch (error) {
+      appLogger.warn(
+        `[HMR] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  encodeDynamicSegments(filepath) {
+    return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
+  }
+}
+export {
+  HmrEntrypointRegistrar
+};

package/src/adapters/shared/hmr-html-response.d.ts

@@ -0,0 +1,22 @@
+import type { IHmrManager } from '../../types/public-types.js';
+/**
+ * Returns whether a response is HTML and therefore eligible for development HMR
+ * runtime injection.
+ */
+export declare function isHtmlResponse(response: Response): boolean;
+/**
+ * Returns whether HTML responses should receive the HMR runtime bootstrap.
+ *
+ * This is shared because filesystem page responses and adapter-level HTML
+ * responses flow through different layers, but both need identical injection
+ * behavior in watch mode.
+ */
+export declare function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>): boolean;
+/**
+ * Injects the development HMR runtime script into an HTML response if it is not
+ * already present.
+ *
+ * The check is intentionally idempotent because an HTML response can pass
+ * through more than one development-layer wrapper before reaching the client.
+ */
+export declare function injectHmrRuntimeIntoHtmlResponse(response: Response): Promise<Response>;

package/src/adapters/shared/hmr-html-response.js

@@ -0,0 +1,32 @@
+const HMR_RUNTIME_IMPORT = "import '/_hmr_runtime.js'";
+const HMR_RUNTIME_SCRIPT = `<script type="module">${HMR_RUNTIME_IMPORT};<\/script>`;
+function isHtmlResponse(response) {
+  const contentType = response.headers.get("Content-Type");
+  return contentType !== null && contentType.startsWith("text/html");
+}
+function shouldInjectHmrHtmlResponse(watch, hmrManager) {
+  return watch && hmrManager?.isEnabled() === true;
+}
+async function injectHmrRuntimeIntoHtmlResponse(response) {
+  const html = await response.text();
+  if (html.includes(HMR_RUNTIME_IMPORT)) {
+    return new Response(html, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+  }
+  const updatedHtml = html.replace(/<\/html>/i, `${HMR_RUNTIME_SCRIPT}</html>`);
+  const headers = new Headers(response.headers);
+  headers.delete("Content-Length");
+  return new Response(updatedHtml, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+export {
+  injectHmrRuntimeIntoHtmlResponse,
+  isHtmlResponse,
+  shouldInjectHmrHtmlResponse
+};

package/src/adapters/shared/render-context.d.ts

@@ -1,7 +1,8 @@
-import type { RenderContext } from '../../public-types.js';
+import type { RenderContext } from '../../types/public-types.js';
 import type { IntegrationPlugin } from '../../plugins/integration-plugin.js';
 export interface CreateRenderContextOptions {
     integrations: IntegrationPlugin[];
+    rendererModules?: unknown;
 }
 /**
  * Creates a render context for route handlers.

package/src/adapters/shared/render-context.js

@@ -15,12 +15,14 @@ function createRenderContext(options) {
     );
     const integration = integrations.find((i) => i.name === integrationName);
     invariant(!!integration, `No integration found for: ${integrationName}`);
-    return integration.initializeRenderer();
+    return integration.initializeRenderer({
+      rendererModules: options.rendererModules
+    });
   };
-  return {
+  const renderContext = {
     async render(view, props, renderOptions) {
       const locals = this?.locals;
-      const mergedProps = mergePropsWithLocals(props, locals);
+      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
       const renderer = getRendererForView(view);
       const ctx = {
         partial: false,
@@ -63,6 +65,7 @@ function createRenderContext(options) {
       });
     }
   };
+  return renderContext;
 }
 export {
   createRenderContext

package/src/adapters/shared/runtime-bootstrap.d.ts

@@ -0,0 +1,38 @@
+import { type BuildExecutor } from '../../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoPagesAppConfig, IClientBridge, IHmrManager } from '../../types/internal-types.js';
+/**
+ * Installs and returns the app-owned runtime build executor used by adapter
+ * startup and follow-up runtime work.
+ */
+export declare function installSharedRuntimeBuildExecutor(appConfig: EcoPagesAppConfig, options: {
+    development: boolean;
+}): BuildExecutor;
+/**
+ * Copies app public assets into dist and ensures the resolved assets directory
+ * exists before request handling begins.
+ */
+export declare function prepareSharedRuntimePublicDir(appConfig: EcoPagesAppConfig): void;
+/**
+ * Runs runtime plugin setup against app-owned config/runtime state and optional
+ * host plugin registration hooks.
+ */
+export declare function initializeSharedRuntimePlugins(options: {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    hmrManager?: IHmrManager;
+    onRuntimePlugin?: (plugin: unknown) => void;
+}): Promise<void>;
+/**
+ * Starts shared project watching for runtime adapters.
+ */
+export declare function startSharedProjectWatching(options: {
+    appConfig: EcoPagesAppConfig;
+    refreshRouterRoutesCallback: () => Promise<void>;
+    hmrManager: IHmrManager;
+    bridge: IClientBridge;
+}): Promise<void>;
+/**
+ * Binds a runtime HMR manager to app-owned plugin and integration state.
+ */
+export declare function bindSharedRuntimeHmrManager(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): EcoBuildPlugin[];

package/src/adapters/shared/runtime-bootstrap.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+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 { ProjectWatcher } from "../../watchers/project-watcher.js";
+function installSharedRuntimeBuildExecutor(appConfig, options) {
+  return installAppRuntimeBuildExecutor(appConfig, options);
+}
+function prepareSharedRuntimePublicDir(appConfig) {
+  const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
+  if (fileSystem.exists(srcPublicDir)) {
+    fileSystem.copyDir(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
+  }
+  fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+}
+async function initializeSharedRuntimePlugins(options) {
+  await setupAppRuntimePlugins(options);
+}
+async function startSharedProjectWatching(options) {
+  const watcher = new ProjectWatcher({
+    config: options.appConfig,
+    refreshRouterRoutesCallback: options.refreshRouterRoutesCallback,
+    hmrManager: options.hmrManager,
+    bridge: options.bridge
+  });
+  await watcher.createWatcherSubscription();
+}
+function bindSharedRuntimeHmrManager(appConfig, hmrManager) {
+  const browserBuildPlugins = getAppBrowserBuildPlugins(appConfig);
+  hmrManager.setPlugins(browserBuildPlugins);
+  for (const integration of appConfig.integrations) {
+    integration.setHmrManager(hmrManager);
+  }
+  return browserBuildPlugins;
+}
+export {
+  bindSharedRuntimeHmrManager,
+  initializeSharedRuntimePlugins,
+  installSharedRuntimeBuildExecutor,
+  prepareSharedRuntimePublicDir,
+  startSharedProjectWatching
+};

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

@@ -1,13 +1,13 @@
 import { AbstractServerAdapter } from '../abstract/server-adapter.js';
 import type { ServerAdapterOptions, ServerAdapterResult } from '../abstract/server-adapter.js';
 import { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
-import { FSRouter } from '../../router/fs-router.js';
-import { SchemaValidationService } from '../../services/schema-validation-service.js';
+import { FSRouter } from '../../router/server/fs-router.js';
+import { SchemaValidationService } from '../../services/validation/schema-validation-service.js';
 import { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.js';
 import { ServerStaticBuilder } from './server-static-builder.js';
 import { FileSystemResponseMatcher } from './fs-server-response-matcher.js';
 import { ServerRouteHandler } from './server-route-handler.js';
-import type { ApiHandler, CacheInvalidator, ErrorHandler, RenderContext, StaticRoute } from '../../public-types.js';
+import type { ApiHandler, CacheInvalidator, ErrorHandler, RenderContext, StaticRoute } from '../../types/public-types.js';
 export declare abstract class SharedServerAdapter<TOptions extends ServerAdapterOptions, TResult extends ServerAdapterResult> extends AbstractServerAdapter<TOptions, TResult> {
     protected router: FSRouter;
     protected fileSystemResponseMatcher: FileSystemResponseMatcher;
@@ -16,6 +16,16 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
     protected staticSiteGenerator: StaticSiteGenerator;
     protected staticBuilder: ServerStaticBuilder;
     protected readonly schemaValidator: SchemaValidationService;
+    protected initializeSharedRouteHandling(options: {
+        staticRoutes: StaticRoute[];
+        hmrManager?: any;
+    }): Promise<void>;
+    protected createSharedWatchRefreshCallback(options: {
+        staticRoutes: StaticRoute[];
+        hmrManager?: any;
+        onRoutesReady?: () => Promise<void> | void;
+        onError?: (error: Error) => Promise<void> | void;
+    }): () => Promise<void>;
     /**
      * Scans the filesystem and dynamically constructs the universal router map.
      *

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

@@ -1,11 +1,11 @@
 import path from "node:path";
 import { AbstractServerAdapter } from "../abstract/server-adapter.js";
 import { RouteRendererFactory } from "../../route-renderer/route-renderer.js";
-import { FSRouter } from "../../router/fs-router.js";
-import { FSRouterScanner } from "../../router/fs-router-scanner.js";
+import { FSRouter } from "../../router/server/fs-router.js";
+import { FSRouterScanner } from "../../router/server/fs-router-scanner.js";
 import { MemoryCacheStore } from "../../services/cache/memory-cache-store.js";
 import { PageCacheService } from "../../services/cache/page-cache-service.js";
-import { SchemaValidationService } from "../../services/schema-validation-service.js";
+import { SchemaValidationService } from "../../services/validation/schema-validation-service.js";
 import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator.js";
 import { ServerStaticBuilder } from "./server-static-builder.js";
 import { ExplicitStaticRouteMatcher } from "./explicit-static-route-matcher.js";
@@ -17,6 +17,7 @@ import { createRequire } from "../../utils/locals-utils.js";
 import { HttpError } from "../../errors/http-error.js";
 import { ApiResponseBuilder } from "./api-response.js";
 import { appLogger } from "../../global/app-logger.js";
+import { fileSystem } from "@ecopages/file-system";
 class SharedServerAdapter extends AbstractServerAdapter {
   router;
   fileSystemResponseMatcher;
@@ -25,6 +26,29 @@ class SharedServerAdapter extends AbstractServerAdapter {
   staticSiteGenerator;
   staticBuilder;
   schemaValidator = new SchemaValidationService();
+  async initializeSharedRouteHandling(options) {
+    await this.initSharedRouter();
+    this.configureSharedResponseHandlers(options.staticRoutes, options.hmrManager);
+  }
+  createSharedWatchRefreshCallback(options) {
+    return async () => {
+      try {
+        await this.initializeSharedRouteHandling({
+          staticRoutes: options.staticRoutes,
+          hmrManager: options.hmrManager
+        });
+        if (options.onRoutesReady) {
+          await options.onRoutesReady();
+        }
+      } catch (error) {
+        if (options.onError) {
+          await options.onError(error instanceof Error ? error : new Error(String(error)));
+          return;
+        }
+        throw error;
+      }
+    };
+  }
   /**
    * Scans the filesystem and dynamically constructs the universal router map.
    *
@@ -67,6 +91,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
   configureSharedResponseHandlers(staticRoutes, hmrManager) {
     this.routeRendererFactory = new RouteRendererFactory({
       appConfig: this.appConfig,
+      rendererModules: this.appConfig.runtime?.rendererModuleContext,
       runtimeOrigin: this.runtimeOrigin
     });
     const fileSystemResponseFactory = new FileSystemServerResponseFactory({
@@ -84,6 +109,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
       cacheService = new PageCacheService({ store, enabled: true });
     }
     this.fileSystemResponseMatcher = new FileSystemResponseMatcher({
+      appConfig: this.appConfig,
       router: this.router,
       routeRendererFactory: this.routeRendererFactory,
       fileSystemResponseFactory,
@@ -107,7 +133,10 @@ class SharedServerAdapter extends AbstractServerAdapter {
     return this.fileSystemResponseMatcher?.getCacheService() ?? null;
   }
   getRenderContext() {
-    return createRenderContext({ integrations: this.appConfig.integrations });
+    return createRenderContext({
+      integrations: this.appConfig.integrations,
+      rendererModules: this.appConfig.runtime?.rendererModuleContext
+    });
   }
   /**
    * Executes an Application Programming Interface (API) handler in an environment-agnostic manner.
@@ -328,13 +357,21 @@ class SharedServerAdapter extends AbstractServerAdapter {
     const url = new URL(request.url);
     if (url.pathname === "/_hmr_runtime.js" && context.hmrManager) {
       const runtimePath = context.hmrManager.getRuntimePath();
-      const fileSystem = (await import("@ecopages/file-system")).fileSystem;
       if (fileSystem.exists(runtimePath)) {
         return new Response(fileSystem.readFileAsBuffer(runtimePath), {
           headers: { "Content-Type": "application/javascript" }
         });
       }
     }
+    if (url.pathname.startsWith("/assets/_hmr/") && context.hmrManager) {
+      const relativePath = url.pathname.slice("/assets/_hmr/".length);
+      const assetPath = path.join(context.hmrManager.getDistDir(), relativePath);
+      if (fileSystem.exists(assetPath)) {
+        return new Response(fileSystem.readFileAsBuffer(assetPath), {
+          headers: { "Content-Type": "application/javascript" }
+        });
+      }
+    }
     const apiMatch = this.matchApiHandler(request, context.apiHandlers);
     if (apiMatch) {
       return this.executeApiHandler(

package/src/adapters/shared/server-route-handler.d.ts

@@ -1,7 +1,7 @@
-import type { IHmrManager } from '../../public-types';
-import type { FSRouter } from '../../router/fs-router';
-import type { ExplicitStaticRouteMatcher } from './explicit-static-route-matcher';
-import type { FileSystemResponseMatcher } from './fs-server-response-matcher';
+import type { IHmrManager } from '../../types/public-types.js';
+import type { FSRouter } from '../../router/server/fs-router.js';
+import type { ExplicitStaticRouteMatcher } from './explicit-static-route-matcher.js';
+import type { FileSystemResponseMatcher } from './fs-server-response-matcher.js';
 /**
  * Configuration parameters for ServerRouteHandler.
  */

package/src/adapters/shared/server-route-handler.js

@@ -1,5 +1,6 @@
-import { appLogger } from "../../global/app-logger";
-import { HttpError } from "../../errors/http-error";
+import { appLogger } from "../../global/app-logger.js";
+import { HttpError } from "../../errors/http-error.js";
+import { injectHmrRuntimeIntoHtmlResponse, isHtmlResponse, shouldInjectHmrHtmlResponse } from "./hmr-html-response.js";
 class ServerRouteHandler {
   router;
   fileSystemResponseMatcher;
@@ -30,7 +31,7 @@ class ServerRouteHandler {
    * @returns true if in watch mode and HMR manager is enabled
    */
   shouldInjectHmrScript() {
-    return this.watch && this.hmrManager?.isEnabled() === true;
+    return shouldInjectHmrHtmlResponse(this.watch, this.hmrManager);
   }
   /**
    * Checks if a response contains HTML content.
@@ -39,8 +40,7 @@ class ServerRouteHandler {
    * @returns true if Content-Type header starts with 'text/html'
    */
   isHtmlResponse(response) {
-    const contentType = response.headers.get("Content-Type");
-    return contentType !== null && contentType.startsWith("text/html");
+    return isHtmlResponse(response);
   }
   /**
    * Handles HTTP requests from the router adapter.
@@ -75,16 +75,7 @@ class ServerRouteHandler {
    */
   async maybeInjectHmrScript(response) {
     if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
-      const html = await response.text();
-      const hmrScript = `<script type="module">import '/_hmr_runtime.js';<\/script>`;
-      const updatedHtml = html.replace(/<\/html>/i, `${hmrScript}</html>`);
-      const headers = new Headers(response.headers);
-      headers.delete("Content-Length");
-      return new Response(updatedHtml, {
-        status: response.status,
-        statusText: response.statusText,
-        headers
-      });
+      return injectHmrRuntimeIntoHtmlResponse(response);
     }
     return response;
   }

package/src/adapters/shared/server-static-builder.d.ts

@@ -1,8 +1,8 @@
-import type { EcoPagesAppConfig } from '../../internal-types';
-import type { StaticRoute } from '../../public-types';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer';
-import type { FSRouter } from '../../router/fs-router';
-import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ApiHandler, StaticRoute } from '../../types/public-types.js';
+import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+import type { FSRouter } from '../../router/server/fs-router.js';
+import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.js';
 export interface StaticBuildOptions {
     preview?: boolean;
 }
@@ -14,6 +14,32 @@ export interface ServerStaticBuilderParams {
     appConfig: EcoPagesAppConfig;
     staticSiteGenerator: StaticSiteGenerator;
     serveOptions: ServeOptions;
+    apiHandlers?: ApiHandler[];
+    logger?: ServerStaticBuilderLogger;
+    previewServerFactory?: ServerStaticPreviewServerFactory;
+}
+/**
+ * Minimal logger dependency used by the static builder.
+ */
+export interface ServerStaticBuilderLogger {
+    warn(message: string, detail?: string): unknown;
+    info(message: string): unknown;
+    error(message: string): unknown;
+}
+/**
+ * Preview server factory dependency used when static preview mode is enabled.
+ */
+export interface ServerStaticPreviewServerFactory {
+    createServer(args: {
+        appConfig: EcoPagesAppConfig;
+        options: {
+            port: number;
+        };
+    }): {
+        server?: {
+            port?: number;
+        } | null;
+    };
 }
 /**
  * Handles static site generation and previews.
@@ -22,7 +48,13 @@ export declare class ServerStaticBuilder {
     private readonly appConfig;
     private readonly staticSiteGenerator;
     private readonly serveOptions;
-    constructor({ appConfig, staticSiteGenerator, serveOptions }: ServerStaticBuilderParams);
+    private readonly apiHandlers;
+    private readonly logger;
+    private readonly previewServerFactory;
+    constructor({ appConfig, staticSiteGenerator, serveOptions, apiHandlers, logger, previewServerFactory, }: ServerStaticBuilderParams);
+    private warnApiHandlersUnavailableInStaticMode;
+    private prepareExportDirectory;
+    private refreshRuntimeAssets;
     /**
      * Generates a static build of the site for deployment.
      * @param options.preview - If true, starts a preview server after build

package/src/adapters/shared/server-static-builder.js

@@ -1,13 +1,64 @@
-import { StaticContentServer } from "../../dev/sc-server";
-import { appLogger } from "../../global/app-logger";
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+import { StaticContentServer } from "../../dev/sc-server.js";
+import { appLogger } from "../../global/app-logger.js";
 class ServerStaticBuilder {
   appConfig;
   staticSiteGenerator;
   serveOptions;
-  constructor({ appConfig, staticSiteGenerator, serveOptions }) {
+  apiHandlers;
+  logger;
+  previewServerFactory;
+  constructor({
+    appConfig,
+    staticSiteGenerator,
+    serveOptions,
+    apiHandlers,
+    logger,
+    previewServerFactory
+  }) {
     this.appConfig = appConfig;
     this.staticSiteGenerator = staticSiteGenerator;
     this.serveOptions = serveOptions;
+    this.apiHandlers = apiHandlers ?? [];
+    this.logger = logger ?? appLogger;
+    this.previewServerFactory = previewServerFactory ?? StaticContentServer;
+  }
+  warnApiHandlersUnavailableInStaticMode() {
+    if (this.apiHandlers.length === 0) {
+      return;
+    }
+    const uniqueHandlers = Array.from(
+      new Set(this.apiHandlers.map((handler) => `${handler.method} ${handler.path}`))
+    );
+    const visibleHandlers = uniqueHandlers.slice(0, 5).join(", ");
+    const remainingCount = uniqueHandlers.length - Math.min(uniqueHandlers.length, 5);
+    const summary = remainingCount > 0 ? `${visibleHandlers}, +${remainingCount} more` : visibleHandlers;
+    this.logger.warn(
+      "Registered API endpoints are not available in static build or preview modes because no server runtime is started. They are excluded from the generated output.\n",
+      `\u27A4 ${summary}`
+    );
+  }
+  prepareExportDirectory() {
+    const exportDir = this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
+    fileSystem.ensureDir(exportDir, true);
+    const srcPublicDir = path.join(
+      this.appConfig.rootDir,
+      this.appConfig.srcDir ?? "src",
+      this.appConfig.publicDir ?? "public"
+    );
+    if (fileSystem.exists(srcPublicDir)) {
+      fileSystem.copyDir(srcPublicDir, exportDir);
+    }
+  }
+  async refreshRuntimeAssets() {
+    for (const processor of this.appConfig.processors.values()) {
+      await processor.setup();
+    }
+    for (const integration of this.appConfig.integrations) {
+      await integration.setup();
+    }
   }
   /**
    * Generates a static build of the site for deployment.
@@ -18,7 +69,10 @@ class ServerStaticBuilder {
    */
   async build(options, dependencies) {
     const { preview = false } = options ?? {};
-    const baseUrl = `http://${this.serveOptions.hostname || "localhost"}:${this.serveOptions.port || 3e3}`;
+    const baseUrl = `http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
+    this.warnApiHandlersUnavailableInStaticMode();
+    this.prepareExportDirectory();
+    await this.refreshRuntimeAssets();
     await this.staticSiteGenerator.run({
       router: dependencies.router,
       baseUrl,
@@ -26,18 +80,18 @@ class ServerStaticBuilder {
       staticRoutes: dependencies.staticRoutes
     });
     if (!preview) {
-      appLogger.info("Build completed");
+      this.logger.info("Build completed");
       return;
     }
-    const previewPort = this.serveOptions.port || 3e3;
-    const { server } = StaticContentServer.createServer({
+    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
+    const { server } = this.previewServerFactory.createServer({
       appConfig: this.appConfig,
       options: { port: Number(previewPort) }
     });
-    if (server) {
-      appLogger.info(`Preview running at http://localhost:${server.port}`);
+    if (server?.port) {
+      this.logger.info(`Preview running at http://localhost:${server.port}`);
     } else {
-      appLogger.error("Failed to start preview server");
+      this.logger.error("Failed to start preview server");
     }
   }
 }