@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.28

package/CHANGELOG.md

@@ -13,6 +13,24 @@ All notable changes to `@ecopages/core` are documented here.
 
 ### Refactoring
 
+- Renamed route-renderer ownership and foreign-child contracts across core so ownership planning, foreign-subtree payloads, and queued foreign-subtree resolution now use the simplified terminology.
+- Introduced a single `RouteRenderFlow` owner for route render preparation and execution, removing the separate execution service seam while keeping boundary planning shared.
+- Narrowed route-render orchestration onto an explicit `RouteRenderFlowAdapter` seam and one structural Html finalization plan, reducing callback-bag plumbing between `RouteRenderFlow` and `IntegrationRenderer`.
+- Renamed renderer-owned page browser asset preparation onto an explicit `buildPageBrowserGraph()` seam so route orchestration no longer treats emitted browser dependencies as a flat route-asset append.
+- Removed the generic HMR runtime-specifier registry and plugin registration seam so core no longer carries import-map-era runtime state that integrations no longer use.
+- Moved foreign-boundary ownership validation out of boundary-plan construction so route root graphs are validated before dependency and data preparation.
+- Moved page-package classification into the asset-processing module so render orchestration no longer carries a dedicated packaging service wrapper.
+- Split file-route page middleware onto its own context contract so page middleware no longer exposes handler-only `ctx.render()` helpers and the pipeline stops carrying fake render traps.
+- Narrowed route-renderer consumers onto explicit resolver contracts, moved filesystem custom 404 rendering back under the filesystem matcher, and shared explicit static render preparation between runtime and static generation.
+
+- Added the `@ecopages/core/dev/host-runtime` seam so host integrations such as the Vite plugin use one explicit development bridge instead of importing host-module-loader and invalidation internals directly.
+- Moved extension-facing merge and assertion helpers behind the integration and processor plugin entrypoints so MDX and image processing no longer depend on raw `utils/deep-merge` or `utils/invariant` package paths.
+- Re-exported shared build-plugin authoring types through the integration and processor plugin entrypoints so extension packages depend on plugin surfaces instead of the raw `build/build-types` module.
+- Removed the legacy `@ecopages/core/errors/locals-access-error` and `@ecopages/core/adapters/bun/client-bridge` exports after moving their remaining consumers to the public `errors` and root type surfaces.
+- Removed the unused `@ecopages/core/utils/parse-cli-args` and `@ecopages/core/services/module-loading/app-server-module-transpiler.service` exports from the published package surface.
+- Removed the unused `@ecopages/core/bun/create-app` and `@ecopages/core/route-renderer/template-serialization` exports to keep the published package surface aligned with the documented entrypoints.
+- Removed the legacy `@ecopages/core/internal-types` export now that the public root package exposes the supported `EcoPagesAppConfig` contract.
+- Removed the duplicate `@ecopages/core/router/client/navigation-coordinator` export in favor of the canonical `@ecopages/core/router/navigation-coordinator` subpath.
 - Bundled page-local component stylesheets and standard file scripts into page-owned assets before processing, reducing per-page asset fan-out in emitted HTML.
 - Grouped Ecopages JSX page and lazy dependency entries into one multi-entry browser build so shared chunks can be emitted once without relying on the runtime alias vendor path.
 - Removed the transitional flat dependency write from render preparation so final HTML injection now follows the structured page-package path only.
@@ -22,9 +40,14 @@ All notable changes to `@ecopages/core` are documented here.
 - Moved shared queued boundary resolution to attachment-policy payloads and constructor-injectable planning services.
 - Extracted shared page, layout, and document-shell composition into a narrow `RouteShellComposer` while keeping renderer-owned boundary handoff in `IntegrationRenderer`.
 - Removed marker-era compatibility capture, the shared route-level fallback resolver, deprecated `@ecopages/core/node*` escape hatches, and other dead route-renderer internals.
+- Replaced the split `FSRouter` and `FSRouterScanner` flow with one `RouteRegistry` seam for filesystem route discovery, request matching, and static-generation planning.
 
 ### Bug Fixes
 
