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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.18",
+  "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.18",
+    "@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",

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

@@ -313,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) {
@@ -321,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);

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

@@ -1,3 +1,11 @@
+/**
+ * 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.
@@ -12,3 +20,9 @@ export declare function resolveHmrEntrypointOutputPaths(srcDir: string, distDir:
  * 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

@@ -1,7 +1,20 @@
+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_");
 }
@@ -28,8 +41,18 @@ function removeStaleHmrEntrypointOutput(outputPath, scope) {
     );
   }
 }
+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.js

@@ -2,7 +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 } from "../hmr-entrypoint-output.js";
+import {
+  removeStaleHmrEntrypointOutput,
+  resolveHmrEntrypointOutputPaths,
+  isRegisteredScriptEntrypoint,
+  isHmrOutputFresh
+} from "../hmr-entrypoint-output.js";
 class JsHmrStrategy extends HmrStrategy {
   type = HmrStrategyType.SCRIPT;
   context;
@@ -25,7 +30,8 @@ class JsHmrStrategy extends HmrStrategy {
     const watchedFiles = this.context.getWatchedFiles();
     const resolvedPath = path.resolve(filePath);
     const isJsTs = /\.(ts|tsx|js|jsx)$/.test(resolvedPath);
-    const isInSrc = resolvedPath.startsWith(this.context.getSrcDir());
+    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;
@@ -56,17 +62,19 @@ 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(path.resolve(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) {
@@ -82,14 +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 outputPath = this.resolveEntrypointOutputPath(entrypoint);
-      const result = await this.processOutput(outputPath, outputUrl);
+      const result = await this.processOutput(outputPath, outputUrl, resolvedEntrypoint);
       if (result.success) {
         updates.push(outputUrl);
         if (result.requiresReload) {
@@ -186,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) {