@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.30

package/src/utils/parse-cli-args.d.ts

@@ -13,6 +13,8 @@ export type ReturnParseCliArgs = {
     build: boolean;
     start: boolean;
     dev: boolean;
+    force: boolean;
+    serveOnly: boolean;
     port?: number;
     hostname?: string;
     reactFastRefresh?: boolean;

package/src/utils/parse-cli-args.js

@@ -7,6 +7,8 @@ function getEmbeddedRuntimeCommandOptions() {
     build: false,
     start: !isDevelopment,
     dev: isDevelopment,
+    force: false,
+    serveOnly: false,
     port: void 0,
     hostname: void 0,
     reactFastRefresh: void 0
@@ -25,6 +27,8 @@ function parseCliArgs(options = {}) {
       dev: { type: "boolean" },
       preview: { type: "boolean" },
       build: { type: "boolean" },
+      force: { type: "boolean" },
+      "serve-only": { type: "boolean" },
       port: { type: "string" },
       hostname: { type: "string" },
       "react-fast-refresh": { type: "boolean" }
@@ -48,6 +52,8 @@ function parseCliArgs(options = {}) {
     build: isBuildCommand,
     start: isStartCommand,
     dev: isDevCommand,
+    force: !!values.force,
+    serveOnly: !!values["serve-only"] || process.env.ECOPAGES_PREVIEW_SERVE_ONLY === "true",
     port: values.port ? Number(values.port) : void 0,
     hostname: values.hostname,
     reactFastRefresh: values["react-fast-refresh"]

package/src/utils/path-pattern.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Normalizes a URL pathname for matching and sitemap location building.
+ *
+ * @remarks
+ * Ensures a leading slash and strips trailing slashes except for `/`.
+ */
+export declare function normalizePathname(pathname: string): string;
+/**
+ * Matches a pathname against a small set of supported patterns.
+ *
+ * @remarks
+ * Supported forms:
+ * - exact: `/admin`
+ * - prefix wildcard: `/admin/**` (matches `/admin` and descendants)
+ * - trailing `**` only as a full segment after `/`
+ *
+ * This is not a full glob engine. Unsupported patterns are treated as exact matches.
+ */
+export declare function matchPathPattern(pathname: string, pattern: string): boolean;
+/**
+ * Returns true when the pathname matches any of the patterns.
+ */
+export declare function matchesAnyPathPattern(pathname: string, patterns: readonly string[]): boolean;

package/src/utils/path-pattern.js

@@ -0,0 +1,27 @@
+function normalizePathname(pathname) {
+  if (!pathname || pathname === "/") {
+    return "/";
+  }
+  const withLeadingSlash = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  return withLeadingSlash.replace(/\/+$/, "") || "/";
+}
+function matchPathPattern(pathname, pattern) {
+  const normalizedPath = normalizePathname(pathname);
+  const normalizedPattern = pattern.trim();
+  if (normalizedPattern.endsWith("/**")) {
+    const prefix = normalizePathname(normalizedPattern.slice(0, -3));
+    if (prefix === "/") {
+      return true;
+    }
+    return normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`);
+  }
+  return normalizedPath === normalizePathname(normalizedPattern);
+}
+function matchesAnyPathPattern(pathname, patterns) {
+  return patterns.some((pattern) => matchPathPattern(pathname, pattern));
+}
+export {
+  matchPathPattern,
+  matchesAnyPathPattern,
+  normalizePathname
+};

package/src/utils/server-utils.module.d.ts

@@ -1,3 +1,4 @@
+import { hasKnownStaticExtension } from './static-file-extensions.js';
 /**
  * Get the content type of a file based on its extension.
  * @param file - The file name.
@@ -9,11 +10,11 @@ export declare const getContentType: (file: string) => string;
  * @param file - The file name or path.
  * @returns true if the extension is recognized.
  */
-export declare const hasKnownExtension: (file: string) => boolean;
+export { hasKnownStaticExtension } from './static-file-extensions.js';
 /**
  * A module for server utilities.
  */
 export declare const ServerUtils: {
     getContentType: (file: string) => string;
-    hasKnownExtension: (file: string) => boolean;
+    hasKnownStaticExtension: typeof hasKnownStaticExtension;
 };

package/src/utils/server-utils.module.js

@@ -1,3 +1,4 @@
+import { hasKnownStaticExtension } from "./static-file-extensions.js";
 const ContentTypeMap = /* @__PURE__ */ new Map([
   ["jpg", "image/jpeg"],
   ["jpeg", "image/jpeg"],
@@ -17,6 +18,7 @@ const ContentTypeMap = /* @__PURE__ */ new Map([
   ["ogv", "video/ogg"],
   ["mov", "video/quicktime"],
   ["txt", "text/plain"],
+  ["md", "text/markdown"],
   ["html", "text/html"],
   ["css", "text/css"],
   ["js", "text/javascript"],
@@ -41,16 +43,13 @@ const getContentType = (file) => {
   const extension = file.split(".").pop() || "txt";
   return ContentTypeMap.get(extension) || "text/plain";
 };
-const hasKnownExtension = (file) => {
-  const extension = file.split(".").pop();
-  return extension !== void 0 && ContentTypeMap.has(extension);
-};
+import { hasKnownStaticExtension as hasKnownStaticExtension2 } from "./static-file-extensions.js";
 const ServerUtils = {
   getContentType,
-  hasKnownExtension
+  hasKnownStaticExtension
 };
 export {
   ServerUtils,
   getContentType,
-  hasKnownExtension
+  hasKnownStaticExtension2 as hasKnownStaticExtension
 };

package/src/utils/static-file-extensions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Known static asset extensions served directly from disk.
+ *
+ * @remarks
+ * Keep this list aligned with server static-file handling and client routers
+ * that must bypass SPA navigation for same-origin asset links.
+ */
+export declare const STATIC_FILE_EXTENSIONS: Set<string>;
+/**
+ * Returns whether a path or filename ends with a known static asset extension.
+ */
+export declare function hasKnownStaticExtension(fileOrPath: string): boolean;

package/src/utils/static-file-extensions.js

@@ -0,0 +1,48 @@
+const STATIC_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+  "jpg",
+  "jpeg",
+  "png",
+  "gif",
+  "bmp",
+  "svg",
+  "tiff",
+  "webp",
+  "avif",
+  "ico",
+  "mp3",
+  "ogg",
+  "wav",
+  "mp4",
+  "webm",
+  "ogv",
+  "mov",
+  "txt",
+  "md",
+  "html",
+  "css",
+  "js",
+  "mjs",
+  "json",
+  "map",
+  "xml",
+  "webmanifest",
+  "wasm",
+  "csv",
+  "ttf",
+  "woff",
+  "woff2",
+  "otf",
+  "eot",
+  "gz",
+  "zip",
+  "pdf",
+  "doc"
+]);
+function hasKnownStaticExtension(fileOrPath) {
+  const extension = fileOrPath.split(".").pop();
+  return extension !== void 0 && STATIC_FILE_EXTENSIONS.has(extension);
+}
+export {
+  STATIC_FILE_EXTENSIONS,
+  hasKnownStaticExtension
+};

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

@@ -0,0 +1,11 @@
+export type ProjectWatcherIgnorePaths = {
+    workDir: string;
+    distDir: string;
+};
+/**
+ * @remarks
+ * chokidar v4+ no longer treats glob strings in `ignored` as patterns. A path
+ * predicate keeps node_modules, VCS metadata, and scoped artifact dirs out of
+ * the watch tree without descending into symlinked monorepo node_modules.
+ */
+export declare function createProjectWatcherIgnorePredicate(absolutePaths: ProjectWatcherIgnorePaths): (watchedPath: string) => boolean;

package/src/watchers/project-watcher-ignore.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+function createProjectWatcherIgnorePredicate(absolutePaths) {
+  const ignoredPrefixes = [absolutePaths.workDir, absolutePaths.distDir];
+  return (watchedPath) => {
+    const segments = watchedPath.split(path.sep);
+    if (segments.includes("node_modules") || segments.includes(".git")) {
+      return true;
+    }
+    return ignoredPrefixes.some(
+      (prefix) => watchedPath === prefix || watchedPath.startsWith(`${prefix}${path.sep}`)
+    );
+  };
+}
+export {
+  createProjectWatcherIgnorePredicate
+};

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

@@ -13,6 +13,10 @@ export interface ProjectWatcherConfig {
     refreshRouterRoutesCallback: () => Promise<void>;
     hmrManager: IHmrManager;
     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).
@@ -42,11 +46,14 @@ export declare class ProjectWatcher {
     private refreshRouterRoutesCallback;
     private hmrManager;
     private bridge;
+    private readonly hostOwnsDevClient;
     private readonly invalidationService;
+    private readonly changeDebounceMs;
     private watcher;
-    private lastHandledChange;
+    private closed;
+    private pendingChangeEvents;
     private changeQueue;
-    constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }: 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.
@@ -55,6 +62,7 @@ export declare class ProjectWatcher {
     private uncacheModules;
     private isRouteSourceFile;
     private isIncludeSourceFile;
+    private requestBrowserReload;
     /**
      * Handles public directory file changes by copying only the changed file.
      * @param filePath - Absolute path of the changed file
@@ -70,7 +78,7 @@ export declare class ProjectWatcher {
      * Follows 5-rule priority:
      * 0. Public directory match? -> copy file and reload
      * 1. additionalWatchPaths match? -> reload
-     * 2. Include template source? -> reload after processor notifications
+     * 2. Include template source? -> current-page refresh via HMR after processor notifications are deferred
      * 3. Processor-owned asset? -> processor already handled it via notification, skip HMR
      * 4. Otherwise -> HMR strategies
      *
@@ -84,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
@@ -101,9 +116,9 @@ export declare class ProjectWatcher {
      */
     private matchesAdditionalWatchPaths;
     /**
-     * Checks if a file is handled by a processor.
-     * Processors that declare asset capabilities own those file types.
-     * Processors without capabilities fall back to checking watch extensions.
+     * Checks if a file is owned by a processor as an asset input.
+     * Ownership requires declared asset capabilities; watch config only drives
+     * {@link notifyProcessors} notifications.
      */
     private isHandledByProcessor;
     /**
@@ -133,4 +148,12 @@ export declare class ProjectWatcher {
      * rapid file changes efficiently.
      */
     createWatcherSubscription(): Promise<FSWatcher>;
+    /**
+     * Closes the active filesystem watcher subscription.
+     *
+     * @remarks
+     * Safe to call multiple times. Used when tearing down dev servers in tests
+     * and other short-lived Ecopages runtimes.
+     */
+    close(): Promise<void>;
 }

package/src/watchers/project-watcher.js

@@ -2,7 +2,14 @@ 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 { prepareHmrFileChange } from "../hmr/hmr-file-change-prep.js";
+import { getAppPageBrowserGraphSession } from "../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.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 {
   /**
    * Duplicate identical watcher events within this window are ignored.
@@ -16,19 +23,33 @@ class ProjectWatcher {
   refreshRouterRoutesCallback;
   hmrManager;
   bridge;
+  hostOwnsDevClient;
   invalidationService;
+  changeDebounceMs;
   watcher = null;
-  lastHandledChange = /* @__PURE__ */ new Map();
+  closed = false;
+  pendingChangeEvents = /* @__PURE__ */ new Map();
   changeQueue = Promise.resolve();
-  constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }) {
+  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.
@@ -51,6 +72,12 @@ class ProjectWatcher {
   isIncludeSourceFile(filePath) {
     return this.invalidationService.isIncludeSourceFile(filePath);
   }
+  requestBrowserReload() {
+    if (this.hostOwnsDevClient) {
+      return;
+    }
+    this.bridge.reload();
+  }
   /**
    * Handles public directory file changes by copying only the changed file.
    * @param filePath - Absolute path of the changed file
@@ -64,10 +91,10 @@ class ProjectWatcher {
         fileSystem.ensureDir(destDir);
         await fileSystem.copyFileAsync(filePath, destPath);
       }
-      this.bridge.reload();
+      this.requestBrowserReload();
     } catch (error) {
       appLogger.error(`Failed to copy public file: ${error instanceof Error ? error.message : String(error)}`);
-      this.bridge.reload();
+      this.requestBrowserReload();
     }
   }
   /**
@@ -77,13 +104,14 @@ 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.
    * Follows 5-rule priority:
    * 0. Public directory match? -> copy file and reload
    * 1. additionalWatchPaths match? -> reload
-   * 2. Include template source? -> reload after processor notifications
+   * 2. Include template source? -> current-page refresh via HMR after processor notifications are deferred
    * 3. Processor-owned asset? -> processor already handled it via notification, skip HMR
    * 4. Otherwise -> HMR strategies
    *
@@ -96,14 +124,26 @@ 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") {
+    if (this.closed) {
+      return Promise.resolve();
+    }
     const filePath = path.resolve(rawPath);
-    const now = Date.now();
-    const lastHandledAt = this.lastHandledChange.get(filePath);
-    if (lastHandledAt !== void 0 && now - lastHandledAt < ProjectWatcher.duplicateChangeWindowMs) {
-      return;
+    if (this.changeDebounceMs === 0) {
+      return this.enqueueChange(() => this.processFileChange(filePath, event));
+    }
+    const existing = this.pendingChangeEvents.get(filePath);
+    if (existing) {
+      clearTimeout(existing.timer);
     }
-    this.lastHandledChange.set(filePath, now);
+    const timer = setTimeout(() => {
+      this.pendingChangeEvents.delete(filePath);
+      void this.enqueueChange(() => this.processFileChange(filePath, event));
+    }, this.changeDebounceMs);
+    this.pendingChangeEvents.set(filePath, { event, timer });
+    return Promise.resolve();
+  }
+  async processFileChange(filePath, event) {
     try {
       const plan = this.invalidationService.planFileChange(filePath);
       if (plan.category === "public-asset") {
@@ -111,26 +151,42 @@ class ProjectWatcher {
         return;
       }
       this.uncacheModules();
-      if (plan.invalidateServerModules) {
+      const resolvedFilePath = path.resolve(filePath);
+      const graphPreparation = this.hmrManager.isEnabled() ? prepareHmrFileChange(this.appConfig, resolvedFilePath) : void 0;
+      if (plan.refreshRoutes && (event === "unlink" || event === "add")) {
+        getAppPageBrowserGraphSession(this.appConfig).invalidateByRouteFile(resolvedFilePath);
+      }
+      const isRegisteredScriptEdit = isRegisteredScriptEntrypoint(
+        this.hmrManager.getWatchedFiles(),
+        resolvedFilePath
+      );
+      if (plan.invalidateServerModules && !isRegisteredScriptEdit) {
         this.invalidationService.invalidateServerModules([filePath]);
       }
       if (plan.refreshRoutes) {
         await this.refreshRouterRoutesCallback();
       }
-      if (plan.category === "additional-watch") {
-        this.bridge.reload();
+      if (plan.reloadBrowser) {
+        this.requestBrowserReload();
         return;
       }
-      await this.notifyProcessors(filePath, event);
-      if (plan.category === "include-source") {
-        this.bridge.reload();
+      const deferProcessorNotifications = plan.category === "include-source" || plan.category === "explicit-server-view" || isRegisteredScriptEdit;
+      if (deferProcessorNotifications && plan.delegateToHmr) {
+        await this.prewarmBeforeHmr(resolvedFilePath, plan);
+        await this.hmrManager.handleFileChange(filePath, {
+          graphIdentities: graphPreparation?.affectedGraphIdentities
+        });
+        await this.notifyProcessors(filePath, event);
         return;
       }
+      await this.notifyProcessors(filePath, event);
       if (plan.processorHandledAsset) {
         return;
       }
       if (plan.delegateToHmr) {
-        await this.hmrManager.handleFileChange(filePath);
+        await this.hmrManager.handleFileChange(filePath, {
+          graphIdentities: graphPreparation?.affectedGraphIdentities
+        });
       }
     } catch (error) {
       if (error instanceof Error) {
@@ -139,6 +195,42 @@ 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) {
+    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
@@ -183,9 +275,9 @@ class ProjectWatcher {
     return this.invalidationService.matchesAdditionalWatchPaths(filePath);
   }
   /**
-   * Checks if a file is handled by a processor.
-   * Processors that declare asset capabilities own those file types.
-   * Processors without capabilities fall back to checking watch extensions.
+   * Checks if a file is owned by a processor as an asset input.
+   * Ownership requires declared asset capabilities; watch config only drives
+   * {@link notifyProcessors} notifications.
    */
   isHandledByProcessor(filePath) {
     return this.invalidationService.isProcessorOwnedAsset(filePath);
@@ -231,36 +323,37 @@ class ProjectWatcher {
     if (this.watcher) {
       return this.watcher;
     }
-    const processorPaths = [];
+    const processorPaths = /* @__PURE__ */ new Set();
     for (const processor of this.appConfig.processors.values()) {
       const watchConfig = processor.getWatchConfig();
       if (!watchConfig) continue;
-      processorPaths.push(...watchConfig.paths);
+      for (const watchPath of watchConfig.paths) {
+        processorPaths.add(watchPath);
+      }
     }
     if (fileSystem.exists(this.appConfig.absolutePaths.includesDir)) {
-      processorPaths.push(this.appConfig.absolutePaths.includesDir);
+      processorPaths.add(this.appConfig.absolutePaths.includesDir);
     }
     if (fileSystem.exists(this.appConfig.absolutePaths.srcDir)) {
-      processorPaths.push(this.appConfig.absolutePaths.srcDir);
-    }
-    if (fileSystem.exists(this.appConfig.absolutePaths.pagesDir)) {
-      processorPaths.push(this.appConfig.absolutePaths.pagesDir);
+      processorPaths.add(this.appConfig.absolutePaths.srcDir);
     }
     if (fileSystem.exists(this.appConfig.absolutePaths.publicDir)) {
-      processorPaths.push(this.appConfig.absolutePaths.publicDir);
+      processorPaths.add(this.appConfig.absolutePaths.publicDir);
     }
-    if (this.appConfig.additionalWatchPaths.length) {
-      processorPaths.push(...this.appConfig.additionalWatchPaths);
+    for (const watchPath of this.appConfig.additionalWatchPaths) {
+      processorPaths.add(watchPath);
     }
-    this.watcher = chokidar.watch(processorPaths, {
+    const ignored = createProjectWatcherIgnorePredicate(this.appConfig.absolutePaths);
+    this.watcher = chokidar.watch(Array.from(processorPaths), {
       ignoreInitial: true,
       ignorePermissionErrors: true,
+      ignored,
       awaitWriteFinish: {
         stabilityThreshold: 50,
         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) {
@@ -269,6 +362,25 @@ class ProjectWatcher {
     }
     return this.watcher;
   }
+  /**
+   * Closes the active filesystem watcher subscription.
+   *
+   * @remarks
+   * Safe to call multiple times. Used when tearing down dev servers in tests
+   * and other short-lived Ecopages runtimes.
+   */
+  async close() {
+    this.closed = true;
+    for (const pending of this.pendingChangeEvents.values()) {
+      clearTimeout(pending.timer);
+    }
+    this.pendingChangeEvents.clear();
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = null;
+    }
+    await this.changeQueue.catch(() => void 0);
+  }
 }
 export {
   ProjectWatcher

package/src/watchers/project-watcher.test-helpers.js

@@ -6,21 +6,21 @@ const createMockHmrManager = () => ({
   }),
   setEnabled: vi.fn(() => {
   }),
-  setPlugins: vi.fn(() => {
-  }),
   registerEntrypoint: vi.fn(async () => ""),
-  registerScriptEntrypoint: vi.fn(async () => ""),
+  registerScriptEntrypoint: vi.fn(async () => ({
+    sourcePath: "",
+    outputPath: "",
+    outputUrl: ""
+  })),
   registerStrategy: vi.fn(() => {
   }),
   isEnabled: vi.fn(() => true),
   getOutputUrl: vi.fn(() => void 0),
   getWatchedFiles: vi.fn(() => /* @__PURE__ */ new Map()),
   getDistDir: vi.fn(() => ""),
-  getPlugins: vi.fn(() => []),
   getDefaultContext: vi.fn(() => ({
     getWatchedFiles: () => /* @__PURE__ */ new Map(),
     getDistDir: () => "",
-    getPlugins: () => [],
     getSrcDir: () => "",
     getLayoutsDir: () => "",
     getPagesDir: () => "",