+- Fixed integration registry typing so `ConfigBuilder.setIntegrations()` accepts heterogeneous framework plugins without rejecting valid JSX or React integrations at type-check time.
+- Fixed page-owned dependency packaging so final Html output suppresses bundled source stylesheet assets that were reintroduced later during shell-time asset merging.
+- Fixed development page dependency packaging so script Dependencies stay source-backed for HMR instead of being collapsed into one page-owned script bundle.
+- Fixed Bun preview builds to start the static preview server only after static generation releases the live build server port, preventing preview mode from double-binding the configured port.
 - Fixed router-owned HMR current-page reloads to clear persisted layout caches so active shared layouts pick up updated implementations during development.
 - Fixed router-owned HMR layout refreshes to reuse the active HMR page entry instead of stale static bootstrap assets during persisted-layout reloads.
 - Fixed fetch-mode static generation to normalize absolute routes onto the active build runtime origin, restoring preview prerendering for routes discovered from absolute router entries.
@@ -50,12 +73,14 @@ All notable changes to `@ecopages/core` are documented here.
 ### Documentation
 
 - Added architecture and API documentation for config, plugins, services, adapters, HMR, routing, and rendering.
+- Documented that Html-owned dependency assets stay shared while page, layout, and component dependency assets are packaged per route.
 
 ### Tests
 
 - Added regression coverage for app-owned runtime services, Node fallback paths, and cross-runtime invalidation behavior.
 - Strengthened the core ghtml integration tests so route and explicit render paths await real outcomes and cover `renderToResponse` behavior.
 - Added core regression coverage for boundary plans, payload contracts, and typed mixed-boundary context flow.
+- Added router and static-generation regression coverage for `RouteRegistry`, explicit static route expansion, and file-response fallbacks.
 
 ---
 

package/README.md

@@ -31,14 +31,14 @@ flowchart TD
 	B --> D[App build manifest]
 	B --> E[Build executor]
 	B --> F[Dev graph service]
-	B --> G[Runtime specifier registry]
-	B --> H[Host module loader boundary]
-	H --> I[PageModuleImportService]
+	B --> G[Host module loader boundary]
+	G --> H[PageModuleImportService]
+	E --> H
 	E --> I
-	E --> J[BrowserBundleService]
-	I --> K[Runtime app adapter]
-	K --> L[Bun adapter or Node adapter]
-	D --> J
+	E --> I[BrowserBundleService]
+	H --> J[Runtime app adapter]
+	J --> K[Bun adapter or Node adapter]
+	D --> I
 ```
 
 ### Development Invalidation And HMR Flow
@@ -178,6 +178,12 @@ export const MyButton = eco.component({
 });
 ```
 
+Dependency ownership affects final asset packaging:
+
+- Stylesheets and scripts declared from `eco.html()` stay Html-owned and can be emitted as shared app-wide assets.
+- Stylesheets and scripts declared from Pages, Layouts, or Components are resolved into page-owned assets for the rendered route.
+- This split is intentional. Shared Html assets can be cached across routes, while page-owned assets can change without invalidating the global shell.
+
 ### 5. API Handlers
 
 Add server-side routes using `defineApiHandler`. Register them on your `app` instance before starting:
@@ -228,3 +234,53 @@ import { defineApiHandler, defineGroupHandler, eco } from '@ecopages/core';
 Use runtime-specific subpaths only when you explicitly need Bun-native APIs that bypass the universal abstractions:
 
 - `@ecopages/core/bun`
