@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.31

package/src/adapters/shared/{fs-server-response-matcher.js → http/fs-server-response-matcher.js}

@@ -1,10 +1,10 @@
 import path from "node:path";
-import { appLogger } from "../../global/app-logger.js";
-import { PageRequestCacheCoordinator } from "../../services/cache/page-request-cache-coordinator.service.js";
-import { ServerUtils } from "../../utils/server-utils.module.js";
+import { appLogger } from "../../../global/app-logger.js";
+import { PageRequestCacheCoordinator } from "../../../services/cache/page-request-cache-coordinator.service.js";
+import { ServerUtils } from "../../../utils/server-utils.module.js";
 import { FileRouteMiddlewarePipeline } from "./file-route-middleware-pipeline.js";
-import { LocalsAccessError } from "../../errors/locals-access-error.js";
-import { isDevelopmentRuntime } from "../../utils/runtime.js";
+import { LocalsAccessError } from "../../../errors/locals-access-error.js";
+import { isDevelopmentRuntime } from "../../../utils/runtime.js";
 class FileSystemResponseMatcher {
   appConfig;
   assetPrefix;
@@ -37,15 +37,15 @@ class FileSystemResponseMatcher {
    * @returns Static file response or rendered 404 response.
    */
   async handleNoMatch(requestUrl) {
-    const isStaticFileRequest = ServerUtils.hasKnownExtension(requestUrl);
+    const isStaticFileRequest = ServerUtils.hasKnownStaticExtension(requestUrl);
     if (!isStaticFileRequest) {
-      return this.renderCustomNotFoundResponse();
+      return this.renderCustomNotFoundResponseOrServerError(requestUrl);
     }
     const relativeUrl = requestUrl.startsWith("/") ? requestUrl.slice(1) : requestUrl;
     const filePath = path.join(this.assetPrefix, relativeUrl);
     const contentType = ServerUtils.getContentType(filePath);
     const response = await this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
-    return response ?? this.renderCustomNotFoundResponse();
+    return response ?? this.renderCustomNotFoundResponseOrServerError(requestUrl);
   }
   /**
    * Handles a matched file-system page route.
@@ -100,17 +100,13 @@ class FileSystemResponseMatcher {
         return error;
       }
       if (error instanceof LocalsAccessError) {
-        return new Response(error.message, {
-          status: 500,
-          headers: { "Content-Type": "text/plain; charset=utf-8" }
-        });
-      }
-      if (error instanceof Error) {
-        if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
-          appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.requestedPathname}`);
-        }
+        return await this.createInternalServerErrorResponse(error.message, match.requestedPathname, error);
       }
-      return this.renderCustomNotFoundResponse();
+      return await this.createInternalServerErrorResponse(
+        error instanceof Error ? error.message : "Internal Server Error",
+        match.requestedPathname,
+        error
+      );
     }
   }
   /**
@@ -118,19 +114,105 @@ class FileSystemResponseMatcher {
    * when the page template cannot be resolved.
    */
   async renderCustomNotFoundResponse() {
-    const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
+    return this.renderCustomErrorPageResponse({
+      templatePath: this.appConfig.absolutePaths.error404TemplatePath,
+      label: "404",
+      createDefaultResponse: () => this.fileSystemResponseFactory.createDefaultNotFoundResponse(),
+      createHtmlResponse: (body) => this.fileSystemResponseFactory.createHtmlNotFoundResponse(body)
+    });
+  }
+  /**
+   * Renders the app-owned custom 500 page, falling back to the default text 500
+   * when the page template cannot be resolved.
+   */
+  async renderCustomServerErrorResponse(error) {
+    return this.renderCustomErrorPageResponse({
+      templatePath: this.appConfig.absolutePaths.error500TemplatePath,
+      label: "500",
+      props: this.buildServerErrorPageProps(error),
+      createDefaultResponse: () => this.fileSystemResponseFactory.createDefaultServerErrorResponse(),
+      createHtmlResponse: (body) => this.fileSystemResponseFactory.createHtmlServerErrorResponse(body)
+    });
+  }
+  /**
+   * Builds development-only error details for the custom 500 page.
+   * @remarks Production omits these fields so stacks are not serialized into HTML.
+   */
+  buildServerErrorPageProps(error) {
+    if (!isDevelopmentRuntime()) {
+      return void 0;
+    }
+    if (error instanceof Error) {
+      return {
+        message: error.message,
+        stack: error.stack
+      };
+    }
+    return {
+      message: String(error)
+    };
+  }
+  async renderCustomErrorPageResponse({
+    templatePath,
+    label,
+    props,
+    createDefaultResponse,
+    createHtmlResponse
+  }) {
+    let routeRenderer;
     try {
-      const routeRenderer = this.routeRendererFactory.getPageRenderer(error404TemplatePath);
-      const result = await routeRenderer.execute({
-        file: error404TemplatePath
-      });
-      return this.fileSystemResponseFactory.createHtmlNotFoundResponse(result.body);
+      routeRenderer = this.routeRendererFactory.getPageRenderer(templatePath);
     } catch {
       appLogger.debug(
-        "Custom 404 template not found, falling back to default 404 response",
-        error404TemplatePath
+        `Custom ${label} template not found, falling back to default ${label} response`,
+        templatePath
+      );
+      return createDefaultResponse();
+    }
+    const result = await routeRenderer.execute({
+      file: templatePath,
+      props
+    });
+    return createHtmlResponse(result.body);
+  }
+  async renderCustomNotFoundResponseOrServerError(pathname) {
+    try {
+      return await this.renderCustomNotFoundResponse();
+    } catch (error) {
+      if (error instanceof Response) {
+        return error;
+      }
+      return await this.createInternalServerErrorResponse(
+        error instanceof Error ? error.message : "Internal Server Error",
+        pathname,
+        error
+      );
+    }
+  }
+  /**
+   * Logs the original render failure, then tries the custom 500 page once.
+   * @remarks Any failure while rendering the custom 500 page falls back to the
+   * default plain-text response and never re-enters the custom page path.
+   * In development the thrown error's `message` and `stack` are passed into the
+   * custom 500 page props.
+   */
+  async createInternalServerErrorResponse(message, pathname, error) {
+    if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
+      appLogger.error(`[FileSystemResponseMatcher] ${message} at ${pathname}`, error);
+    } else {
+      appLogger.error(`[FileSystemResponseMatcher] Render error at ${pathname}`, error);
+    }
+    try {
+      return await this.renderCustomServerErrorResponse(error);
+    } catch (serverErrorPageError) {
+      if (serverErrorPageError instanceof Response) {
+        return serverErrorPageError;
+      }
+      appLogger.error(
+        `[FileSystemResponseMatcher] Custom 500 template failed at ${pathname}`,
+        serverErrorPageError
       );
-      return this.fileSystemResponseFactory.createDefaultNotFoundResponse();
+      return this.fileSystemResponseFactory.createDefaultServerErrorResponse();
     }
   }
   async createExecutionPlan(match, request) {

package/src/adapters/shared/http/run-middleware-chain.d.ts

@@ -0,0 +1,5 @@
+export type MiddlewareHandler<TContext> = (context: TContext, next: () => Promise<Response>) => Response | Promise<Response>;
+/**
+ * Runs an onion middleware chain and invokes the terminal handler when the chain completes.
+ */
+export declare function runMiddlewareChain<TContext>(middleware: readonly MiddlewareHandler<TContext>[], context: TContext, terminal: () => Promise<Response>): Promise<Response>;

package/src/adapters/shared/http/run-middleware-chain.js

@@ -0,0 +1,17 @@
+async function runMiddlewareChain(middleware, context, terminal) {
+  if (middleware.length === 0) {
+    return terminal();
+  }
+  let index = 0;
+  const executeNext = async () => {
+    if (index < middleware.length) {
+      const current = middleware[index++];
+      return await current(context, executeNext);
+    }
+    return terminal();
+  };
+  return executeNext();
+}
+export {
+  runMiddlewareChain
+};

package/src/adapters/shared/{application-adapter.d.ts → runtime/application-adapter.d.ts}

@@ -1,5 +1,5 @@
-import type { ApiHandler, ApiHandlerContext, Middleware, RouteGroupBuilder, RouteOptions } from '../../types/public-types.js';
-import { AbstractApplicationAdapter, type ApplicationAdapterOptions, type RouteGroupDefinition, type RouteHandler } from '../abstract/application-adapter.js';
+import type { ApiHandler, ApiHandlerContext, Middleware, RouteGroupBuilder, RouteOptions } from '../../../types/public-types.js';
+import { AbstractApplicationAdapter, type ApplicationAdapterOptions, type RouteGroupDefinition, type RouteHandler } from '../../abstract/application-adapter.js';
 export declare abstract class SharedApplicationAdapter<TOptions extends ApplicationAdapterOptions = ApplicationAdapterOptions, TServer = any, TRequest extends Request = Request> extends AbstractApplicationAdapter<TOptions, TServer, TRequest> {
     protected register<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, method: ApiHandler['method'], handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
     get<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;

package/src/adapters/shared/{application-adapter.js → runtime/application-adapter.js}

@@ -1,6 +1,6 @@
 import {
   AbstractApplicationAdapter
-} from "../abstract/application-adapter.js";
+} from "../../abstract/application-adapter.js";
 class SharedApplicationAdapter extends AbstractApplicationAdapter {
   register(path, method, handler, options) {
     return this.addRouteHandler(path, method, handler, options?.middleware, options?.schema);

package/src/adapters/shared/runtime/copy-runtime-public-dir.d.ts

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

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

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

package/src/adapters/shared/runtime/port-manager.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Detects whether a thrown error indicates the requested port is already in
+ * use.
+ *
+ * @remarks
+ * Matches Node's `code: 'EADDRINUSE'` and Bun's surface, where the error
+ * carries the same `code` plus a human-readable message such as
+ * `"Failed to start server. Is port 3000 in use?"`. Older Bun builds that do
+ * not set `.code` are covered by a fallback match on `syscall === 'listen'`
+ * plus the message shape.
+ */
+export declare function isPortInUseError(error: unknown): boolean;
+/**
+ * Probes whether a TCP port is currently bindable from this process. Uses a
+ * short-lived Node `net.Server` so both Node and Bun can run it via their
+ * Node-compatible core.
+ *
+ * @remarks
+ * A successful probe only guarantees the port was free at probe time; callers
+ * must still handle EADDRINUSE when they actually bind, since release races
+ * can flip the answer between probe and bind.
+ */
+export declare function isPortAvailable(port: number, hostname?: string): Promise<boolean>;
+/**
+ * Default interactive prompt. Asks a yes/no question on stdin/stdout and
+ * auto-approves (returns `true`) after `timeoutMs` with no input.
+ *
+ * @returns `true` when the user accepted (or timed out), `false` when they declined.
+ */
+export type PromptFunction = (message: string, timeoutMs: number) => Promise<boolean>;
+export interface PortManagerOptions {
+    /**
+     * Bind factory. Should throw on EADDRINUSE (or return `null`/`undefined`
+     * when it declines without a port collision). Returning a non-null port
+     * marks the bind as successful.
+     */
+    startOnPort: (port: number) => Promise<number | null | undefined>;
+    /** Emits the "moved to port X" warning when the bound port differs from the preferred port. */
+    warn?: (message: string) => void;
+    /** Infers a free port to display in the prompt. Defaults to {@link isPortAvailable}. */
+    probePort?: (port: number) => Promise<boolean>;
+    /** Custom prompter. Defaults to a readline-based yes/no prompt on the process stdio. */
+    prompt?: PromptFunction;
+    /** Enables the prompt flow at all. Defaults to `process.stdin.isTTY && process.stdout.isTTY`. */
+    interactive?: boolean;
+    /** Auto-approve timeout (ms) for the prompt. Defaults to 10000. */
+    autoApproveMs?: number;
+    /** Maximum port offset to scan when falling back. Defaults to 20. */
+    maxPortOffset?: number;
+    /** Retry attempts for the same port before declaring it taken. Defaults to 2. */
+    releaseRaceRetries?: number;
+    /** Backoff between same-port retries. Defaults to 100 ms. */
+    releaseRaceDelayMs?: number;
+}
+export interface BindPortOptions {
+    /** Port the caller would prefer to bind. */
+    preferredPort: number;
+    /**
+     * Whether the caller permits moving to the next free port automatically when
+     * the preferred port is busy and no interactive prompt is available
+     * (non-TTY / CI). Explicit ports that fall back silently in CI would surprise
+     * operators, so this is honoured by the non-interactive path only.
+     */
+    allowPortFallback: boolean;
+}
+/**
+ * Owns preview-port assignment: probing, race-release retries, fallback, and
+ * an optional interactive auto-approve prompt.
+ *
+ * @remarks
+ * Single-process API. The manager does not cache ports across calls; each
+ * `bind()` runs fresh from the preferred port.
+ */
+export declare class PortManager {
+    private readonly startOnPort;
+    private readonly warn;
+    private readonly probePort;
+    private readonly prompt;
+    private readonly interactive;
+    private readonly autoApproveMs;
+    private readonly maxPortOffset;
+    private readonly releaseRaceRetries;
+    private readonly releaseRaceDelayMs;
+    constructor(options: PortManagerOptions);
+    /**
+     * Binds the preview server to the preferred port.
+     *
+     * @remarks
+     * When the preferred port is free, binds it directly — no prompt, no
+     * fallback. The interactive prompt only fires on a genuine EADDRINUSE
+     * collision (TTY runs), and auto-approves after
+     * {@link PortManagerOptions.autoApproveMs}. In non-interactive (CI) runs,
+     * the manager falls back silently only when
+     * {@link BindPortOptions.allowPortFallback} is true (the default-port
+     * path); pinned ports rethrow EADDRINUSE so Docker-style fixed-port
+     * deployments fail loudly instead of silently moving.
+     */
+    bind(options: BindPortOptions): Promise<number | null>;
+    private shouldFallback;
+    private fallForward;
+    /**
+     * Attempts to bind via {@link PortManagerOptions.startOnPort} on `port`,
+     * retrying EADDRINUSE collisions up to
+     * {@link PortManagerOptions.releaseRaceRetries} to ride through TIME_WAIT
+     * race release.
+     *
+     * @remarks
+     * Only EADDRINUSE is retryable. Any other error is rethrown synchronously
+     * rather than swallowed as a soft "port taken" result, so a misconfigured
+     * factory surfaces loudly instead of causing a silent fallback. A `null`
+     * return from the factory (no throw) is reported as `factory-refused`, not
+     * conflated with a real collision.
+     */
+    private tryPort;
+    private findNextFreePort;
+}

package/src/adapters/shared/runtime/port-manager.js

@@ -0,0 +1,196 @@
+import { createServer as createNetServer } from "node:net";
+import { createInterface } from "node:readline";
+function isPortInUseError(error) {
+  if (!(error instanceof Error) && (typeof error !== "object" || error === null)) {
+    return false;
+  }
+  const maybeErr = error;
+  const code = typeof maybeErr.code === "string" || typeof maybeErr.code === "number" ? String(maybeErr.code) : void 0;
+  const syscall = typeof maybeErr.syscall === "string" ? maybeErr.syscall : void 0;
+  const message = error instanceof Error ? error.message : String(maybeErr.message ?? "");
+  if (code === "EADDRINUSE") {
+    return true;
+  }
+  if (message.includes("EADDRINUSE")) {
+    return true;
+  }
+  if (syscall === "listen" && /is port \d+ in use\??/i.test(message)) {
+    return true;
+  }
+  return false;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isPortAvailable(port, hostname = "127.0.0.1") {
+  return new Promise((resolve) => {
+    const tester = createNetServer();
+    tester.once("error", () => resolve(false));
+    tester.once("listening", () => {
+      tester.close(() => resolve(true));
+    });
+    tester.listen(port, hostname);
+  });
+}
+function createDefaultPrompt(stdin, stdout) {
+  return async (message, timeoutMs) => {
+    stdout.write(`${message} `);
+    return await new Promise((resolve) => {
+      const rl = createInterface({ input: stdin, output: void 0, terminal: false });
+      let settled = false;
+      const finish = (value) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        rl.close();
+        stdout.write("\n");
+        resolve(value);
+      };
+      const timer = setTimeout(() => finish(true), timeoutMs);
+      rl.once("line", (line) => {
+        const answer = line.trim().toLowerCase();
+        if (answer === "" || answer === "y" || answer === "yes") {
+          finish(true);
+        } else {
+          finish(false);
+        }
+      });
+      rl.once("close", () => finish(true));
+    });
+  };
+}
+const PREVIEW_PORT_RELEASE_RACE_RETRIES = 2;
+const PREVIEW_PORT_FALLBACK_ATTEMPTS = 20;
+const PREVIEW_PORT_RELEASE_RACE_DELAY_MS = 100;
+const PREVIEW_PORT_AUTO_APPROVE_MS = 1e4;
+class PortManager {
+  startOnPort;
+  warn;
+  probePort;
+  prompt;
+  interactive;
+  autoApproveMs;
+  maxPortOffset;
+  releaseRaceRetries;
+  releaseRaceDelayMs;
+  constructor(options) {
+    this.startOnPort = options.startOnPort;
+    this.warn = options.warn;
+    this.probePort = options.probePort ?? isPortAvailable;
+    this.maxPortOffset = options.maxPortOffset ?? PREVIEW_PORT_FALLBACK_ATTEMPTS - 1;
+    this.releaseRaceRetries = options.releaseRaceRetries ?? PREVIEW_PORT_RELEASE_RACE_RETRIES;
+    this.releaseRaceDelayMs = options.releaseRaceDelayMs ?? PREVIEW_PORT_RELEASE_RACE_DELAY_MS;
+    this.autoApproveMs = options.autoApproveMs ?? PREVIEW_PORT_AUTO_APPROVE_MS;
+    this.interactive = typeof options.interactive === "boolean" ? options.interactive : Boolean(typeof process !== "undefined" && process.stdin?.isTTY && process.stdout?.isTTY);
+    if (options.prompt) {
+      this.prompt = options.prompt;
+    } else if (this.interactive) {
+      this.prompt = createDefaultPrompt(process.stdin, process.stdout);
+    } else {
+      this.prompt = void 0;
+    }
+  }
+  /**
+   * Binds the preview server to the preferred port.
+   *
+   * @remarks
+   * When the preferred port is free, binds it directly — no prompt, no
+   * fallback. The interactive prompt only fires on a genuine EADDRINUSE
+   * collision (TTY runs), and auto-approves after
+   * {@link PortManagerOptions.autoApproveMs}. In non-interactive (CI) runs,
+   * the manager falls back silently only when
+   * {@link BindPortOptions.allowPortFallback} is true (the default-port
+   * path); pinned ports rethrow EADDRINUSE so Docker-style fixed-port
+   * deployments fail loudly instead of silently moving.
+   */
+  async bind(options) {
+    const preferredPort = options.preferredPort;
+    const firstAttempt = await this.tryPort(preferredPort);
+    if (firstAttempt.status === "bound") {
+      return firstAttempt.boundPort;
+    }
+    if (firstAttempt.status === "factory-refused") {
+      return null;
+    }
+    await this.shouldFallback(preferredPort, options.allowPortFallback, firstAttempt.error);
+    return await this.fallForward(preferredPort);
+  }
+  async shouldFallback(preferredPort, allowPortFallback, error) {
+    if (this.interactive && this.prompt) {
+      const nextFree = await this.findNextFreePort(preferredPort);
+      const nextFreeSuffix = typeof nextFree === "number" ? ` (next free: ${nextFree})` : "";
+      const autoApproveHint = `auto-yes in ${Math.round(this.autoApproveMs / 1e3)}s`;
+      const message = `[@ecopages/core] Port ${preferredPort} is already in use${nextFreeSuffix}. Bind there instead? [Y/n] (${autoApproveHint})`;
+      const accepted = await this.prompt(message, this.autoApproveMs);
+      if (!accepted) {
+        throw error;
+      }
+      return;
+    }
+    if (!allowPortFallback) {
+      throw error;
+    }
+  }
+  async fallForward(preferredPort) {
+    for (let offset = 1; offset <= this.maxPortOffset; offset += 1) {
+      const candidatePort = preferredPort + offset;
+      const attempt = await this.tryPort(candidatePort);
+      if (attempt.status === "bound") {
+        this.warn?.(
+          `Port ${preferredPort} is in use; preview serving on port ${attempt.boundPort} instead. Pin the preview port with --port or ECOPAGES_PORT when a fixed binding is required.`
+        );
+        return attempt.boundPort;
+      }
+    }
+    return null;
+  }
+  /**
+   * Attempts to bind via {@link PortManagerOptions.startOnPort} on `port`,
+   * retrying EADDRINUSE collisions up to
+   * {@link PortManagerOptions.releaseRaceRetries} to ride through TIME_WAIT
+   * race release.
+   *
+   * @remarks
+   * Only EADDRINUSE is retryable. Any other error is rethrown synchronously
+   * rather than swallowed as a soft "port taken" result, so a misconfigured
+   * factory surfaces loudly instead of causing a silent fallback. A `null`
+   * return from the factory (no throw) is reported as `factory-refused`, not
+   * conflated with a real collision.
+   */
+  async tryPort(port) {
+    for (let attempt = 0; attempt < this.releaseRaceRetries; attempt += 1) {
+      try {
+        const bound = await this.startOnPort(port);
+        if (bound) {
+          return { status: "bound", boundPort: bound };
+        }
+        return { status: "factory-refused" };
+      } catch (error) {
+        if (!isPortInUseError(error)) {
+          throw error;
+        }
+        if (attempt === this.releaseRaceRetries - 1) {
+          return { status: "port-in-use", error };
+        }
+        await sleep(this.releaseRaceDelayMs);
+      }
+    }
+    return { status: "factory-refused" };
+  }
+  async findNextFreePort(startPort) {
+    for (let offset = 1; offset <= this.maxPortOffset; offset += 1) {
+      const candidate = startPort + offset;
+      if (await this.probePort(candidate)) {
+        return candidate;
+      }
+    }
+    return null;
+  }
+}
+export {
+  PortManager,
+  isPortAvailable,
+  isPortInUseError
+};

package/src/adapters/shared/{render-context.d.ts → runtime/render-context.d.ts}

@@ -1,5 +1,5 @@
-import type { RenderContext } from '../../types/public-types.js';
-import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.js';
+import type { RenderContext } from '../../../types/public-types.js';
+import type { AnyIntegrationPlugin } from '../../../plugins/integration-plugin.js';
 export interface CreateRenderContextOptions {
     integrations: AnyIntegrationPlugin[];
     rendererModules?: unknown;

package/src/adapters/shared/{render-context.js → runtime/render-context.js}

@@ -1,5 +1,6 @@
 import { fileURLToPath } from "node:url";
-import { invariant } from "../../utils/invariant.js";
+import { invariant } from "../../../utils/invariant.js";
+import { createBodyResponse } from "../http/create-body-response.js";
 function resolveServerModulePath(filePath) {
   return filePath instanceof URL ? fileURLToPath(filePath) : filePath;
 }
@@ -64,25 +65,15 @@ function createRenderContext(options) {
       return renderer.renderToResponse(view, mergedProps, ctx);
     },
     json(data, responseOptions) {
-      const headers = new Headers({ "Content-Type": "application/json; charset=utf-8" });
-      if (responseOptions?.headers) {
-        const incomingHeaders = new Headers(responseOptions.headers);
-        incomingHeaders.forEach((value, key) => headers.set(key, value));
-      }
-      return new Response(JSON.stringify(data), {
-        status: responseOptions?.status ?? 200,
-        headers
+      return createBodyResponse("json", data, {
+        status: responseOptions?.status,
+        headers: responseOptions?.headers
       });
     },
     html(content, responseOptions) {
-      const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
-      if (responseOptions?.headers) {
-        const incomingHeaders = new Headers(responseOptions.headers);
-        incomingHeaders.forEach((value, key) => headers.set(key, value));
-      }
-      return new Response(content, {
-        status: responseOptions?.status ?? 200,
-        headers
+      return createBodyResponse("html", content, {
+        status: responseOptions?.status,
+        headers: responseOptions?.headers
       });
     }
   };

package/src/adapters/shared/{runtime-app-bootstrap.d.ts → runtime/runtime-app-bootstrap.d.ts}

@@ -1,14 +1,15 @@
-import type { ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ReturnParseCliArgs } from '../../../utils/parse-cli-args.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
 export type RuntimeBinding = {
     preferredPort: number;
     preferredHostname: string;
     runtimeOrigin: string;
     serveOptions: Record<string, unknown>;
     watch: boolean;
+    /** Whether preview may bind to the next free port when the preferred port is busy. */
+    allowPortFallback: boolean;
 };
 export type StaticRuntimeMode = {
-    requiresFetchRuntime: boolean;
     canBuildWithoutRuntimeServer: boolean;
 };
 export declare function resolveServeRuntimeOrigin(serveOptions: {

package/src/adapters/shared/{runtime-app-bootstrap.js → runtime/runtime-app-bootstrap.js}

@@ -1,4 +1,4 @@
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../../config/constants.js";
 function normalizeOriginHostname(hostname) {
   if (hostname.includes(":") && !hostname.startsWith("[") && !hostname.endsWith("]")) {
     return `[${hostname}]`;
@@ -12,11 +12,13 @@ function resolveServeRuntimeOrigin(serveOptions) {
 }
 function resolveRuntimeBinding(options) {
   const env = options.env ?? process.env;
+  const portExplicitlyConfigured = options.cliArgs.port !== void 0 || Boolean(env.ECOPAGES_PORT) || options.serverOptions?.port !== void 0;
   const preferredPort = options.cliArgs.port ?? (env.ECOPAGES_PORT ? Number(env.ECOPAGES_PORT) : void 0) ?? DEFAULT_ECOPAGES_PORT;
   const preferredHostname = options.cliArgs.hostname ?? env.ECOPAGES_HOSTNAME ?? DEFAULT_ECOPAGES_HOSTNAME;
   return {
     preferredPort,
     preferredHostname,
+    allowPortFallback: !portExplicitlyConfigured,
     runtimeOrigin: resolveServeRuntimeOrigin({
       hostname: preferredHostname,
       port: preferredPort
@@ -30,13 +32,8 @@ function resolveRuntimeBinding(options) {
   };
 }
 function resolveStaticRuntimeMode(options) {
-  const requiresFetchRuntime = options.appConfig.integrations.some(
-    (integration) => integration.staticBuildStep === "fetch"
-  );
-  const canBuildWithoutRuntimeServer = (options.cliArgs.build || options.cliArgs.preview) && !requiresFetchRuntime;
   return {
-    requiresFetchRuntime,
-    canBuildWithoutRuntimeServer
+    canBuildWithoutRuntimeServer: options.cliArgs.build || options.cliArgs.preview
   };
 }
 export {