@ecopages/core 0.2.0-beta.7 → 0.2.0-beta.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.8",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.7",
+    "@ecopages/file-system": "0.2.0-beta.8",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",
@@ -45,6 +45,10 @@
       "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
       "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
+    "./route-renderer/route-renderer": {
+      "types": "./src/route-renderer/route-renderer.d.ts",
+      "default": "./src/route-renderer/route-renderer.js"
+    },
     "./route-renderer/component-render-context": {
       "import": "./src/route-renderer/orchestration/component-render-context.js",
       "types": "./src/route-renderer/orchestration/component-render-context.d.ts",
@@ -117,6 +121,14 @@
       "types": "./src/build/build-adapter.d.ts",
       "default": "./src/build/build-adapter.js"
     },
+    "./build/runtime-build-executor": {
+      "types": "./src/build/runtime-build-executor.d.ts",
+      "default": "./src/build/runtime-build-executor.js"
+    },
+    "./build/server-entry-build-cache": {
+      "types": "./src/build/server-entry-build-cache.d.ts",
+      "default": "./src/build/server-entry-build-cache.js"
+    },
     "./build/runtime-build-output-normalizer": {
       "types": "./src/build/runtime-build-output-normalizer.d.ts",
       "default": "./src/build/runtime-build-output-normalizer.js"
@@ -174,6 +186,10 @@
       "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
       "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
+    "./route-renderer/route-renderer.ts": {
+      "types": "./src/route-renderer/route-renderer.d.ts",
+      "default": "./src/route-renderer/route-renderer.js"
+    },
     "./route-renderer/component-render-context.ts": {
       "import": "./src/route-renderer/orchestration/component-render-context.js",
       "types": "./src/route-renderer/orchestration/component-render-context.d.ts",
@@ -246,6 +262,14 @@
       "types": "./src/build/build-adapter.d.ts",
       "default": "./src/build/build-adapter.js"
     },
+    "./build/runtime-build-executor.ts": {
+      "types": "./src/build/runtime-build-executor.d.ts",
+      "default": "./src/build/runtime-build-executor.js"
+    },
+    "./build/server-entry-build-cache.ts": {
+      "types": "./src/build/server-entry-build-cache.d.ts",
+      "default": "./src/build/server-entry-build-cache.js"
+    },
     "./build/runtime-build-output-normalizer.ts": {
       "types": "./src/build/runtime-build-output-normalizer.d.ts",
       "default": "./src/build/runtime-build-output-normalizer.js"

package/src/adapters/abstract/application-adapter.d.ts

@@ -50,8 +50,9 @@ export interface ApplicationAdapterOptions {
 /**
  * Common interface for application adapters
  */
-export interface ApplicationAdapter<T = any> {
+export interface ApplicationAdapter<T = any> extends AsyncDisposable {
     start(): Promise<T | void>;
+    stop(force?: boolean): Promise<void>;
 }
 /**
  * Handler function type for route handlers
@@ -231,6 +232,16 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
      * Start the application server
      */
     abstract start(): Promise<TServer | void>;
+    /**
+     * Stops the application server and releases runtime resources.
+     *
+     * @remarks
+     * Subclasses override this to shut down bound servers, watchers, and other
+     * dev-time resources. The default implementation is a no-op so embedded
+     * adapters that never call `start()` can still be used with `await using`.
+     */
+    stop(_force?: boolean): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Handles a standard Web request without requiring a bound network server.
      * This is the primary interoperability surface for embedding Ecopages inside

package/src/adapters/abstract/application-adapter.js

@@ -185,6 +185,19 @@ class AbstractApplicationAdapter {
   getErrorHandler() {
     return this.errorHandler;
   }
+  /**
+   * Stops the application server and releases runtime resources.
+   *
+   * @remarks
+   * Subclasses override this to shut down bound servers, watchers, and other
+   * dev-time resources. The default implementation is a no-op so embedded
+   * adapters that never call `start()` can still be used with `await using`.
+   */
+  async stop(_force = true) {
+  }
+  async [Symbol.asyncDispose]() {
+    await this.stop(true);
+  }
 }
 export {
   AbstractApplicationAdapter

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

@@ -31,7 +31,9 @@ export interface ServerAdapterResult {
     }) => any;
     buildStatic: (options?: {
         preview?: boolean;
+        force?: boolean;
     }) => Promise<void>;
+    dispose(): Promise<void>;
 }
 /**
  * Abstract base class for server adapters across different runtimes
@@ -57,6 +59,7 @@ export declare abstract class AbstractServerAdapter<TOptions extends ServerAdapt
      */
     abstract buildStatic(options?: {
         preview?: boolean;
+        force?: boolean;
     }): Promise<void>;
     /**
      * Factory method to create a server adapter with runtime-specific functionality

package/src/adapters/bun/client-bridge.d.ts

@@ -30,5 +30,6 @@ export declare class ClientBridge implements IClientBridge {
      */
     error(message: string): void;
     get subscriberCount(): number;
+    destroy(): void;
 }
 export {};

package/src/adapters/bun/client-bridge.js

@@ -42,6 +42,9 @@ class ClientBridge {
   get subscriberCount() {
     return this.subscribers.size;
   }
+  destroy() {
+    this.subscribers.clear();
+  }
 }
 export {
   ClientBridge

package/src/adapters/bun/create-app.d.ts

@@ -31,6 +31,7 @@ export type BunRouteGroupBuilder<WebSocketData = undefined, TContext extends Api
 export declare class BunEcopagesApp<WebSocketData = undefined> extends SharedApplicationAdapter<EcopagesAppOptions, Server<WebSocketData>, Request> {
     serverAdapter: BunServerAdapterResult | undefined;
     private server;
+    private stopped;
     private readonly runtimeHost;
     private readonly previewHost;
     constructor(options: EcopagesAppOptions, dependencies: {
@@ -56,6 +57,7 @@ export declare class BunEcopagesApp<WebSocketData = undefined> extends SharedApp
      * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
      */
     start(): Promise<Server<WebSocketData> | void>;
+    stop(force?: boolean): Promise<void>;
 }
 /**
  * Factory function to create a Bun application

package/src/adapters/bun/create-app.js

@@ -8,6 +8,7 @@ import { BunRuntimeHost } from "./runtime-host.js";
 class BunEcopagesApp extends SharedApplicationAdapter {
   serverAdapter;
   server = null;
+  stopped = false;
   runtimeHost;
   previewHost;
   constructor(options, dependencies) {
@@ -73,17 +74,21 @@ class BunEcopagesApp extends SharedApplicationAdapter {
    * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
    */
   async start() {
+    if (this.stopped) {
+      this.serverAdapter = void 0;
+      this.stopped = false;
+    }
     if (!this.serverAdapter) {
       this.serverAdapter = await this.initializeServerAdapter();
     }
-    const { dev, preview, build } = this.cliArgs;
+    const { dev, preview, build, force } = this.cliArgs;
     const staticRuntimeMode = resolveStaticRuntimeMode({
       appConfig: this.appConfig,
       cliArgs: this.cliArgs
     });
     if (staticRuntimeMode.canBuildWithoutRuntimeServer) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview });
+      await this.serverAdapter.buildStatic({ preview, force });
       appLogger.debugTimeEnd("Building static pages");
       if (build) {
         process.exit(0);
@@ -94,10 +99,7 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     const serverOptions = this.serverAdapter.getServerOptions({ enableHmr });
     const configuredHostname = String(serverOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME);
     const configuredPort = Number(serverOptions.port ?? DEFAULT_ECOPAGES_PORT);
-    const runtimeServerOptions = (preview || build) && staticRuntimeMode.requiresFetchRuntime ? {
-      ...serverOptions,
-      port: 0
-    } : serverOptions;
+    const runtimeServerOptions = serverOptions;
     this.server = await this.runtimeHost.start({
       serveOptions: runtimeServerOptions,
       handleRequest: async () => new Response(null, { status: 500 }),
@@ -115,8 +117,10 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     );
     if (build || preview) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview: false });
-      await this.runtimeHost.stop(this.server, { force: true });
+      await this.serverAdapter.buildStatic({ preview: false, force });
+      const buildRuntimeServer = this.server;
+      this.server = null;
+      await this.runtimeHost.stop(buildRuntimeServer, { force: true });
       if (preview) {
         const previewPort = await this.previewHost.start({
           appConfig: this.appConfig,
@@ -132,7 +136,22 @@ class BunEcopagesApp extends SharedApplicationAdapter {
         process.exit(0);
       }
     }
-    return this.server;
+    return this.server ?? void 0;
+  }
+  async stop(force = true) {
+    if (this.stopped) {
+      return;
+    }
+    if (this.server) {
+      const activeServer = this.server;
+      this.server = null;
+      await this.runtimeHost.stop(activeServer, { force });
+    }
+    await this.previewHost.stop();
+    if (this.serverAdapter) {
+      await this.serverAdapter.dispose();
+    }
+    this.stopped = true;
   }
 }
 async function createApp(options) {

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

@@ -47,12 +47,14 @@ export interface BunServerAdapterResult extends ServerAdapterResult {
     }) => BunServeOptions;
     buildStatic: (options?: {
         preview?: boolean;
+        force?: boolean;
     }) => Promise<void>;
     completeInitialization: (server?: BunServerInstance | null) => Promise<void>;
     handleRequest: (request: Request) => Promise<Response>;
     attachUserWebSocketUpgrades: (server: NodeHttpServer, options?: {
         passthroughUnmatched?: boolean;
     }) => void;
+    dispose: () => Promise<void>;
 }
 /**
  * Bun transport adapter that wires shared Ecopages request handling onto a live
@@ -76,6 +78,8 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
     private initializationPromise;
     private fullyInitialized;
     serverInstance: BunServerInstance | null;
+    private projectWatcher;
+    private adapterDisposed;
     private readonly previewHost;
     /**
      * Reference to the application-level WebSocket handlers map.
@@ -219,6 +223,7 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      */
     buildStatic(options?: {
         preview?: boolean;
+        force?: boolean;
     }): Promise<void>;
     /**
      * Initializes the server with dynamic routes after server creation.
@@ -240,6 +245,14 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      * @returns Configured adapter with server methods
      */
     createAdapter(): Promise<BunServerAdapterResult>;
+    /**
+     * Releases dev-time resources owned by the adapter.
+     *
+     * @remarks
+     * Safe to call multiple times. Does not stop the bound Bun server — callers
+     * should shut down transport through the runtime host before disposing.
+     */
+    dispose(): Promise<void>;
     /**
      * Handles HTTP requests by passing them securely to the shared core router adapter.
      *

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

@@ -21,6 +21,7 @@ import {
 import { attachNodeHttpWebSocketUpgrades } from "../shared/node-http-websocket-upgrades.js";
 import { createBunUserWebSocketLifecycle } from "../shared/bun-user-websocket-lifecycle.js";
 import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
+import { copyRuntimePublicDirIfChanged } from "../shared/copy-runtime-public-dir.js";
 import { ClientBridge } from "./client-bridge.js";
 import { HmrManager } from "./hmr-manager.js";
 import { BunStaticPreviewHost } from "./static-preview-host.js";
@@ -32,6 +33,8 @@ class BunServerAdapter extends SharedServerAdapter {
   hmrManager;
   initializationPromise = null;
   fullyInitialized = false;
+  projectWatcher = null;
+  adapterDisposed = false;
   previewHost;
   /**
    * Reference to the application-level WebSocket handlers map.
@@ -194,7 +197,9 @@ class BunServerAdapter extends SharedServerAdapter {
   async initialize() {
     installAppRuntimeBuildExecutor(this.appConfig);
     this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
-    await this.hmrManager.buildRuntime();
+    if (this.options?.watch) {
+      await this.hmrManager.buildRuntime();
+    }
     this.prepareRuntimePublicDir();
     const staticBuilderOptions = {
       appConfig: this.appConfig,
@@ -212,7 +217,7 @@ class BunServerAdapter extends SharedServerAdapter {
   prepareRuntimePublicDir() {
     const srcPublicDir = path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.publicDir);
     if (fileSystem.exists(srcPublicDir)) {
-      fileSystem.copyDir(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
+      copyRuntimePublicDirIfChanged(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
     }
     fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
   }
@@ -276,6 +281,7 @@ class BunServerAdapter extends SharedServerAdapter {
       hmrManager: this.hmrManager,
       bridge: this.bridge
     });
+    this.projectWatcher = watcher;
     await watcher.createWatcherSubscription();
   }
   /**
@@ -500,7 +506,7 @@ class BunServerAdapter extends SharedServerAdapter {
         hmrManager: this.hmrManager
       });
     }
-    const buildRuntimeOrigin = this.serverInstance ? `http://${this.serverInstance.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serverInstance.port || DEFAULT_ECOPAGES_PORT}` : void 0;
+    const buildRuntimeOrigin = resolveServeRuntimeOrigin(this.serveOptions);
     await this.staticBuilder.build(
       { ...options, preview: false, baseUrl: buildRuntimeOrigin },
       {
@@ -575,9 +581,28 @@ class BunServerAdapter extends SharedServerAdapter {
       buildStatic: this.buildStatic.bind(this),
       completeInitialization: this.completeInitialization.bind(this),
       handleRequest: this.handleRequest.bind(this),
-      attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this)
+      attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this),
+      dispose: this.dispose.bind(this)
     };
   }
+  /**
+   * Releases dev-time resources owned by the adapter.
+   *
+   * @remarks
+   * Safe to call multiple times. Does not stop the bound Bun server — callers
+   * should shut down transport through the runtime host before disposing.
+   */
+  async dispose() {
+    if (this.adapterDisposed) {
+      return;
+    }
+    this.adapterDisposed = true;
+    await this.projectWatcher?.close();
+    this.projectWatcher = null;
+    this.hmrManager?.stop();
+    this.bridge?.destroy();
+    await this.previewHost.stop();
+  }
   /**
    * Handles HTTP requests by passing them securely to the shared core router adapter.
    *

package/src/adapters/create-app.d.ts

@@ -2,8 +2,20 @@ import type { EcoPagesAppConfig } from '../types/internal-types.js';
 import { AbstractApplicationAdapter } from './abstract/application-adapter.js';
 import type { ApplicationAdapterOptions } from './abstract/application-adapter.js';
 import { SharedApplicationAdapter } from './shared/application-adapter.js';
+export type EcopagesRuntimeAdapter = 'auto' | 'node' | 'bun';
 export interface EcopagesAppOptions extends ApplicationAdapterOptions {
     appConfig: EcoPagesAppConfig;
+    /**
+     * Selects the runtime adapter used by the universal `createApp()` entrypoint.
+     *
+     * @default 'auto'
+     *
+     * @remarks
+     * This is separate from `runtime`, which configures embedded host behavior.
+     * Use `auto` to select Bun when the current process exposes `globalThis.Bun`
+     * and Node otherwise.
+     */
+    adapter?: EcopagesRuntimeAdapter;
     serverOptions?: Record<string, any>;
 }
 export type UniversalEcopagesApp = AbstractApplicationAdapter<EcopagesAppOptions, unknown, Request>;
@@ -17,4 +29,5 @@ export declare class EcopagesApp extends SharedApplicationAdapter<EcopagesAppOpt
     protected initializeServerAdapter(): Promise<UniversalEcopagesApp>;
     start(): Promise<unknown>;
     fetch(request: Request): Promise<Response>;
+    stop(force?: boolean): Promise<void>;
 }

package/src/adapters/create-app.js

@@ -3,8 +3,9 @@ import { SharedApplicationAdapter } from "./shared/application-adapter.js";
 import { createApp as createBunApp } from "./bun/create-app.js";
 import { createNodeApp } from "./node/create-app.js";
 async function createRuntimeApp(options) {
+  const adapter = options.adapter ?? "auto";
   const bun = globalThis.Bun;
-  if (bun) {
+  if (adapter === "bun" || adapter === "auto" && bun) {
     return await createBunApp(options);
   }
   return await createNodeApp(options);
@@ -59,6 +60,14 @@ class EcopagesApp extends SharedApplicationAdapter {
     }
     return candidate.fetch(request);
   }
+  async stop(force = true) {
+    const runtimeApp = this.runtimeApp ?? (this.runtimeAppPromise ? await this.runtimeAppPromise : null);
+    if (runtimeApp) {
+      await runtimeApp.stop(force);
+    }
+    this.runtimeApp = null;
+    this.runtimeAppPromise = null;
+  }
 }
 export {
   EcopagesApp,

package/src/adapters/node/create-app.d.ts

@@ -7,6 +7,7 @@ export declare class NodeEcopagesApp extends SharedApplicationAdapter<EcopagesAp
     serverAdapter: NodeServerAdapterResult | undefined;
     private server;
     private runtimeOrigin;
+    private stopped;
     private readonly runtimeHost;
     constructor(options: EcopagesAppOptions, dependencies: {
         runtimeHost: RuntimeHost<NodeServerInstance, {

package/src/adapters/node/create-app.js

@@ -8,6 +8,7 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
   serverAdapter;
   server = null;
   runtimeOrigin = "";
+  stopped = false;
   runtimeHost;
   constructor(options, dependencies) {
     super(options);
@@ -17,12 +18,18 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
     return createNodeServerAdapter(params);
   }
   async stop(force = true) {
-    if (!this.server) {
+    if (this.stopped) {
       return;
     }
-    const activeServer = this.server;
-    this.server = null;
-    await this.runtimeHost.stop(activeServer, { force });
+    if (this.server) {
+      const activeServer = this.server;
+      this.server = null;
+      await this.runtimeHost.stop(activeServer, { force });
+    }
+    if (this.serverAdapter) {
+      await this.serverAdapter.dispose();
+    }
+    this.stopped = true;
   }
   async initializeServerAdapter() {
     const binding = resolveRuntimeBinding({
@@ -42,17 +49,20 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
     });
   }
   async start() {
+    if (this.stopped) {
+      this.serverAdapter = void 0;
+      this.stopped = false;
+    }
     if (!this.serverAdapter) {
       this.serverAdapter = await this.initializeServerAdapter();
     }
     if (this.server) {
       return this.server;
     }
-    const { build, preview } = this.cliArgs;
+    const { build, preview, force } = this.cliArgs;
     if (build || preview) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview });
-      await this.stop(true);
+      await this.serverAdapter.buildStatic({ preview, force });
       appLogger.debugTimeEnd("Building static pages");
       if (build) {
         process.exit(0);

package/src/adapters/node/node-client-bridge.d.ts

@@ -23,4 +23,5 @@ export declare class NodeClientBridge implements IClientBridge {
      * Call this when the dev server is shutting down.
      */
     destroy(): void;
+    [Symbol.dispose](): void;
 }

package/src/adapters/node/node-client-bridge.js

@@ -60,6 +60,9 @@ class NodeClientBridge {
     }
     this.subscribers.clear();
   }
+  [Symbol.dispose]() {
+    this.destroy();
+  }
 }
 export {
   NodeClientBridge

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

@@ -33,6 +33,7 @@ export interface NodeServerAdapterResult extends ServerAdapterResult {
     attachUserWebSocketUpgrades: (server: NodeServerInstance, options?: {
         passthroughUnmatched?: boolean;
     }) => void;
+    dispose: () => Promise<void>;
 }
 /**
  * Node.js HTTP server adapter for the Ecopages runtime.
@@ -62,6 +63,8 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
     private errorHandler?;
     private bridge;
     private hmrManager;
+    private projectWatcher;
+    private adapterDisposed;
     private readonly previewHost;
     private readonly requestBridge;
     private readonly devRuntimeFactory;
@@ -106,23 +109,17 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
     getServerOptions(): NodeServeAdapterServerOptions;
     buildStatic(options?: {
         preview?: boolean;
+        force?: boolean;
     }): Promise<void>;
-    private startBuildRuntimeServer;
-    private getListeningServerOrigin;
+    createAdapter(): Promise<NodeServerAdapterResult>;
     /**
-     * Gracefully shuts down the ephemeral build runtime server.
-     *
-     * `closeAllConnections()` is called *before* `close()` because `server.close()`
-     * only stops accepting new connections — it waits for existing keep-alive
-     * connections to finish naturally, which can stall the build indefinitely.
-     * `closeAllConnections()` force-closes any lingering sockets immediately so
-     * the `close()` callback fires promptly.
+     * Releases dev-time resources owned by the adapter.
      *
-     * The `NodeClientBridge` heartbeat is also destroyed here so its `setInterval`
-     * does not prevent the Node.js process from exiting cleanly after the build.
+     * @remarks
+     * Safe to call multiple times. Does not stop the bound HTTP server — callers
+     * should shut down transport through the runtime host before disposing.
      */
-    private stopBuildRuntimeServer;
-    createAdapter(): Promise<NodeServerAdapterResult>;
+    dispose(): Promise<void>;
     /**
      * Handles a single incoming Web `Request` and returns a Web `Response`.
      *