@ecopages/core 0.2.0-alpha.50 → 0.2.0-alpha.52

package/README.md

@@ -280,7 +280,6 @@ Use these entrypoints only when implementing host adapters or framework-owned bu
 - `@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.50",
+  "version": "0.2.0-alpha.52",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.50",
+    "@ecopages/file-system": "0.2.0-alpha.52",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",
@@ -115,14 +115,18 @@
       "types": "./src/build/build-adapter.d.ts",
       "default": "./src/build/build-adapter.js"
     },
+    "./build/browser-runtime-manifest": {
+      "types": "./src/build/browser-runtime-manifest.d.ts",
+      "default": "./src/build/browser-runtime-manifest.js"
+    },
+    "./build/browser-runtime-import-rewrite-plugin": {
+      "types": "./src/build/browser-runtime-import-rewrite-plugin.d.ts",
+      "default": "./src/build/browser-runtime-import-rewrite-plugin.js"
+    },
     "./build/runtime-specifier-alias-plugin": {
       "types": "./src/build/runtime-specifier-alias-plugin.d.ts",
       "default": "./src/build/runtime-specifier-alias-plugin.js"
     },
-    "./build/runtime-specifier-aliases": {
-      "types": "./src/build/runtime-specifier-aliases.d.ts",
-      "default": "./src/build/runtime-specifier-aliases.js"
-    },
     "./plugins/foreign-jsx-override-plugin": {
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
       "default": "./src/plugins/foreign-jsx-override-plugin.js"
@@ -226,14 +230,18 @@
       "types": "./src/build/build-adapter.d.ts",
       "default": "./src/build/build-adapter.js"
     },
+    "./build/browser-runtime-manifest.ts": {
+      "types": "./src/build/browser-runtime-manifest.d.ts",
+      "default": "./src/build/browser-runtime-manifest.js"
+    },
+    "./build/browser-runtime-import-rewrite-plugin.ts": {
+      "types": "./src/build/browser-runtime-import-rewrite-plugin.d.ts",
+      "default": "./src/build/browser-runtime-import-rewrite-plugin.js"
+    },
     "./build/runtime-specifier-alias-plugin.ts": {
       "types": "./src/build/runtime-specifier-alias-plugin.d.ts",
       "default": "./src/build/runtime-specifier-alias-plugin.js"
     },
-    "./build/runtime-specifier-aliases.ts": {
-      "types": "./src/build/runtime-specifier-aliases.d.ts",
-      "default": "./src/build/runtime-specifier-aliases.js"
-    },
     "./plugins/foreign-jsx-override-plugin.ts": {
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
       "default": "./src/plugins/foreign-jsx-override-plugin.js"

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

@@ -1,6 +1,5 @@
 import { createServer } from "node:http";
 import path from "node:path";
-import { WebSocketServer } from "ws";
 import { fileSystem } from "@ecopages/file-system";
 import { getAppBrowserBuildPlugins, setupAppRuntimePlugins } from "../../build/build-adapter.js";
 import { installAppRuntimeBuildExecutor } from "../../build/runtime-build-executor.js";

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

@@ -177,6 +177,7 @@ class SharedHmrManager {
       getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
       getBuildExecutor: () => getAppBuildExecutor(this.appConfig),
       getBrowserBundleService: () => this.browserBundleService,
+      getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
       importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
         filePath,
         outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),

package/src/build/browser-runtime-import-rewrite-plugin.d.ts

@@ -0,0 +1,26 @@
+import type { EcoBuildPlugin } from './build-types.js';
+import { type BrowserRuntimeManifest } from './browser-runtime-manifest.js';
+export declare const DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME = "browser-runtime-import-rewrite";
+export type CreateBrowserRuntimeImportRewritePluginOptions = {
+    /** Stable build plugin name used for deduplication and selective exclusion. */
+    name?: string;
+    /** Manifest containing specifier-to-public-URL runtime asset mappings. */
+    manifest: BrowserRuntimeManifest;
+};
+/**
+ * Rewrites static ESM import/export specifiers and string-literal dynamic imports
+ * from manifest-owned runtime specifiers to concrete browser public URLs.
+ */
+export declare function rewriteBrowserRuntimeImports(code: string, specifierMap: ReadonlyMap<string, string>, filePath?: string): string;
+export declare function getBrowserRuntimeImportRewriteMap(plugin: EcoBuildPlugin): ReadonlyMap<string, string> | undefined;
+export declare function collectBrowserRuntimeImportRewriteMap(plugins: EcoBuildPlugin[] | undefined): ReadonlyMap<string, string>;
+/**
+ * Creates a build plugin that applies browser runtime manifest import rewrites
+ * before the bundler resolves source modules.
+ *
+ * @remarks
+ * This is the migration path away from browser import-map-style runtime aliases:
+ * generated and authored browser modules can keep importing manifest-owned
+ * specifiers, while the build turns those specifiers into concrete public URLs.
+ */
+export declare function createBrowserRuntimeImportRewritePlugin(options: CreateBrowserRuntimeImportRewritePluginOptions): EcoBuildPlugin | null;

package/src/build/browser-runtime-import-rewrite-plugin.js

@@ -0,0 +1,165 @@
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { parseSync } from "oxc-parser";
+import { getBrowserRuntimeSpecifierMap } from "./browser-runtime-manifest.js";
+const BROWSER_RUNTIME_IMPORT_REWRITE_MAP = /* @__PURE__ */ Symbol.for("ecopages.browserRuntimeImportRewriteMap");
+const DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME = "browser-runtime-import-rewrite";
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object";
+}
+function inferLoaderFromPath(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  switch (extension) {
+    case ".mts":
+    case ".cts":
+    case ".ts":
+      return "ts";
+    case ".tsx":
+      return "tsx";
+    case ".jsx":
+      return "jsx";
+    default:
+      return "js";
+  }
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function queueReplacement(options) {
+  if (!isRecord(options.source) || typeof options.source.value !== "string") {
+    return;
+  }
+  const mappedPath = options.specifierMap.get(options.source.value);
+  if (!mappedPath || typeof options.source.start !== "number" || typeof options.source.end !== "number") {
+    return;
+  }
+  const quote = options.code[options.source.start] === "'" ? "'" : '"';
+  options.edits.push({
+    start: options.source.start,
+    end: options.source.end,
+    replacement: `${quote}${mappedPath}${quote}`
+  });
+}
+function rewriteBrowserRuntimeImports(code, specifierMap, filePath = "browser-runtime-imports.js") {
+  if (specifierMap.size === 0) {
+    return code;
+  }
+  const edits = [];
+  try {
+    const result = parseSync(filePath, code, {
+      sourceType: "module",
+      lang: path.extname(filePath).endsWith("x") ? "tsx" : "ts"
+    });
+    const walk = (node) => {
+      if (!isRecord(node)) {
+        return;
+      }
+      if (node.type === "ImportDeclaration" || node.type === "ExportNamedDeclaration" || node.type === "ExportAllDeclaration") {
+        queueReplacement({ code, source: node.source, specifierMap, edits });
+      }
+      if (node.type === "ImportExpression" && isRecord(node.source)) {
+        if (node.source.type === "StringLiteral" || node.source.type === "Literal") {
+          queueReplacement({ code, source: node.source, specifierMap, edits });
+        }
+      }
+      for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+          for (const child of value) {
+            walk(child);
+          }
+        } else {
+          walk(value);
+        }
+      }
+    };
+    walk(result.program);
+  } catch {
+    return code;
+  }
+  if (edits.length === 0) {
+    return code;
+  }
+  edits.sort((left, right) => right.start - left.start);
+  let rewritten = code;
+  for (const edit of edits) {
+    rewritten = rewritten.slice(0, edit.start) + edit.replacement + rewritten.slice(edit.end);
+  }
+  return rewritten;
+}
+function getBrowserRuntimeImportRewriteMap(plugin) {
+  return plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP];
+}
+function collectBrowserRuntimeImportRewriteMap(plugins) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const plugin of plugins ?? []) {
+    const specifierMap = getBrowserRuntimeImportRewriteMap(plugin);
+    if (!specifierMap) {
+      continue;
+    }
+    for (const [specifier, publicPath] of specifierMap.entries()) {
+      if (!merged.has(specifier)) {
+        merged.set(specifier, publicPath);
+      }
+    }
+  }
+  return merged;
+}
+function createBrowserRuntimeImportRewritePlugin(options) {
+  const specifierMap = getBrowserRuntimeSpecifierMap(options.manifest);
+  const publicPathSet = new Set(specifierMap.values());
+  const specifierFilter = new RegExp(`^(${Array.from(specifierMap.keys()).map(escapeRegExp).join("|")})$`);
+  if (specifierMap.size === 0) {
+    return null;
+  }
+  const plugin = {
+    name: options.name ?? DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME,
+    setup(build) {
+      build.onResolve({ filter: specifierFilter }, (args) => {
+        const mappedPath = specifierMap.get(args.path);
+        if (!mappedPath) {
+          return void 0;
+        }
+        return {
+          path: mappedPath,
+          external: true
+        };
+      });
+      build.onResolve({ filter: /^\// }, (args) => {
+        if (!publicPathSet.has(args.path)) {
+          return void 0;
+        }
+        return {
+          path: args.path,
+          external: true
+        };
+      });
+      build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) => {
+        if (!path.isAbsolute(args.path) || !existsSync(args.path)) {
+          return void 0;
+        }
+        const code = readFileSync(args.path, "utf-8");
+        if (!Array.from(specifierMap.keys()).some((specifier) => code.includes(specifier))) {
+          return void 0;
+        }
+        const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, args.path);
+        if (rewritten === code) {
+          return void 0;
+        }
+        return {
+          contents: rewritten,
+          loader: inferLoaderFromPath(args.path),
+          resolveDir: path.dirname(args.path)
+        };
+      });
+    }
+  };
+  plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP] = specifierMap;
+  return plugin;
+}
+export {
+  DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME,
+  collectBrowserRuntimeImportRewriteMap,
+  createBrowserRuntimeImportRewritePlugin,
+  getBrowserRuntimeImportRewriteMap,
+  rewriteBrowserRuntimeImports
+};

package/src/build/browser-runtime-manifest.d.ts

@@ -0,0 +1,31 @@
+export type BrowserRuntimeMode = 'development' | 'production';
+export type BrowserRuntimeAssetDeclaration = {
+    /** Bare or virtual specifier used by authored/generated browser modules. */
+    specifier: string;
+    /** Integration, processor, or core subsystem that owns this runtime asset. */
+    owner: string;
+    /** Source import path used to build or resolve the runtime asset. */
+    importPath: string;
+    /** Concrete browser URL emitted or served for this runtime asset. */
+    publicPath: string;
+    /** Runtime mode this declaration applies to. Omit when the URL is mode-independent. */
+    mode?: BrowserRuntimeMode;
+    /** Specifiers that should be treated as external while building this runtime asset. */
+    externals?: readonly string[];
+};
+export type BrowserRuntimeAsset = BrowserRuntimeAssetDeclaration & {
+    externals: readonly string[];
+};
+export type BrowserRuntimeManifest = {
+    assets: readonly BrowserRuntimeAsset[];
+    bySpecifier: ReadonlyMap<string, BrowserRuntimeAsset>;
+};
+export declare class BrowserRuntimeManifestConflictError extends Error {
+    readonly specifier: string;
+    readonly existing: BrowserRuntimeAsset;
+    readonly incoming: BrowserRuntimeAsset;
+    constructor(specifier: string, existing: BrowserRuntimeAsset, incoming: BrowserRuntimeAsset);
+}
+export declare function createBrowserRuntimeManifest(declarations?: readonly BrowserRuntimeAssetDeclaration[]): BrowserRuntimeManifest;
+export declare function mergeBrowserRuntimeManifests(...manifests: Array<BrowserRuntimeManifest | undefined>): BrowserRuntimeManifest;
+export declare function getBrowserRuntimeSpecifierMap(manifest: BrowserRuntimeManifest): ReadonlyMap<string, string>;

package/src/build/browser-runtime-manifest.js

@@ -0,0 +1,61 @@
+class BrowserRuntimeManifestConflictError extends Error {
+  specifier;
+  existing;
+  incoming;
+  constructor(specifier, existing, incoming) {
+    super(
+      `Browser runtime asset conflict for ${specifier}: ${existing.owner} maps to ${existing.publicPath}, ${incoming.owner} maps to ${incoming.publicPath}`
+    );
+    this.name = "BrowserRuntimeManifestConflictError";
+    this.specifier = specifier;
+    this.existing = existing;
+    this.incoming = incoming;
+  }
+}
+function normalizeDeclaration(declaration) {
+  return {
+    ...declaration,
+    externals: declaration.externals ?? []
+  };
+}
+function hasCompatibleRuntimeAsset(existing, incoming) {
+  return existing.owner === incoming.owner && existing.importPath === incoming.importPath && existing.publicPath === incoming.publicPath && existing.mode === incoming.mode && arrayEquals(existing.externals, incoming.externals);
+}
+function arrayEquals(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  return left.every((value, index) => value === right[index]);
+}
+function createBrowserRuntimeManifest(declarations = []) {
+  const assets = [];
+  const bySpecifier = /* @__PURE__ */ new Map();
+  for (const declaration of declarations) {
+    const asset = normalizeDeclaration(declaration);
+    const existing = bySpecifier.get(asset.specifier);
+    if (existing) {
+      if (!hasCompatibleRuntimeAsset(existing, asset)) {
+        throw new BrowserRuntimeManifestConflictError(asset.specifier, existing, asset);
+      }
+      continue;
+    }
+    assets.push(asset);
+    bySpecifier.set(asset.specifier, asset);
+  }
+  return {
+    assets,
+    bySpecifier
+  };
+}
+function mergeBrowserRuntimeManifests(...manifests) {
+  return createBrowserRuntimeManifest(manifests.flatMap((manifest) => manifest?.assets ?? []));
+}
+function getBrowserRuntimeSpecifierMap(manifest) {
+  return new Map(manifest.assets.map((asset) => [asset.specifier, asset.publicPath]));
+}
+export {
+  BrowserRuntimeManifestConflictError,
+  createBrowserRuntimeManifest,
+  getBrowserRuntimeSpecifierMap,
+  mergeBrowserRuntimeManifests
+};

package/src/build/build-adapter.d.ts

@@ -123,9 +123,9 @@ export declare class BunBuildAdapter implements BuildAdapter {
     private resolveTemplatedOutputPath;
     private relocateOutputFile;
     private hasJavaScriptExtension;
+    private rewriteBrowserRuntimeImportsInOutputs;
     private findOutputMatchForEntrypoint;
     private normalizeBunOutputs;
-    private rewriteAliasedRuntimeSpecifiers;
     build(options: BuildOptions): Promise<BuildResult>;
     resolve(importPath: string, rootDir: string): string;
     getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
@@ -198,7 +198,7 @@ export declare function updateAppBuildManifest(appConfig: EcoPagesAppConfig, inp
  * as HMR registration, cache prewarming, and runtime-origin wiring belong to
  * the startup path and must not be triggered here.
  */
-export declare function collectConfiguredAppBuildManifestContributions(appConfig: EcoPagesAppConfig): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins'>>;
+export declare function collectConfiguredAppBuildManifestContributions(appConfig: EcoPagesAppConfig): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins' | 'browserRuntimeManifest'>>;
 /**
  * Runs runtime-only processor and integration setup against an already sealed
  * app manifest.

package/src/build/build-adapter.js

@@ -1,10 +1,14 @@
+import { mergeBrowserRuntimeManifests } from "./browser-runtime-manifest.js";
+import {
+  collectBrowserRuntimeImportRewriteMap,
+  rewriteBrowserRuntimeImports
+} from "./browser-runtime-import-rewrite-plugin.js";
 import {
   createAppBuildManifest,
   getBrowserBuildPlugins,
   getServerBuildPlugins
 } from "./build-manifest.js";
 import { EsbuildBuildAdapter } from "./esbuild-build-adapter.js";
-import { collectRuntimeSpecifierAliasMap, rewriteRuntimeSpecifierAliases } from "./runtime-specifier-aliases.js";
 import { getBunRuntime } from "../utils/runtime.js";
 import fs from "node:fs";
 import path from "node:path";
@@ -325,6 +329,26 @@ class BunBuildAdapter {
   hasJavaScriptExtension(outputPath) {
     return /\.(?:[cm]?js)$/u.test(outputPath);
   }
+  rewriteBrowserRuntimeImportsInOutputs(result, plugins) {
+    if (!result.success || result.outputs.length === 0) {
+      return result;
+    }
+    const specifierMap = collectBrowserRuntimeImportRewriteMap(plugins);
+    if (specifierMap.size === 0) {
+      return result;
+    }
+    for (const output of result.outputs) {
+      if (!this.hasJavaScriptExtension(output.path) || !fs.existsSync(output.path)) {
+        continue;
+      }
+      const code = fs.readFileSync(output.path, "utf-8");
+      const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, output.path);
+      if (rewritten !== code) {
+        fs.writeFileSync(output.path, rewritten);
+      }
+    }
+    return result;
+  }
   findOutputMatchForEntrypoint(options, entrypointPath, outputs, usedOutputIndexes) {
     const expectedOutputPath = this.resolveTemplatedOutputPath(options, entrypointPath);
     if (!expectedOutputPath) {
@@ -401,26 +425,6 @@ class BunBuildAdapter {
       })
     };
   }
-  rewriteAliasedRuntimeSpecifiers(result, plugins) {
-    if (!result.success || result.outputs.length === 0) {
-      return result;
-    }
-    const aliasMap = collectRuntimeSpecifierAliasMap(plugins);
-    if (aliasMap.size === 0) {
-      return result;
-    }
-    for (const output of result.outputs) {
-      if (!/\.(?:[cm]?js)$/u.test(output.path) || !fs.existsSync(output.path)) {
-        continue;
-      }
-      const code = fs.readFileSync(output.path, "utf-8");
-      const rewritten = rewriteRuntimeSpecifierAliases(code, aliasMap);
-      if (rewritten !== code) {
-        fs.writeFileSync(output.path, rewritten);
-      }
-    }
-    return result;
-  }
   async build(options) {
     const bun = getBunRuntime();
     if (!bun) {
@@ -449,7 +453,7 @@ class BunBuildAdapter {
         jsx: options.jsx,
         plugins: plugins.length > 0 ? [this.createEcoPluginBridge(plugins, contextRoot)] : void 0
       });
-      return this.rewriteAliasedRuntimeSpecifiers(
+      return this.rewriteBrowserRuntimeImportsInOutputs(
         this.normalizeBunOutputs(
           {
             success: result.success,
@@ -554,7 +558,8 @@ function createConfiguredAppBuildManifest(appConfig, input) {
   return createAppBuildManifest({
     loaderPlugins: input?.loaderPlugins ?? Array.from(appConfig.loaders.values()),
     runtimePlugins: input?.runtimePlugins,
-    browserBundlePlugins: input?.browserBundlePlugins
+    browserBundlePlugins: input?.browserBundlePlugins,
+    browserRuntimeManifest: input?.browserRuntimeManifest
   });
 }
 function updateAppBuildManifest(appConfig, input) {
@@ -563,6 +568,7 @@ function updateAppBuildManifest(appConfig, input) {
 async function collectConfiguredAppBuildManifestContributions(appConfig) {
   const runtimePlugins = [];
   const browserBundlePlugins = [];
+  const browserRuntimeManifests = [];
   for (const processor of appConfig.processors.values()) {
     await processor.prepareBuildContributions();
     if (processor.plugins) {
@@ -577,10 +583,12 @@ async function collectConfiguredAppBuildManifestContributions(appConfig) {
     await integration.prepareBuildContributions();
     runtimePlugins.push(...integration.plugins ?? []);
     browserBundlePlugins.push(...integration.browserBuildPlugins ?? []);
+    browserRuntimeManifests.push(integration.browserRuntimeManifest);
   }
   return {
     runtimePlugins,
-    browserBundlePlugins
+    browserBundlePlugins,
+    browserRuntimeManifest: mergeBrowserRuntimeManifests(...browserRuntimeManifests)
   };
 }
 async function setupAppRuntimePlugins(options) {

package/src/build/build-manifest.d.ts

@@ -1,8 +1,10 @@
 import type { EcoBuildPlugin } from './build-types.js';
+import { type BrowserRuntimeManifest } from './browser-runtime-manifest.js';
 export interface AppBuildManifest {
     loaderPlugins: EcoBuildPlugin[];
     runtimePlugins: EcoBuildPlugin[];
     browserBundlePlugins: EcoBuildPlugin[];
+    browserRuntimeManifest: BrowserRuntimeManifest;
 }
 /**
  * Merges plugin lists while preserving first-registration precedence by name.
@@ -17,6 +19,10 @@ export declare function mergeEcoBuildPlugins(...pluginLists: Array<EcoBuildPlugi
  * Creates one app-owned build manifest from the supplied plugin buckets.
  */
 export declare function createAppBuildManifest(input?: Partial<AppBuildManifest>): AppBuildManifest;
+/**
+ * Returns the shared browser runtime asset manifest sealed into the app build manifest.
+ */
+export declare function getBrowserRuntimeManifest(manifest: AppBuildManifest): BrowserRuntimeManifest;
 /**
  * Returns the plugin list used for server-oriented builds.
  */

package/src/build/build-manifest.js

@@ -1,3 +1,11 @@
+import {
+  createBrowserRuntimeImportRewritePlugin,
+  DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME
+} from "./browser-runtime-import-rewrite-plugin.js";
+import {
+  createBrowserRuntimeManifest,
+  mergeBrowserRuntimeManifests
+} from "./browser-runtime-manifest.js";
 function mergeEcoBuildPlugins(...pluginLists) {
   const byName = /* @__PURE__ */ new Map();
   for (const plugins of pluginLists) {
@@ -13,18 +21,32 @@ function createAppBuildManifest(input) {
   return {
     loaderPlugins: mergeEcoBuildPlugins(input?.loaderPlugins),
     runtimePlugins: mergeEcoBuildPlugins(input?.runtimePlugins),
-    browserBundlePlugins: mergeEcoBuildPlugins(input?.browserBundlePlugins)
+    browserBundlePlugins: mergeEcoBuildPlugins(input?.browserBundlePlugins),
+    browserRuntimeManifest: mergeBrowserRuntimeManifests(input?.browserRuntimeManifest)
   };
 }
+function getBrowserRuntimeManifest(manifest) {
+  return manifest.browserRuntimeManifest ?? createBrowserRuntimeManifest();
+}
 function getServerBuildPlugins(manifest) {
   return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins);
 }
 function getBrowserBuildPlugins(manifest) {
-  return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins, manifest.browserBundlePlugins);
+  const runtimeRewritePlugin = createBrowserRuntimeImportRewritePlugin({
+    name: DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME,
+    manifest: getBrowserRuntimeManifest(manifest)
+  });
+  return mergeEcoBuildPlugins(
+    manifest.loaderPlugins,
+    manifest.runtimePlugins,
+    runtimeRewritePlugin ? [runtimeRewritePlugin] : [],
+    manifest.browserBundlePlugins
+  );
 }
 export {
   createAppBuildManifest,
   getBrowserBuildPlugins,
+  getBrowserRuntimeManifest,
   getServerBuildPlugins,
   mergeEcoBuildPlugins
 };

package/src/build/esbuild-build-adapter.d.ts

@@ -12,7 +12,7 @@ export declare class EsbuildBuildAdapter implements BuildAdapter {
     private getJavaScriptOutExtension;
     private collectWorkspaceNodePaths;
     private getFallbackNodePaths;
-    private rewriteAliasedRuntimeSpecifiers;
+    private rewriteBrowserRuntimeImportsInOutputs;
     private escapeRegExp;
     private getPluginsForBuild;
     private normalizeEsbuildLoader;

package/src/build/esbuild-build-adapter.js

@@ -3,7 +3,10 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { fileSystem } from "@ecopages/file-system";
-import { collectRuntimeSpecifierAliasMap, rewriteRuntimeSpecifierAliases } from "./runtime-specifier-aliases.js";
+import {
+  collectBrowserRuntimeImportRewriteMap,
+  rewriteBrowserRuntimeImports
+} from "./browser-runtime-import-rewrite-plugin.js";
 const moduleRequire = createRequire(import.meta.url);
 const esbuildPath = moduleRequire.resolve("esbuild");
 const workspaceNodePathsCache = /* @__PURE__ */ new Map();
@@ -93,12 +96,12 @@ class EsbuildBuildAdapter {
     }
     return Array.from(nodePaths);
   }
-  rewriteAliasedRuntimeSpecifiers(result, plugins) {
+  rewriteBrowserRuntimeImportsInOutputs(result, plugins) {
     if (!result.success || result.outputs.length === 0) {
       return result;
     }
-    const aliasMap = collectRuntimeSpecifierAliasMap(plugins);
-    if (aliasMap.size === 0) {
+    const specifierMap = collectBrowserRuntimeImportRewriteMap(plugins);
+    if (specifierMap.size === 0) {
       return result;
     }
     for (const output of result.outputs) {
@@ -106,7 +109,7 @@ class EsbuildBuildAdapter {
         continue;
       }
       const code = readFileSync(output.path, "utf-8");
-      const rewritten = rewriteRuntimeSpecifierAliases(code, aliasMap);
+      const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, output.path);
       if (rewritten !== code) {
         writeFileSync(output.path, rewritten);
       }
@@ -389,7 +392,7 @@ class EsbuildBuildAdapter {
     }));
     const logs = result.warnings.map((warning) => ({ message: warning.text }));
     const dependencyGraph = this.extractDependencyGraph(result.metafile, contextRoot);
-    return this.rewriteAliasedRuntimeSpecifiers(
+    return this.rewriteBrowserRuntimeImportsInOutputs(
       {
         success: true,
         logs,

package/src/build/runtime-specifier-alias-plugin.js

@@ -1,4 +1,3 @@
-import { attachRuntimeSpecifierAliasMap } from "./runtime-specifier-aliases.js";
 function toRuntimeSpecifierMap(specifierMap) {
   return specifierMap instanceof Map ? specifierMap : new Map(Object.entries(specifierMap));
 }
@@ -11,24 +10,21 @@ function createRuntimeSpecifierAliasPlugin(specifierMapInput, options) {
     return null;
   }
   const filter = new RegExp(`^(${Array.from(specifierMap.keys()).map(escapeRegExp).join("|")})$`);
-  return attachRuntimeSpecifierAliasMap(
-    {
-      name: options?.name ?? "runtime-specifier-alias",
-      setup(build) {
-        build.onResolve({ filter }, (args) => {
-          const mappedPath = specifierMap.get(args.path);
-          if (!mappedPath) {
-            return void 0;
-          }
-          return {
-            path: mappedPath,
-            external: options?.external ?? true
-          };
-        });
-      }
-    },
-    specifierMap
-  );
+  return {
+    name: options?.name ?? "runtime-specifier-alias",
+    setup(build) {
+      build.onResolve({ filter }, (args) => {
+        const mappedPath = specifierMap.get(args.path);
+        if (!mappedPath) {
+          return void 0;
+        }
+        return {
+          path: mappedPath,
+          external: options?.external ?? true
+        };
+      });
+    }
+  };
 }
 export {
   createRuntimeSpecifierAliasPlugin

package/src/plugins/integration-plugin.d.ts

@@ -1,4 +1,5 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
+import { type BrowserRuntimeManifest } from '../build/browser-runtime-manifest.js';
 import type { EcoPagesAppConfig, IHmrManager } from '../types/internal-types.js';
 import type { HmrStrategy } from '../hmr/hmr-strategy.js';
 import type { EcoPagesElement } from '../types/public-types.js';
@@ -114,6 +115,15 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * do not affect server bundles or static-page module generation.
      */
     get browserBuildPlugins(): EcoBuildPlugin[];
+    /**
+     * Returns shared browser runtime asset declarations owned by this integration.
+     *
+     * @remarks
+     * Core seals these declarations into the app build manifest so app-owned browser
+     * bundle paths can rewrite manifest-owned imports even when a specific build
+     * request does not install an integration-local runtime rewrite plugin.
+     */
+    get browserRuntimeManifest(): BrowserRuntimeManifest;
     /**
      * Creates the integration with static declaration-only configuration.
      *
@@ -144,7 +154,7 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * ```typescript
      * getHmrStrategy(): HmrStrategy {
      *   const context = this.hmrManager!.getDefaultContext();
-     *   return new ReactHmrStrategy({ context, pageMetadataCache, runtimeAliasMap });
+     *   return new ReactHmrStrategy({ context, pageMetadataCache, runtimeManifest });
      * }
      * ```
      */

package/src/plugins/integration-plugin.js

@@ -1,3 +1,4 @@
+import { createBrowserRuntimeManifest } from "../build/browser-runtime-manifest.js";
 import { AssetProcessingService } from "../services/assets/asset-processing-service/asset-processing.service.js";
 import { deepMerge } from "../utils/deep-merge.js";
 import { invariant } from "../utils/invariant.js";
@@ -36,6 +37,17 @@ class IntegrationPlugin {
   get browserBuildPlugins() {
     return [];
   }
+  /**
+   * Returns shared browser runtime asset declarations owned by this integration.
+   *
+   * @remarks
+   * Core seals these declarations into the app build manifest so app-owned browser
+   * bundle paths can rewrite manifest-owned imports even when a specific build
+   * request does not install an integration-local runtime rewrite plugin.
+   */
+  get browserRuntimeManifest() {
+    return createBrowserRuntimeManifest();
+  }
   /**
    * Creates the integration with static declaration-only configuration.
    *

package/src/services/assets/asset-processing-service/browser-runtime-asset.factory.d.ts

@@ -25,6 +25,7 @@ export declare function createBrowserRuntimeScriptAsset(options: {
         define?: Record<string, string>;
         minify?: boolean;
         external?: string[];
+        excludeAppBuildPlugins?: string[];
         naming?: string;
         plugins?: EcoBuildPlugin[];
     };
@@ -48,6 +49,7 @@ export declare function createBrowserRuntimeModuleAsset(options: {
         define?: Record<string, string>;
         minify?: boolean;
         external?: string[];
+        excludeAppBuildPlugins?: string[];
         naming?: string;
         plugins?: EcoBuildPlugin[];
     };

package/src/types/public-types.d.ts

@@ -10,6 +10,7 @@ import type { BrowserBundleExecutor } from '../services/assets/browser-bundle.se
 import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
 import type { CacheStats, CacheStrategy } from '../services/cache/cache.types.js';
 import type { InteractionEventsString as ScriptsInjectorInteractionEventsString } from '@ecopages/scripts-injector/types';
+import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
 export type { EcoPagesAppConfig } from './internal-types.js';
 export type { EcoPageComponent } from '../eco/eco.types.js';
 export type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
@@ -128,6 +129,10 @@ export interface DefaultHmrContext {
      * Server-side module loader owned by the active app/runtime.
      */
     importServerModule<T = unknown>(filePath: string | URL): Promise<T>;
+    /**
+     * Entrypoint dependency graph for selective HMR invalidation.
+     */
+    getEntrypointDependencyGraph(): EntrypointDependencyGraph;
 }
 /**
  * Represents an event broadcast to connected clients via the ClientBridge.

package/src/build/runtime-specifier-aliases.d.ts

@@ -1,5 +0,0 @@
-import type { EcoBuildPlugin } from './build-types.js';
-export declare function attachRuntimeSpecifierAliasMap(plugin: EcoBuildPlugin, specifierMap: ReadonlyMap<string, string>): EcoBuildPlugin;
-export declare function getRuntimeSpecifierAliasMap(plugin: EcoBuildPlugin): ReadonlyMap<string, string> | undefined;
-export declare function collectRuntimeSpecifierAliasMap(plugins: EcoBuildPlugin[] | undefined): ReadonlyMap<string, string>;
-export declare function rewriteRuntimeSpecifierAliases(code: string, specifierMap: ReadonlyMap<string, string>): string;

package/src/build/runtime-specifier-aliases.js

@@ -1,95 +0,0 @@
-import { parseSync } from "oxc-parser";
-const RUNTIME_SPECIFIER_ALIAS_MAP = /* @__PURE__ */ Symbol.for("ecopages.runtimeSpecifierAliasMap");
-function attachRuntimeSpecifierAliasMap(plugin, specifierMap) {
-  plugin[RUNTIME_SPECIFIER_ALIAS_MAP] = specifierMap;
-  return plugin;
-}
-function getRuntimeSpecifierAliasMap(plugin) {
-  return plugin[RUNTIME_SPECIFIER_ALIAS_MAP];
-}
-function collectRuntimeSpecifierAliasMap(plugins) {
-  const merged = /* @__PURE__ */ new Map();
-  for (const plugin of plugins ?? []) {
-    const specifierMap = getRuntimeSpecifierAliasMap(plugin);
-    if (!specifierMap) {
-      continue;
-    }
-    for (const [specifier, mappedPath] of specifierMap.entries()) {
-      if (!merged.has(specifier)) {
-        merged.set(specifier, mappedPath);
-      }
-    }
-  }
-  return merged;
-}
-function rewriteRuntimeSpecifierAliases(code, specifierMap) {
-  if (specifierMap.size === 0) {
-    return code;
-  }
-  const edits = [];
-  try {
-    const result = parseSync("runtime-alias-output.js", code, {
-      sourceType: "module",
-      lang: "js"
-    });
-    const queueReplacement = (source) => {
-      if (typeof source.value !== "string") {
-        return;
-      }
-      const mappedPath = specifierMap.get(source.value);
-      if (!mappedPath) {
-        return;
-      }
-      const quote = code[source.start] === "'" ? "'" : '"';
-      edits.push({
-        start: source.start,
-        end: source.end,
-        replacement: `${quote}${mappedPath}${quote}`
-      });
-    };
-    const walk = (node) => {
-      if (!node || typeof node !== "object") {
-        return;
-      }
-      if (Array.isArray(node)) {
-        for (const child of node) {
-          walk(child);
-        }
-        return;
-      }
-      const candidate = node;
-      if (candidate.type === "ImportDeclaration" || candidate.type === "ExportNamedDeclaration" || candidate.type === "ExportAllDeclaration") {
-        if (candidate.source) {
-          queueReplacement(candidate.source);
-        }
-      }
-      if (candidate.type === "ImportExpression") {
-        const importNode = candidate;
-        if (importNode.source?.type === "StringLiteral" || importNode.source?.type === "Literal") {
-          queueReplacement(importNode.source);
-        }
-      }
-      for (const value of Object.values(candidate)) {
-        walk(value);
-      }
-    };
-    walk(result.program);
-  } catch {
-    return code;
-  }
-  if (edits.length === 0) {
-    return code;
-  }
-  edits.sort((left, right) => right.start - left.start);
-  let rewritten = code;
-  for (const edit of edits) {
-    rewritten = rewritten.slice(0, edit.start) + edit.replacement + rewritten.slice(edit.end);
-  }
-  return rewritten;
-}
-export {
-  attachRuntimeSpecifierAliasMap,
-  collectRuntimeSpecifierAliasMap,
-  getRuntimeSpecifierAliasMap,
-  rewriteRuntimeSpecifierAliases
-};