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

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

@@ -1,20 +1,4 @@
-/**
- * Shared runtime state used while registering HMR-owned entrypoints.
- */
-export interface HmrEntrypointRegistrarOptions {
-    /** Absolute source directory used to derive the emitted HMR path. */
-    srcDir: string;
-    /** Absolute distribution directory where HMR outputs are written. */
-    distDir: string;
-    /** In-flight registrations keyed by normalized absolute entrypoint path. */
-    entrypointRegistrations: Map<string, Promise<string>>;
-    /** Stable entrypoint-to-output mapping retained once an entrypoint is registered. */
-    watchedFiles: Map<string, string>;
-    /** Runtime-specific cleanup invoked when an entrypoint registration fails. */
-    clearFailedRegistration?: (entrypointPath: string) => void;
-    /** Development-only guardrail for integrations that never finish producing output. */
-    registrationTimeoutMs: number;
-}
+import { type ResolvedHmrEntrypoint } from '../../hmr/hmr-entrypoint-output.js';
 /**
  * Runtime-specific hooks required to materialize a single HMR entrypoint.
  */
@@ -28,28 +12,35 @@ export interface HmrEntrypointRegistrationOptions {
      */
     getMissingOutputError(entrypointPath: string, outputPath: string): Error;
 }
+export interface HmrEntrypointRegistrarOptions {
+    /** Absolute source directory used to derive the emitted HMR path. */
+    srcDir: string;
+    /** Absolute distribution directory where HMR outputs are written. */
+    distDir: string;
+    /** Runtime-specific cleanup invoked when an entrypoint registration fails. */
+    clearFailedRegistration?: (entrypointPath: string) => void;
+}
 /**
  * Coordinates the shared HMR entrypoint registration lifecycle for both Node and Bun managers.
  *
- * The registrar owns the cross-runtime policy: normalize entrypoint identities, dedupe concurrent
- * registrations, derive the emitted `_hmr` output path, clear stale output before rebuilding, and
- * apply the development timeout that prevents unresolved registrations from hanging navigation.
- * Runtime-specific managers remain responsible for the actual emit step and any cleanup outside
- * this shared registration flow.
+ * @remarks
+ * The registrar owns in-flight deduplication and the registered entrypoint table.
+ * A source path is committed only after emit succeeds and the expected output exists on disk.
  */
 export declare class HmrEntrypointRegistrar {
     private readonly options;
+    private readonly inFlight;
+    private readonly registered;
     constructor(options: HmrEntrypointRegistrarOptions);
+    getRegistered(): ReadonlyMap<string, ResolvedHmrEntrypoint>;
+    getWatchedFiles(): Map<string, string>;
+    clearRegistration(entrypointPath: string): void;
+    clearAll(): void;
     /**
-     * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
+     * Registers a single source entrypoint and returns its verified HMR artifact.
      *
-     * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
-     * integration only builds once per registration cycle.
+     * Concurrent requests for the same normalized entrypoint share the same in-flight promise.
      */
-    registerEntrypoint(entrypointPath: string, registrationOptions: HmrEntrypointRegistrationOptions): Promise<string>;
+    registerEntrypoint(entrypointPath: string, registrationOptions: HmrEntrypointRegistrationOptions): Promise<ResolvedHmrEntrypoint>;
     private registerEntrypointInternal;
-    private awaitEntrypointRegistration;
-    private getEntrypointOutput;
-    private removeStaleEntrypointOutput;
-    private encodeDynamicSegments;
 }

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

@@ -1,85 +1,80 @@
 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;
+  inFlight = /* @__PURE__ */ new Map();
+  registered = /* @__PURE__ */ new Map();
   constructor(options) {
     this.options = options;
   }
+  getRegistered() {
+    return this.registered;
+  }
+  getWatchedFiles() {
+    const watchedFiles = /* @__PURE__ */ new Map();
+    for (const [sourcePath, entrypoint] of this.registered) {
+      watchedFiles.set(sourcePath, entrypoint.outputUrl);
+    }
+    return watchedFiles;
+  }
+  clearRegistration(entrypointPath) {
+    this.registered.delete(path.resolve(entrypointPath));
+  }
+  clearAll() {
+    this.inFlight.clear();
+    this.registered.clear();
+  }
   /**
-   * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
+   * Registers a single source entrypoint and returns its verified HMR artifact.
    *
-   * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
-   * integration only builds once per registration cycle.
+   * Concurrent requests for the same normalized entrypoint share the same in-flight promise.
    */
   async registerEntrypoint(entrypointPath, registrationOptions) {
     const normalizedEntrypoint = path.resolve(entrypointPath);
-    const existingRegistration = this.options.entrypointRegistrations.get(normalizedEntrypoint);
+    const existing = this.registered.get(normalizedEntrypoint);
+    if (existing && fileSystem.exists(existing.outputPath)) {
+      return existing;
+    }
+    const existingRegistration = this.inFlight.get(normalizedEntrypoint);
     if (existingRegistration) {
-      return await this.awaitEntrypointRegistration(existingRegistration, normalizedEntrypoint);
+      return await existingRegistration;
     }
     const registration = this.registerEntrypointInternal(normalizedEntrypoint, registrationOptions);
-    this.options.entrypointRegistrations.set(normalizedEntrypoint, registration);
+    this.inFlight.set(normalizedEntrypoint, registration);
     try {
-      return await this.awaitEntrypointRegistration(registration, normalizedEntrypoint);
+      return await registration;
     } catch (error) {
       this.options.clearFailedRegistration?.(normalizedEntrypoint);
+      this.registered.delete(normalizedEntrypoint);
       throw error;
     } finally {
-      this.options.entrypointRegistrations.delete(normalizedEntrypoint);
+      if (this.inFlight.get(normalizedEntrypoint) === registration) {
+        this.inFlight.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);
+    const { outputPath, outputUrl } = resolveHmrEntrypointOutputPaths(
+      this.options.srcDir,
+      this.options.distDir,
+      entrypointPath
+    );
+    removeStaleHmrEntrypointOutput(outputPath, "HMR");
     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)
+    const resolved = {
+      sourcePath: entrypointPath,
+      outputPath,
+      outputUrl
     };
-  }
-  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_");
+    this.registered.set(entrypointPath, resolved);
+    return resolved;
   }
 }
 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;
+}