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

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>;

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

@@ -0,0 +1,43 @@
+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 { clearAppDevClientBridge } from "../../dev/client-bridge-registry.js";
+import { clearAppHmrManager } from "../../dev/hmr-manager-registry.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();
+  clearAppDevClientBridge(options.appConfig);
+  clearAppHmrManager(options.appConfig);
+  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) {
@@ -164,8 +166,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
       importServerModule: async (filePath) => await serverModuleTranspiler.importModule({
         filePath,
         outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
-        externalPackages: true,
-        bypassCache: this.options?.watch === true
+        externalPackages: true
       })
     });
   }
@@ -380,7 +381,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 +393,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 { ApiHandler, StaticRoute } from '../../types/public-types.js';
+import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { 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,10 +16,17 @@ export interface ServerStaticBuilderParams {
     appConfig: EcoPagesAppConfig;
     staticSiteGenerator: StaticSiteGenerator;
     serveOptions: ServeOptions;
-    apiHandlers?: ApiHandler[];
+    runtimeOrigin: string;
+    /**
+     * Whether the app requires a server entry bundle for production use.
+     * When `true`, the build step bundles the server entry file for `ecopages start`.
+     * Defaults to `false` (static-only build, no server needed).
+     */
+    needsServerBundle?: boolean;
     logger?: ServerStaticBuilderLogger;
-    previewServerFactory?: ServerStaticPreviewServerFactory;
     entryFile?: string;
+    hmrManager?: IHmrManager;
+    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
 }
 /**
  * Minimal logger dependency used by the static builder.
@@ -29,50 +37,34 @@ 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 apiHandlers;
+    private readonly runtimeOrigin;
+    private readonly needsServerBundle;
     private readonly logger;
-    private readonly previewServerFactory;
     private readonly entryFile;
-    constructor({ appConfig, staticSiteGenerator, serveOptions, apiHandlers, logger, previewServerFactory, entryFile, }: ServerStaticBuilderParams);
-    private warnApiHandlersUnavailableInStaticMode;
+    private readonly hmrManager?;
+    private readonly onRuntimePlugin?;
+    constructor({ appConfig, staticSiteGenerator, serveOptions, runtimeOrigin, needsServerBundle, logger, entryFile, hmrManager, onRuntimePlugin, }: ServerStaticBuilderParams);
     private prepareExportDirectory;
     private refreshRuntimeAssets;
     /**
      * Bundles the server entry file for production use.
      *
      * @remarks
-     * When the project has API endpoints, the entry file must be bundled
-     * into a single JS file so the production server can start without
-     * on-the-fly TypeScript transpilation. The bundle is output to
-     * `dist/{SERVER_BUNDLE_DIR}/{SERVER_BUNDLE_FILENAME}` and used by
-     * `ecopages start` in production.
+     * Only invoked when the app requires a runtime server (API handlers,
+     * websocket handlers, etc.). Static-only apps skip this step entirely.
+     * 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.
      *
-     * Skips silently when no API endpoints are registered (static-only site).
      * Throws if the build adapter is unavailable, is owned by a host
      * runtime, or bundling fails.
      *
@@ -81,7 +73,6 @@ export declare class ServerStaticBuilder {
     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,53 +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 { getAppBuildAdapter } from "../../build/build-adapter.js";
-import { resolveEntryFile, SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from "../../utils/resolve-entry-file.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;
-  apiHandlers;
+  runtimeOrigin;
+  needsServerBundle;
   logger;
-  previewServerFactory;
   entryFile;
+  hmrManager;
+  onRuntimePlugin;
   constructor({
     appConfig,
     staticSiteGenerator,
     serveOptions,
-    apiHandlers,
+    runtimeOrigin,
+    needsServerBundle,
     logger,
-    previewServerFactory,
-    entryFile
+    entryFile,
+    hmrManager,
+    onRuntimePlugin
   }) {
     this.appConfig = appConfig;
     this.staticSiteGenerator = staticSiteGenerator;
     this.serveOptions = serveOptions;
-    this.apiHandlers = apiHandlers ?? [];
+    this.runtimeOrigin = runtimeOrigin;
+    this.needsServerBundle = needsServerBundle ?? false;
     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",
@@ -56,39 +68,40 @@ 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();
-    }
-    for (const integration of this.appConfig.integrations) {
-      await integration.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
-   * When the project has API endpoints, the entry file must be bundled
-   * into a single JS file so the production server can start without
-   * on-the-fly TypeScript transpilation. The bundle is output to
-   * `dist/{SERVER_BUNDLE_DIR}/{SERVER_BUNDLE_FILENAME}` and used by
-   * `ecopages start` in production.
+   * Only invoked when the app requires a runtime server (API handlers,
+   * websocket handlers, etc.). Static-only apps skip this step entirely.
+   * 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.
    *
-   * Skips silently when no API endpoints are registered (static-only site).
    * 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() {
-    if (this.apiHandlers.length === 0) {
-      return;
-    }
+  async bundleServerEntry(options) {
     const buildAdapter = getAppBuildAdapter(this.appConfig);
     if (buildAdapter.ownership === "vite-host") {
       throw new Error(
@@ -101,60 +114,71 @@ class ServerStaticBuilder {
         `Cannot bundle server entry: file "${this.entryFile}" not found in "${this.appConfig.rootDir}".`
       );
     }
-    const distDir = this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
-    const serverOutdir = path.join(distDir, SERVER_BUNDLE_DIR);
-    this.logger.info("Bundling server entry file...");
-    const result = await buildAdapter.build({
-      entrypoints: [entryPath],
-      outdir: serverOutdir,
-      naming: SERVER_BUNDLE_FILENAME,
-      target: "node",
-      format: "esm",
-      sourcemap: "hidden",
-      externalPackages: true,
-      root: this.appConfig.rootDir
+    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();
+    if (this.needsServerBundle) {
+      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;
@@ -29,6 +30,7 @@ export declare abstract class SharedHmrManager implements IHmrManager {
     protected readonly browserBundleService: BrowserBundleService;
     protected readonly entrypointDependencyGraph: EntrypointDependencyGraph;
     protected readonly serverModuleTranspiler: ServerModuleTranspiler;
+    private runtimeBuildPromise;
     constructor({ appConfig, bridge, registrationTimeoutMs }: SharedHmrManagerParams);
     protected abstract createEntrypointDependencyGraph(existingEntrypointDependencyGraph: EntrypointDependencyGraph): EntrypointDependencyGraph;
     protected shouldSkipMissingFileChange(_filePath: string): boolean;
@@ -40,11 +42,36 @@ export declare abstract class SharedHmrManager implements IHmrManager {
     setPlugins(plugins: EcoBuildPlugin[]): void;
     setEnabled(enabled: boolean): void;
     isEnabled(): boolean;
+    isRuntimeReady(): boolean;
+    /**
+     * Builds the browser HMR runtime once and reuses the in-flight build for concurrent callers.
+     */
+    ensureRuntimeReady(): Promise<boolean>;
     buildRuntime(): Promise<void>;
     getRuntimePath(): string;
+    private buildRuntimeInternal;
+    /**
+     * @remarks
+     * Rolldown may emit the runtime bundle under a derived filename when the
+     * entrypoint lives outside the app root. The dev server always serves
+     * `/_hmr_runtime.js` from a stable path under `.eco/assets/_hmr/`.
+     */
+    private syncRuntimeOutput;
     broadcast(event: ClientBridgeEvent): void;
     handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
     getOutputUrl(entrypointPath: string): string | undefined;
+    /**
+     * Returns the emitted HMR script output when the entrypoint is already registered
+     * and its browser bundle exists on disk.
+     *
+     * @remarks
+     * Disk artifacts alone are not enough: a fresh dev session must still register
+     * the entrypoint so file watchers can rebuild it on change.
+     */
+    getResolvedScriptOutput(entrypointPath: string): {
+        outputUrl: string;
+        outputPath: string;
+    } | undefined;
     getWatchedFiles(): Map<string, string>;
     getDistDir(): string;
     getPlugins(): EcoBuildPlugin[];
@@ -55,5 +82,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 {};