@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.32

package/src/watchers/project-watcher.js

@@ -1,387 +1,406 @@
-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 { 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.
-   *
-   * Some editors or save pipelines emit two near-identical filesystem change
-   * notifications for the same file. Ecopages should treat those as one logical
-   * update so HMR and route refresh work are not repeated unnecessarily.
-   */
-  static duplicateChangeWindowMs = 150;
-  appConfig;
-  refreshRouterRoutesCallback;
-  hmrManager;
-  bridge;
-  hostOwnsDevClient;
-  invalidationService;
-  changeDebounceMs;
-  watcher = null;
-  closed = false;
-  pendingChangeEvents = /* @__PURE__ */ new Map();
-  changeQueue = Promise.resolve();
-  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.
-   * This is necessary for hot module replacement to work correctly.
-   * @private
-   */
-  uncacheModules() {
-    if (typeof require === "undefined") return;
-    const { srcDir, rootDir } = this.appConfig;
-    const regex = new RegExp(`${rootDir}/${srcDir}/.*`);
-    for (const key in require.cache) {
-      if (regex.test(key)) {
-        delete require.cache[key];
-      }
+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 { prepareHmrFileChange } from '../hmr/hmr-file-change-prep.js';
+import { getAppPageBrowserGraphSession } from '../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js';
+import { isRegisteredDevTransformEntrypoint } from '../hmr/hmr-entrypoint-output.js';
+import { resolveInternalExecutionDir } from '../utils/resolve-work-dir.js';
+import { createProjectWatcherIgnorePredicate } from './project-watcher-ignore.js';
+/**
+ * ProjectWatcher handles file system changes for hot module replacement (HMR).
+ * It uses chokidar to watch for file changes and triggers appropriate actions:
+ * - Uncaches modules when files change
+ * - Refreshes router routes for page files
+ * - Triggers HMR server reload
+ * - Handles processor-specific file changes
+ *
+ * The watcher uses chokidar's built-in debouncing through `awaitWriteFinish`
+ * to handle rapid file changes efficiently:
+ * - stabilityThreshold: 50ms - Time to wait for writes to stabilize
+ * - pollInterval: 50ms - Interval to poll for file changes
+ *
+ * @class ProjectWatcher
+ */
+export class ProjectWatcher {
+    /**
+     * Duplicate identical watcher events within this window are ignored.
+     *
+     * Some editors or save pipelines emit two near-identical filesystem change
+     * notifications for the same file. Ecopages should treat those as one logical
+     * update so HMR and route refresh work are not repeated unnecessarily.
+     */
+    static duplicateChangeWindowMs = 150;
+    appConfig;
+    refreshRouterRoutesCallback;
+    hmrManager;
+    bridge;
+    hostOwnsDevClient;
+    invalidationService;
+    changeDebounceMs;
+    watcher = null;
+    closed = false;
+    pendingChangeEvents = new Map();
+    changeQueue = Promise.resolve();
+    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 !== undefined && envDebounceMs !== '' ? Number(envDebounceMs) : undefined) ??
+                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);
     }
-  }
-  isRouteSourceFile(filePath) {
-    return this.invalidationService.isRouteSourceFile(filePath);
-  }
-  isIncludeSourceFile(filePath) {
-    return this.invalidationService.isIncludeSourceFile(filePath);
-  }
-  requestBrowserReload() {
-    if (this.hostOwnsDevClient) {
-      return;
+    /**
+     * Uncaches modules in the source directory to ensure fresh imports.
+     * This is necessary for hot module replacement to work correctly.
+     * @private
+     */
+    uncacheModules() {
+        if (typeof require === 'undefined')
+            return;
+        const { srcDir, rootDir } = this.appConfig;
+        const regex = new RegExp(`${rootDir}/${srcDir}/.*`);
+        for (const key in require.cache) {
+            if (regex.test(key)) {
+                delete require.cache[key];
+            }
+        }
     }
-    this.bridge.reload();
-  }
-  /**
-   * Handles public directory file changes by copying only the changed file.
-   * @param filePath - Absolute path of the changed file
-   */
-  async handlePublicDirFileChange(filePath) {
-    try {
-      const relativePath = path.relative(this.appConfig.absolutePaths.publicDir, filePath);
-      const destPath = path.join(this.appConfig.absolutePaths.distDir, relativePath);
-      if (fileSystem.exists(filePath)) {
-        const destDir = path.dirname(destPath);
-        fileSystem.ensureDir(destDir);
-        await fileSystem.copyFileAsync(filePath, destPath);
-      }
-      this.requestBrowserReload();
-    } catch (error) {
-      appLogger.error(`Failed to copy public file: ${error instanceof Error ? error.message : String(error)}`);
-      this.requestBrowserReload();
+    isRouteSourceFile(filePath) {
+        return this.invalidationService.isRouteSourceFile(filePath);
     }
-  }
-  /**
-   * Serializes file change handling so that concurrent chokidar events are
-   * processed one at a time, preventing overlapping builds and race conditions.
-   */
-  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? -> 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
-   *
-   * Processors that watch a file extension as a dependency (e.g. PostCSS watching
-   * .tsx for Tailwind class scanning) are always notified first, but do not
-   * prevent the file from flowing through the normal HMR strategy pipeline.
-   *
-   * Duplicate identical watcher events for the same file are coalesced within a
-   * short window before any of the priority rules run.
-   * @param rawPath - Path of the changed file
-   * @param event - The type of file system event
-   */
-  handleFileChange(rawPath, event = "change") {
-    if (this.closed) {
-      return Promise.resolve();
+    isIncludeSourceFile(filePath) {
+        return this.invalidationService.isIncludeSourceFile(filePath);
     }
-    const filePath = path.resolve(rawPath);
-    if (this.changeDebounceMs === 0) {
-      return this.enqueueChange(() => this.processFileChange(filePath, event));
+    requestBrowserReload() {
+        if (this.hostOwnsDevClient) {
+            return;
+        }
+        this.bridge.reload();
     }
-    const existing = this.pendingChangeEvents.get(filePath);
-    if (existing) {
-      clearTimeout(existing.timer);
+    /**
+     * Handles public directory file changes by copying only the changed file.
+     * @param filePath - Absolute path of the changed file
+     */
+    async handlePublicDirFileChange(filePath) {
+        try {
+            const relativePath = path.relative(this.appConfig.absolutePaths.publicDir, filePath);
+            const destPath = path.join(this.appConfig.absolutePaths.distDir, relativePath);
+            if (fileSystem.exists(filePath)) {
+                const destDir = path.dirname(destPath);
+                fileSystem.ensureDir(destDir);
+                await fileSystem.copyFileAsync(filePath, destPath);
+            }
+            this.requestBrowserReload();
+        }
+        catch (error) {
+            appLogger.error(`Failed to copy public file: ${error instanceof Error ? error.message : String(error)}`);
+            this.requestBrowserReload();
+        }
     }
-    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") {
-        await this.handlePublicDirFileChange(filePath);
-        return;
-      }
-      this.uncacheModules();
-      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.reloadBrowser) {
-        this.requestBrowserReload();
-        return;
-      }
-      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, {
-          graphIdentities: graphPreparation?.affectedGraphIdentities
-        });
-      }
-    } catch (error) {
-      if (error instanceof Error) {
-        this.bridge.error(error.message);
-        this.handleError(error);
-      }
+    /**
+     * Serializes file change handling so that concurrent chokidar events are
+     * processed one at a time, preventing overlapping builds and race conditions.
+     */
+    enqueueChange(task) {
+        const queuedTask = this.changeQueue.then(task, task);
+        this.changeQueue = queuedTask.catch(() => undefined);
+        return queuedTask;
     }
-  }
-  /**
-   * 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;
+    /**
+     * 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? -> 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
+     *
+     * Processors that watch a file extension as a dependency (e.g. PostCSS watching
+     * .tsx for Tailwind class scanning) are always notified first, but do not
+     * prevent the file from flowing through the normal HMR strategy pipeline.
+     *
+     * Duplicate identical watcher events for the same file are coalesced within a
+     * short window before any of the priority rules run.
+     * @param rawPath - Path of the changed file
+     * @param event - The type of file system event
+     */
+    handleFileChange(rawPath, event = 'change') {
+        if (this.closed) {
+            return Promise.resolve();
+        }
+        const filePath = path.resolve(rawPath);
+        if (this.changeDebounceMs === 0) {
+            return this.enqueueChange(() => this.processFileChange(filePath, event));
+        }
+        const existing = this.pendingChangeEvents.get(filePath);
+        if (existing) {
+            clearTimeout(existing.timer);
+        }
+        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();
     }
-    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)}`
-        );
-      }
+    async processFileChange(filePath, event) {
+        try {
+            const plan = this.invalidationService.planFileChange(filePath);
+            if (plan.category === 'public-asset') {
+                await this.handlePublicDirFileChange(filePath);
+                return;
+            }
+            this.uncacheModules();
+            const resolvedFilePath = path.resolve(filePath);
+            const graphPreparation = this.hmrManager.isEnabled()
+                ? prepareHmrFileChange(this.appConfig, resolvedFilePath)
+                : undefined;
+            if (plan.refreshRoutes && (event === 'unlink' || event === 'add')) {
+                getAppPageBrowserGraphSession(this.appConfig).invalidateByRouteFile(resolvedFilePath);
+            }
+            const isRegisteredDevTransformEdit = isRegisteredDevTransformEntrypoint(this.hmrManager.getRegisteredEntrypoints(), resolvedFilePath);
+            if (plan.invalidateServerModules && !isRegisteredDevTransformEdit) {
+                this.invalidationService.invalidateServerModules([filePath]);
+            }
+            if (plan.refreshRoutes) {
+                await this.refreshRouterRoutesCallback();
+            }
+            if (plan.reloadBrowser) {
+                this.requestBrowserReload();
+                return;
+            }
+            const deferProcessorNotifications = plan.category === 'include-source' ||
+                plan.category === 'explicit-server-view' ||
+                isRegisteredDevTransformEdit;
+            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, {
+                    graphIdentities: graphPreparation?.affectedGraphIdentities,
+                });
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.bridge.error(error.message);
+                this.handleError(error);
+            }
+        }
     }
-  }
-  /**
-   * Notifies all processors whose watch config matches the given file extension.
-   * This is called before checking processor ownership so that dependency-only
-   * processors (e.g. PostCSS watching .tsx for class scanning) receive their
-   * notifications regardless of whether they own the file.
-   */
-  async notifyProcessors(filePath, event) {
-    const ctx = { path: filePath, bridge: this.bridge };
-    for (const processor of this.appConfig.processors.values()) {
-      const watchConfig = processor.getWatchConfig();
-      if (!watchConfig) continue;
-      const { extensions = [] } = watchConfig;
-      if (extensions.length && !extensions.some((ext) => filePath.endsWith(ext))) {
-        continue;
-      }
-      const handler = this.getProcessorHandler(watchConfig, event);
-      if (handler) {
-        await handler(ctx);
-      }
+    /**
+     * 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' });
     }
-  }
-  getProcessorHandler(watchConfig, event) {
-    switch (event) {
-      case "change":
-        return watchConfig.onChange;
-      case "add":
-        return watchConfig.onCreate;
-      case "unlink":
-        return watchConfig.onDelete;
+    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)}`);
+            }
+        }
     }
