@ecopages/core 0.2.0-beta.0 → 0.2.0-beta.10

package/src/adapters/shared/runtime-server-lifecycle.js

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+import { disposeAppBuildRuntime } from "../../build/build-runtime.js";
+import { getAppBrowserBuildPlugins } from "../../build/build-adapter.js";
+import { copyRuntimePublicDirIfChanged } from "./copy-runtime-public-dir.js";
+import { injectHmrRuntimeIntoHtmlResponse, isHtmlResponse, shouldInjectHmrHtmlResponse } from "./hmr-html-response.js";
+function prepareRuntimePublicDir(appConfig) {
+  const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
+  if (fileSystem.exists(srcPublicDir)) {
+    copyRuntimePublicDirIfChanged(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
+  }
+  fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+}
+function wireIntegrationHmrManagers(appConfig, hmrManager) {
+  hmrManager.setPlugins(getAppBrowserBuildPlugins(appConfig));
+  for (const integration of appConfig.integrations) {
+    integration.setHmrManager(hmrManager);
+  }
+}
+async function maybeInjectAdapterHmrHtmlResponse(response, options) {
+  if (shouldInjectHmrHtmlResponse(options.watch, options.hmrManager, options.hostOwnsDevClient) && isHtmlResponse(response)) {
+    return injectHmrRuntimeIntoHtmlResponse(response);
+  }
+  return response;
+}
+async function disposeDevResources(options) {
+  await options.projectWatcher?.close();
+  await disposeAppBuildRuntime(options.appConfig);
+  options.hmrManager?.stop();
+  options.bridge?.destroy();
+  await options.previewHost.stop();
+}
+export {
+  disposeDevResources,
+  maybeInjectAdapterHmrHtmlResponse,
+  prepareRuntimePublicDir,
+  wireIntegrationHmrManagers
+};

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

@@ -21,7 +21,8 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
     protected routeHandler: ServerRouteHandler;
     protected staticSiteGenerator: StaticSiteGenerator;
     protected staticBuilder: ServerStaticBuilder;
-    protected readonly schemaValidator: SchemaValidationService;
+    protected schemaValidator: SchemaValidationService;
+    protected hostOwnsDevClient: boolean;
     protected initializeSharedRouteHandling(options: {
         staticRoutes: StaticRoute[];
         hmrManager?: any;

package/src/adapters/shared/server-adapter.js

@@ -27,6 +27,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
   staticSiteGenerator;
   staticBuilder;
   schemaValidator = new SchemaValidationService();
+  hostOwnsDevClient = false;
   async initializeSharedRouteHandling(options) {
     await this.initSharedRouter();
     this.configureSharedResponseHandlers(options.staticRoutes, options.hmrManager);
@@ -76,7 +77,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
         const module = await serverModuleTranspiler.importModule({
           filePath,
           outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-route-modules"),
-          externalPackages: false,
+          externalPackages: true,
           transpileErrorMessage: (details) => `Error transpiling route module: ${details}`,
           noOutputMessage: (targetFilePath) => `No transpiled output generated for route module: ${targetFilePath}`
         });
@@ -115,7 +116,8 @@ class SharedServerAdapter extends AbstractServerAdapter {
       fileSystemResponseMatcher: this.fileSystemResponseMatcher,
       explicitStaticRouteMatcher,
       watch: !!this.options?.watch,
-      hmrManager
+      hmrManager,
+      hostOwnsDevClient: this.hostOwnsDevClient
     });
   }
   createSharedResponseHandlerDependencies(staticRoutes) {
@@ -380,7 +382,10 @@ class SharedServerAdapter extends AbstractServerAdapter {
       const runtimePath = context.hmrManager.getRuntimePath();
       if (fileSystem.exists(runtimePath)) {
         return new Response(fileSystem.readFileAsBuffer(runtimePath), {
-          headers: { "Content-Type": "application/javascript" }
+          headers: {
+            "Content-Type": "application/javascript",
+            "Cache-Control": "no-store, must-revalidate"
+          }
         });
       }
     }
@@ -389,7 +394,10 @@ class SharedServerAdapter extends AbstractServerAdapter {
       const assetPath = path.join(context.hmrManager.getDistDir(), relativePath);
       if (fileSystem.exists(assetPath)) {
         return new Response(fileSystem.readFileAsBuffer(assetPath), {
-          headers: { "Content-Type": "application/javascript" }
+          headers: {
+            "Content-Type": "application/javascript",
+            "Cache-Control": "no-store, must-revalidate"
+          }
         });
       }
     }

package/src/adapters/shared/server-route-handler.d.ts

@@ -16,6 +16,8 @@ export interface ServerRouteHandlerParams {
     watch?: boolean;
     /** HMR manager for broadcasting hot module reload events in development. */
     hmrManager?: IHmrManager;
+    /** When true, the host dev server owns browser dev-client bootstrap. */
+    hostOwnsDevClient?: boolean;
 }
 /**
  * Handles HTTP requests and routing for the server.
@@ -33,12 +35,13 @@ export declare class ServerRouteHandler {
     private readonly explicitStaticRouteMatcher?;
     private readonly watch;
     private readonly hmrManager?;
+    private readonly hostOwnsDevClient;
     /**
      * Creates a new ServerRouteHandler instance.
      *
      * @param params - Configuration parameters
      */
-    constructor({ router, fileSystemResponseMatcher, explicitStaticRouteMatcher, watch, hmrManager, }: ServerRouteHandlerParams);
+    constructor({ router, fileSystemResponseMatcher, explicitStaticRouteMatcher, watch, hmrManager, hostOwnsDevClient, }: ServerRouteHandlerParams);
     /**
      * Determines if HMR script should be injected.
      *

package/src/adapters/shared/server-route-handler.js

@@ -7,6 +7,7 @@ class ServerRouteHandler {
   explicitStaticRouteMatcher;
   watch;
   hmrManager;
+  hostOwnsDevClient;
   /**
    * Creates a new ServerRouteHandler instance.
    *
@@ -17,13 +18,15 @@ class ServerRouteHandler {
     fileSystemResponseMatcher,
     explicitStaticRouteMatcher,
     watch = false,
-    hmrManager
+    hmrManager,
+    hostOwnsDevClient = false
   }) {
     this.router = router;
     this.fileSystemResponseMatcher = fileSystemResponseMatcher;
     this.explicitStaticRouteMatcher = explicitStaticRouteMatcher;
     this.watch = watch;
     this.hmrManager = hmrManager;
+    this.hostOwnsDevClient = hostOwnsDevClient;
   }
   /**
    * Determines if HMR script should be injected.
@@ -31,7 +34,7 @@ class ServerRouteHandler {
    * @returns true if in watch mode and HMR manager is enabled
    */
   shouldInjectHmrScript() {
-    return shouldInjectHmrHtmlResponse(this.watch, this.hmrManager);
+    return shouldInjectHmrHtmlResponse(this.watch, this.hmrManager, this.hostOwnsDevClient);
   }
   /**
    * Checks if a response contains HTML content.

package/src/adapters/shared/server-static-builder.d.ts

@@ -1,11 +1,12 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
 import type { ApiHandler, StaticRoute } from '../../types/public-types.js';
 import type { RouteRegistry } from '../../router/server/route-registry.js';
 import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.js';
 import type { StaticGenerationRendererResolver } from '../../route-renderer/route-renderer.js';
 export interface StaticBuildOptions {
-    preview?: boolean;
     baseUrl?: string;
+    force?: boolean;
 }
 export interface ServeOptions {
     hostname?: string;
@@ -15,9 +16,12 @@ export interface ServerStaticBuilderParams {
     appConfig: EcoPagesAppConfig;
     staticSiteGenerator: StaticSiteGenerator;
     serveOptions: ServeOptions;
+    runtimeOrigin: string;
     apiHandlers?: ApiHandler[];
     logger?: ServerStaticBuilderLogger;
-    previewServerFactory?: ServerStaticPreviewServerFactory;
+    entryFile?: string;
+    hmrManager?: IHmrManager;
+    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
 }
 /**
  * Minimal logger dependency used by the static builder.
@@ -28,37 +32,41 @@ export interface ServerStaticBuilderLogger {
     error(message: string): unknown;
 }
 /**
- * Preview server factory dependency used when static preview mode is enabled.
- */
-export interface ServerStaticPreviewServerFactory {
-    createServer(args: {
-        appConfig: EcoPagesAppConfig;
-        options: {
-            port: number;
-        };
-    }): {
-        server?: {
-            port?: number;
-        } | null;
-    };
-}
-/**
- * Handles static site generation and previews.
+ * Handles static site generation.
  */
 export declare class ServerStaticBuilder {
     private readonly appConfig;
     private readonly staticSiteGenerator;
     private readonly serveOptions;
+    private readonly runtimeOrigin;
     private readonly apiHandlers;
     private readonly logger;
-    private readonly previewServerFactory;
-    constructor({ appConfig, staticSiteGenerator, serveOptions, apiHandlers, logger, previewServerFactory, }: ServerStaticBuilderParams);
-    private warnApiHandlersUnavailableInStaticMode;
+    private readonly entryFile;
+    private readonly hmrManager?;
+    private readonly onRuntimePlugin?;
+    constructor({ appConfig, staticSiteGenerator, serveOptions, runtimeOrigin, apiHandlers, logger, entryFile, hmrManager, onRuntimePlugin, }: ServerStaticBuilderParams);
     private prepareExportDirectory;
     private refreshRuntimeAssets;
+    /**
+     * Bundles the server entry file for production use.
+     *
+     * @remarks
+     * Every production build emits a runnable server entry for `ecopages start`,
+     * including static-only and websocket-only apps. Incremental builds may skip
+     * Rolldown when the `.eco/.server-entry` cache is still valid.
+     *
+     * Package imports remain external so native addons and runtime-owned
+     * dependencies continue to load through the app's installed
+     * `node_modules` tree. Only the app entry graph is bundled.
+     *
+     * Throws if the build adapter is unavailable, is owned by a host
+     * runtime, or bundling fails.
+     *
+     * @throws If the build adapter is unavailable, is host-owned, or bundling fails.
+     */
+    private bundleServerEntry;
     /**
      * Generates a static build of the site for deployment.
-     * @param options.preview - If true, starts a preview server after build
      * @param dependencies.router - The initialized router
      * @param dependencies.routeRendererFactory - The route renderer factory
      * @param dependencies.staticRoutes - Explicit static routes registered via app.static()

package/src/adapters/shared/server-static-builder.js

@@ -1,48 +1,65 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
-import { StaticContentServer } from "../../dev/sc-server.js";
 import { appLogger } from "../../global/app-logger.js";
+import { build, getAppBuildAdapter, setupAppRuntimePlugins } from "../../build/build-adapter.js";
+import { resolveBuildProfileOptions } from "../../build/build-profile-options.js";
+import {
+  getServerBundleOutputPaths,
+  lookupServerEntryBuildCache,
+  recordServerEntryBuildCache,
+  writeServerBundleDeployManifest
+} from "../../build/server-entry-build-cache.js";
+import { getInstalledServerEntryBuildExecutor } from "../../build/runtime-build-executor.js";
+import {
+  clearProductionBuildCaches,
+  shouldResetStaticExportDirectory
+} from "../../static-site-generator/static-build-invalidation.js";
+import { resolveEntryFile, SERVER_BUNDLE_FILENAME } from "../../utils/resolve-entry-file.js";
 class ServerStaticBuilder {
   appConfig;
   staticSiteGenerator;
   serveOptions;
+  runtimeOrigin;
   apiHandlers;
   logger;
-  previewServerFactory;
+  entryFile;
+  hmrManager;
+  onRuntimePlugin;
   constructor({
     appConfig,
     staticSiteGenerator,
     serveOptions,
+    runtimeOrigin,
     apiHandlers,
     logger,
-    previewServerFactory
+    entryFile,
+    hmrManager,
+    onRuntimePlugin
   }) {
     this.appConfig = appConfig;
     this.staticSiteGenerator = staticSiteGenerator;
     this.serveOptions = serveOptions;
+    this.runtimeOrigin = runtimeOrigin;
     this.apiHandlers = apiHandlers ?? [];
     this.logger = logger ?? appLogger;
-    this.previewServerFactory = previewServerFactory ?? StaticContentServer;
+    this.entryFile = resolveEntryFile({ entryFile });
+    this.hmrManager = hmrManager;
+    this.onRuntimePlugin = onRuntimePlugin;
   }
-  warnApiHandlersUnavailableInStaticMode() {
-    if (this.apiHandlers.length === 0) {
-      return;
+  prepareExportDirectory(force) {
+    if (force) {
+      clearProductionBuildCaches(this.appConfig);
     }
-    const uniqueHandlers = Array.from(
-      new Set(this.apiHandlers.map((handler) => `${handler.method} ${handler.path}`))
-    );
-    const visibleHandlers = uniqueHandlers.slice(0, 5).join(", ");
-    const remainingCount = uniqueHandlers.length - Math.min(uniqueHandlers.length, 5);
-    const summary = remainingCount > 0 ? `${visibleHandlers}, +${remainingCount} more` : visibleHandlers;
-    this.logger.warn(
-      "Registered API endpoints are not available in static build or preview modes because no server runtime is started. They are excluded from the generated output.\n",
-      `\u27A4 ${summary}`
-    );
-  }
-  prepareExportDirectory() {
     const exportDir = this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
-    fileSystem.ensureDir(exportDir, true);
+    const shouldCleanDist = shouldResetStaticExportDirectory(this.appConfig, force);
+    fileSystem.ensureDir(exportDir, shouldCleanDist);
+    if (shouldCleanDist) {
+      this.appConfig.runtime = {
+        ...this.appConfig.runtime ?? {},
+        runtimeAssetsPrepared: false
+      };
+    }
     const srcPublicDir = path.join(
       this.appConfig.rootDir,
       this.appConfig.srcDir ?? "src",
@@ -51,48 +68,114 @@ class ServerStaticBuilder {
     if (fileSystem.exists(srcPublicDir)) {
       fileSystem.copyDir(srcPublicDir, exportDir);
     }
+    return !shouldCleanDist;
   }
   async refreshRuntimeAssets() {
-    for (const processor of this.appConfig.processors.values()) {
-      await processor.setup();
+    appLogger.debugTime("refreshRuntimeAssets");
+    try {
+      await setupAppRuntimePlugins({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin,
+        hmrManager: this.hmrManager,
+        onRuntimePlugin: this.onRuntimePlugin
+      });
+    } finally {
+      appLogger.debugTimeEnd("refreshRuntimeAssets");
+    }
+  }
+  /**
+   * Bundles the server entry file for production use.
+   *
+   * @remarks
+   * Every production build emits a runnable server entry for `ecopages start`,
+   * including static-only and websocket-only apps. Incremental builds may skip
+   * Rolldown when the `.eco/.server-entry` cache is still valid.
+   *
+   * Package imports remain external so native addons and runtime-owned
+   * dependencies continue to load through the app's installed
+   * `node_modules` tree. Only the app entry graph is bundled.
+   *
+   * Throws if the build adapter is unavailable, is owned by a host
+   * runtime, or bundling fails.
+   *
+   * @throws If the build adapter is unavailable, is host-owned, or bundling fails.
+   */
+  async bundleServerEntry(options) {
+    const buildAdapter = getAppBuildAdapter(this.appConfig);
+    if (buildAdapter.ownership === "vite-host") {
+      throw new Error(
+        'Cannot bundle the server entry file: build ownership is "vite-host". The host runtime is expected to produce its own server bundle.'
+      );
+    }
+    const entryPath = path.isAbsolute(this.entryFile) ? this.entryFile : path.join(this.appConfig.rootDir, this.entryFile);
+    if (!fileSystem.exists(entryPath)) {
+      throw new Error(
+        `Cannot bundle server entry: file "${this.entryFile}" not found in "${this.appConfig.rootDir}".`
+      );
     }
-    for (const integration of this.appConfig.integrations) {
-      await integration.setup();
+    const { serverOutdir, serverEntryPath } = getServerBundleOutputPaths(this.appConfig);
+    const cached = lookupServerEntryBuildCache({
+      appConfig: this.appConfig,
+      entryPath,
+      force: options?.force
+    });
+    if (cached) {
+      const hasBundle = cached.outputPaths.some(
+        (outputPath) => path.resolve(outputPath) === path.resolve(serverEntryPath) && fileSystem.exists(outputPath)
+      );
+      if (hasBundle) {
+        this.logger.info("Reusing cached server entry bundle");
+        writeServerBundleDeployManifest(this.appConfig, serverEntryPath);
+        return;
+      }
+    }
+    this.logger.info("Bundling server entry file...");
+    const buildOptions = {
+      ...resolveBuildProfileOptions("server-entry", this.appConfig, {
+        entrypoints: [entryPath],
+        outdir: serverOutdir,
+        naming: SERVER_BUNDLE_FILENAME,
+        sourcemap: "hidden"
+      }),
+      entrypoints: [entryPath]
+    };
+    const result = await build(buildOptions, getInstalledServerEntryBuildExecutor(this.appConfig));
+    if (!result.success) {
+      const errorMessages = result.logs.map((log) => log.message).join("\n");
+      throw new Error(`Failed to bundle server entry file:
+${errorMessages}`);
     }
+    const outputPaths = result.outputs.length > 0 ? result.outputs.map((output) => output.path) : fileSystem.exists(serverEntryPath) ? [serverEntryPath] : [];
+    recordServerEntryBuildCache({
+      appConfig: this.appConfig,
+      entryPath,
+      buildResult: result,
+      outputPaths
+    });
+    writeServerBundleDeployManifest(this.appConfig, serverEntryPath);
+    this.logger.info("Server entry file bundled successfully");
   }
   /**
    * Generates a static build of the site for deployment.
-   * @param options.preview - If true, starts a preview server after build
    * @param dependencies.router - The initialized router
    * @param dependencies.routeRendererFactory - The route renderer factory
    * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
    */
   async build(options, dependencies) {
-    const { preview = false, baseUrl: explicitBaseUrl } = options ?? {};
+    const { baseUrl: explicitBaseUrl, force = false } = options ?? {};
     const baseUrl = explicitBaseUrl ?? `http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
-    this.warnApiHandlersUnavailableInStaticMode();
-    this.prepareExportDirectory();
+    const preserveExportDirectory = this.prepareExportDirectory(force);
     await this.refreshRuntimeAssets();
+    await this.bundleServerEntry({ force });
     await this.staticSiteGenerator.run({
       router: dependencies.router,
       baseUrl,
       routeRendererFactory: dependencies.routeRendererFactory,
-      staticRoutes: dependencies.staticRoutes
+      staticRoutes: dependencies.staticRoutes,
+      force,
+      preserveExportDirectory
     });
-    if (!preview) {
-      this.logger.info("Build completed");
-      return;
-    }
-    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
-    const { server } = this.previewServerFactory.createServer({
-      appConfig: this.appConfig,
-      options: { port: Number(previewPort) }
-    });
-    if (server?.port) {
-      this.logger.info(`Preview running at http://localhost:${server.port}`);
-    } else {
-      this.logger.error("Failed to start preview server");
-    }
+    this.logger.info("Build completed");
   }
 }
 export {

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

@@ -10,6 +10,7 @@ import type { ServerModuleTranspiler } from '../../services/module-loading/serve
 type HandleFileChangeOptions = {
     broadcast?: boolean;
 };
+export declare function resolveHmrRegistrationTimeoutMs(explicitTimeoutMs?: number): number;
 type SharedHmrManagerParams = {
     appConfig: EcoPagesAppConfig;
     bridge: IClientBridge;
@@ -45,6 +46,16 @@ export declare abstract class SharedHmrManager implements IHmrManager {
     broadcast(event: ClientBridgeEvent): void;
     handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
     getOutputUrl(entrypointPath: string): string | undefined;
+    /**
+     * Returns the emitted HMR script output when the artifact already exists on disk.
+     *
+     * SSR must not block on entrypoint registration when a previous build already
+     * produced the browser bundle.
+     */
+    getResolvedScriptOutput(entrypointPath: string): {
+        outputUrl: string;
+        outputPath: string;
+    } | undefined;
     getWatchedFiles(): Map<string, string>;
     getDistDir(): string;
     getPlugins(): EcoBuildPlugin[];
@@ -55,5 +66,6 @@ export declare abstract class SharedHmrManager implements IHmrManager {
     protected emitStrictEntrypoint(entrypointPath: string): Promise<void>;
     protected emitScriptEntrypoint(entrypointPath: string, outputPath: string): Promise<void>;
     stop(): void;
+    [Symbol.dispose](): void;
 }
 export {};

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

@@ -2,11 +2,13 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
-import { getAppBuildExecutor } from "../../build/build-adapter.js";
+import { requireBuildRuntime } from "../../build/build-runtime.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 { ServerRenderedTemplateHmrStrategy } from "../../hmr/strategies/server-rendered-template-hmr-strategy.js";
+import { DevelopmentInvalidationService } from "../../services/invalidation/development-invalidation.service.js";
 import { appLogger } from "../../global/app-logger.js";
 import { HmrEntrypointRegistrar } from "./hmr-entrypoint-registrar.js";
 import { BrowserBundleService } from "../../services/assets/browser-bundle.service.js";
@@ -16,6 +18,24 @@ import {
   setAppEntrypointDependencyGraph
 } from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
 import { resolveInternalExecutionDir, resolveInternalWorkDir } from "../../utils/resolve-work-dir.js";
+const DEFAULT_HMR_REGISTRATION_TIMEOUT_MS = 4e3;
+const DEVELOPMENT_HMR_REGISTRATION_TIMEOUT_MS = 15e3;
+function resolveHmrRegistrationTimeoutMs(explicitTimeoutMs) {
+  if (explicitTimeoutMs !== void 0) {
+    return explicitTimeoutMs;
+  }
+  const envTimeoutMs = process.env.ECOPAGES_HMR_REGISTRATION_TIMEOUT_MS;
+  if (envTimeoutMs !== void 0 && envTimeoutMs !== "") {
+    const parsedTimeoutMs = Number(envTimeoutMs);
+    if (Number.isFinite(parsedTimeoutMs) && parsedTimeoutMs > 0) {
+      return parsedTimeoutMs;
+    }
+  }
+  if (process.env.NODE_ENV === "development") {
+    return DEVELOPMENT_HMR_REGISTRATION_TIMEOUT_MS;
+  }
+  return DEFAULT_HMR_REGISTRATION_TIMEOUT_MS;
+}
 class SharedHmrManager {
   appConfig;
   bridge;
@@ -24,13 +44,13 @@ class SharedHmrManager {
   entrypointRegistrations = /* @__PURE__ */ new Map();
   distDir;
   plugins = [];
-  enabled = true;
+  enabled = false;
   strategies = [];
   entrypointRegistrar;
   browserBundleService;
   entrypointDependencyGraph;
   serverModuleTranspiler;
-  constructor({ appConfig, bridge, registrationTimeoutMs = 4e3 }) {
+  constructor({ appConfig, bridge, registrationTimeoutMs }) {
     this.appConfig = appConfig;
     this.bridge = bridge;
     this.distDir = path.join(resolveInternalWorkDir(this.appConfig), RESOLVED_ASSETS_DIR, "_hmr");
@@ -40,7 +60,7 @@ class SharedHmrManager {
       entrypointRegistrations: this.entrypointRegistrations,
       watchedFiles: this.watchedFiles,
       clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath),
-      registrationTimeoutMs
+      registrationTimeoutMs: resolveHmrRegistrationTimeoutMs(registrationTimeoutMs)
     });
     this.browserBundleService = new BrowserBundleService(appConfig);
     this.entrypointDependencyGraph = this.createEntrypointDependencyGraph(
@@ -86,7 +106,12 @@ class SharedHmrManager {
       getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
       shouldProcessEntrypoint: (entrypointPath) => this.shouldJsStrategyProcessEntrypoint(entrypointPath)
     };
-    this.strategies = [new JsHmrStrategy(jsContext), new DefaultHmrStrategy()];
+    const invalidationService = new DevelopmentInvalidationService(this.appConfig);
+    this.strategies = [
+      new JsHmrStrategy(jsContext),
+      new ServerRenderedTemplateHmrStrategy(invalidationService),
+      new DefaultHmrStrategy()
+    ];
   }
   registerStrategy(strategy) {
     this.strategies.push(strategy);
@@ -158,6 +183,24 @@ class SharedHmrManager {
   getOutputUrl(entrypointPath) {
     return this.watchedFiles.get(entrypointPath);
   }
+  /**
+   * Returns the emitted HMR script output when the artifact already exists on disk.
+   *
+   * SSR must not block on entrypoint registration when a previous build already
+   * produced the browser bundle.
+   */
+  getResolvedScriptOutput(entrypointPath) {
+    const normalizedEntrypoint = path.resolve(entrypointPath);
+    const relativePath = path.relative(this.appConfig.absolutePaths.srcDir, normalizedEntrypoint);
+    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js").replace(/\[([^\]]+)\]/g, "_$1_");
+    const urlPath = relativePathJs.split(path.sep).join("/");
+    const outputPath = path.join(this.distDir, urlPath);
+    if (!fileSystem.exists(outputPath)) {
+      return void 0;
+    }
+    const outputUrl = this.watchedFiles.get(normalizedEntrypoint) ?? `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath).split(path.sep).join("/")}`;
+    return { outputUrl, outputPath };
+  }
   getWatchedFiles() {
     return this.watchedFiles;
   }
@@ -175,7 +218,7 @@ class SharedHmrManager {
       getSrcDir: () => this.appConfig.absolutePaths.srcDir,
       getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
       getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
-      getBuildExecutor: () => getAppBuildExecutor(this.appConfig),
+      getBuildExecutor: () => requireBuildRuntime(this.appConfig).getProfile("browser-hmr"),
       getBrowserBundleService: () => this.browserBundleService,
       getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
       importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
@@ -220,6 +263,16 @@ class SharedHmrManager {
       appLogger.error(`[HMR] Generic script entrypoint build failed for ${entrypointPath}:`, buildResult.logs);
       return;
     }
+    if (!fileSystem.exists(outputPath) && buildResult.outputs.length > 0) {
+      const resolvedOutputPath = path.resolve(outputPath);
+      const emittedOutput = buildResult.outputs.find((output) => path.resolve(output.path) === resolvedOutputPath)?.path ?? buildResult.outputs.find((output) => path.basename(output.path) === path.basename(outputPath))?.path;
+      if (emittedOutput && fileSystem.exists(emittedOutput)) {
+        fileSystem.ensureDir(path.dirname(outputPath));
+        if (path.resolve(emittedOutput) !== resolvedOutputPath) {
+          fileSystem.copyFile(emittedOutput, outputPath);
+        }
+      }
+    }
     const entrypointDependencies = buildResult.dependencyGraph?.entrypoints?.[entrypointPath];
     if (entrypointDependencies) {
       this.entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, entrypointDependencies);
@@ -235,7 +288,11 @@ class SharedHmrManager {
     this.entrypointDependencyGraph.reset();
     this.plugins = [];
   }
+  [Symbol.dispose]() {
+    this.stop();
+  }
 }
 export {
-  SharedHmrManager
+  SharedHmrManager,
+  resolveHmrRegistrationTimeoutMs
 };

package/src/adapters/shared/static-preview-host.d.ts

@@ -7,4 +7,9 @@ export interface StaticPreviewHostStartOptions {
     appConfig: EcoPagesAppConfig;
     hostname: string;
     port: number;
+    /**
+     * When true, bind to the next available port if the preferred one is busy.
+     * Should remain false when the port was explicitly configured.
+     */
+    allowPortFallback?: boolean;
 }