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

package/src/adapters/node/node-hmr-manager.d.ts

@@ -1,29 +1,42 @@
-import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge } from '../../internal-types.js';
+import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge } from '../../types/internal-types.js';
 import type { EcoBuildPlugin } from '../../build/build-types.js';
-import type { HmrStrategy } from '../../hmr/hmr-strategy.js';
-import type { ClientBridgeEvent } from '../../public-types.js';
+import { type HmrStrategy } from '../../hmr/hmr-strategy.js';
+import type { ClientBridgeEvent } from '../../types/public-types.js';
 export interface NodeHmrManagerParams {
     appConfig: EcoPagesAppConfig;
     bridge: IClientBridge;
 }
+type HandleFileChangeOptions = {
+    broadcast?: boolean;
+};
+/**
+ * Node development HMR manager.
+ *
+ * @remarks
+ * This manager owns three separate concerns:
+ * - runtime websocket event fanout
+ * - entrypoint registration and dedupe
+ * - strategy coordination for rebuilds and invalidation
+ *
+ * The strict page-entrypoint contract lives here: `registerEntrypoint()` is
+ * reserved for integration-owned page bundles, while generic script assets must
+ * go through `registerScriptEntrypoint()`.
+ */
 export declare class NodeHmrManager implements IHmrManager {
+    private static readonly entrypointRegistrationTimeoutMs;
     readonly appConfig: EcoPagesAppConfig;
     private readonly bridge;
     private watchers;
     private watchedFiles;
-    private specifierMap;
-    /**
-     * Node-only reverse invalidation index: dependency file -> affected entrypoints.
-     */
-    private dependencyEntrypoints;
-    /**
-     * Node-only forward index: entrypoint -> latest dependency set.
-     */
-    private entrypointDependencies;
+    private entrypointRegistrations;
     private distDir;
     private plugins;
     private enabled;
     private strategies;
+    private readonly entrypointRegistrar;
+    private readonly browserBundleService;
+    private readonly entrypointDependencyGraph;
+    private readonly serverModuleTranspiler;
     constructor({ appConfig, bridge }: NodeHmrManagerParams);
     /**
      * Ensures the HMR output directory exists.
@@ -32,32 +45,77 @@ export declare class NodeHmrManager implements IHmrManager {
      * can share the same dist path during e2e runs.
      */
     private cleanDistDir;
+    /**
+     * Returns whether the generic JS strategy is allowed to rebuild an entrypoint.
+     *
+     * @remarks
+     * Higher-priority integration strategies own framework page entrypoints. When
+     * one of them matches, the generic JS strategy must stay out of the way so a
+     * shared dependency invalidation does not overwrite framework-specific output.
+     */
+    private shouldJsStrategyProcessEntrypoint;
     private initializeStrategies;
     registerStrategy(strategy: HmrStrategy): void;
     setPlugins(plugins: EcoBuildPlugin[]): void;
     setEnabled(enabled: boolean): void;
     isEnabled(): boolean;
-    registerSpecifierMap(map: Record<string, string>): void;
     buildRuntime(): Promise<void>;
     getRuntimePath(): string;
     broadcast(event: ClientBridgeEvent): void;
-    canHandleFileChange(filePath: string): boolean;
-    handleFileChange(filePath: string): Promise<void>;
+    handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
     getOutputUrl(entrypointPath: string): string | undefined;
     getWatchedFiles(): Map<string, string>;
-    getSpecifierMap(): Map<string, string>;
     getDistDir(): string;
     getPlugins(): EcoBuildPlugin[];
     getDefaultContext(): DefaultHmrContext;
+    private clearFailedEntrypointRegistration;
     /**
-     * Updates Node HMR dependency indexes for selective invalidation.
+     * Registers one integration-owned page entrypoint.
      *
      * @remarks
-     * Graph data comes from Node/esbuild build metadata and does not affect Bun
-     * HMR behavior.
+     * Concurrent callers share one in-flight registration. The registration is
+     * removed from the dedupe map once it resolves or fails so later requests do
+     * not inherit stale state.
      */
-    private setEntrypointDependencies;
     registerEntrypoint(entrypointPath: string): Promise<string>;
-    private encodeDynamicSegments;
+    /**
+     * Registers one generic script entrypoint.
+     *
+     * @remarks
+     * This path is intentionally separate from page entrypoints so non-framework
+     * scripts can still use the generic build fallback without weakening the page
+     * ownership contract.
+     */
+    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
+    /**
+     * Performs strict integration-owned entrypoint registration for one normalized source path.
+     *
+     * @remarks
+     * The flow is:
+     * 1. Reserve the output URL in the watched map.
+     * 2. Remove any stale emitted file from an earlier process or failed build.
+     * 3. Let the strategy chain try to emit the entrypoint without broadcasting.
+     * 4. Fail if the owning integration did not emit the expected output.
+     */
+    private emitStrictEntrypoint;
+    /**
+     * Performs registration for a generic script asset.
+     *
+     * @remarks
+     * This path performs a targeted browser bundle for the requested script
+     * entrypoint only. The resulting dependency graph is retained so later file
+     * changes can invalidate just the affected script entrypoints.
+     */
+    private emitScriptEntrypoint;
+    /**
+     * Stops active watchers and releases retained registration state.
+     *
+     * @remarks
+     * The manager intentionally does not remove emitted `_hmr` files from disk
+     * because multiple app processes may share the same dist directory during test
+     * runs. It does clear in-memory indexes so old entrypoints and dependencies
+     * cannot leak across a reused manager instance.
+     */
     stop(): void;
 }