-  }
-  /**
-   * Checks if a file is in the public directory.
-   */
-  isPublicDirFile(filePath) {
-    return this.invalidationService.isPublicDirFile(filePath);
-  }
-  /**
-   * Checks if file path matches any additionalWatchPaths patterns.
-   */
-  matchesAdditionalWatchPaths(filePath) {
-    return this.invalidationService.matchesAdditionalWatchPaths(filePath);
-  }
-  /**
-   * 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);
-  }
-  /**
-   * Triggers router refresh for page directory changes.
-   * This ensures the router is updated when pages are added or removed.
-   *
-   * @param {string} path - Path of the changed directory
-   */
-  async triggerRouterRefresh(changedPath) {
-    const resolvedPath = path.resolve(changedPath);
-    const isPageDir = resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir) && path.extname(resolvedPath) === "";
-    if (isPageDir || this.isRouteSourceFile(resolvedPath)) {
-      await this.refreshRouterRoutesCallback();
+    /**
+     * Notifies all processors whose watch config matches the given file extension.
+     * This is called before checking processor ownership so that dependency-only
+     * processors (e.g. PostCSS watching .tsx for class scanning) receive their
+     * notifications regardless of whether they own the file.
+     */
+    async notifyProcessors(filePath, event) {
+        const ctx = { path: filePath, bridge: this.bridge };
+        for (const processor of this.appConfig.processors.values()) {
+            const watchConfig = processor.getWatchConfig();
+            if (!watchConfig)
+                continue;
+            const { extensions = [] } = watchConfig;
+            if (extensions.length && !extensions.some((ext) => filePath.endsWith(ext))) {
+                continue;
+            }
+            const handler = this.getProcessorHandler(watchConfig, event);
+            if (handler) {
+                await handler(ctx);
+            }
+        }
     }
-  }
-  /**
-   * Handles and logs errors that occur during file watching.
-   *
-   * @param {unknown} error - The error to handle
-   */
-  handleError(error) {
-    if (error instanceof Error) {
-      this.hmrManager.broadcast({ type: "error", message: error.message });
+    getProcessorHandler(watchConfig, event) {
+        switch (event) {
+            case 'change':
+                return watchConfig.onChange;
+            case 'add':
+                return watchConfig.onCreate;
+            case 'unlink':
+                return watchConfig.onDelete;
+        }
     }
-    appLogger.error(`Watcher error: ${error}`);
-  }
-  /**
-   * Creates and configures the file system watcher.
-   * This sets up:
-   * 1. Page file watching
-   * 2. Directory watching
-   * 3. Error handling
-   *
-   * Processor notifications are dispatched inside handleFileChange, ensuring
-   * a single unified event pipeline with no parallel chokidar bindings.
-   *
-   * Uses chokidar's built-in debouncing through `awaitWriteFinish` to handle
-   * rapid file changes efficiently.
-   */
-  async createWatcherSubscription() {
-    if (this.watcher) {
-      return this.watcher;
+    /**
+     * Checks if a file is in the public directory.
+     */
+    isPublicDirFile(filePath) {
+        return this.invalidationService.isPublicDirFile(filePath);
     }
-    const processorPaths = /* @__PURE__ */ new Set();
-    for (const processor of this.appConfig.processors.values()) {
-      const watchConfig = processor.getWatchConfig();
-      if (!watchConfig) continue;
-      for (const watchPath of watchConfig.paths) {
-        processorPaths.add(watchPath);
-      }
+    /**
+     * Checks if file path matches any additionalWatchPaths patterns.
+     */
+    matchesAdditionalWatchPaths(filePath) {
+        return this.invalidationService.matchesAdditionalWatchPaths(filePath);
     }
-    if (fileSystem.exists(this.appConfig.absolutePaths.includesDir)) {
-      processorPaths.add(this.appConfig.absolutePaths.includesDir);
+    /**
+     * 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);
     }
-    if (fileSystem.exists(this.appConfig.absolutePaths.srcDir)) {
-      processorPaths.add(this.appConfig.absolutePaths.srcDir);
+    /**
+     * Triggers router refresh for page directory changes.
+     * This ensures the router is updated when pages are added or removed.
+     *
+     * @param {string} path - Path of the changed directory
+     */
+    async triggerRouterRefresh(changedPath) {
+        const resolvedPath = path.resolve(changedPath);
+        const isPageDir = resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir) && path.extname(resolvedPath) === '';
+        if (isPageDir || this.isRouteSourceFile(resolvedPath)) {
+            await this.refreshRouterRoutesCallback();
+        }
     }
-    if (fileSystem.exists(this.appConfig.absolutePaths.publicDir)) {
-      processorPaths.add(this.appConfig.absolutePaths.publicDir);
+    /**
+     * Handles and logs errors that occur during file watching.
+     *
+     * @param {unknown} error - The error to handle
+     */
+    handleError(error) {
+        if (error instanceof Error) {
+            this.hmrManager.broadcast({ type: 'error', message: error.message });
+        }
+        appLogger.error(`Watcher error: ${error}`);
     }
-    for (const watchPath of this.appConfig.additionalWatchPaths) {
-      processorPaths.add(watchPath);
-    }
-    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.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) {
-        this.watcher.on("error", watchConfig.onError);
-      }
-    }
-    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);
+    /**
+     * Creates and configures the file system watcher.
+     * This sets up:
+     * 1. Page file watching
+     * 2. Directory watching
+     * 3. Error handling
+     *
+     * Processor notifications are dispatched inside handleFileChange, ensuring
+     * a single unified event pipeline with no parallel chokidar bindings.
+     *
+     * Uses chokidar's built-in debouncing through `awaitWriteFinish` to handle
+     * rapid file changes efficiently.
+     */
+    async createWatcherSubscription() {
+        if (this.watcher) {
+            return this.watcher;
+        }
+        const processorPaths = new Set();
+        for (const processor of this.appConfig.processors.values()) {
+            const watchConfig = processor.getWatchConfig();
+            if (!watchConfig)
+                continue;
+            for (const watchPath of watchConfig.paths) {
+                processorPaths.add(watchPath);
+            }
+        }
+        if (fileSystem.exists(this.appConfig.absolutePaths.includesDir)) {
+            processorPaths.add(this.appConfig.absolutePaths.includesDir);
+        }
+        if (fileSystem.exists(this.appConfig.absolutePaths.srcDir)) {
+            processorPaths.add(this.appConfig.absolutePaths.srcDir);
+        }
+        if (fileSystem.exists(this.appConfig.absolutePaths.publicDir)) {
+            processorPaths.add(this.appConfig.absolutePaths.publicDir);
+        }
+        for (const watchPath of this.appConfig.additionalWatchPaths) {
+            processorPaths.add(watchPath);
+        }
+        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.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) {
+                this.watcher.on('error', watchConfig.onError);
+            }
+        }
+        return this.watcher;
     }
-    this.pendingChangeEvents.clear();
-    if (this.watcher) {
-      await this.watcher.close();
-      this.watcher = null;
+    /**
+     * 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(() => undefined);
     }
-    await this.changeQueue.catch(() => void 0);
-  }
 }
-export {
-  ProjectWatcher
-};