+
+## Entry Point Roles
+
+The published subpaths are grouped by architectural role rather than by source folder.
+
+### App Authoring
+
+Use these entrypoints when building an Ecopages app:
+
+- `@ecopages/core`
+- `@ecopages/core/create-app`
+- `@ecopages/core/config-builder`
+- `@ecopages/core/errors`
+- `@ecopages/core/html`
+- `@ecopages/core/hash`
+- `@ecopages/core/declarations`
+- `@ecopages/core/env`
+- `@ecopages/core/bun`
+
+### Browser Navigation
+
+Use these entrypoints when a browser runtime needs to coordinate document ownership and link intent:
+
+- `@ecopages/core/router/navigation-coordinator`
+- `@ecopages/core/router/link-intent`
+
+### Extension Authoring
+
+Use these entrypoints when implementing integrations, processors, or source transforms:
+
+- `@ecopages/core/plugins/integration-plugin`
+- `@ecopages/core/plugins/processor`
+- `@ecopages/core/plugins/source-transform`
+- `@ecopages/core/route-renderer/integration-renderer`
+- `@ecopages/core/services/asset-processing-service`
+- `@ecopages/core/hmr/hmr-strategy`
+- `@ecopages/core/integrations/ghtml`
+
+### Host And Runtime Composition
+
+Use these entrypoints only when implementing host adapters or framework-owned bundling seams:
+
+- `@ecopages/core/dev/host-runtime`
+- `@ecopages/core/build/build-adapter`
+- `@ecopages/core/build/build-types`
+- `@ecopages/core/build/runtime-specifier-alias-plugin`
+- `@ecopages/core/build/runtime-specifier-aliases`
+- `@ecopages/core/plugins/foreign-jsx-override-plugin`
+
+These host-facing entrypoints are narrower compatibility seams. App code and most extensions should prefer the app-authoring or extension-authoring surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.26",
+  "version": "0.2.0-alpha.28",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.26",
+    "@ecopages/file-system": "0.2.0-alpha.28",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.3",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",
@@ -51,23 +51,11 @@
       "types": "./src/router/client/link-intent.d.ts",
       "default": "./src/router/client/link-intent.js"
     },
-    "./router/client/navigation-coordinator": {
-      "types": "./src/router/client/navigation-coordinator.d.ts",
-      "default": "./src/router/client/navigation-coordinator.js"
-    },
-    "./errors/locals-access-error": {
-      "types": "./src/errors/locals-access-error.d.ts",
-      "default": "./src/errors/locals-access-error.js"
-    },
     "./eco": {
       "browser": "./src/eco/eco.browser.js",
       "types": "./src/eco/eco.d.ts",
       "default": "./src/eco/eco.js"
     },
-    "./route-renderer/template-serialization": {
-      "types": "./src/route-renderer/orchestration/template-serialization.d.ts",
-      "default": "./src/route-renderer/orchestration/template-serialization.js"
-    },
     "./declarations": {
       "types": "./src/declarations.d.ts"
     },
@@ -86,45 +74,18 @@
       "types": "./src/adapters/bun/index.d.ts",
       "default": "./src/adapters/bun/index.js"
     },
-    "./bun/create-app": {
-      "types": "./src/adapters/bun/create-app.d.ts",
-      "default": "./src/adapters/bun/create-app.js"
-    },
     "./hmr/hmr-strategy": {
       "types": "./src/hmr/hmr-strategy.d.ts",
       "default": "./src/hmr/hmr-strategy.js"
     },