+export {};

package/src/adapters/node/node-hmr-manager.js

@@ -1,35 +1,53 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { RESOLVED_ASSETS_DIR } from "../../constants.js";
-import { defaultBuildAdapter } from "../../build/build-adapter.js";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+import { getAppBuildExecutor } from "../../build/build-adapter.js";
 import { fileSystem } from "@ecopages/file-system";
 import { HmrStrategyType } from "../../hmr/hmr-strategy.js";
 import { DefaultHmrStrategy } from "../../hmr/strategies/default-hmr-strategy.js";
 import { JsHmrStrategy } from "../../hmr/strategies/js-hmr-strategy.js";
 import { appLogger } from "../../global/app-logger.js";
+import { HmrEntrypointRegistrar } from "../shared/hmr-entrypoint-registrar.js";
+import { BrowserBundleService } from "../../services/assets/browser-bundle.service.js";
+import { getAppServerModuleTranspiler } from "../../services/module-loading/app-server-module-transpiler.service.js";
+import {
+  getAppEntrypointDependencyGraph,
+  InMemoryEntrypointDependencyGraph,
+  setAppEntrypointDependencyGraph
+} from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from "../../utils/resolve-work-dir.js";
 class NodeHmrManager {
+  static entrypointRegistrationTimeoutMs = 4e3;
   appConfig;
   bridge;
   watchers = /* @__PURE__ */ new Map();
   watchedFiles = /* @__PURE__ */ new Map();
-  specifierMap = /* @__PURE__ */ new Map();
-  /**
-   * Node-only reverse invalidation index: dependency file -> affected entrypoints.
-   */
-  dependencyEntrypoints = /* @__PURE__ */ new Map();
-  /**
-   * Node-only forward index: entrypoint -> latest dependency set.
-   */
-  entrypointDependencies = /* @__PURE__ */ new Map();
+  entrypointRegistrations = /* @__PURE__ */ new Map();
   distDir;
   plugins = [];
   enabled = true;
   strategies = [];
+  entrypointRegistrar;
+  browserBundleService;
+  entrypointDependencyGraph;
+  serverModuleTranspiler;
   constructor({ appConfig, bridge }) {
     this.appConfig = appConfig;
     this.bridge = bridge;
-    this.distDir = path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR, "_hmr");
+    this.distDir = path.join(resolveInternalWorkDir(this.appConfig), RESOLVED_ASSETS_DIR, "_hmr");
+    this.entrypointRegistrar = new HmrEntrypointRegistrar({
+      srcDir: this.appConfig.absolutePaths.srcDir,
+      distDir: this.distDir,
+      entrypointRegistrations: this.entrypointRegistrations,
+      watchedFiles: this.watchedFiles,
+      clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath),
+      registrationTimeoutMs: NodeHmrManager.entrypointRegistrationTimeoutMs
+    });
+    this.browserBundleService = new BrowserBundleService(appConfig);
+    const existingEntrypointDependencyGraph = getAppEntrypointDependencyGraph(appConfig);
+    this.entrypointDependencyGraph = existingEntrypointDependencyGraph instanceof InMemoryEntrypointDependencyGraph ? existingEntrypointDependencyGraph : new InMemoryEntrypointDependencyGraph();
+    setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
+    this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
     this.cleanDistDir();
     this.initializeStrategies();
   }
