@ecopages/core 0.2.0-beta.17 → 0.2.0-beta.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.17",
+  "version": "0.2.0-beta.19",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.17",
+    "@ecopages/file-system": "0.2.0-beta.19",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",
@@ -133,6 +133,10 @@
       "types": "./src/dev/client-bridge-registry.d.ts",
       "default": "./src/dev/client-bridge-registry.js"
     },
+    "./dev/hmr-manager-registry": {
+      "types": "./src/dev/hmr-manager-registry.d.ts",
+      "default": "./src/dev/hmr-manager-registry.js"
+    },
     "./dev/dev-client-ownership": {
       "types": "./src/dev/dev-client-ownership.d.ts",
       "default": "./src/dev/dev-client-ownership.js"
@@ -338,6 +342,10 @@
       "types": "./src/dev/client-bridge-registry.d.ts",
       "default": "./src/dev/client-bridge-registry.js"
     },
+    "./dev/hmr-manager-registry.ts": {
+      "types": "./src/dev/hmr-manager-registry.d.ts",
+      "default": "./src/dev/hmr-manager-registry.js"
+    },
     "./dev/dev-client-ownership.ts": {
       "types": "./src/dev/dev-client-ownership.d.ts",
       "default": "./src/dev/dev-client-ownership.js"

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

@@ -24,6 +24,7 @@ import {
 } from "../shared/runtime-server-lifecycle.js";
 import { ClientBridge } from "./client-bridge.js";
 import { setAppDevClientBridge } from "../../dev/client-bridge-registry.js";
+import { setAppHmrManager } from "../../dev/hmr-manager-registry.js";
 import { HmrManager } from "./hmr-manager.js";
 import { BunStaticPreviewHost } from "./static-preview-host.js";
 class BunServerAdapter extends SharedServerAdapter {
@@ -312,6 +313,7 @@ class BunServerAdapter extends SharedServerAdapter {
   wrapFetchWithWebSocketUpgrades(originalFetch, { serveHmrEndpoints }) {
     const matchRoute = (pathname) => findWebSocketRoute(this.websocketHandlers, pathname);
     const hmrManager = this.hmrManager;
+    const waitForInit = this.waitForInitialization.bind(this);
     return async function(request, server) {
       const url = new URL(request.url);
       if (serveHmrEndpoints) {
@@ -320,9 +322,23 @@ class BunServerAdapter extends SharedServerAdapter {
           return success ? void 0 : new Response("WebSocket upgrade failed", { status: 400 });
         }
         if (url.pathname === "/_hmr_runtime.js") {
-          return new Response(fileSystem.readFileAsBuffer(hmrManager.getRuntimePath()), {
-            headers: { "Content-Type": "application/javascript" }
-          });
+          await waitForInit();
+          const runtimePath = hmrManager.getRuntimePath();
+          if (!fileSystem.exists(runtimePath)) {
+            appLogger.warn(
+              `[HMR] Runtime script missing at ${runtimePath}; attempting to rebuild before serving.`
+            );
+            await hmrManager.buildRuntime();
+          }
+          if (fileSystem.exists(runtimePath)) {
+            return new Response(fileSystem.readFileAsBuffer(runtimePath), {
+              headers: { "Content-Type": "application/javascript" }
+            });
+          }
+          appLogger.warn(
+            `[HMR] Runtime script not found at ${runtimePath}; the HMR runtime build likely failed during startup.`
+          );
+          return new Response("Not Found", { status: 404 });
         }
       }
       const wsMatch = matchRoute(url.pathname);
@@ -600,6 +616,7 @@ async function createBunServerAdapter(params) {
   const bridge = params.bridge ?? new ClientBridge();
   const hmrManager = params.hmrManager ?? new HmrManager({ appConfig: params.appConfig, bridge });
   setAppDevClientBridge(params.appConfig, bridge);
+  setAppHmrManager(params.appConfig, hmrManager);
   const previewHost = params.previewHost ?? new BunStaticPreviewHost();
   const adapter = new BunServerAdapter({
     ...params,

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

@@ -1,5 +1,6 @@
 import { WebSocketServer } from "ws";
 import { setAppDevClientBridge } from "../../dev/client-bridge-registry.js";
+import { setAppHmrManager } from "../../dev/hmr-manager-registry.js";
 import { NodeClientBridge } from "./node-client-bridge.js";
 import { NodeHmrManager } from "./node-hmr-manager.js";
 class DefaultNodeServerDevRuntimeFactory {
@@ -8,6 +9,7 @@ class DefaultNodeServerDevRuntimeFactory {
     const bridge = new NodeClientBridge();
     const hmrManager = new NodeHmrManager({ appConfig: options.appConfig, bridge });
     setAppDevClientBridge(options.appConfig, bridge);
+    setAppHmrManager(options.appConfig, hmrManager);
     return {
       websocketServer,
       bridge,

package/src/adapters/shared/hmr-entrypoint-registrar.d.ts

@@ -50,6 +50,4 @@ export declare class HmrEntrypointRegistrar {
     private registerEntrypointInternal;
     private awaitEntrypointRegistration;
     private getEntrypointOutput;
-    private removeStaleEntrypointOutput;
-    private encodeDynamicSegments;
 }

package/src/adapters/shared/hmr-entrypoint-registrar.js

@@ -1,7 +1,6 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
-import { appLogger } from "../../global/app-logger.js";
-import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+import { removeStaleHmrEntrypointOutput, resolveHmrEntrypointOutputPaths } from "../../hmr/hmr-entrypoint-output.js";
 class HmrEntrypointRegistrar {
   options;
   constructor(options) {
@@ -36,7 +35,7 @@ class HmrEntrypointRegistrar {
     }
     const { outputPath, outputUrl } = this.getEntrypointOutput(entrypointPath);
     this.options.watchedFiles.set(entrypointPath, outputUrl);
-    this.removeStaleEntrypointOutput(outputPath);
+    removeStaleHmrEntrypointOutput(outputPath, "HMR");
     await registrationOptions.emit(entrypointPath, outputPath);
     if (!fileSystem.exists(outputPath)) {
       throw registrationOptions.getMissingOutputError(entrypointPath, outputPath);
@@ -57,29 +56,7 @@ class HmrEntrypointRegistrar {
     ]);
   }
   getEntrypointOutput(entrypointPath) {
-    const relativePath = path.relative(this.options.srcDir, entrypointPath);
-    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
-    const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
-    const urlPath = encodedPathJs.split(path.sep).join("/");
-    return {
-      outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath)}`,
-      outputPath: path.join(this.options.distDir, urlPath)
-    };
-  }
-  removeStaleEntrypointOutput(outputPath) {
-    if (!fileSystem.exists(outputPath)) {
-      return;
-    }
-    try {
-      fileSystem.remove(outputPath);
-    } catch (error) {
-      appLogger.warn(
-        `[HMR] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
-  }
-  encodeDynamicSegments(filepath) {
-    return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
+    return resolveHmrEntrypointOutputPaths(this.options.srcDir, this.options.distDir, entrypointPath);
   }
 }
 export {

package/src/adapters/shared/runtime-server-lifecycle.js

@@ -4,6 +4,8 @@ import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
 import { disposeAppBuildRuntime } from "../../build/build-runtime.js";
 import { getAppBrowserBuildPlugins } from "../../build/build-adapter.js";
 import { copyRuntimePublicDirIfChanged } from "./copy-runtime-public-dir.js";
+import { clearAppDevClientBridge } from "../../dev/client-bridge-registry.js";
+import { clearAppHmrManager } from "../../dev/hmr-manager-registry.js";
 import { injectHmrRuntimeIntoHtmlResponse, isHtmlResponse, shouldInjectHmrHtmlResponse } from "./hmr-html-response.js";
 function prepareRuntimePublicDir(appConfig) {
   const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
@@ -29,6 +31,8 @@ async function disposeDevResources(options) {
   await disposeAppBuildRuntime(options.appConfig);
   options.hmrManager?.stop();
   options.bridge?.destroy();
+  clearAppDevClientBridge(options.appConfig);
+  clearAppHmrManager(options.appConfig);
   await options.previewHost.stop();
 }
 export {

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

@@ -166,8 +166,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
       importServerModule: async (filePath) => await serverModuleTranspiler.importModule({
         filePath,
         outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
-        externalPackages: true,
-        bypassCache: this.options?.watch === true
+        externalPackages: true
       })
     });
   }

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

@@ -47,10 +47,12 @@ export declare abstract class SharedHmrManager implements IHmrManager {
     handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
     getOutputUrl(entrypointPath: string): string | undefined;
     /**
-     * Returns the emitted HMR script output when the artifact already exists on disk.
+     * Returns the emitted HMR script output when the entrypoint is already registered
+     * and its browser bundle exists on disk.
      *
-     * SSR must not block on entrypoint registration when a previous build already
-     * produced the browser bundle.
+     * @remarks
+     * Disk artifacts alone are not enough: a fresh dev session must still register
+     * the entrypoint so file watchers can rebuild it on change.
      */
     getResolvedScriptOutput(entrypointPath: string): {
         outputUrl: string;

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

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+import { resolveHmrEntrypointOutputPaths } from "../../hmr/hmr-entrypoint-output.js";
 import { requireBuildRuntime } from "../../build/build-runtime.js";
 import { fileSystem } from "@ecopages/file-system";
 import { HmrStrategyType } from "../../hmr/hmr-strategy.js";
@@ -184,21 +185,27 @@ class SharedHmrManager {
     return this.watchedFiles.get(entrypointPath);
   }
   /**
-   * Returns the emitted HMR script output when the artifact already exists on disk.
+   * Returns the emitted HMR script output when the entrypoint is already registered
+   * and its browser bundle exists on disk.
    *
-   * SSR must not block on entrypoint registration when a previous build already
-   * produced the browser bundle.
+   * @remarks
+   * Disk artifacts alone are not enough: a fresh dev session must still register
+   * the entrypoint so file watchers can rebuild it on change.
    */
   getResolvedScriptOutput(entrypointPath) {
     const normalizedEntrypoint = path.resolve(entrypointPath);
-    const relativePath = path.relative(this.appConfig.absolutePaths.srcDir, normalizedEntrypoint);
-    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js").replace(/\[([^\]]+)\]/g, "_$1_");
-    const urlPath = relativePathJs.split(path.sep).join("/");
-    const outputPath = path.join(this.distDir, urlPath);
+    if (!this.watchedFiles.has(normalizedEntrypoint)) {
+      return void 0;
+    }
+    const { outputPath, outputUrl: derivedOutputUrl } = resolveHmrEntrypointOutputPaths(
+      this.appConfig.absolutePaths.srcDir,
+      this.distDir,
+      normalizedEntrypoint
+    );
     if (!fileSystem.exists(outputPath)) {
       return void 0;
     }
-    const outputUrl = this.watchedFiles.get(normalizedEntrypoint) ?? `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath).split(path.sep).join("/")}`;
+    const outputUrl = this.watchedFiles.get(normalizedEntrypoint) ?? derivedOutputUrl;
     return { outputUrl, outputPath };
   }
   getWatchedFiles() {

package/src/dev/hmr-manager-registry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Per-app registry for the shared HMR manager used by host-owned dev clients.
+ */
+import type { EcoPagesAppConfig } from '../types/public-types.js';
+import type { IHmrManager } from '../types/public-types.js';
+export declare function setAppHmrManager(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): void;
+export declare function getAppHmrManager(appConfig: EcoPagesAppConfig): IHmrManager | undefined;
+export declare function clearAppHmrManager(appConfig: EcoPagesAppConfig): void;

package/src/dev/hmr-manager-registry.js

@@ -0,0 +1,15 @@
+const appHmrManagers = /* @__PURE__ */ new WeakMap();
+function setAppHmrManager(appConfig, hmrManager) {
+  appHmrManagers.set(appConfig, hmrManager);
+}
+function getAppHmrManager(appConfig) {
+  return appHmrManagers.get(appConfig);
+}
+function clearAppHmrManager(appConfig) {
+  appHmrManagers.delete(appConfig);
+}
+export {
+  clearAppHmrManager,
+  getAppHmrManager,
+  setAppHmrManager
+};

package/src/hmr/hmr-entrypoint-output.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Returns whether a source path is a registered client script HMR entrypoint.
+ *
+ * @remarks
+ * Registration comes from `dependencies.scripts` via `FileScriptProcessor`,
+ * not from filename conventions such as `.script.tsx`.
+ */
+export declare function isRegisteredScriptEntrypoint(watchedFiles: ReadonlyMap<string, string>, 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,58 @@
+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(watchedFiles, filePath) {
+  const resolvedPath = path.resolve(filePath);
+  if (watchedFiles.has(resolvedPath)) {
+    return true;
+  }
+  for (const entrypointPath of watchedFiles.keys()) {
+    if (path.resolve(entrypointPath) === resolvedPath) {
+      return true;
+    }
+  }
+  return false;
+}
+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,
+  isHmrOutputFresh,
+  isRegisteredScriptEntrypoint,
+  removeStaleHmrEntrypointOutput,
+  resolveHmrEntrypointOutputPaths
+};

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

@@ -98,6 +98,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 +117,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,6 +142,30 @@ 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,
+          plugins: this.context.getPlugins(),
+          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,
@@ -153,8 +199,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/router/client/link-navigation-policy.d.ts

@@ -37,3 +37,9 @@ export declare function shouldPrefetchLink(link: HTMLAnchorElement, options: Lin
  * `application/xhtml+xml` responses are accepted; missing or asset types are rejected.
  */
 export declare function isHtmlPageResponse(response: Response): boolean;
+/**
+ * @remarks
+ * Servers should send `text/html`. When the type is missing or the runtime
+ * defaults to `text/plain` (common in tests), a document-shaped body is accepted.
+ */
+export declare function assertHtmlPageResponse(response: Response): Promise<void>;

package/src/router/client/link-navigation-policy.js

@@ -77,7 +77,22 @@ function isHtmlPageResponse(response) {
   const normalized = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
   return normalized === "text/html" || normalized === "application/xhtml+xml";
 }
+async function assertHtmlPageResponse(response) {
+  if (isHtmlPageResponse(response)) {
+    return;
+  }
+  const contentType = response.headers.get("Content-Type");
+  const normalized = contentType?.split(";")[0]?.trim().toLowerCase() ?? "";
+  if (normalized === "text/plain" || normalized === "") {
+    const sample = (await response.clone().text()).trimStart();
+    if (sample.startsWith("<")) {
+      return;
+    }
+  }
+  throw new Error(`Expected HTML page response, received ${contentType ?? "unknown content type"}`);
+}
 export {
+  assertHtmlPageResponse,
   getLinkNavigationDecision,
   getNavigableHrefFromClick,
   isHtmlPageResponse,

package/src/services/assets/asset-processing-service/processors/script/file-script.processor.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { RESOLVED_ASSETS_DIR } from "../../../../../config/constants.js";
 import { fileSystem } from "@ecopages/file-system";
+import { appLogger } from "../../../../../global/app-logger.js";
 import { BaseScriptProcessor } from "../base/base-script-processor.js";
 class FileScriptProcessor extends BaseScriptProcessor {
   hmrManager;
@@ -50,7 +51,10 @@ class FileScriptProcessor extends BaseScriptProcessor {
           packageRole: dep.packageRole,
           bundledSourceFilepaths: dep.bundledSourceFilepaths
         };
-      } catch {
+      } catch (error) {
+        appLogger.warn(
+          `[FileScriptProcessor] HMR script registration failed for ${dep.filepath}, falling back to non-HMR asset: ${error instanceof Error ? error.message : String(error)}`
+        );
       }
     }
     const content = fileSystem.readFileSync(dep.filepath);

package/src/services/invalidation/development-invalidation.service.d.ts

@@ -1,4 +1,5 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { EcoPagesAppConfig, RegisteredScriptEntrypointChangeHandler } from '../../types/internal-types.js';
+export type { RegisteredScriptEntrypointChangeHandler };
 export type DevelopmentInvalidationCategory = 'public-asset' | 'additional-watch' | 'include-source' | 'explicit-server-view' | 'route-source' | 'processor-owned-asset' | 'server-source' | 'other';
 /**
  * Framework-owned invalidation plan for one changed file.
@@ -38,6 +39,14 @@ export declare class DevelopmentInvalidationService {
      * Invalidates the app-owned server-module graph.
      */
     invalidateServerModules(changedFiles?: string[]): void;
+    /**
+     * Registers an integration-owned handler for registered script entrypoint edits.
+     */
+    registerRegisteredScriptEntrypointChangeHandler(handler: RegisteredScriptEntrypointChangeHandler): void;
+    /**
+     * Notifies integration handlers that a registered script entrypoint changed.
+     */
+    notifyRegisteredScriptEntrypointChange(filePath: string): Promise<void>;
     /**
      * Resets runtime-owned graph state and invalidates server modules.
      */

package/src/services/invalidation/development-invalidation.service.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { getAppServerInvalidationState } from "../runtime-state/server-invalidation-state.service.js";
+import { appLogger } from "../../global/app-logger.js";
 class DevelopmentInvalidationService {
   appConfig;
   constructor(appConfig) {
@@ -18,6 +19,30 @@ class DevelopmentInvalidationService {
     getAppServerInvalidationState(this.appConfig).invalidateServerModules(changedFiles);
     this.appConfig.runtime?.appModuleLoader?.invalidateDevelopmentGraph();
   }
+  /**
+   * Registers an integration-owned handler for registered script entrypoint edits.
+   */
+  registerRegisteredScriptEntrypointChangeHandler(handler) {
+    const runtime = this.appConfig.runtime ?? {};
+    this.appConfig.runtime = runtime;
+    runtime.registeredScriptEntrypointChangeHandlers ??= [];
+    runtime.registeredScriptEntrypointChangeHandlers.push(handler);
+  }
+  /**
+   * Notifies integration handlers that a registered script entrypoint changed.
+   */
+  async notifyRegisteredScriptEntrypointChange(filePath) {
+    const handlers = this.appConfig.runtime?.registeredScriptEntrypointChangeHandlers ?? [];
+    for (const handler of handlers) {
+      try {
+        await handler(filePath);
+      } catch (error) {
+        appLogger.error(
+          `Failed to handle registered script entrypoint change for ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+  }
   /**
    * Resets runtime-owned graph state and invalidates server modules.
    */

package/src/services/module-loading/page-module-import.service.d.ts

@@ -62,6 +62,7 @@ export interface PageModuleImportDependencies {
 export declare class PageModuleImportService {
     private readonly appConfig?;
     private readonly dependencies;
+    private readonly dependencyHasher;
     private readonly importCache;
     private developmentInvalidationVersion;
     constructor(appConfig?: EcoPagesAppConfig, dependencies?: Partial<PageModuleImportDependencies>);

package/src/services/module-loading/page-module-import.service.js

@@ -16,11 +16,15 @@ import {
   createJsxCacheKey
 } from "./route-module-build-cache.js";
 import { getSharedRouteModuleBuildCache } from "./route-module-build-cache-registry.js";
-import { resolveRouteModuleDependencyPaths } from "./route-module-dependency-hasher.js";
+import {
+  RouteModuleDependencyHasher,
+  resolveRouteModuleDependencyPaths
+} from "./route-module-dependency-hasher.js";
 import { supportsSourceModuleLoading } from "./source-module-support.js";
 class PageModuleImportService {
   appConfig;
   dependencies;
+  dependencyHasher;
   importCache = /* @__PURE__ */ new Map();
   developmentInvalidationVersion = 0;
   constructor(appConfig, dependencies) {
@@ -31,6 +35,10 @@ class PageModuleImportService {
       canLoadSourceModuleFromHost: dependencies?.canLoadSourceModuleFromHost ?? supportsSourceModuleLoading,
       getHostModuleLoader: dependencies?.getHostModuleLoader ?? (() => void 0)
     };
+    this.dependencyHasher = new RouteModuleDependencyHasher({
+      hashFile: (filePath) => this.dependencies.hashFile(filePath),
+      exists: (filePath) => fileSystem.exists(filePath)
+    });
   }
   /**
    * Clears the shared import cache used by framework-owned page-module loads.
@@ -49,6 +57,7 @@ class PageModuleImportService {
    */
   invalidateDevelopmentGraph() {
     this.clearImportCache();
+    this.dependencyHasher.clearMemo();
     this.developmentInvalidationVersion += 1;
   }
   /**
@@ -97,13 +106,21 @@ class PageModuleImportService {
     ].join("::");
     const cachedModule = this.importCache.get(cacheKey);
     if (cachedModule) {
-      return await cachedModule;
+      if (!cachedModule.dependencyHashes) {
+        return await cachedModule.promise;
+      }
+      this.dependencyHasher.clearMemo();
+      if (this.dependencyHasher.matchesStoredHashes(cachedModule.dependencyHashes, filePath, fileHash)) {
+        return await cachedModule.promise;
+      }
+      this.importCache.delete(cacheKey);
     }
     const importPromise = this.loadModule({
       ...options,
-      fileHash
+      fileHash,
+      importCacheKey: cacheKey
     });
-    this.importCache.set(cacheKey, importPromise);
+    this.importCache.set(cacheKey, { promise: importPromise });
     try {
       return await importPromise;
     } catch (error) {
@@ -112,7 +129,13 @@ class PageModuleImportService {
     }
   }
   async loadModule(options) {
-    const { filePath, invalidationVersion = this.developmentInvalidationVersion, cacheScope, fileHash } = options;
+    const {
+      filePath,
+      invalidationVersion = this.developmentInvalidationVersion,
+      cacheScope,
+      fileHash,
+      importCacheKey
+    } = options;
     const {
       rootDir,
       outdir,
@@ -170,11 +193,20 @@ class PageModuleImportService {
       throw new Error(noOutputMessage(filePath));
     }
     normalizeNodeRuntimeBuildOutputFile(compiledOutput, rootDir);
+    const dependencyModulePaths = resolveRouteModuleDependencyPaths(buildResult, filePath, rootDir);
+    const dependencyHashes = this.dependencyHasher.createDependencyHashes(dependencyModulePaths);
+    dependencyHashes[path.normalize(filePath)] = fileHash;
+    if (importCacheKey) {
+      const cacheEntry = this.importCache.get(importCacheKey);
+      if (cacheEntry) {
+        cacheEntry.dependencyHashes = dependencyHashes;
+      }
+    }
     routeModuleBuildCache.recordBuild({
       ...options,
       fileHash,
       outputPath: compiledOutput,
-      dependencyModulePaths: resolveRouteModuleDependencyPaths(buildResult, filePath, rootDir)
+      dependencyModulePaths
     });
     const compiledOutputUrl = pathToFileURL(compiledOutput);
     if (shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope)) {

package/src/services/module-loading/route-module-dependency-hasher.d.ts

@@ -50,8 +50,8 @@ export declare class RouteModuleDependencyHasher {
      * @returns `true` when all stored hashes are present and still valid.
      */
     matchesStoredHashes(storedHashes: RouteModuleDependencyHashes | undefined, entrypointPath?: string, entrypointSourceHash?: string): boolean;
-    /** Clears the per-build memo. Intended for unit tests only. */
-    clearMemoForTests(): void;
+    /** Clears the per-build memo so subsequent reads reflect current file contents. */
+    clearMemo(): void;
 }
 /**
  * Returns whether a bundler module id should participate in route-module cache invalidation.

package/src/services/module-loading/route-module-dependency-hasher.js

@@ -73,8 +73,8 @@ class RouteModuleDependencyHasher {
     }
     return true;
   }
-  /** Clears the per-build memo. Intended for unit tests only. */
-  clearMemoForTests() {
+  /** Clears the per-build memo so subsequent reads reflect current file contents. */
+  clearMemo() {
     this.memo.clear();
   }
 }

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

@@ -15,6 +15,8 @@ import type { EntrypointDependencyGraph } from '../services/runtime-state/entryp
 import type { ServerInvalidationState } from '../services/runtime-state/server-invalidation-state.service.js';
 import type { ServerModuleTranspiler } from '../services/module-loading/server-module-transpiler.service.js';
 import type { RouteModuleBuildCache } from '../services/module-loading/route-module-build-cache.store.js';
+/** Integration hook for registered `dependencies.scripts` entrypoint changes in dev. */
+export type RegisteredScriptEntrypointChangeHandler = (filePath: string) => void | Promise<void>;
 export interface RobotsPreference {
     /**
      * The user agent
@@ -164,6 +166,8 @@ export type EcoPagesAppConfig = {
         runtimeAssetsPrepared?: boolean;
         /** When `'host'`, the embedded dev server owns browser dev-client bootstrap. */
         devClientOwner?: 'core' | 'host';
+        /** Integration hooks run when a registered `dependencies.scripts` entrypoint changes. */
+        registeredScriptEntrypointChangeHandlers?: RegisteredScriptEntrypointChangeHandler[];
         /** @deprecated Prefer {@link devClientOwner}: `'host'`. */
         delegateBrowserReloadToHost?: boolean;
     };

package/src/watchers/project-watcher.d.ts

@@ -15,6 +15,8 @@ export interface ProjectWatcherConfig {
     bridge: IClientBridge;
     /** When true, the host dev server owns browser dev-client bootstrap. */
     hostOwnsDevClient?: boolean;
+    /** Delay before a change event is processed; 0 disables debouncing. */
+    changeDebounceMs?: number;
 }
 /**
  * ProjectWatcher handles file system changes for hot module replacement (HMR).
@@ -46,10 +48,12 @@ export declare class ProjectWatcher {
     private bridge;
     private readonly hostOwnsDevClient;
     private readonly invalidationService;
+    private readonly changeDebounceMs;
     private watcher;
     private lastHandledChange;
+    private pendingChangeTimers;
     private changeQueue;
-    constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge, hostOwnsDevClient }: ProjectWatcherConfig);
+    constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge, hostOwnsDevClient, changeDebounceMs, }: ProjectWatcherConfig);
     /**
      * Uncaches modules in the source directory to ensure fresh imports.
      * This is necessary for hot module replacement to work correctly.
@@ -88,6 +92,13 @@ export declare class ProjectWatcher {
      * @param event - The type of file system event
      */
     private handleFileChange;
+    private processFileChange;
+    /**
+     * Re-imports server modules before HMR broadcast so reload/refetch does not
+     * race stale in-memory imports or custom-element registry state.
+     */
+    private prewarmBeforeHmr;
+    private prewarmServerModuleImports;
     /**
      * Notifies all processors whose watch config matches the given file extension.
      * This is called before checking processor ownership so that dependency-only

package/src/watchers/project-watcher.js

@@ -2,7 +2,11 @@ import path from "node:path";
 import chokidar, {} from "chokidar";
 import { fileSystem } from "@ecopages/file-system";
 import { appLogger } from "../global/app-logger.js";
-import { DevelopmentInvalidationService } from "../services/invalidation/development-invalidation.service.js";
+import {
+  DevelopmentInvalidationService
+} from "../services/invalidation/development-invalidation.service.js";
+import { isRegisteredScriptEntrypoint } from "../hmr/hmr-entrypoint-output.js";
+import { resolveInternalExecutionDir } from "../utils/resolve-work-dir.js";
 import { createProjectWatcherIgnorePredicate } from "./project-watcher-ignore.js";
 class ProjectWatcher {
   /**
@@ -19,19 +23,31 @@ class ProjectWatcher {
   bridge;
   hostOwnsDevClient;
   invalidationService;
+  changeDebounceMs;
   watcher = null;
   lastHandledChange = /* @__PURE__ */ new Map();
+  pendingChangeTimers = /* @__PURE__ */ new Map();
   changeQueue = Promise.resolve();
-  constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge, hostOwnsDevClient }) {
+  constructor({
+    config,
+    refreshRouterRoutesCallback,
+    hmrManager,
+    bridge,
+    hostOwnsDevClient,
+    changeDebounceMs
+  }) {
     this.appConfig = config;
     this.refreshRouterRoutesCallback = refreshRouterRoutesCallback;
     this.hmrManager = hmrManager;
     this.bridge = bridge;
     this.hostOwnsDevClient = hostOwnsDevClient === true;
+    const envDebounceMs = process.env.ECOPAGES_WATCH_CHANGE_DEBOUNCE_MS;
+    this.changeDebounceMs = changeDebounceMs ?? (envDebounceMs !== void 0 && envDebounceMs !== "" ? Number(envDebounceMs) : void 0) ?? ProjectWatcher.duplicateChangeWindowMs;
     this.invalidationService = new DevelopmentInvalidationService(config);
     this.triggerRouterRefresh = this.triggerRouterRefresh.bind(this);
     this.handleError = this.handleError.bind(this);
     this.handleFileChange = this.handleFileChange.bind(this);
+    this.processFileChange = this.processFileChange.bind(this);
   }
   /**
    * Uncaches modules in the source directory to ensure fresh imports.
@@ -86,6 +102,7 @@ class ProjectWatcher {
   enqueueChange(task) {
     const queuedTask = this.changeQueue.then(task, task);
     this.changeQueue = queuedTask.catch(() => void 0);
+    return queuedTask;
   }
   /**
    * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
@@ -105,8 +122,23 @@ class ProjectWatcher {
    * @param rawPath - Path of the changed file
    * @param event - The type of file system event
    */
-  async handleFileChange(rawPath, event = "change") {
+  handleFileChange(rawPath, event = "change") {
     const filePath = path.resolve(rawPath);
+    if (this.changeDebounceMs === 0) {
+      return this.enqueueChange(() => this.processFileChange(filePath, event));
+    }
+    const existing = this.pendingChangeTimers.get(filePath);
+    if (existing) {
+      clearTimeout(existing);
+    }
+    const timer = setTimeout(() => {
+      this.pendingChangeTimers.delete(filePath);
+      this.enqueueChange(() => this.processFileChange(filePath, event));
+    }, this.changeDebounceMs);
+    this.pendingChangeTimers.set(filePath, timer);
+    return Promise.resolve();
+  }
+  async processFileChange(filePath, event) {
     const now = Date.now();
     const lastHandledAt = this.lastHandledChange.get(filePath);
     if (lastHandledAt !== void 0 && now - lastHandledAt < ProjectWatcher.duplicateChangeWindowMs) {
@@ -120,8 +152,16 @@ class ProjectWatcher {
         return;
       }
       this.uncacheModules();
+      const resolvedFilePath = path.resolve(filePath);
+      const isRegisteredScriptEdit = isRegisteredScriptEntrypoint(
+        this.hmrManager.getWatchedFiles(),
+        resolvedFilePath
+      );
       if (plan.invalidateServerModules) {
         this.invalidationService.invalidateServerModules([filePath]);
+        if (isRegisteredScriptEdit) {
+          await this.invalidationService.notifyRegisteredScriptEntrypointChange(resolvedFilePath);
+        }
       }
       if (plan.refreshRoutes) {
         await this.refreshRouterRoutesCallback();
@@ -130,8 +170,9 @@ class ProjectWatcher {
         this.requestBrowserReload();
         return;
       }
-      const deferProcessorNotifications = plan.category === "include-source" || plan.category === "explicit-server-view";
+      const deferProcessorNotifications = plan.category === "include-source" || plan.category === "explicit-server-view" || isRegisteredScriptEdit;
       if (deferProcessorNotifications && plan.delegateToHmr) {
+        await this.prewarmBeforeHmr(resolvedFilePath, plan, isRegisteredScriptEdit);
         await this.hmrManager.handleFileChange(filePath);
         void this.notifyProcessors(filePath, event);
         return;
@@ -150,6 +191,46 @@ class ProjectWatcher {
       }
     }
   }
+  /**
+   * Re-imports server modules before HMR broadcast so reload/refetch does not
+   * race stale in-memory imports or custom-element registry state.
+   */
+  async prewarmBeforeHmr(filePath, plan, isRegisteredScriptEdit) {
+    if (isRegisteredScriptEdit) {
+      await this.prewarmServerModuleImports([filePath], { bypassCache: true, scope: "registered script" });
+      return;
+    }
+    if (plan.category !== "include-source" && plan.category !== "explicit-server-view") {
+      return;
+    }
+    const modulePaths = plan.category === "include-source" ? [this.appConfig.absolutePaths.htmlTemplatePath] : [path.resolve(filePath)];
+    await this.prewarmServerModuleImports(modulePaths, { scope: "server template" });
+  }
+  async prewarmServerModuleImports(modulePaths, options) {
+    const appModuleLoader = this.appConfig.runtime?.appModuleLoader;
+    if (!appModuleLoader) {
+      return;
+    }
+    const outdir = path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules");
+    for (const modulePath of modulePaths) {
+      if (!modulePath) {
+        continue;
+      }
+      try {
+        await appModuleLoader.importModule({
+          filePath: modulePath,
+          rootDir: this.appConfig.rootDir,
+          outdir,
+          externalPackages: true,
+          bypassCache: options.bypassCache
+        });
+      } catch (error) {
+        appLogger.error(
+          `Failed to prewarm ${options.scope} ${modulePath}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+  }
   /**
    * Notifies all processors whose watch config matches the given file extension.
    * This is called before checking processor ownership so that dependency-only
@@ -272,7 +353,7 @@ class ProjectWatcher {
         pollInterval: 50
       }
     });
-    this.watcher.on("change", (p) => this.enqueueChange(() => this.handleFileChange(p, "change"))).on("add", (p) => this.enqueueChange(() => this.handleFileChange(p, "add"))).on("addDir", (p) => this.enqueueChange(() => this.triggerRouterRefresh(p))).on("unlink", (p) => this.enqueueChange(() => this.handleFileChange(p, "unlink"))).on("unlinkDir", (p) => this.enqueueChange(() => this.triggerRouterRefresh(p))).on("error", (error) => this.handleError(error));
+    this.watcher.on("change", (p) => this.handleFileChange(p, "change")).on("add", (p) => this.handleFileChange(p, "add")).on("addDir", (p) => this.enqueueChange(() => this.triggerRouterRefresh(p))).on("unlink", (p) => this.handleFileChange(p, "unlink")).on("unlinkDir", (p) => this.enqueueChange(() => this.triggerRouterRefresh(p))).on("error", (error) => this.handleError(error));
     for (const processor of this.appConfig.processors.values()) {
       const watchConfig = processor.getWatchConfig();
       if (watchConfig?.onError) {