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

package/src/eco/eco.js

@@ -4,6 +4,7 @@ import {
   interceptForeignChild
 } from "../route-renderer/orchestration/component-render-context.js";
 import { isThenable } from "../route-renderer/orchestration/render-output.utils.js";
+import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts } from "./page-layout-normalization.js";
 function createComponentFactory(options) {
   const integrationName = options.integration ?? options.__eco?.integration;
   const comp = ((props) => {
@@ -74,18 +75,16 @@ function layout(options) {
 }
 function page(options) {
   const { layout: layout2, dependencies, render, staticPaths: staticPaths2, staticProps: staticProps2, metadata: metadata2, cache, requires, middleware } = options;
+  const layoutEntries = normalizePageLayouts(layout2);
   const componentOptions = {
     __eco: options.__eco,
     integration: options.integration,
-    dependencies: layout2 ? {
-      ...dependencies,
-      components: [...dependencies?.components || [], layout2]
-    } : dependencies,
+    dependencies: mergeLayoutDependencies(dependencies, layoutEntries),
     render
   };
   const pageComponent = createComponentFactory(componentOptions);
-  if (layout2 && pageComponent.config) {
-    pageComponent.config.layout = layout2;
+  if (pageComponent.config) {
+    applyPageLayoutConfig(pageComponent.config, layoutEntries);
   }
   if (staticPaths2) pageComponent.staticPaths = staticPaths2;
   if (staticProps2) pageComponent.staticProps = staticProps2;

package/src/eco/eco.types.d.ts

@@ -2,7 +2,7 @@
  * Type definitions for the eco namespace API
  * @module
  */
-import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayoutComponent, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext } from '../types/public-types.js';
+import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayouts, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext } from '../types/public-types.js';
 import type { CacheStrategy } from '../services/cache/cache.types.js';
 /**
  * Extracts the props type from one eco component.
@@ -81,7 +81,7 @@ export interface PageOptionsBase<T, E = EcoPagesElement> {
     __eco?: EcoInjectedMeta;
     integration?: string;
     dependencies?: EcoComponentDependencies;
-    layout?: EcoPageLayoutComponent<E>;
+    layout?: EcoPageLayouts<E>;
     /**
      * Define static paths for dynamic routes (e.g., [slug].tsx).
      * Returns all possible paths that should be pre-rendered at build time.

package/src/eco/page-layout-normalization.d.ts

@@ -0,0 +1,21 @@
+import type { EcoComponentConfig, EcoComponentDependencies, EcoPageLayoutEntry, EcoPageLayouts } from '../types/public-types.js';
+/**
+ * Normalizes `layout` page options to an outer→inner stack of layout entries.
+ */
+export declare function normalizePageLayouts<E>(layout?: EcoPageLayouts<E>): EcoPageLayoutEntry<E>[];
+/**
+ * Merges layout components into `dependencies.components` without duplicates.
+ */
+export declare function mergeLayoutDependencies(dependencies: EcoComponentDependencies | undefined, layoutEntries: EcoPageLayoutEntry[]): EcoComponentDependencies | undefined;
+/**
+ * Writes normalized layout metadata onto a page `config`.
+ */
+export declare function applyPageLayoutConfig(pageConfig: EcoComponentConfig, layoutEntries: EcoPageLayoutEntry[]): void;
+/**
+ * Migrates MDX-exported `config.layout` values onto normalized layout metadata.
+ *
+ * @remarks
+ * `eco.page({ layout })` already normalizes at factory time. MDX modules that
+ * export `config.layout` directly still need this import-time migration.
+ */
+export declare function ensurePageConfigLayouts(config: EcoComponentConfig | undefined): EcoComponentConfig | undefined;

package/src/eco/page-layout-normalization.js

@@ -0,0 +1,59 @@
+function isLayoutSpecObject(spec) {
+  return typeof spec === "object" && spec !== null && "component" in spec;
+}
+function normalizePageLayouts(layout) {
+  if (!layout) {
+    return [];
+  }
+  const specs = Array.isArray(layout) ? layout : [layout];
+  return specs.map((spec) => {
+    if (isLayoutSpecObject(spec)) {
+      return {
+        component: spec.component,
+        props: spec.props
+      };
+    }
+    return {
+      component: spec
+    };
+  });
+}
+function mergeLayoutDependencies(dependencies, layoutEntries) {
+  if (layoutEntries.length === 0) {
+    return dependencies;
+  }
+  const mergedComponents = [...dependencies?.components ?? []];
+  for (const entry of layoutEntries) {
+    if (!mergedComponents.includes(entry.component)) {
+      mergedComponents.push(entry.component);
+    }
+  }
+  return {
+    ...dependencies,
+    components: mergedComponents
+  };
+}
+function applyPageLayoutConfig(pageConfig, layoutEntries) {
+  if (layoutEntries.length === 0) {
+    return;
+  }
+  pageConfig.layouts = layoutEntries.map((entry) => entry.component);
+  pageConfig.layoutEntries = layoutEntries;
+}
+function ensurePageConfigLayouts(config) {
+  if (!config || config.layouts && config.layouts.length > 0) {
+    return config;
+  }
+  const legacyLayout = config.layout;
+  if (!legacyLayout) {
+    return config;
+  }
+  applyPageLayoutConfig(config, normalizePageLayouts(legacyLayout));
+  return config;
+}
+export {
+  applyPageLayoutConfig,
+  ensurePageConfigLayouts,
+  mergeLayoutDependencies,
+  normalizePageLayouts
+};

package/src/errors/index.d.ts

@@ -1,3 +1,4 @@
 export { HttpError } from './http-error.js';
 export type { HttpErrorDetails, HttpErrorJson } from './http-error.js';
 export { LocalsAccessError } from './locals-access-error.js';
+export { UndeclaredComponentDependencyError, getUndeclaredComponentDependencyMessage, } from './undeclared-component-dependency-error.js';

package/src/errors/index.js

@@ -1,6 +1,12 @@
 import { HttpError } from "./http-error.js";
 import { LocalsAccessError } from "./locals-access-error.js";
+import {
+  UndeclaredComponentDependencyError,
+  getUndeclaredComponentDependencyMessage
+} from "./undeclared-component-dependency-error.js";
 export {
   HttpError,
-  LocalsAccessError
+  LocalsAccessError,
+  UndeclaredComponentDependencyError,
+  getUndeclaredComponentDependencyMessage
 };

package/src/errors/undeclared-component-dependency-error.d.ts

@@ -0,0 +1,11 @@
+export declare function getUndeclaredComponentDependencyMessage(parentComponentFile?: string): string;
+/**
+ * Thrown when `dependencies.components` contains a plain function or component
+ * without plugin-injected `config.__eco` metadata.
+ */
+export declare class UndeclaredComponentDependencyError extends Error {
+    name: string;
+    /** Parent component file path when the invalid entry was declared. */
+    readonly parentComponentFile?: string;
+    constructor(parentComponentFile?: string);
+}

package/src/errors/undeclared-component-dependency-error.js

@@ -0,0 +1,17 @@
+function getUndeclaredComponentDependencyMessage(parentComponentFile) {
+  const parentHint = parentComponentFile ? ` (declared by ${parentComponentFile})` : "";
+  return `[ecopages] dependencies.components entries must be eco.component(), eco.layout(), or eco.html() components with __eco metadata${parentHint}. Plain functions and untyped components are not valid dependency entries.`;
+}
+class UndeclaredComponentDependencyError extends Error {
+  name = "UndeclaredComponentDependencyError";
+  /** Parent component file path when the invalid entry was declared. */
+  parentComponentFile;
+  constructor(parentComponentFile) {
+    super(getUndeclaredComponentDependencyMessage(parentComponentFile));
+    this.parentComponentFile = parentComponentFile;
+  }
+}
+export {
+  UndeclaredComponentDependencyError,
+  getUndeclaredComponentDependencyMessage
+};

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/hmr-entrypoint-output.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Verified HMR entrypoint artifact produced by registration.
+ */
+export interface ResolvedHmrEntrypoint {
+    sourcePath: string;
+    outputPath: string;
+    outputUrl: string;
+}
+/**
+ * Returns whether a source path is a registered client script HMR entrypoint.
+ */
+export declare function isRegisteredScriptEntrypoint(registered: ReadonlyMap<string, unknown>, filePath: string): boolean;
+/**
+ * Returns whether a registered script entrypoint is browser-only and must not be
+ * server-imported during HMR invalidation.
+ *
+ * @remarks
+ * Declared `*.script.ts` modules run only in the browser bundle. Re-importing them
+ * on the server during `prepareRegisteredScriptChange()` executes DOM globals and
+ * aborts the watcher before the client artifact rebuilds. Radiant `*.script.tsx`
+ * entrypoints are server-rendered and remain on the invalidation path.
+ */
+export declare function isBrowserOnlyRegisteredScriptEntrypoint(filePath: string): boolean;
+export declare function encodeHmrDynamicSegments(filepath: string): string;
+/**
+ * Resolves the on-disk and browser URL targets for one HMR script entrypoint.
+ */
+export declare function resolveHmrEntrypointOutputPaths(srcDir: string, distDir: string, entrypointPath: string): {
+    outputPath: string;
+    outputUrl: string;
+};
+/**
+ * @remarks
+ * Rebuilds must delete the previous artifact so browser-hmr does not reuse a
+ * stale bundle when the source file changed.
+ */
+export declare function removeStaleHmrEntrypointOutput(outputPath: string, scope: string): void;
+/**
+ * @remarks
+ * Guards against broadcasting reload/update before the bundler has flushed a
+ * fresher artifact than the edited source file.
+ */
+export declare function isHmrOutputFresh(outputPath: string, sourcePath: string): boolean;

package/src/hmr/hmr-entrypoint-output.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { RESOLVED_ASSETS_DIR } from "../config/constants.js";
+import { appLogger } from "../global/app-logger.js";
+function isRegisteredScriptEntrypoint(registered, filePath) {
+  return registered.has(path.resolve(filePath));
+}
+function isBrowserOnlyRegisteredScriptEntrypoint(filePath) {
+  return /\.script\.ts$/u.test(path.resolve(filePath));
+}
+function encodeHmrDynamicSegments(filepath) {
+  return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
+}
+function resolveHmrEntrypointOutputPaths(srcDir, distDir, entrypointPath) {
+  const normalizedEntrypoint = path.resolve(entrypointPath);
+  const relativePath = path.relative(srcDir, normalizedEntrypoint);
+  const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
+  const encodedPathJs = encodeHmrDynamicSegments(relativePathJs);
+  const urlPath = encodedPathJs.split(path.sep).join("/");
+  return {
+    outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath).split(path.sep).join("/")}`,
+    outputPath: path.join(distDir, urlPath)
+  };
+}
+function removeStaleHmrEntrypointOutput(outputPath, scope) {
+  if (!fileSystem.exists(outputPath)) {
+    return;
+  }
+  try {
+    fileSystem.remove(outputPath);
+  } catch (error) {
+    appLogger.warn(
+      `[${scope}] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function isHmrOutputFresh(outputPath, sourcePath) {
+  if (!fileSystem.exists(outputPath) || !fileSystem.exists(sourcePath)) {
+    return false;
+  }
+  const outputMtimeMs = fs.statSync(outputPath).mtimeMs;
+  const sourceMtimeMs = fs.statSync(sourcePath).mtimeMs;
+  return outputMtimeMs >= sourceMtimeMs;
+}
+export {
+  encodeHmrDynamicSegments,
+  isBrowserOnlyRegisteredScriptEntrypoint,
+  isHmrOutputFresh,
+  isRegisteredScriptEntrypoint,
+  removeStaleHmrEntrypointOutput,
+  resolveHmrEntrypointOutputPaths
+};

package/src/hmr/hmr-strategy.d.ts

@@ -133,6 +133,21 @@ export declare abstract class HmrStrategy {
      * ```
      */
     abstract matches(filePath: string): boolean;
+    /**
+     * Returns whether this strategy owns cold registration for the entrypoint.
+     *
+     * @remarks
+     * Registration dispatch uses only integration strategies that claim the
+     * entrypoint. File-change dispatch continues to use {@link matches}.
+     */
+    canEmitEntrypoint(_entrypointPath: string): boolean;
+    /**
+     * Materializes one integration-owned HMR entrypoint during registration.
+     *
+     * @remarks
+     * Must write the canonical output path and must not broadcast client events.
+     */
+    emitEntrypoint(_entrypointPath: string, _outputPath: string): Promise<void>;
     /**
      * Processes a file change and returns the action to take.
      *

package/src/hmr/hmr-strategy.js

@@ -37,6 +37,25 @@ class HmrStrategy {
   get priority() {
     return this.type + this.priorityOffset;
   }
+  /**
+   * Returns whether this strategy owns cold registration for the entrypoint.
+   *
+   * @remarks
+   * Registration dispatch uses only integration strategies that claim the
+   * entrypoint. File-change dispatch continues to use {@link matches}.
+   */
+  canEmitEntrypoint(_entrypointPath) {
+    return false;
+  }
+  /**
+   * Materializes one integration-owned HMR entrypoint during registration.
+   *
+   * @remarks
+   * Must write the canonical output path and must not broadcast client events.
+   */
+  async emitEntrypoint(_entrypointPath, _outputPath) {
+    return;
+  }
 }
 export {
   HmrStrategy,

package/src/hmr/strategies/js-hmr-strategy.d.ts

@@ -8,7 +8,6 @@
  * @module
  */
 import { HmrStrategy, type HmrAction } from '../hmr-strategy.js';
-import type { EcoBuildPlugin } from '../../build/build-types.js';
 import type { BrowserBundleExecutor } from '../../services/assets/browser-bundle.service.js';
 import type { EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
 /**
@@ -25,10 +24,6 @@ export interface JsHmrContext {
      * Directory where HMR bundles are written.
      */
     getDistDir(): string;
-    /**
-     * Build plugins to use during bundling.
-     */
-    getPlugins(): EcoBuildPlugin[];
     /**
      * Absolute path to the source directory.
      */
@@ -98,6 +93,7 @@ export declare class JsHmrStrategy extends HmrStrategy {
      * Matches if:
      * 1. There are registered entrypoints to rebuild
      * 2. The changed file is a JS/TS file in the src directory
+     * 3. Registered entrypoints always match, even when they share an integration template extension
      *
      * @param filePath - Absolute path to the changed file
      * @returns True if this file should trigger entrypoint rebuilds
@@ -116,6 +112,8 @@ export declare class JsHmrStrategy extends HmrStrategy {
      * @returns Action to broadcast update events
      */
     process(filePath: string): Promise<HmrAction>;
+    private resolveEntrypointOutputPath;
+    private removeStaleEntrypointOutput;
     /**
      * Bundles one or more entrypoints in a single build invocation.
      * Uses the source directory as the output base so that the directory structure

package/src/hmr/strategies/js-hmr-strategy.js

@@ -2,6 +2,12 @@ import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
 import { appLogger } from "../../global/app-logger.js";
+import {
+  removeStaleHmrEntrypointOutput,
+  resolveHmrEntrypointOutputPaths,
+  isRegisteredScriptEntrypoint,
+  isHmrOutputFresh
+} from "../hmr-entrypoint-output.js";
 class JsHmrStrategy extends HmrStrategy {
   type = HmrStrategyType.SCRIPT;
   context;
@@ -15,27 +21,30 @@ class JsHmrStrategy extends HmrStrategy {
    * Matches if:
    * 1. There are registered entrypoints to rebuild
    * 2. The changed file is a JS/TS file in the src directory
+   * 3. Registered entrypoints always match, even when they share an integration template extension
    *
    * @param filePath - Absolute path to the changed file
    * @returns True if this file should trigger entrypoint rebuilds
    */
   matches(filePath) {
     const watchedFiles = this.context.getWatchedFiles();
-    const isJsTs = /\.(ts|tsx|js|jsx)$/.test(filePath);
-    const isInSrc = filePath.startsWith(this.context.getSrcDir());
-    const isIntegrationTemplate = this.context.getTemplateExtensions().some((extension) => filePath.endsWith(extension));
+    const resolvedPath = path.resolve(filePath);
+    const isJsTs = /\.(ts|tsx|js|jsx)$/.test(resolvedPath);
+    const srcDir = path.resolve(this.context.getSrcDir());
+    const isInSrc = resolvedPath.startsWith(`${srcDir}${path.sep}`) || resolvedPath === srcDir;
+    const isIntegrationTemplate = this.context.getTemplateExtensions().some((extension) => resolvedPath.endsWith(extension));
     if (watchedFiles.size === 0) {
       return false;
     }
     if (!isJsTs || !isInSrc) {
       return false;
     }
+    if (watchedFiles.has(resolvedPath)) {
+      return true;
+    }
     if (isIntegrationTemplate) {
       return false;
     }
-    if (watchedFiles.has(filePath)) {
-      return true;
-    }
     return true;
   }
   /**
@@ -53,22 +62,27 @@ class JsHmrStrategy extends HmrStrategy {
   async process(filePath) {
     appLogger.debug(`[JsHmrStrategy] Processing ${filePath}`);
     const watchedFiles = this.context.getWatchedFiles();
+    const resolvedChanged = path.resolve(filePath);
+    const isRegisteredEntrypointEdit = isRegisteredScriptEntrypoint(watchedFiles, resolvedChanged);
     if (watchedFiles.size === 0) {
       appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
       return { type: "none" };
     }
     const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
     const hasDependencyHit = dependencyHits.size > 0;
-    const impactedEntrypoints = hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(entrypoint)) : Array.from(watchedFiles.keys());
+    const impactedEntrypoints = isRegisteredEntrypointEdit ? [resolvedChanged] : hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(path.resolve(entrypoint))) : Array.from(watchedFiles.keys());
     const buildableEntrypoints = impactedEntrypoints.filter(
       (entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true
     );
-    if (!hasDependencyHit) {
+    if (!hasDependencyHit && !isRegisteredEntrypointEdit) {
       appLogger.debug("[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints");
     }
     if (buildableEntrypoints.length === 0) {
       return { type: "none" };
     }
+    for (const entrypoint of buildableEntrypoints) {
+      this.removeStaleEntrypointOutput(this.resolveEntrypointOutputPath(entrypoint));
+    }
     const buildResult = await this.bundleEntrypoints(buildableEntrypoints);
     if (!buildResult.success) {
       return { type: "none" };
@@ -76,17 +90,19 @@ class JsHmrStrategy extends HmrStrategy {
     const updates = [];
     let reloadRequired = false;
     for (const entrypoint of buildableEntrypoints) {
-      const outputUrl = watchedFiles.get(entrypoint);
-      if (!outputUrl) continue;
+      const resolvedEntrypoint = path.resolve(entrypoint);
+      const derivedOutput = resolveHmrEntrypointOutputPaths(
+        this.context.getSrcDir(),
+        this.context.getDistDir(),
+        resolvedEntrypoint
+      );
+      const outputUrl = watchedFiles.get(resolvedEntrypoint) ?? derivedOutput.outputUrl;
+      const outputPath = this.resolveEntrypointOutputPath(resolvedEntrypoint);
       if (buildResult.dependencies) {
-        const entrypointDeps = buildResult.dependencies.get(path.resolve(entrypoint)) ?? [];
-        this.context.getEntrypointDependencyGraph().setEntrypointDependencies(entrypoint, entrypointDeps);
+        const entrypointDeps = buildResult.dependencies.get(resolvedEntrypoint) ?? [];
+        this.context.getEntrypointDependencyGraph().setEntrypointDependencies(resolvedEntrypoint, entrypointDeps);
       }
-      const srcDir = this.context.getSrcDir();
-      const relativePath = path.relative(srcDir, entrypoint);
-      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
-      const outputPath = path.join(this.context.getDistDir(), relativePathJs);
-      const result = await this.processOutput(outputPath, outputUrl);
+      const result = await this.processOutput(outputPath, outputUrl, resolvedEntrypoint);
       if (result.success) {
         updates.push(outputUrl);
         if (result.requiresReload) {
@@ -113,6 +129,12 @@ class JsHmrStrategy extends HmrStrategy {
     }
     return { type: "none" };
   }
+  resolveEntrypointOutputPath(entrypointPath) {
+    return resolveHmrEntrypointOutputPaths(this.context.getSrcDir(), this.context.getDistDir(), entrypointPath).outputPath;
+  }
+  removeStaleEntrypointOutput(outputPath) {
+    removeStaleHmrEntrypointOutput(outputPath, "JsHmrStrategy");
+  }
   /**
    * Bundles one or more entrypoints in a single build invocation.
    * Uses the source directory as the output base so that the directory structure
@@ -120,13 +142,35 @@ class JsHmrStrategy extends HmrStrategy {
    */
   async bundleEntrypoints(entrypoints) {
     try {
+      if (entrypoints.length === 1) {
+        const entrypoint = entrypoints[0];
+        const outputPath = this.resolveEntrypointOutputPath(entrypoint);
+        const naming = path.relative(this.context.getDistDir(), outputPath).split(path.sep).join("/");
+        const result2 = await this.context.getBrowserBundleService().bundle({
+          profile: "hmr-entrypoint",
+          entrypoints: [entrypoint],
+          outdir: this.context.getDistDir(),
+          naming,
+          minify: false
+        });
+        if (!result2.success) {
+          appLogger.error("[JsHmrStrategy] Entrypoint build failed:", result2.logs);
+          return { success: false };
+        }
+        const dependencies2 = /* @__PURE__ */ new Map();
+        if (result2.dependencyGraph?.entrypoints) {
+          for (const [resolvedEntrypoint, deps] of Object.entries(result2.dependencyGraph.entrypoints)) {
+            dependencies2.set(path.resolve(resolvedEntrypoint), deps);
+          }
+        }
+        return { success: true, dependencies: dependencies2 };
+      }
       const result = await this.context.getBrowserBundleService().bundle({
         profile: "hmr-entrypoint",
         entrypoints,
         outdir: this.context.getDistDir(),
         outbase: this.context.getSrcDir(),
         naming: "[dir]/[name]",
-        plugins: this.context.getPlugins(),
         minify: false
       });
       if (!result.success) {
@@ -153,8 +197,12 @@ class JsHmrStrategy extends HmrStrategy {
    * @param url - URL path for the bundled file
    * @returns True if processing was successful and update should be broadcast
    */
-  async processOutput(filepath, url) {
+  async processOutput(filepath, url, sourcePath) {
     try {
+      if (sourcePath && !isHmrOutputFresh(filepath, sourcePath)) {
+        appLogger.warn(`[JsHmrStrategy] Skipping broadcast for stale HMR output ${url}`);
+        return { success: false, requiresReload: false };
+      }
       const code = await fileSystem.readFile(filepath);
       if (code.includes("/* [ecopages] hmr */")) {
         return { success: true, requiresReload: !code.includes("import.meta.hot.accept") };

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