@ecopages/core 0.2.0-beta.1 → 0.2.0-beta.11

package/src/adapters/shared/bun-user-websocket-lifecycle.js

@@ -0,0 +1,96 @@
+import { appLogger } from "../../global/app-logger.js";
+import { invokeWebSocketHandlerHook, toWebSocketCloseInfo } from "./websocket-lifecycle.js";
+function toUpgradeRequest(ws, runtimeOrigin) {
+  const upgradeUrl = ws.data?.upgradeUrl;
+  if (upgradeUrl) {
+    return new Request(upgradeUrl);
+  }
+  return new Request(runtimeOrigin);
+}
+async function runUserWebSocketOpen(ws, kind, deps) {
+  const handler = deps.userHandlers.get(kind);
+  if (!handler) {
+    return;
+  }
+  const params = ws.data?.params ?? {};
+  const search = ws.data?.search ?? {};
+  const request = toUpgradeRequest(ws, deps.runtimeOrigin);
+  let context;
+  try {
+    context = await deps.resolveContext(request, handler, kind, params, search);
+  } catch {
+    ws.close(1011, "context initialization failed");
+    return;
+  }
+  ws.data.context = context;
+  const socket = deps.adaptSocket(ws, kind, params, search, context);
+  try {
+    await handler.onConnect?.(socket);
+  } catch (error) {
+    appLogger.error(`[WS:${kind}] onConnect failed:`, error);
+    ws.close(1011, "onConnect failed");
+  }
+}
+function createBunUserWebSocketLifecycle(deps) {
+  const resolveSocketForEvent = (ws) => {
+    const kind = ws.data?.kind;
+    if (!kind) {
+      return void 0;
+    }
+    const handler = deps.userHandlers.get(kind);
+    if (!handler) {
+      return void 0;
+    }
+    const params = ws.data?.params ?? {};
+    const search = ws.data?.search ?? {};
+    const socket = deps.adaptSocket(ws, kind, params, search, ws.data?.context);
+    return { kind, handler, socket };
+  };
+  return {
+    open(ws) {
+      const kind = ws.data?.kind;
+      if (!kind) {
+        return;
+      }
+      void runUserWebSocketOpen(ws, kind, deps).catch((error) => {
+        appLogger.error(`[WS:${kind}] open failed:`, error);
+        ws.close(1011, "internal error");
+      });
+    },
+    message(ws, msg) {
+      const resolved = resolveSocketForEvent(ws);
+      if (!resolved) {
+        return;
+      }
+      if (ws.data?.context === void 0 && resolved.handler.context) {
+        appLogger.warn(`[WS:${resolved.kind}] message received before context resolved; dropping.`);
+        return;
+      }
+      const message = typeof msg === "string" ? { kind: "text", text: msg } : { kind: "binary", data: new Uint8Array(msg.buffer, msg.byteOffset, msg.byteLength) };
+      invokeWebSocketHandlerHook(
+        resolved.kind,
+        "onMessage",
+        resolved.handler.onMessage?.(resolved.socket, message)
+      );
+    },
+    close(ws, code, reason) {
+      const resolved = resolveSocketForEvent(ws);
+      if (!resolved) {
+        return;
+      }
+      const event = toWebSocketCloseInfo(code, reason);
+      invokeWebSocketHandlerHook(resolved.kind, "onClose", resolved.handler.onClose?.(resolved.socket, event));
+    },
+    error(ws, error) {
+      const resolved = resolveSocketForEvent(ws);
+      if (!resolved) {
+        return;
+      }
+      appLogger.error(`[WS:${resolved.kind}] error:`, error);
+      invokeWebSocketHandlerHook(resolved.kind, "onError", resolved.handler.onError?.(resolved.socket, error));
+    }
+  };
+}
+export {
+  createBunUserWebSocketLifecycle
+};

package/src/adapters/shared/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/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/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 {

package/src/adapters/shared/runtime-server-lifecycle.d.ts

@@ -0,0 +1,38 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { IHmrManager } from '../../types/public-types.js';
+import type { ProjectWatcher } from '../../watchers/project-watcher.js';
+/**
+ * Copies source `public/` into dist and ensures the resolved assets directory exists.
+ */
+export declare function prepareRuntimePublicDir(appConfig: EcoPagesAppConfig): void;
+/**
+ * Propagates browser build plugins and the shared HMR manager into integrations.
+ */
+export declare function wireIntegrationHmrManagers(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): void;
+/**
+ * Injects the dev HMR runtime into adapter-level HTML responses when watch mode is active.
+ */
+export declare function maybeInjectAdapterHmrHtmlResponse(response: Response, options: {
+    watch: boolean;
+    hmrManager?: Pick<IHmrManager, 'isEnabled'>;
+    hostOwnsDevClient: boolean;
+}): Promise<Response>;
+/**
+ * Releases shared dev resources in a consistent order across server adapters.
+ *
+ * @remarks
+ * Bun calls `buildRuntime()` during `initialize()` when watch is enabled; Node defers
+ * runtime creation to `completeInitialization()`. Transport-specific setup stays in
+ * each adapter — only shared teardown lives here.
+ */
+export declare function disposeDevResources(options: {
+    projectWatcher: ProjectWatcher | null | undefined;
+    appConfig: EcoPagesAppConfig;
+    hmrManager: IHmrManager | null | undefined;
+    bridge: {
+        destroy(): void;
+    } | null | undefined;
+    previewHost: {
+        stop(): Promise<void>;
+    };
+}): Promise<void>;