-    "./internal-types": {
-      "types": "./src/types/internal-types.d.ts"
+    "./dev/host-runtime": {
+      "types": "./src/dev/host-runtime.d.ts",
+      "default": "./src/dev/host-runtime.js"
     },
     "./services/asset-processing-service": {
       "types": "./src/services/assets/asset-processing-service/index.d.ts",
       "default": "./src/services/assets/asset-processing-service/index.js"
     },
-    "./services/invalidation/development-invalidation.service": {
-      "types": "./src/services/invalidation/development-invalidation.service.d.ts",
-      "default": "./src/services/invalidation/development-invalidation.service.js"
-    },
-    "./services/module-loading/app-server-module-transpiler.service": {
-      "types": "./src/services/module-loading/app-server-module-transpiler.service.d.ts",
-      "default": "./src/services/module-loading/app-server-module-transpiler.service.js"
-    },
-    "./host-module-loader": {
-      "types": "./src/services/module-loading/host-module-loader-registry.d.ts",
-      "default": "./src/services/module-loading/host-module-loader-registry.js"
-    },
-    "./utils/deep-merge": {
-      "types": "./src/utils/deep-merge.d.ts",
-      "default": "./src/utils/deep-merge.js"
-    },
-    "./utils/invariant": {
-      "types": "./src/utils/invariant.d.ts",
-      "default": "./src/utils/invariant.js"
-    },
-    "./utils/parse-cli-args": {
-      "types": "./src/utils/parse-cli-args.d.ts",
-      "default": "./src/utils/parse-cli-args.js"
-    },
     "./plugins/processor": {
       "types": "./src/plugins/processor.d.ts",
       "default": "./src/plugins/processor.js"
@@ -157,10 +118,6 @@
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
       "default": "./src/plugins/foreign-jsx-override-plugin.js"
     },
-    "./adapters/bun/client-bridge": {
-      "types": "./src/adapters/bun/client-bridge.d.ts",
-      "default": "./src/adapters/bun/client-bridge.js"
-    },
     "./html": {
       "import": "./src/utils/html.js",
       "default": "./src/utils/html.js",
@@ -196,23 +153,11 @@
       "types": "./src/router/client/link-intent.d.ts",
       "default": "./src/router/client/link-intent.js"
     },
-    "./router/client/navigation-coordinator.ts": {
-      "types": "./src/router/client/navigation-coordinator.d.ts",
-      "default": "./src/router/client/navigation-coordinator.js"
-    },
-    "./errors/locals-access-error.ts": {
-      "types": "./src/errors/locals-access-error.d.ts",
-      "default": "./src/errors/locals-access-error.js"
-    },
     "./eco.ts": {
       "browser": "./src/eco/eco.browser.js",
       "types": "./src/eco/eco.d.ts",
       "default": "./src/eco/eco.js"
     },
-    "./route-renderer/template-serialization.ts": {
-      "types": "./src/route-renderer/orchestration/template-serialization.d.ts",
-      "default": "./src/route-renderer/orchestration/template-serialization.js"
-    },
     "./declarations.ts": {
       "types": "./src/declarations.d.ts"
     },
@@ -231,45 +176,18 @@
       "types": "./src/adapters/bun/index.d.ts",
       "default": "./src/adapters/bun/index.js"
     },
-    "./bun/create-app.ts": {
-      "types": "./src/adapters/bun/create-app.d.ts",
-      "default": "./src/adapters/bun/create-app.js"
-    },
     "./hmr/hmr-strategy.ts": {
       "types": "./src/hmr/hmr-strategy.d.ts",
       "default": "./src/hmr/hmr-strategy.js"
     },