@@ -42,15 +60,39 @@ class NodeHmrManager {
   cleanDistDir() {
     fileSystem.ensureDir(this.distDir);
   }
+  /**
+   * Returns whether the generic JS strategy is allowed to rebuild an entrypoint.
+   *
+   * @remarks
+   * Higher-priority integration strategies own framework page entrypoints. When
+   * one of them matches, the generic JS strategy must stay out of the way so a
+   * shared dependency invalidation does not overwrite framework-specific output.
+   */
+  shouldJsStrategyProcessEntrypoint(entrypointPath) {
+    return !this.strategies.some((strategy) => {
+      if (strategy.type !== HmrStrategyType.INTEGRATION || strategy.priority <= HmrStrategyType.SCRIPT) {
+        return false;
+      }
+      try {
+        return strategy.matches(entrypointPath);
+      } catch (error) {
+        appLogger.error(error);
+        return false;
+      }
+    });
+  }
   initializeStrategies() {
     const jsContext = {
       getWatchedFiles: () => this.watchedFiles,
-      getSpecifierMap: () => this.specifierMap,
-      getDependencyEntrypoints: (filePath) => new Set(this.dependencyEntrypoints.get(path.resolve(filePath)) ?? []),
-      setEntrypointDependencies: (entrypointPath, dependencies) => this.setEntrypointDependencies(entrypointPath, dependencies),
       getDistDir: () => this.distDir,
       getPlugins: () => this.plugins,
-      getSrcDir: () => this.appConfig.absolutePaths.srcDir
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getTemplateExtensions: () => this.appConfig.templatesExt,
+      getBrowserBundleService: () => this.browserBundleService,
+      getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+      shouldProcessEntrypoint: (entrypointPath) => this.shouldJsStrategyProcessEntrypoint(entrypointPath)
     };
     this.strategies = [new JsHmrStrategy(jsContext), new DefaultHmrStrategy()];
   }
@@ -66,24 +108,24 @@ class NodeHmrManager {
   isEnabled() {
     return this.enabled;
   }
-  registerSpecifierMap(map) {
-    for (const [specifier, url] of Object.entries(map)) {
-      this.specifierMap.set(specifier, url);
-    }
-  }
   async buildRuntime() {
-    const currentDir = path.dirname(fileURLToPath(import.meta.url));
-    const runtimeSource = path.resolve(currentDir, "../../hmr/client/hmr-runtime.js");
-    const result = await defaultBuildAdapter.build({
-      entrypoints: [runtimeSource],
-      outdir: this.distDir,
-      naming: "_hmr_runtime.js",
-      minify: false,
-      ...defaultBuildAdapter.getTranspileOptions("hmr-runtime"),
-      plugins: this.plugins
-    });
-    if (!result.success) {
-      appLogger.error("[HMR] Failed to build runtime script:", result.logs);
+    const runtimeSource = path.resolve(import.meta.dirname, "../../hmr/client/hmr-runtime.js");
+    try {
+      const result = await this.browserBundleService.bundle({
+        profile: "hmr-runtime",
+        entrypoints: [runtimeSource],
+        outdir: this.distDir,
+        naming: "_hmr_runtime.js",
+        minify: false,
+        plugins: this.plugins
+      });
+      if (!result.success) {
+        this.enabled = false;
+        appLogger.error("[HMR] Failed to build runtime script; continuing with HMR disabled.", result.logs);
+      }
+    } catch (error) {
+      this.enabled = false;
+      appLogger.error("[HMR] Failed to build runtime script; continuing with HMR disabled.", error);
     }
   }
   getRuntimePath() {
@@ -95,28 +137,13 @@ class NodeHmrManager {
     );
     this.bridge.broadcast(event);
   }
-  canHandleFileChange(filePath) {
-    const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
-    const strategy = sorted.find((candidate) => {
-      try {
-        return candidate.matches(filePath);
-      } catch (err) {
-        appLogger.error(
-          `[NodeHmrManager] Error checking match for ${candidate.constructor.name}:`,
-          err
-        );
-        return false;
-      }
-    });
-    return strategy !== void 0 && strategy.type !== HmrStrategyType.FALLBACK;
-  }
-  async handleFileChange(filePath) {
+  async handleFileChange(filePath, options = {}) {
     const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
     const strategy = sorted.find((s) => {
       try {
         return s.matches(filePath);
       } catch (err) {
-        appLogger.error(`[NodeHmrManager] Error checking match for ${s.constructor.name}:`, err);
+        appLogger.error(err);
         return false;
       }
     });
@@ -126,7 +153,8 @@ class NodeHmrManager {
     }
     appLogger.debug(`[NodeHmrManager] Selected strategy: ${strategy.constructor.name}`);
     const action = await strategy.process(filePath);
-    if (action.type === "broadcast") {
+    const shouldBroadcast = options.broadcast ?? true;
+    if (shouldBroadcast && action.type === "broadcast") {
       if (action.events) {
         for (const event of action.events) {
           this.broadcast(event);
@@ -140,9 +168,6 @@ class NodeHmrManager {
   getWatchedFiles() {
     return this.watchedFiles;
   }
-  getSpecifierMap() {
-    return this.specifierMap;
-  }
   getDistDir() {
     return this.distDir;
   }
@@ -152,84 +177,112 @@ class NodeHmrManager {
   getDefaultContext() {
     return {
       getWatchedFiles: () => this.watchedFiles,
-      getSpecifierMap: () => this.specifierMap,
       getDistDir: () => this.distDir,
       getPlugins: () => this.plugins,
       getSrcDir: () => this.appConfig.absolutePaths.srcDir,
       getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
-      getPagesDir: () => this.appConfig.absolutePaths.pagesDir
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getBuildExecutor: () => getAppBuildExecutor(this.appConfig),
+      getBrowserBundleService: () => this.browserBundleService,
+      importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
+        filePath,
+        outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
+        externalPackages: true
+      })
     };
   }
+  clearFailedEntrypointRegistration(entrypointPath) {
+    this.watchedFiles.delete(entrypointPath);
+    this.entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath);
+  }
   /**
-   * Updates Node HMR dependency indexes for selective invalidation.
+   * Registers one integration-owned page entrypoint.
    *
    * @remarks
-   * Graph data comes from Node/esbuild build metadata and does not affect Bun
-   * HMR behavior.
+   * Concurrent callers share one in-flight registration. The registration is
+   * removed from the dedupe map once it resolves or fails so later requests do
+   * not inherit stale state.
    */
-  setEntrypointDependencies(entrypointPath, dependencies) {
-    const normalizedEntrypoint = path.resolve(entrypointPath);
-    const previousDependencies = this.entrypointDependencies.get(normalizedEntrypoint);
-    if (previousDependencies) {
-      for (const dependencyPath of previousDependencies) {
-        const entrypoints = this.dependencyEntrypoints.get(dependencyPath);
-        if (!entrypoints) {
-          continue;
-        }
-        entrypoints.delete(normalizedEntrypoint);
-        if (entrypoints.size === 0) {
-          this.dependencyEntrypoints.delete(dependencyPath);
-        }
-      }
-    }
-    const normalizedDependencies = /* @__PURE__ */ new Set([
-      normalizedEntrypoint,
-      ...dependencies.map((dependencyPath) => path.resolve(dependencyPath))
-    ]);
-    this.entrypointDependencies.set(normalizedEntrypoint, normalizedDependencies);
-    for (const dependencyPath of normalizedDependencies) {
-      const entrypoints = this.dependencyEntrypoints.get(dependencyPath) ?? /* @__PURE__ */ new Set();
-      entrypoints.add(normalizedEntrypoint);
-      this.dependencyEntrypoints.set(dependencyPath, entrypoints);
-    }
-  }
   async registerEntrypoint(entrypointPath) {
-    if (this.watchedFiles.has(entrypointPath)) {
-      return this.watchedFiles.get(entrypointPath);
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint) => await this.emitStrictEntrypoint(normalizedEntrypoint),
+      getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(
+        `[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`
+      )
+    });
+  }
+  /**
+   * Registers one generic script entrypoint.
+   *
+   * @remarks
+   * This path is intentionally separate from page entrypoints so non-framework
+   * scripts can still use the generic build fallback without weakening the page
+   * ownership contract.
+   */
+  async registerScriptEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint, outputPath) => await this.emitScriptEntrypoint(normalizedEntrypoint, outputPath),
+      getMissingOutputError: (normalizedEntrypoint) => new Error(`[HMR] Failed to register script entrypoint: ${normalizedEntrypoint}`)
+    });
+  }
+  /**
+   * Performs strict integration-owned entrypoint registration for one normalized source path.
+   *
+   * @remarks
+   * The flow is:
+   * 1. Reserve the output URL in the watched map.
+   * 2. Remove any stale emitted file from an earlier process or failed build.
+   * 3. Let the strategy chain try to emit the entrypoint without broadcasting.
+   * 4. Fail if the owning integration did not emit the expected output.
+   */
+  async emitStrictEntrypoint(entrypointPath) {
+    await this.handleFileChange(entrypointPath, { broadcast: false });
+  }
+  /**
+   * Performs registration for a generic script asset.
+   *
+   * @remarks
+   * This path performs a targeted browser bundle for the requested script
+   * entrypoint only. The resulting dependency graph is retained so later file
+   * changes can invalidate just the affected script entrypoints.
+   */
+  async emitScriptEntrypoint(entrypointPath, outputPath) {
+    const naming = path.relative(this.distDir, outputPath).split(path.sep).join("/");
+    const buildResult = await this.browserBundleService.bundle({
+      profile: "hmr-entrypoint",
+      entrypoints: [entrypointPath],
+      outdir: this.distDir,
+      naming,
+      minify: false,
+      plugins: this.plugins
+    });
+    if (!buildResult.success) {
+      appLogger.error(`[HMR] Generic script entrypoint build failed for ${entrypointPath}:`, buildResult.logs);
+      return;
     }
-    const srcDir = this.appConfig.absolutePaths.srcDir;
-    const relativePath = path.relative(srcDir, entrypointPath);
-    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
-    const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
-    const urlPath = encodedPathJs.split(path.sep).join("/");
-    const outputUrl = `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath)}`;
-    const outputPath = path.join(this.distDir, urlPath);
-    this.watchedFiles.set(entrypointPath, outputUrl);
-    await this.handleFileChange(entrypointPath);
-    if (!fileSystem.exists(outputPath)) {
-      const fallback = await defaultBuildAdapter.build({
-        entrypoints: [entrypointPath],
-        outdir: this.distDir,
-        naming: encodedPathJs,
-        minify: false,
-        external: Array.from(this.specifierMap.keys()),
-        ...defaultBuildAdapter.getTranspileOptions("hmr-entrypoint"),
-        plugins: this.plugins
-      });
-      if (!fallback.success) {
-        appLogger.error(`[HMR] Fallback build failed for ${entrypointPath}:`, fallback.logs);
-      }
+    const entrypointDependencies = buildResult.dependencyGraph?.entrypoints?.[entrypointPath];
+    if (entrypointDependencies) {
+      this.entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, entrypointDependencies);
     }
-    return outputUrl;
-  }
-  encodeDynamicSegments(filepath) {
-    return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
   }
+  /**
+   * Stops active watchers and releases retained registration state.
+   *
+   * @remarks
+   * The manager intentionally does not remove emitted `_hmr` files from disk
+   * because multiple app processes may share the same dist directory during test
+   * runs. It does clear in-memory indexes so old entrypoints and dependencies
+   * cannot leak across a reused manager instance.
+   */
   stop() {
+    this.entrypointRegistrations.clear();
     for (const watcher of this.watchers.values()) {
       watcher.close();
     }
     this.watchers.clear();
+    this.watchedFiles.clear();
+    this.entrypointDependencyGraph.reset();
+    this.plugins = [];
   }
 }
 export {

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

@@ -1,6 +1,6 @@
 import { type Server as NodeHttpServer } from 'node:http';
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { ApiHandler, ErrorHandler, StaticRoute } from '../../public-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ApiHandler, ErrorHandler, StaticRoute } from '../../types/public-types.js';
 import { SharedServerAdapter } from '../shared/server-adapter.js';
 import type { ServerAdapterResult } from '../abstract/server-adapter.js';
 export type NodeServerInstance = NodeHttpServer;
@@ -53,7 +53,6 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
     private previewServer;
     private bridge;
     private hmrManager;
-    private processorBuildPlugins;
     constructor(options: NodeServerAdapterParams);
     /**
      * Prepares the adapter for use.
@@ -69,34 +68,6 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      *    processors during their `setup()` calls.
      */
     initialize(): Promise<void>;
-    /**
-     * Registers every configured file loader as a build plugin on the shared
-     * `defaultBuildAdapter`.
-     *
-     * Loaders are registered on the *shared* adapter (not on a per-build instance)
-     * because they must be available globally to both the SSR build and any dynamic
-     * transpile passes that happen outside of a top-level `build()` call (e.g. HMR
-     * incremental rebuilds).
-     */
-    private setupLoaders;
-    private copyPublicDir;
-    /**
-     * Sets up all configured processors and integrations in two distinct phases.
-     *
-     * **Phase 1 — Processors:**
-     * Each processor's `setup()` is called first. A processor may expose two
-     * plugin lists:
-     * - `plugins` — transform plugins used during SSR rendering (e.g. PostCSS).
-     * - `buildPlugins` — esbuild plugins used during the client bundle step.
-     * Both are registered on `defaultBuildAdapter` so later build calls pick them up.
-     *
-     * **Phase 2 — Integrations:**
-     * Integrations receive the fully-resolved app config, the runtime origin, and
-     * (if already initialised) the HMR manager before their own `setup()` is called.
-     * This ordering ensures integrations can query config values that processors
-     * may have mutated during phase 1.
-     */
-    private initializePlugins;
     getServerOptions(): NodeServeAdapterServerOptions;
     buildStatic(options?: {
         preview?: boolean;
@@ -138,6 +109,7 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      * `stopBuildRuntimeServer`, so it never overlaps with the actual dev/prod server.
      */
     private startBuildRuntimeServer;
+    private getListeningServerOrigin;
     /**
      * Gracefully shuts down the ephemeral build runtime server.
      *
@@ -161,7 +133,7 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      * underlying socket closes early — into a 499 response so it does not
      * incorrectly surface as a 500 in application logs.
      */
-    handleRequest(_request: Request): Promise<Response>;
+    handleRequest(request: Request): Promise<Response>;
     /**
      * Called once the HTTP server is bound and listening.
      *
@@ -172,13 +144,13 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      *   broadcast + heartbeat cleanup.
      * - `NodeHmrManager` watches the filesystem and triggers incremental esbuild
      *   rebuilds, notifying connected clients via the bridge.
-     * - `ProjectWatcher` listens for route-level file changes and refreshes the
-     *   router and response handlers when pages are added or removed.
+     * - Shared watcher bootstrapping listens for route-level file changes and
+     *   refreshes the router and response handlers when pages are added or removed.
      *
      * WebSocket upgrade requests that do not target `/_hmr` are rejected with an
      * immediate socket destroy to prevent unhandled upgrade leaks.
      */
-    completeInitialization(_server: NodeServerInstance): Promise<void>;
+    completeInitialization(server: NodeServerInstance): Promise<void>;
 }
 /**
  * Factory function that creates and fully initialises a `NodeServerAdapter`.