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

package/src/build/runtime-build-output-normalizer.js

@@ -4,6 +4,8 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 const corePackageRequire = createRequire(new URL("../../package.json", import.meta.url));
 const appDeclaredPackageCache = /* @__PURE__ */ new Map();
+const appWorkspacePackageCache = /* @__PURE__ */ new Map();
+const CORE_RUNTIME_BARE_SPECIFIER_PACKAGES = /* @__PURE__ */ new Set(["ws"]);
 function tryResolveRuntimeImport(specifier, resolver) {
   try {
     return resolver.resolve(specifier);
@@ -14,6 +16,24 @@ function tryResolveRuntimeImport(specifier, resolver) {
 function isBareRuntimeImport(specifier) {
   return !specifier.startsWith(".") && !path.isAbsolute(specifier) && !specifier.startsWith("/") && !specifier.startsWith("node:") && !specifier.startsWith("@/") && !specifier.startsWith("~/") && !specifier.startsWith("#") && !specifier.includes(":");
 }
+function extractPackageNameFromFileUrl(specifier) {
+  if (!specifier.startsWith("file://")) {
+    return void 0;
+  }
+  const lastNodeModulesIndex = specifier.lastIndexOf("/node_modules/");
+  if (lastNodeModulesIndex === -1) {
+    return void 0;
+  }
+  const afterNodeModules = specifier.slice(lastNodeModulesIndex + "/node_modules/".length);
+  const parts = afterNodeModules.split("/");
+  if (parts.length === 0) {
+    return void 0;
+  }
+  if (parts[0]?.startsWith("@") && parts.length > 1) {
+    return `${parts[0]}/${parts[1]}`;
+  }
+  return parts[0];
+}
 function getPackageNameFromSpecifier(specifier) {
   if (specifier.startsWith("@")) {
     return specifier.split("/").slice(0, 2).join("/");
@@ -46,14 +66,52 @@ function getDeclaredAppPackages(rootDir) {
   appDeclaredPackageCache.set(cacheKey, declaredPackages);
   return declaredPackages;
 }
+function getWorkspacePackages(rootDir) {
+  const cacheKey = path.resolve(rootDir);
+  const cached = appWorkspacePackageCache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+  const packageJsonPath = path.resolve(rootDir, "package.json");
+  const workspacePackages = /* @__PURE__ */ new Set();
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+      const entries = packageJson[field];
+      if (!entries || typeof entries !== "object") {
+        continue;
+      }
+      for (const [packageName, version] of Object.entries(entries)) {
+        if (typeof version === "string" && version.startsWith("workspace:")) {
+          workspacePackages.add(packageName);
+        }
+      }
+    }
+  } catch {
+    appWorkspacePackageCache.set(cacheKey, workspacePackages);
+    return workspacePackages;
+  }
+  appWorkspacePackageCache.set(cacheKey, workspacePackages);
+  return workspacePackages;
+}
+function isWorkspacePackageImport(specifier, rootDir) {
+  return getWorkspacePackages(rootDir).has(getPackageNameFromSpecifier(specifier));
+}
 function isDeclaredAppPackageImport(specifier, rootDir) {
   return getDeclaredAppPackages(rootDir).has(getPackageNameFromSpecifier(specifier));
 }
+function isDeclaredInResolutionChain(specifier, rootDir) {
+  const packageName = getPackageNameFromSpecifier(specifier);
+  if (CORE_RUNTIME_BARE_SPECIFIER_PACKAGES.has(packageName)) {
+    return true;
+  }
+  return isDeclaredAppPackageImport(specifier, rootDir);
+}
 function rewriteRuntimeImportSpecifier(specifier, quote, rootDir) {
   if (!isBareRuntimeImport(specifier)) {
     return void 0;
   }
-  if (isDeclaredAppPackageImport(specifier, rootDir)) {
+  if (isDeclaredInResolutionChain(specifier, rootDir)) {
     return void 0;
   }
   const resolvedPath = tryResolveRuntimeImport(specifier, corePackageRequire);
@@ -67,6 +125,23 @@ function rewriteRuntimeBuildOutputImports(code, rootDir) {
     const rewrittenSpecifier = rewriteRuntimeImportSpecifier(specifier, quote, rootDir);
     return `${prefix}${rewrittenSpecifier ?? `${quote}${specifier}${quote}`}`;
   };
+  const rewriteFileUrl = (prefix, quote, specifier) => {
+    const packageName = extractPackageNameFromFileUrl(specifier);
+    if (!packageName) {
+      return `${prefix}${quote}${specifier}${quote}`;
+    }
+    if (!isDeclaredInResolutionChain(packageName, rootDir)) {
+      return `${prefix}${quote}${specifier}${quote}`;
+    }
+    const lastNodeModulesIndex = specifier.lastIndexOf("/node_modules/");
+    if (lastNodeModulesIndex === -1) {
+      return `${prefix}${quote}${specifier}${quote}`;
+    }
+    const afterNodeModules = specifier.slice(lastNodeModulesIndex + "/node_modules/".length);
+    const afterPackage = afterNodeModules.slice(packageName.length);
+    const bareSpecifier = packageName + afterPackage;
+    return `${prefix}${quote}${bareSpecifier}${quote}`;
+  };
   const withResolvedPackages = code.replace(
     /(\bfrom\s+)(['"])([^'"\\]+)\2/g,
     (_match, prefix, quote, specifier) => rewriteSpecifier(prefix, quote, specifier)
@@ -77,7 +152,17 @@ function rewriteRuntimeBuildOutputImports(code, rootDir) {
     /(\bimport\s*\(\s*)(['"])([^'"\\]+)\2/g,
     (_match, prefix, quote, specifier) => rewriteSpecifier(prefix, quote, specifier)
   );
-  return withResolvedPackages.replace(
+  const withBareSpecifiers = withResolvedPackages.replace(
+    /(\bfrom\s+)(['"])(file:\/\/[^'"\\]+)\2/g,
+    (_match, prefix, quote, specifier) => rewriteFileUrl(prefix, quote, specifier)
+  ).replace(
+    /(\bimport\s+)(['"])(file:\/\/[^'"\\]+)\2/g,
+    (_match, prefix, quote, specifier) => rewriteFileUrl(prefix, quote, specifier)
+  ).replace(
+    /(\bimport\s*\(\s*)(['"])(file:\/\/[^'"\\]+)\2/g,
+    (_match, prefix, quote, specifier) => rewriteFileUrl(prefix, quote, specifier)
+  );
+  return withBareSpecifiers.replace(
     /(['"])(@oxc-project\/runtime\/(?:helpers(?:\/esm)?\/[^'"\\]+))\1/g,
     (match, quote, specifier) => {
       const resolvedPath = tryResolveRuntimeImport(specifier, corePackageRequire);
@@ -86,6 +171,9 @@ function rewriteRuntimeBuildOutputImports(code, rootDir) {
   );
 }
 function normalizeNodeRuntimeBuildOutputFile(filePath, rootDir) {
+  if (process.env.ECOPAGES_LOGGER_DEBUG === "true") {
+    console.log(`[normalizeNodeRuntimeBuildOutputFile] Checking ${filePath}`);
+  }
   if (!/\.(?:[cm]?js)$/u.test(filePath)) {
     return;
   }
@@ -96,6 +184,9 @@ function normalizeNodeRuntimeBuildOutputFile(filePath, rootDir) {
   const code = fileSystem.readFileSync(filePath, "utf-8");
   const rewritten = rewriteRuntimeBuildOutputImports(code, rootDir);
   if (rewritten !== code) {
+    if (process.env.ECOPAGES_LOGGER_DEBUG === "true") {
+      console.log(`[normalizeNodeRuntimeBuildOutputFile] Rewriting ${filePath}`);
+    }
     fileSystem.writeFileSync(filePath, rewritten);
   }
 }
@@ -106,6 +197,7 @@ function normalizeNodeRuntimeBuildOutputs(outputPaths, rootDir) {
 }
 export {
   isDeclaredAppPackageImport,
+  isWorkspacePackageImport,
   normalizeNodeRuntimeBuildOutputFile,
   normalizeNodeRuntimeBuildOutputs
 };

package/src/build/server-entry-build-cache.d.ts

@@ -0,0 +1,44 @@
+import type { BuildResult } from './build-adapter.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+/** @deprecated Use {@link ROUTE_MODULE_BUILD_CACHE_FILENAME}; both caches share the same manifest filename. */
+export declare const SERVER_ENTRY_BUILD_CACHE_FILENAME = ".build-cache.json";
+export declare const SERVER_BUNDLE_MANIFEST_FILENAME = "manifest.json";
+export interface ServerBundleDeployManifest {
+    serverEntry: string;
+    distDir: string;
+    builtAt: number;
+}
+export interface ServerEntryBuildCacheManifest {
+    invalidationVersion: string;
+    entryPath: string;
+    entryHash: string;
+    buildInputsFingerprint: string;
+    buildKey: string;
+    outputPaths: string[];
+    dependencyHashes: Record<string, string>;
+    builtAt: number;
+}
+export interface ServerEntryBuildCacheLookup {
+    manifest: ServerEntryBuildCacheManifest;
+    outputPaths: string[];
+}
+export declare function getServerBundleOutputPaths(appConfig: EcoPagesAppConfig): {
+    distDir: string;
+    serverOutdir: string;
+    serverEntryPath: string;
+    manifestPath: string;
+};
+export declare function readServerEntryBuildCacheManifest(appConfig: EcoPagesAppConfig): ServerEntryBuildCacheManifest | undefined;
+export declare function writeServerBundleDeployManifest(appConfig: EcoPagesAppConfig, serverEntryPath: string): void;
+export declare function lookupServerEntryBuildCache(options: {
+    appConfig: EcoPagesAppConfig;
+    entryPath: string;
+    force?: boolean;
+}): ServerEntryBuildCacheLookup | undefined;
+export declare function recordServerEntryBuildCache(options: {
+    appConfig: EcoPagesAppConfig;
+    entryPath: string;
+    buildResult: BuildResult;
+    outputPaths: string[];
+}): void;
+export declare function resolveProductionServerEntry(cwd?: string): string | undefined;

package/src/build/server-entry-build-cache.js

@@ -0,0 +1,161 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { getAppServerBuildPlugins } from "./build-adapter.js";
+import { createBuildInputsFingerprint } from "./build-input-fingerprint.js";
+import {
+  isProductionCacheManifestCurrent,
+  matchesProductionCacheBuildKey,
+  matchesProductionCacheFingerprint,
+  readProductionCacheManifest,
+  writeProductionCacheManifest
+} from "./production-build-cache.js";
+import { getCorePackageVersion } from "../services/module-loading/route-module-build-manifest.js";
+import {
+  RouteModuleDependencyHasher,
+  createRouteModuleDependencyHashes
+} from "../services/module-loading/route-module-dependency-hasher.js";
+import { resolveInternalExecutionDir } from "../utils/resolve-work-dir.js";
+import { SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from "../utils/resolve-entry-file.js";
+import { ROUTE_MODULE_BUILD_CACHE_FILENAME } from "../services/module-loading/route-module-build-manifest.js";
+const SERVER_ENTRY_BUILD_CACHE_FILENAME = ROUTE_MODULE_BUILD_CACHE_FILENAME;
+const SERVER_BUNDLE_MANIFEST_FILENAME = "manifest.json";
+function getServerEntryCacheDir(appConfig) {
+  return path.join(resolveInternalExecutionDir(appConfig), ".server-entry");
+}
+function getServerEntryCacheManifestPath(appConfig) {
+  return path.join(getServerEntryCacheDir(appConfig), SERVER_ENTRY_BUILD_CACHE_FILENAME);
+}
+function hashDependencyGraph(entryPath, dependencyGraph, hasher, rootDir) {
+  if (!dependencyGraph) {
+    return { [path.resolve(entryPath)]: fileSystem.hash(entryPath) };
+  }
+  return createRouteModuleDependencyHashes(hasher, { dependencyGraph }, entryPath, rootDir);
+}
+function createServerEntryBuildKey(appConfig) {
+  try {
+    const plugins = getAppServerBuildPlugins(appConfig);
+    const pluginNames = plugins.map((plugin) => plugin.name).sort().join("|");
+    return ["node", "esm", "external-packages", pluginNames].join("::");
+  } catch {
+    return "node::esm::external-packages";
+  }
+}
+function getServerBundleOutputPaths(appConfig) {
+  const distDir = appConfig.absolutePaths?.distDir ?? path.join(appConfig.rootDir, appConfig.distDir);
+  const serverOutdir = path.join(distDir, SERVER_BUNDLE_DIR);
+  const serverEntryPath = path.join(serverOutdir, SERVER_BUNDLE_FILENAME);
+  const manifestPath = path.join(serverOutdir, SERVER_BUNDLE_MANIFEST_FILENAME);
+  return { distDir, serverOutdir, serverEntryPath, manifestPath };
+}
+function readServerEntryBuildCacheManifest(appConfig) {
+  return readProductionCacheManifest(getServerEntryCacheManifestPath(appConfig));
+}
+function writeServerEntryBuildCacheManifest(appConfig, manifest) {
+  writeProductionCacheManifest(
+    path.join(getServerEntryCacheDir(appConfig), SERVER_ENTRY_BUILD_CACHE_FILENAME),
+    manifest
+  );
+}
+function writeServerBundleDeployManifest(appConfig, serverEntryPath) {
+  const { distDir, manifestPath } = getServerBundleOutputPaths(appConfig);
+  fileSystem.ensureDir(path.dirname(manifestPath));
+  const payload = {
+    serverEntry: path.relative(path.dirname(manifestPath), serverEntryPath) || SERVER_BUNDLE_FILENAME,
+    distDir,
+    builtAt: Date.now()
+  };
+  fileSystem.write(manifestPath, `${JSON.stringify(payload, null, "	")}
+`);
+}
+function lookupServerEntryBuildCache(options) {
+  if (options.force) {
+    return void 0;
+  }
+  if (process.env.NODE_ENV !== "production") {
+    return void 0;
+  }
+  const entryPath = path.resolve(options.entryPath);
+  const entryHash = fileSystem.hash(entryPath);
+  const buildInputsFingerprint = createBuildInputsFingerprint(options.appConfig);
+  const buildKey = createServerEntryBuildKey(options.appConfig);
+  const manifest = readServerEntryBuildCacheManifest(options.appConfig);
+  if (!manifest) {
+    return void 0;
+  }
+  if (!isProductionCacheManifestCurrent(manifest, getCorePackageVersion())) {
+    return void 0;
+  }
+  if (manifest.entryPath !== entryPath || manifest.entryHash !== entryHash || !matchesProductionCacheFingerprint(manifest, buildInputsFingerprint) || !matchesProductionCacheBuildKey(manifest, buildKey)) {
+    return void 0;
+  }
+  const hasher = new RouteModuleDependencyHasher();
+  if (!hasher.matchesStoredHashes(manifest.dependencyHashes, entryPath, entryHash)) {
+    return void 0;
+  }
+  const existingOutputs = manifest.outputPaths.filter((outputPath) => fileSystem.exists(outputPath));
+  if (existingOutputs.length === 0) {
+    return void 0;
+  }
+  return {
+    manifest,
+    outputPaths: existingOutputs
+  };
+}
+function recordServerEntryBuildCache(options) {
+  if (process.env.NODE_ENV !== "production") {
+    return;
+  }
+  const entryPath = path.resolve(options.entryPath);
+  const entryHash = fileSystem.hash(entryPath);
+  const hasher = new RouteModuleDependencyHasher();
+  const dependencyHashes = hashDependencyGraph(
+    entryPath,
+    options.buildResult.dependencyGraph,
+    hasher,
+    options.appConfig.rootDir
+  );
+  const manifest = {
+    invalidationVersion: getCorePackageVersion(),
+    entryPath,
+    entryHash,
+    buildInputsFingerprint: createBuildInputsFingerprint(options.appConfig),
+    buildKey: createServerEntryBuildKey(options.appConfig),
+    outputPaths: options.outputPaths,
+    dependencyHashes,
+    builtAt: Date.now()
+  };
+  writeServerEntryBuildCacheManifest(options.appConfig, manifest);
+}
+function resolveProductionServerEntry(cwd = process.cwd()) {
+  const manifestPath = path.join(cwd, "dist", SERVER_BUNDLE_DIR, SERVER_BUNDLE_MANIFEST_FILENAME);
+  if (fileSystem.exists(manifestPath)) {
+    try {
+      const parsed = JSON.parse(fileSystem.readFileSync(manifestPath));
+      if (parsed?.serverEntry) {
+        const fromManifest = path.isAbsolute(parsed.serverEntry) ? parsed.serverEntry : path.join(path.dirname(manifestPath), parsed.serverEntry);
+        if (fileSystem.exists(fromManifest)) {
+          return fromManifest;
+        }
+      }
+      if (parsed?.distDir) {
+        const fromDistDir = path.join(parsed.distDir, SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+        if (fileSystem.exists(fromDistDir)) {
+          return fromDistDir;
+        }
+      }
+    } catch {
+    }
+  }
+  const legacyPath = path.join(cwd, "dist", SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+  return fileSystem.exists(legacyPath) ? legacyPath : void 0;
+}
+export {
+  SERVER_BUNDLE_MANIFEST_FILENAME,
+  SERVER_ENTRY_BUILD_CACHE_FILENAME,
+  getServerBundleOutputPaths,
+  lookupServerEntryBuildCache,
+  readServerEntryBuildCacheManifest,
+  recordServerEntryBuildCache,
+  resolveProductionServerEntry,
+  writeServerBundleDeployManifest
+};

package/src/config/config-builder.d.ts

@@ -70,12 +70,7 @@ export declare class ConfigBuilder {
      *
      * - `'rolldown'` (default): Ecopages runs builds through
      *   {@link RolldownBuildAdapter}, creating a new `rolldown()` instance
-     *   per build. Best for one-shot production builds and benchmarks.
-     * - `'rolldown-dev'`: Ecopages runs builds through
-     *   {@link RolldownDevBuildAdapter}, which wraps Rolldown's experimental
-     *   `DevEngine` and reuses the cached module graph, resolver, and
-     *   transform cache across rebuilds. Best for HMR and watch mode where
-     *   the same entrypoints are rebuilt repeatedly.
+     *   per build.
      * - `'vite-host'`: a host runtime owns the build. Ecopages exposes a
      *   {@link ViteHostBuildAdapter} boundary marker that throws on direct
      *   use. Select this only for host-driven compatibility flows where
@@ -250,7 +245,17 @@ export declare class ConfigBuilder {
     private compareVersions;
     /**
      * Initializes default loaders that are required for EcoPages to function.
-     * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
+     *
+     * @remarks
+     * `eco-component-meta` is registered twice on purpose:
+     *
+     * - `sourceTransforms` is the canonical browser/HMR path. The Rolldown bridge
+     *   runs these after first-wins `onLoad` plugins rewrite module source.
+     * - `loaders` keeps the same transform available to server-oriented builds
+     *   that still use competing `onLoad` handlers directly.
+     *
+     * Browser builds exclude the loader copy in {@link getAppBrowserBuildPlugins}
+     * when the transform name is already present in `sourceTransforms`.
      */
     private initializeDefaultLoaders;
     private reviewBaseUrl;

package/src/config/config-builder.js

@@ -9,7 +9,6 @@ import {
   collectConfiguredAppBuildManifestContributions,
   createBuildAdapter,
   setAppBuildAdapter,
-  setAppBuildExecutor,
   updateAppBuildManifest
 } from "../build/build-adapter.js";
 import { GHTML_PLUGIN_NAME } from "../integrations/ghtml/ghtml.constants.js";
@@ -112,12 +111,7 @@ class ConfigBuilder {
    *
    * - `'rolldown'` (default): Ecopages runs builds through
    *   {@link RolldownBuildAdapter}, creating a new `rolldown()` instance
-   *   per build. Best for one-shot production builds and benchmarks.
-   * - `'rolldown-dev'`: Ecopages runs builds through
-   *   {@link RolldownDevBuildAdapter}, which wraps Rolldown's experimental
-   *   `DevEngine` and reuses the cached module graph, resolver, and
-   *   transform cache across rebuilds. Best for HMR and watch mode where
-   *   the same entrypoints are rebuilt repeatedly.
+   *   per build.
    * - `'vite-host'`: a host runtime owns the build. Ecopages exposes a
    *   {@link ViteHostBuildAdapter} boundary marker that throws on direct
    *   use. Select this only for host-driven compatibility flows where
@@ -547,7 +541,17 @@ class ConfigBuilder {
   }
   /**
    * Initializes default loaders that are required for EcoPages to function.
-   * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
+   *
+   * @remarks
+   * `eco-component-meta` is registered twice on purpose:
+   *
+   * - `sourceTransforms` is the canonical browser/HMR path. The Rolldown bridge
+   *   runs these after first-wins `onLoad` plugins rewrite module source.
+   * - `loaders` keeps the same transform available to server-oriented builds
+   *   that still use competing `onLoad` handlers directly.
+   *
+   * Browser builds exclude the loader copy in {@link getAppBrowserBuildPlugins}
+   * when the transform name is already present in `sourceTransforms`.
    */
   async initializeDefaultLoaders() {
     const componentMetaTransform = createEcoComponentMetaTransform({ config: this.config });
@@ -593,7 +597,6 @@ class ConfigBuilder {
     updateAppBuildManifest(this.config, await collectConfiguredAppBuildManifestContributions(this.config));
     setAppServerInvalidationState(this.config, new CounterServerInvalidationState());
     setAppEntrypointDependencyGraph(this.config, new NoopEntrypointDependencyGraph());
-    setAppBuildExecutor(this.config, buildAdapter);
     return this.config;
   }
 }

package/src/dev/client-bridge-registry.d.ts

@@ -0,0 +1,5 @@
+import type { EcoPagesAppConfig } from '../types/public-types.js';
+import type { IClientBridge } from '../types/public-types.js';
+export declare function setAppDevClientBridge(appConfig: EcoPagesAppConfig, bridge: IClientBridge): void;
+export declare function getAppDevClientBridge(appConfig: EcoPagesAppConfig): IClientBridge | undefined;
+export declare function clearAppDevClientBridge(appConfig: EcoPagesAppConfig): void;

package/src/dev/client-bridge-registry.js

@@ -0,0 +1,15 @@
+const appDevClientBridges = /* @__PURE__ */ new WeakMap();
+function setAppDevClientBridge(appConfig, bridge) {
+  appDevClientBridges.set(appConfig, bridge);
+}
+function getAppDevClientBridge(appConfig) {
+  return appDevClientBridges.get(appConfig);
+}
+function clearAppDevClientBridge(appConfig) {
+  appDevClientBridges.delete(appConfig);
+}
+export {
+  clearAppDevClientBridge,
+  getAppDevClientBridge,
+  setAppDevClientBridge
+};

package/src/dev/dev-client-ownership.d.ts

@@ -0,0 +1,7 @@
+import type { ApplicationRuntimeOptions } from '../adapters/abstract/application-adapter.js';
+/**
+ * Returns whether the host dev server owns all browser dev-client bootstrap.
+ *
+ * When true, core must not inject the HMR runtime or signal full-page reloads.
+ */
+export declare function hostOwnsDevClient(runtime?: ApplicationRuntimeOptions): boolean;

package/src/dev/dev-client-ownership.js

@@ -0,0 +1,6 @@
+function hostOwnsDevClient(runtime) {
+  return runtime?.devClientOwner === "host" || runtime?.delegateBrowserReloadToHost === true;
+}
+export {
+  hostOwnsDevClient
+};

package/src/dev/host-runtime.d.ts

@@ -1,10 +1,13 @@
 import type { EcoPagesAppConfig } from '../types/public-types.js';
 import { type DevelopmentInvalidationPlan } from '../services/invalidation/development-invalidation.service.js';
+import type { ClientBridgeEvent } from '../types/public-types.js';
 export type HostRuntimeModuleLoader = (id: string) => Promise<unknown>;
 export interface DevelopmentHostRuntime {
     registerHostModuleLoader(loader: HostRuntimeModuleLoader): void;
     planFileChange(filePath: string): DevelopmentInvalidationPlan;
     invalidateServerModules(changedFiles?: string[]): void;
     resetRuntimeState(changedFiles?: string[]): void;
+    broadcastClientEvent(event: ClientBridgeEvent): void;
+    isServerRenderedTemplatePlan(plan: DevelopmentInvalidationPlan): boolean;
 }
 export declare function createDevelopmentHostRuntime(appConfig: EcoPagesAppConfig): DevelopmentHostRuntime;

package/src/dev/host-runtime.js

@@ -1,6 +1,7 @@
 import {
   DevelopmentInvalidationService
 } from "../services/invalidation/development-invalidation.service.js";
+import { getAppDevClientBridge } from "./client-bridge-registry.js";
 import { setHostModuleLoader } from "../services/module-loading/host-module-loader-registry.js";
 function createDevelopmentHostRuntime(appConfig) {
   const invalidationService = new DevelopmentInvalidationService(appConfig);
@@ -16,6 +17,12 @@ function createDevelopmentHostRuntime(appConfig) {
     },
     resetRuntimeState(changedFiles) {
       invalidationService.resetRuntimeState(changedFiles);
+    },
+    broadcastClientEvent(event) {
+      getAppDevClientBridge(appConfig)?.broadcast(event);
+    },
+    isServerRenderedTemplatePlan(plan) {
+      return plan.category === "include-source" || plan.category === "explicit-server-view";
     }
   };
 }

package/src/hmr/client/hmr-runtime.js

@@ -12,7 +12,7 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
     socket.addEventListener("message", async (event) => {
       try {
         const payload = JSON.parse(event.data);
-        handleMessage(payload);
+        await handleMessage(payload);
       } catch (e) {
         console.error("[ecopages] Invalid HMR message:", e);
       }
@@ -29,12 +29,15 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
     switch (payload.type) {
       case "reload":
         await waitForNavigationToSettle(navigationRuntime);
+        if (window.__ECOPAGES_HOST_OWNS_RELOAD__) {
+          break;
+        }
         location.reload();
         break;
       case "layout-update": {
         await waitForNavigationToSettle(navigationRuntime);
         if (await navigationRuntime.reloadCurrentPage({ clearCache: true, moduleUrl: getActiveHmrModuleUrl() })) {
-        } else {
+        } else if (!window.__ECOPAGES_HOST_OWNS_RELOAD__) {
           location.reload();
         }
         break;

package/src/hmr/strategies/server-rendered-template-hmr-strategy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * HMR strategy for server-rendered include templates and explicit server views.
+ *
+ * These files affect SSR output (head, layout shell, explicit views) but are not
+ * client HMR entrypoints. Broadcast a layout-update so the active navigation
+ * runtime can refresh the current page without a full document reload.
+ */
+import { HmrStrategy, type HmrAction } from '../hmr-strategy.js';
+import type { DevelopmentInvalidationService } from '../../services/invalidation/development-invalidation.service.js';
+export declare class ServerRenderedTemplateHmrStrategy extends HmrStrategy {
+    private readonly invalidationService;
+    readonly type: 100;
+    readonly priorityOffset = 50;
+    constructor(invalidationService: DevelopmentInvalidationService);
+    matches(filePath: string): boolean;
+    process(filePath: string): Promise<HmrAction>;
+}

package/src/hmr/strategies/server-rendered-template-hmr-strategy.js

@@ -0,0 +1,29 @@
+import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
+const SERVER_RENDERED_TEMPLATE_PRIORITY_OFFSET = 50;
+class ServerRenderedTemplateHmrStrategy extends HmrStrategy {
+  constructor(invalidationService) {
+    super();
+    this.invalidationService = invalidationService;
+  }
+  invalidationService;
+  type = HmrStrategyType.INTEGRATION;
+  priorityOffset = SERVER_RENDERED_TEMPLATE_PRIORITY_OFFSET;
+  matches(filePath) {
+    return this.invalidationService.isIncludeSourceFile(filePath) || this.invalidationService.isExplicitServerViewFile(filePath);
+  }
+  async process(filePath) {
+    return {
+      type: "broadcast",
+      events: [
+        {
+          type: "layout-update",
+          path: filePath,
+          timestamp: Date.now()
+        }
+      ]
+    };
+  }
+}
+export {
+  ServerRenderedTemplateHmrStrategy
+};

package/src/integrations/ghtml/ghtml-renderer.d.ts

@@ -2,15 +2,11 @@
  * This module contains the ghtml renderer
  * @module
  */
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../types/public-types.js';
-import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/orchestration/integration-renderer.js';
+import { StringMarkupRenderer } from '../../route-renderer/orchestration/string-markup-renderer.js';
 /**
  * A renderer for the ghtml integration.
  * It renders a page using the HtmlTemplate and Page components.
  */
-export declare class GhtmlRenderer extends IntegrationRenderer<EcoPagesElement> {
+export declare class GhtmlRenderer extends StringMarkupRenderer {
     name: string;
-    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
-    render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, }: IntegrationRendererRenderOptions): Promise<RouteRendererBody>;
-    renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }

package/src/integrations/ghtml/ghtml-renderer.js

@@ -1,56 +1,7 @@
-import {
-  IntegrationRenderer
-} from "../../route-renderer/orchestration/integration-renderer.js";
+import { StringMarkupRenderer } from "../../route-renderer/orchestration/string-markup-renderer.js";
 import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
-class GhtmlRenderer extends IntegrationRenderer {
+class GhtmlRenderer extends StringMarkupRenderer {
   name = GHTML_PLUGIN_NAME;
-  async renderComponent(input) {
-    return this.renderStringComponentWithQueuedForeignSubtrees(
-      input,
-      input.component
-    );
-  }
-  async render({
-    params,
-    query,
-    props,
-    locals,
-    pageLocals,
-    metadata,
-    Page,
-    Layout,
-    HtmlTemplate
-  }) {
-    try {
-      return await this.renderPageWithDocumentShell({
-        page: {
-          component: Page,
-          props: { params, query, ...props, locals: pageLocals }
-        },
-        layout: Layout ? {
-          component: Layout,
-          props: locals ? { locals } : {}
-        } : void 0,
-        htmlTemplate: HtmlTemplate,
-        metadata,
-        pageProps: props ?? {}
-      });
-    } catch (error) {
-      throw this.createRenderError("Error rendering page", error);
-    }
-  }
-  async renderToResponse(view, props, ctx) {
-    try {
-      return await this.renderViewWithDocumentShell({
-        view,
-        props,
-        ctx,
-        layout: view.config?.layout
-      });
-    } catch (error) {
-      throw this.createRenderError("Error rendering view", error);
-    }
-  }
 }
 export {
   GhtmlRenderer