-    "./internal-types.ts": {
-      "types": "./src/types/internal-types.d.ts"
+    "./dev/host-runtime.ts": {
+      "types": "./src/dev/host-runtime.d.ts",
+      "default": "./src/dev/host-runtime.js"
     },
     "./services/asset-processing-service.ts": {
       "types": "./src/services/assets/asset-processing-service/index.d.ts",
       "default": "./src/services/assets/asset-processing-service/index.js"
     },
-    "./services/invalidation/development-invalidation.service.ts": {
-      "types": "./src/services/invalidation/development-invalidation.service.d.ts",
-      "default": "./src/services/invalidation/development-invalidation.service.js"
-    },
-    "./services/module-loading/app-server-module-transpiler.service.ts": {
-      "types": "./src/services/module-loading/app-server-module-transpiler.service.d.ts",
-      "default": "./src/services/module-loading/app-server-module-transpiler.service.js"
-    },
-    "./host-module-loader.ts": {
-      "types": "./src/services/module-loading/host-module-loader-registry.d.ts",
-      "default": "./src/services/module-loading/host-module-loader-registry.js"
-    },
-    "./utils/deep-merge.ts": {
-      "types": "./src/utils/deep-merge.d.ts",
-      "default": "./src/utils/deep-merge.js"
-    },
-    "./utils/invariant.ts": {
-      "types": "./src/utils/invariant.d.ts",
-      "default": "./src/utils/invariant.js"
-    },
-    "./utils/parse-cli-args.ts": {
-      "types": "./src/utils/parse-cli-args.d.ts",
-      "default": "./src/utils/parse-cli-args.js"
-    },
     "./plugins/processor.ts": {
       "types": "./src/plugins/processor.d.ts",
       "default": "./src/plugins/processor.js"
@@ -302,10 +220,6 @@
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
       "default": "./src/plugins/foreign-jsx-override-plugin.js"
     },
-    "./adapters/bun/client-bridge.ts": {
-      "types": "./src/adapters/bun/client-bridge.d.ts",
-      "default": "./src/adapters/bun/client-bridge.js"
-    },
     "./html.ts": {
       "import": "./src/utils/html.js",
       "default": "./src/utils/html.js",

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

@@ -29,6 +29,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 startStaticPreviewServer;
     fetch(request: Request): Promise<Response>;
     /**
      * Complete the initialization of the server adapter by processing dynamic routes

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

@@ -1,4 +1,5 @@
 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 { getBunRuntime } from "../../utils/runtime.js";
 import { SharedApplicationAdapter } from "../shared/application-adapter.js";
@@ -6,6 +7,31 @@ import { createBunServerAdapter } from "./server-adapter.js";
 class BunEcopagesApp extends SharedApplicationAdapter {
   serverAdapter;
   server = null;
+  async startStaticPreviewServer(port, hostname) {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      try {
+        const previewServer = StaticContentServer.createServer({
+          appConfig: this.appConfig,
+          options: { port }
+        });
+        if (previewServer.server?.port) {
+          appLogger.info(`Preview running at http://${hostname}:${previewServer.server.port}`);
+          return;
+        }
+        break;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorCode = typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
+        const isPortReleaseRace = errorCode === "EADDRINUSE" || errorMessage.includes("EADDRINUSE");
+        if (!isPortReleaseRace || attempt === 19) {
+          throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+    }
+    appLogger.error("Failed to start preview server");
+  }
   async fetch(request) {
     if (!this.serverAdapter) {
       this.serverAdapter = await this.initializeServerAdapter();
@@ -82,11 +108,17 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     }
     const enableHmr = dev || !preview && !build;
     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) && requiresFetchRuntime ? {
+      ...serverOptions,
+      port: 0
+    } : serverOptions;
     const bun = getBunRuntime();
     if (!bun) {
       throw new Error("Bun runtime is required for the Bun adapter");
     }
-    const bunServer = bun.serve(serverOptions);
+    const bunServer = bun.serve(runtimeServerOptions);
     this.server = bunServer;
     await this.serverAdapter.completeInitialization(this.server).catch((error) => {
       appLogger.error(`Failed to complete initialization: ${error}`);
@@ -97,8 +129,13 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     appLogger.info(`Server running at http://${this.server.hostname}:${this.server.port}`);
     if (build || preview) {
       appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview });
+      await this.serverAdapter.buildStatic({ preview: false });
       this.server.stop(true);
+      if (preview) {
+        const previewHostname = configuredHostname;
+        const previewPort = configuredPort;
+        await this.startStaticPreviewServer(previewPort, previewHostname);
+      }
       appLogger.debugTimeEnd("Building static pages");
       if (build) {
         process.exit(0);

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

@@ -36,7 +36,6 @@ export declare class HmrManager implements IHmrManager {
     private readonly entrypointRegistrar;
     private readonly browserBundleService;
     private readonly entrypointDependencyGraph;
-    private readonly runtimeSpecifierRegistry;
     private readonly serverModuleTranspiler;
     private wsHandler;
     constructor({ appConfig, bridge }: HmrManagerParams);
@@ -70,16 +69,6 @@ export declare class HmrManager implements IHmrManager {
     setPlugins(plugins: EcoBuildPlugin[]): void;
     setEnabled(enabled: boolean): void;
     isEnabled(): boolean;
-    /**
-     * Registers runtime bare-specifier mappings exposed by integrations.
-     *
-     * @remarks
-     * These mappings are consumed by framework-owned HMR strategies that preserve
-     * shared runtime imports in browser bundles. The registry stays generic so
-     * these mappings can later support broader import-map-style runtime features
-     * without moving integration semantics into core.
-     */
-    registerSpecifierMap(map: Record<string, string>): void;
     getWebSocketHandler(): BunSocketHandler;
     /**
      * Builds the client-side HMR runtime script.
@@ -90,7 +79,6 @@ export declare class HmrManager implements IHmrManager {
     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;
@@ -136,7 +124,7 @@ export declare class HmrManager implements IHmrManager {
      * @remarks
      * Emitted `_hmr` files remain on disk because parallel app processes may share
      * the same dist directory. The in-memory indexes are cleared so stale
-     * entrypoints and specifier maps cannot leak through a reused manager object.
+     * entrypoints cannot leak through a reused manager object.
      */
     stop(): void;
 }

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

@@ -15,7 +15,6 @@ import {
   NoopEntrypointDependencyGraph,
   setAppEntrypointDependencyGraph
 } from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
-import { getAppRuntimeSpecifierRegistry } from "../../services/runtime-state/runtime-specifier-registry.service.js";
 import { resolveInternalExecutionDir, resolveInternalWorkDir } from "../../utils/resolve-work-dir.js";
 class HmrManager {
   static entrypointRegistrationTimeoutMs = 4e3;
@@ -33,7 +32,6 @@ class HmrManager {
   entrypointRegistrar;
   browserBundleService;
   entrypointDependencyGraph;
-  runtimeSpecifierRegistry;
   serverModuleTranspiler;
   wsHandler;
   constructor({ appConfig, bridge }) {
@@ -52,7 +50,6 @@ class HmrManager {
     const existingEntrypointDependencyGraph = getAppEntrypointDependencyGraph(appConfig);
     this.entrypointDependencyGraph = existingEntrypointDependencyGraph instanceof NoopEntrypointDependencyGraph ? existingEntrypointDependencyGraph : new NoopEntrypointDependencyGraph();
     setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
-    this.runtimeSpecifierRegistry = getAppRuntimeSpecifierRegistry(this.appConfig);
     this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
     this.cleanDistDir();
     this.initializeStrategies();
@@ -94,7 +91,6 @@ class HmrManager {
   initializeStrategies() {
     const jsContext = {
       getWatchedFiles: () => this.watchedFiles,
-      getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
       getDistDir: () => this.distDir,
       getPlugins: () => this.plugins,
       getSrcDir: () => this.appConfig.absolutePaths.srcDir,
@@ -124,18 +120,6 @@ class HmrManager {
   isEnabled() {
     return this.enabled;
   }
-  /**
-   * Registers runtime bare-specifier mappings exposed by integrations.
-   *
-   * @remarks
-   * These mappings are consumed by framework-owned HMR strategies that preserve
-   * shared runtime imports in browser bundles. The registry stays generic so
-   * these mappings can later support broader import-map-style runtime features
-   * without moving integration semantics into core.
-   */
-  registerSpecifierMap(map) {
-    this.runtimeSpecifierRegistry.register(map);
-  }
   getWebSocketHandler() {
     const open = (ws) => {
       this.bridge.subscribe(ws);
@@ -211,9 +195,6 @@ class HmrManager {
   getWatchedFiles() {
     return this.watchedFiles;
   }
-  getSpecifierMap() {
-    return this.runtimeSpecifierRegistry.getAll();
-  }
   getDistDir() {
     return this.distDir;
   }
@@ -223,7 +204,6 @@ class HmrManager {
   getDefaultContext() {
     return {
       getWatchedFiles: () => this.watchedFiles,
-      getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
       getDistDir: () => this.distDir,
       getPlugins: () => this.plugins,
       getSrcDir: () => this.appConfig.absolutePaths.srcDir,
@@ -314,7 +294,7 @@ class HmrManager {
    * @remarks
    * Emitted `_hmr` files remain on disk because parallel app processes may share
    * the same dist directory. The in-memory indexes are cleared so stale
-   * entrypoints and specifier maps cannot leak through a reused manager object.
+   * entrypoints cannot leak through a reused manager object.
    */
   stop() {
     this.entrypointRegistrations.clear();
@@ -323,7 +303,6 @@ class HmrManager {
     }
     this.watchers.clear();
     this.watchedFiles.clear();
-    this.runtimeSpecifierRegistry.clear();
     this.entrypointDependencyGraph.reset();
     this.plugins = [];
   }

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

@@ -6,6 +6,7 @@ import { fileSystem } from "@ecopages/file-system";
 import { SharedServerAdapter } from "../shared/server-adapter.js";
 import { ApiResponseBuilder } from "../shared/api-response.js";
 import { installSharedRuntimeBuildExecutor } from "../shared/runtime-bootstrap.js";
+import { StaticContentServer } from "../../dev/sc-server.js";
 import { ServerRouteHandler } from "../shared/server-route-handler.js";
 import { ServerStaticBuilder } from "../shared/server-static-builder.js";
 import {
@@ -253,11 +254,29 @@ class BunServerAdapter extends SharedServerAdapter {
         hmrManager: this.hmrManager
       });
     }
-    await this.staticBuilder.build(options, {
-      router: this.router,
-      routeRendererFactory: this.routeRendererFactory,
-      staticRoutes: this.staticRoutes
+    const buildRuntimeOrigin = this.serverInstance ? `http://${this.serverInstance.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serverInstance.port || DEFAULT_ECOPAGES_PORT}` : void 0;
+    await this.staticBuilder.build(
+      { ...options, preview: false, baseUrl: buildRuntimeOrigin },
+      {
+        router: this.router,
+        routeRendererFactory: this.routeRendererFactory,
+        staticRoutes: this.staticRoutes
+      }
+    );
+    if (!options?.preview) {
+      return;
+    }
+    const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
+    const previewPort = Number(this.serveOptions.port || DEFAULT_ECOPAGES_PORT);
+    const previewServer = StaticContentServer.createServer({
+      appConfig: this.appConfig,
+      options: { port: previewPort }
     });
+    if (previewServer.server?.port) {
+      appLogger.info(`Preview running at http://${previewHostname}:${previewServer.server.port}`);
+      return;
+    }
+    appLogger.error("Failed to start preview server");
   }
   /**
    * Initializes the server with dynamic routes after server creation.

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

@@ -36,7 +36,6 @@ export declare class NodeHmrManager implements IHmrManager {
     private readonly entrypointRegistrar;
     private readonly browserBundleService;
     private readonly entrypointDependencyGraph;
-    private readonly runtimeSpecifierRegistry;
     private readonly serverModuleTranspiler;
     constructor({ appConfig, bridge }: NodeHmrManagerParams);
     /**
@@ -60,23 +59,12 @@ export declare class NodeHmrManager implements IHmrManager {
     setPlugins(plugins: EcoBuildPlugin[]): void;
     setEnabled(enabled: boolean): void;
     isEnabled(): boolean;
-    /**
-     * Registers runtime bare-specifier mappings exposed by integrations.
-     *
-     * @remarks
-     * These mappings are consumed by framework-owned HMR strategies such as the
-     * React integration strategy when they rewrite browser bundles. The registry
-     * stays generic so the same mappings can support broader import-map-style
-     * runtime features later without moving integration semantics into core.
-     */
-    registerSpecifierMap(map: Record<string, string>): void;
     buildRuntime(): Promise<void>;
     getRuntimePath(): string;
     broadcast(event: ClientBridgeEvent): 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;
@@ -125,8 +113,8 @@ export declare class NodeHmrManager implements IHmrManager {
      * @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, dependencies, and
-     * specifier maps cannot leak across a reused manager instance.
+     * runs. It does clear in-memory indexes so old entrypoints and dependencies
+     * cannot leak across a reused manager instance.
      */
     stop(): void;
 }