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

package/src/adapters/shared/fs-server-response-matcher.js

@@ -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 this.createInternalServerErrorResponse(error.message, match.requestedPathname, error);
       }
-      return this.renderCustomNotFoundResponse();
+      return this.createInternalServerErrorResponse(
+        error instanceof Error ? error.message : "Internal Server Error",
+        match.requestedPathname,
+        error
+      );
     }
   }
   /**
@@ -119,12 +115,9 @@ class FileSystemResponseMatcher {
    */
   async renderCustomNotFoundResponse() {
     const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
+    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(error404TemplatePath);
     } catch {
       appLogger.debug(
         "Custom 404 template not found, falling back to default 404 response",
@@ -132,6 +125,35 @@ class FileSystemResponseMatcher {
       );
       return this.fileSystemResponseFactory.createDefaultNotFoundResponse();
     }
+    const result = await routeRenderer.execute({
+      file: error404TemplatePath
+    });
+    return this.fileSystemResponseFactory.createHtmlNotFoundResponse(result.body);
+  }
+  async renderCustomNotFoundResponseOrServerError(pathname) {
+    try {
+      return await this.renderCustomNotFoundResponse();
+    } catch (error) {
+      if (error instanceof Response) {
+        return error;
+      }
+      return this.createInternalServerErrorResponse(
+        error instanceof Error ? error.message : "Internal Server Error",
+        pathname,
+        error
+      );
+    }
+  }
+  createInternalServerErrorResponse(message, pathname, error) {
+    if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
+      appLogger.error(`[FileSystemResponseMatcher] ${message} at ${pathname}`, error);
+    } else {
+      appLogger.error(`[FileSystemResponseMatcher] Render error at ${pathname}`, error);
+    }
+    return new Response("Internal Server Error", {
+      status: 500,
+      headers: { "Content-Type": "text/plain; charset=utf-8" }
+    });
   }
   async createExecutionPlan(match, request) {
     const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey({

package/src/adapters/shared/hmr-entrypoint-registrar.d.ts

@@ -50,6 +50,4 @@ export declare class HmrEntrypointRegistrar {
     private registerEntrypointInternal;
     private awaitEntrypointRegistration;
     private getEntrypointOutput;
-    private removeStaleEntrypointOutput;
-    private encodeDynamicSegments;
 }

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

@@ -1,7 +1,6 @@
 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";
+import { removeStaleHmrEntrypointOutput, resolveHmrEntrypointOutputPaths } from "../../hmr/hmr-entrypoint-output.js";
 class HmrEntrypointRegistrar {
   options;
   constructor(options) {
@@ -36,7 +35,7 @@ class HmrEntrypointRegistrar {
     }
     const { outputPath, outputUrl } = this.getEntrypointOutput(entrypointPath);
     this.options.watchedFiles.set(entrypointPath, outputUrl);
-    this.removeStaleEntrypointOutput(outputPath);
+    removeStaleHmrEntrypointOutput(outputPath, "HMR");
     await registrationOptions.emit(entrypointPath, outputPath);
     if (!fileSystem.exists(outputPath)) {
       throw registrationOptions.getMissingOutputError(entrypointPath, outputPath);
@@ -57,29 +56,7 @@ class HmrEntrypointRegistrar {
     ]);
   }
   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_");
+    return resolveHmrEntrypointOutputPaths(this.options.srcDir, this.options.distDir, entrypointPath);
   }
 }
 export {

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

@@ -11,7 +11,7 @@ export declare function isHtmlResponse(response: Response): boolean;
  * 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;
+export declare function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>, hostOwnsDevClient?: boolean): boolean;
 /**
  * Injects the development HMR runtime script into an HTML response if it is not
  * already present.

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

@@ -4,7 +4,10 @@ function isHtmlResponse(response) {
   const contentType = response.headers.get("Content-Type");
   return contentType !== null && contentType.startsWith("text/html");
 }
-function shouldInjectHmrHtmlResponse(watch, hmrManager) {
+function shouldInjectHmrHtmlResponse(watch, hmrManager, hostOwnsDevClient = false) {
+  if (hostOwnsDevClient) {
+    return false;
+  }
   return watch && hmrManager?.isEnabled() === true;
 }
 async function injectHmrRuntimeIntoHtmlResponse(response) {

package/src/adapters/shared/node-http-websocket-upgrades.d.ts

@@ -0,0 +1,21 @@
+import type { Duplex } from 'node:stream';
+import type { Server as NodeHttpServer, IncomingMessage } from 'node:http';
+import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
+export type NodeHttpWebSocketUpgradePreflight = (req: IncomingMessage, socket: Duplex, head: Buffer) => boolean;
+export type AttachNodeHttpWebSocketUpgradesOptions = {
+    runtimeOrigin: string;
+    websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    /**
+     * When true, unmatched upgrade requests are left for other listeners (e.g.
+     * Vite HMR). When false, unmatched upgrades are destroyed immediately.
+     */
+    passthroughUnmatched?: boolean;
+    preflight?: NodeHttpWebSocketUpgradePreflight;
+};
+/**
+ * Wires Ecopages user WebSocket routes onto a Node HTTP server's `upgrade` event.
+ *
+ * Used by the Node adapter in standalone mode and by host integrations such as
+ * the Vite plugin that embed Ecopages behind a foreign HTTP server.
+ */
+export declare function attachNodeHttpWebSocketUpgrades(server: NodeHttpServer, options: AttachNodeHttpWebSocketUpgradesOptions): void;

package/src/adapters/shared/node-http-websocket-upgrades.js

@@ -0,0 +1,100 @@
+import { WebSocketServer } from "ws";
+import { appLogger } from "../../global/app-logger.js";
+import { findWebSocketRoute } from "../abstract/ws-pattern-matcher.js";
+import { createEcopagesSocket, invokeWebSocketHandlerHook, toWebSocketCloseInfo } from "./websocket-lifecycle.js";
+const attachedUpgradeServers = /* @__PURE__ */ new WeakSet();
+function adaptNodeWebSocket(ws, kind, params, search, context) {
+  return createEcopagesSocket(
+    {
+      send: (data) => ws.send(data),
+      close: (code, reason) => ws.close(code, reason)
+    },
+    { kind, params, search, context }
+  );
+}
+function toUpgradeRequest(runtimeOrigin, req) {
+  const upgradeUrl = new URL(req.url ?? "/", runtimeOrigin);
+  return new Request(upgradeUrl, {
+    method: req.method,
+    headers: req.headers
+  });
+}
+async function resolveNodeContext(request, handler, kind, params, search) {
+  if (!handler.context) {
+    return void 0;
+  }
+  try {
+    return await handler.context({ request, kind, params, search });
+  } catch (error) {
+    appLogger.error(`[WS:${kind}] context() failed; closing connection.`, error);
+    throw error;
+  }
+}
+async function setupNodeWebSocketConnection(ws, wsMatch, req, runtimeOrigin, search) {
+  const handler = wsMatch.handler;
+  const baseRequest = toUpgradeRequest(runtimeOrigin, req);
+  let context;
+  try {
+    context = await resolveNodeContext(baseRequest, handler, wsMatch.kind, wsMatch.params, search);
+  } catch {
+    ws.close(1011, "context initialization failed");
+    return;
+  }
+  const socket = adaptNodeWebSocket(ws, wsMatch.kind, wsMatch.params, search, context);
+  try {
+    await handler.onConnect?.(socket);
+  } catch (error) {
+    appLogger.error(`[WS:${wsMatch.kind}] onConnect failed:`, error);
+    ws.close(1011, "onConnect failed");
+    return;
+  }
+  ws.on("message", (msg, isBinary) => {
+    const message = isBinary ? {
+      kind: "binary",
+      data: msg instanceof ArrayBuffer ? new Uint8Array(msg) : Array.isArray(msg) ? new Uint8Array(Buffer.concat(msg)) : new Uint8Array(msg)
+    } : { kind: "text", text: msg.toString() };
+    invokeWebSocketHandlerHook(wsMatch.kind, "onMessage", handler.onMessage?.(socket, message));
+  });
+  ws.on("close", (code, reason) => {
+    const event = toWebSocketCloseInfo(code, reason.toString());
+    invokeWebSocketHandlerHook(wsMatch.kind, "onClose", handler.onClose?.(socket, event));
+  });
+  ws.on("error", (err) => {
+    appLogger.error(`[WS:${wsMatch.kind}] error:`, err);
+    invokeWebSocketHandlerHook(wsMatch.kind, "onError", handler.onError?.(socket, err));
+  });
+}
+function attachNodeHttpWebSocketUpgrades(server, options) {
+  if (options.websocketHandlers.size === 0) {
+    return;
+  }
+  if (attachedUpgradeServers.has(server)) {
+    appLogger.warn("[WS] WebSocket upgrades already attached to this HTTP server; skipping duplicate attach.");
+    return;
+  }
+  attachedUpgradeServers.add(server);
+  const userWss = new WebSocketServer({ noServer: true });
+  server.on("upgrade", (req, socket, head) => {
+    if (options.preflight?.(req, socket, head)) {
+      return;
+    }
+    const url = new URL(req.url ?? "/", options.runtimeOrigin);
+    const wsMatch = findWebSocketRoute(options.websocketHandlers, url.pathname);
+    if (!wsMatch) {
+      if (!options.passthroughUnmatched) {
+        socket.destroy();
+      }
+      return;
+    }
+    userWss.handleUpgrade(req, socket, head, (ws) => {
+      const search = Object.fromEntries(url.searchParams.entries());
+      void setupNodeWebSocketConnection(ws, wsMatch, req, options.runtimeOrigin, search).catch((error) => {
+        appLogger.error(`[WS:${wsMatch.kind}] unexpected error:`, error);
+        ws.close(1011, "internal error");
+      });
+    });
+  });
+}
+export {
+  attachNodeHttpWebSocketUpgrades
+};

package/src/adapters/shared/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/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/runtime-app-bootstrap.d.ts

@@ -6,9 +6,10 @@ export type RuntimeBinding = {
     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

@@ -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 {