@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.5

package/CHANGELOG.md

@@ -65,8 +65,11 @@ All notable changes to `@ecopages/core` are documented here.
 - Fixed invariant checks for route paths with improved error messaging in `AbstractApplicationAdapter` (`9c2a6242`).
 - Fixed dependency import name extraction in `extractEcopagesVirtualImports` (`39bbc472`).
 - Removed an invalid npm export entry that pointed to a non-existent `utils/ecopages-url-resolver` declaration target.
-- Kept source module HMR active when stylesheet processors also watch TSX and JSX files for Tailwind-driven CSS rebuilds.
-- Triggered HMR current-page refreshes instead of fallback reload suppression for processor-watched TSX and JSX changes that are not client entrypoints.
+- Fixed processor lifecycle hijacking where PostCSS watching TSX/HTML for Tailwind class scanning incorrectly prevented those files from reaching the HMR strategy pipeline.
+- Unified the file watcher event pipeline: processors are now notified inside `handleFileChange` instead of binding separate chokidar listeners, eliminating double-execution and race conditions.
+- Added async task queue to `ProjectWatcher` to serialize concurrent file change handling and prevent overlapping builds.
+- Batched `JsHmrStrategy` entrypoint builds into a single esbuild invocation for improved AST sharing and rebuild speed.
+- Added `outbase` support to `BuildOptions` for correct output directory structure with multi-entrypoint builds.
 
 ### Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.4",
+  "version": "0.2.0-alpha.5",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.4",
+    "@ecopages/file-system": "0.2.0-alpha.5",
     "@ecopages/logger": "latest",
     "@ecopages/scripts-injector": "^0.1.3",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",

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

@@ -58,12 +58,6 @@ export declare class HmrManager implements IHmrManager {
     buildRuntime(): Promise<void>;
     getRuntimePath(): string;
     broadcast(event: ClientBridgeEvent): void;
-    canHandleFileChange(filePath: string): boolean;
-    /**
-     * Handles file changes using registered HMR strategies.
-     * Strategies are evaluated in priority order until one matches.
-     * @param filePath - Absolute path to the changed file
-     */
     handleFileChange(filePath: string): Promise<void>;
     /**
      * Registers a client entrypoint to be built and watched by Bun.

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

@@ -3,7 +3,6 @@ import path from "node:path";
 import { RESOLVED_ASSETS_DIR } from "../../constants";
 import { defaultBuildAdapter } from "../../build/build-adapter.js";
 import { fileSystem } from "@ecopages/file-system";
-import { HmrStrategyType } from "../../hmr/hmr-strategy";
 import { DefaultHmrStrategy } from "../../hmr/strategies/default-hmr-strategy";
 import { JsHmrStrategy } from "../../hmr/strategies/js-hmr-strategy";
 import { appLogger } from "../../global/app-logger";
@@ -122,30 +121,13 @@ class HmrManager {
     );
     this.bridge.broadcast(event);
   }
-  canHandleFileChange(filePath) {
-    const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
-    const strategy = sorted.find((candidate) => {
-      try {
-        return candidate.matches(filePath);
-      } catch (err) {
-        appLogger.error(`[HmrManager] Error checking match for ${candidate.constructor.name}:`, err);
-        return false;
-      }
-    });
-    return strategy !== void 0 && strategy.type !== HmrStrategyType.FALLBACK;
-  }
-  /**
-   * Handles file changes using registered HMR strategies.
-   * Strategies are evaluated in priority order until one matches.
-   * @param filePath - Absolute path to the changed file
-   */
   async handleFileChange(filePath) {
     const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
     const strategy = sorted.find((s) => {
       try {
         return s.matches(filePath);
       } catch (err) {
-        appLogger.error(`[HmrManager] Error checking match for ${s.constructor.name}:`, err);
+        appLogger.error(err);
         return false;
       }
     });

package/src/adapters/bun/hmr-manager.ts

@@ -7,7 +7,6 @@ import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager } from '../../in
 import type { EcoBuildPlugin } from '../../build/build-types.ts';
 import { fileSystem } from '@ecopages/file-system';
 import type { HmrStrategy } from '../../hmr/hmr-strategy';
-import { HmrStrategyType } from '../../hmr/hmr-strategy';
 import { DefaultHmrStrategy } from '../../hmr/strategies/default-hmr-strategy';
 import { JsHmrStrategy } from '../../hmr/strategies/js-hmr-strategy';
 import { appLogger } from '../../global/app-logger';
@@ -159,32 +158,13 @@ export class HmrManager implements IHmrManager {
 		this.bridge.broadcast(event);
 	}
 
-	public canHandleFileChange(filePath: string): boolean {
-		const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
-		const strategy = sorted.find((candidate) => {
-			try {
-				return candidate.matches(filePath);
-			} catch (err) {
-				appLogger.error(`[HmrManager] Error checking match for ${candidate.constructor.name}:`, err as Error);
-				return false;
-			}
-		});
-
-		return strategy !== undefined && strategy.type !== HmrStrategyType.FALLBACK;
-	}
-
-	/**
-	 * Handles file changes using registered HMR strategies.
-	 * Strategies are evaluated in priority order until one matches.
-	 * @param filePath - Absolute path to the changed file
-	 */
 	public async handleFileChange(filePath: string): Promise<void> {
 		const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
 		const strategy = sorted.find((s) => {
 			try {
 				return s.matches(filePath);
 			} catch (err) {
-				appLogger.error(`[HmrManager] Error checking match for ${s.constructor.name}:`, err as Error);
+				appLogger.error(err);
 				return false;
 			}
 		});

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

@@ -41,7 +41,6 @@ export declare class NodeHmrManager implements IHmrManager {
     buildRuntime(): Promise<void>;
     getRuntimePath(): string;
     broadcast(event: ClientBridgeEvent): void;
-    canHandleFileChange(filePath: string): boolean;
     handleFileChange(filePath: string): Promise<void>;
     getOutputUrl(entrypointPath: string): string | undefined;
     getWatchedFiles(): Map<string, string>;

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

@@ -4,7 +4,6 @@ import { fileURLToPath } from "node:url";
 import { RESOLVED_ASSETS_DIR } from "../../constants.js";
 import { defaultBuildAdapter } from "../../build/build-adapter.js";
 import { fileSystem } from "@ecopages/file-system";
-import { HmrStrategyType } from "../../hmr/hmr-strategy.js";
 import { DefaultHmrStrategy } from "../../hmr/strategies/default-hmr-strategy.js";
 import { JsHmrStrategy } from "../../hmr/strategies/js-hmr-strategy.js";
 import { appLogger } from "../../global/app-logger.js";
@@ -95,28 +94,13 @@ class NodeHmrManager {
     );
     this.bridge.broadcast(event);
   }
-  canHandleFileChange(filePath) {
-    const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
-    const strategy = sorted.find((candidate) => {
-      try {
-        return candidate.matches(filePath);
-      } catch (err) {
-        appLogger.error(
-          `[NodeHmrManager] Error checking match for ${candidate.constructor.name}:`,
-          err
-        );
-        return false;
-      }
-    });
-    return strategy !== void 0 && strategy.type !== HmrStrategyType.FALLBACK;
-  }
   async handleFileChange(filePath) {
     const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
     const strategy = sorted.find((s) => {
       try {
         return s.matches(filePath);
       } catch (err) {
-        appLogger.error(`[NodeHmrManager] Error checking match for ${s.constructor.name}:`, err);
+        appLogger.error(err);
         return false;
       }
     });

package/src/adapters/node/node-hmr-manager.ts

@@ -7,7 +7,6 @@ import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge }
 import type { EcoBuildPlugin } from '../../build/build-types.ts';
 import { fileSystem } from '@ecopages/file-system';
 import type { HmrStrategy } from '../../hmr/hmr-strategy.ts';
-import { HmrStrategyType } from '../../hmr/hmr-strategy.ts';
 import { DefaultHmrStrategy } from '../../hmr/strategies/default-hmr-strategy.ts';
 import { JsHmrStrategy } from '../../hmr/strategies/js-hmr-strategy.ts';
 import { appLogger } from '../../global/app-logger.ts';
@@ -122,30 +121,13 @@ export class NodeHmrManager implements IHmrManager {
 		this.bridge.broadcast(event);
 	}
 
-	public canHandleFileChange(filePath: string): boolean {
-		const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
-		const strategy = sorted.find((candidate) => {
-			try {
-				return candidate.matches(filePath);
-			} catch (err) {
-				appLogger.error(
-					`[NodeHmrManager] Error checking match for ${candidate.constructor.name}:`,
-					err as Error,
-				);
-				return false;
-			}
-		});
-
-		return strategy !== undefined && strategy.type !== HmrStrategyType.FALLBACK;
-	}
-
 	public async handleFileChange(filePath: string): Promise<void> {
 		const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
 		const strategy = sorted.find((s) => {
 			try {
 				return s.matches(filePath);
 			} catch (err) {
-				appLogger.error(`[NodeHmrManager] Error checking match for ${s.constructor.name}:`, err as Error);
+				appLogger.error(err);
 				return false;
 			}
 		});

package/src/build/build-adapter.d.ts

@@ -36,6 +36,7 @@ export interface BuildResult {
 export interface BuildOptions {
     entrypoints: string[];
     outdir?: string;
+    outbase?: string;
     naming?: string;
     minify?: boolean;
     treeshaking?: boolean;

package/src/build/build-adapter.ts

@@ -45,6 +45,7 @@ export interface BuildResult {
 export interface BuildOptions {
 	entrypoints: string[];
 	outdir?: string;
+	outbase?: string;
 	naming?: string;
 	minify?: boolean;
 	treeshaking?: boolean;

package/src/build/esbuild-build-adapter.js

@@ -318,6 +318,7 @@ class EsbuildBuildAdapter {
     }
     const outputOptions = outfile ? { outfile } : {
       outdir,
+      ...options.outbase ? { outbase: path.resolve(options.outbase) } : {},
       entryNames: usesTemplatedNaming ? this.toEntryNamePattern(options.naming) : "[name]",
       chunkNames: "[name]-[hash]",
       assetNames: "[name]-[hash]"

package/src/build/esbuild-build-adapter.ts

@@ -433,6 +433,7 @@ export class EsbuildBuildAdapter implements BuildAdapter {
 			? { outfile }
 			: {
 					outdir,
+					...(options.outbase ? { outbase: path.resolve(options.outbase) } : {}),
 					entryNames: usesTemplatedNaming ? this.toEntryNamePattern(options.naming) : '[name]',
 					chunkNames: '[name]-[hash]',
 					assetNames: '[name]-[hash]',

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

@@ -105,17 +105,17 @@ export declare class JsHmrStrategy extends HmrStrategy {
      * @remarks
      * If runtime-specific dependency graph hooks are unavailable, this strategy
      * falls back to rebuilding all watched entrypoints.
+     * When multiple entrypoints are impacted they are bundled in a single esbuild
+     * invocation to share AST parsing and chunk deduplication.
      * @returns Action to broadcast update events
      */
     process(filePath: string): Promise<HmrAction>;
     /**
-     * Bundles a single entrypoint and processes the output.
-     *
-     * @param entrypointPath - Absolute path to the source file
-     * @param outputUrl - URL path for the bundled file
-     * @returns True if bundling was successful
+     * Bundles one or more entrypoints in a single esbuild invocation.
+     * Uses the source directory as the output base so that the directory structure
+     * is preserved under the HMR dist folder.
      */
-    private bundleEntrypoint;
+    private bundleEntrypoints;
     /**
      * Processes bundled output by replacing specifiers and injecting HMR code.
      *

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

@@ -45,6 +45,8 @@ class JsHmrStrategy extends HmrStrategy {
    * @remarks
    * If runtime-specific dependency graph hooks are unavailable, this strategy
    * falls back to rebuilding all watched entrypoints.
+   * When multiple entrypoints are impacted they are bundled in a single esbuild
+   * invocation to share AST parsing and chunk deduplication.
    * @returns Action to broadcast update events
    */
   async process(filePath) {
@@ -54,24 +56,34 @@ class JsHmrStrategy extends HmrStrategy {
       appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
       return { type: "none" };
     }
-    const updates = [];
-    let reloadRequired = false;
     const dependencyHits = this.context.getDependencyEntrypoints?.(filePath) ?? /* @__PURE__ */ new Set();
     const hasDependencyHit = dependencyHits.size > 0;
     const impactedEntrypoints = hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(entrypoint)) : Array.from(watchedFiles.keys());
     if (!hasDependencyHit) {
       appLogger.debug("[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints");
     }
+    if (impactedEntrypoints.length === 0) {
+      return { type: "none" };
+    }
+    const buildResult = await this.bundleEntrypoints(impactedEntrypoints);
+    if (!buildResult.success) {
+      return { type: "none" };
+    }
+    const updates = [];
+    let reloadRequired = false;
     for (const entrypoint of impactedEntrypoints) {
       const outputUrl = watchedFiles.get(entrypoint);
-      if (!outputUrl) {
-        continue;
+      if (!outputUrl) continue;
+      if (buildResult.dependencies && this.context.setEntrypointDependencies) {
+        const entrypointDeps = buildResult.dependencies.get(path.resolve(entrypoint)) ?? [];
+        this.context.setEntrypointDependencies(entrypoint, entrypointDeps);
       }
-      const result = await this.bundleEntrypoint(entrypoint, outputUrl);
+      const srcDir = this.context.getSrcDir();
+      const relativePath = path.relative(srcDir, entrypoint);
+      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?)$/, ".js");
+      const outputPath = path.join(this.context.getDistDir(), relativePathJs);
+      const result = await this.processOutput(outputPath, outputUrl);
       if (result.success) {
-        if (result.dependencies && this.context.setEntrypointDependencies) {
-          this.context.setEntrypointDependencies(entrypoint, result.dependencies);
-        }
         updates.push(outputUrl);
         if (result.requiresReload) {
           reloadRequired = true;
@@ -83,18 +95,14 @@ class JsHmrStrategy extends HmrStrategy {
         appLogger.debug(`[JsHmrStrategy] Full reload required (no HMR accept found)`);
         return {
           type: "broadcast",
-          events: [
-            {
-              type: "reload"
-            }
-          ]
+          events: [{ type: "reload" }]
         };
       }
       return {
         type: "broadcast",
-        events: updates.map((path2) => ({
+        events: updates.map((p) => ({
           type: "update",
-          path: path2,
+          path: p,
           timestamp: Date.now()
         }))
       };
@@ -102,40 +110,36 @@ class JsHmrStrategy extends HmrStrategy {
     return { type: "none" };
   }
   /**
-   * Bundles a single entrypoint and processes the output.
-   *
-   * @param entrypointPath - Absolute path to the source file
-   * @param outputUrl - URL path for the bundled file
-   * @returns True if bundling was successful
+   * Bundles one or more entrypoints in a single esbuild invocation.
+   * Uses the source directory as the output base so that the directory structure
+   * is preserved under the HMR dist folder.
    */
-  async bundleEntrypoint(entrypointPath, outputUrl) {
+  async bundleEntrypoints(entrypoints) {
     try {
-      const srcDir = this.context.getSrcDir();
-      const relativePath = path.relative(srcDir, entrypointPath);
-      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?)$/, ".js");
-      const outputPath = path.join(this.context.getDistDir(), relativePathJs);
       const result = await defaultBuildAdapter.build({
-        entrypoints: [entrypointPath],
+        entrypoints,
         outdir: this.context.getDistDir(),
-        naming: relativePathJs,
+        outbase: this.context.getSrcDir(),
+        naming: "[dir]/[name]",
         ...defaultBuildAdapter.getTranspileOptions("hmr-entrypoint"),
         plugins: this.context.getPlugins(),
         minify: false,
         external: ["react", "react-dom"]
       });
       if (!result.success) {
-        appLogger.error(`[JsHmrStrategy] Failed to build ${entrypointPath}:`, result.logs);
-        return { success: false, requiresReload: false, dependencies: void 0 };
+        appLogger.error("[JsHmrStrategy] Batched build failed:", result.logs);
+        return { success: false };
       }
-      const dependencyGraph = result.dependencyGraph?.entrypoints?.[path.resolve(entrypointPath)] ?? [];
-      const output = await this.processOutput(outputPath, outputUrl);
-      return {
-        ...output,
-        dependencies: dependencyGraph
-      };
+      const dependencies = /* @__PURE__ */ new Map();
+      if (result.dependencyGraph?.entrypoints) {
+        for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
+          dependencies.set(path.resolve(entrypoint), deps);
+        }
+      }
+      return { success: true, dependencies };
     } catch (error) {
-      appLogger.error(`[JsHmrStrategy] Error bundling ${entrypointPath}:`, error);
-      return { success: false, requiresReload: false, dependencies: void 0 };
+      appLogger.error("[JsHmrStrategy] Error in batched build:", error);
+      return { success: false };
     }
   }
   /**

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

@@ -144,6 +144,8 @@ export class JsHmrStrategy extends HmrStrategy {
 	 * @remarks
 	 * If runtime-specific dependency graph hooks are unavailable, this strategy
 	 * falls back to rebuilding all watched entrypoints.
+	 * When multiple entrypoints are impacted they are bundled in a single esbuild
+	 * invocation to share AST parsing and chunk deduplication.
 	 * @returns Action to broadcast update events
 	 */
 	async process(filePath: string): Promise<HmrAction> {
@@ -155,8 +157,6 @@ export class JsHmrStrategy extends HmrStrategy {
 			return { type: 'none' };
 		}
 
-		const updates: string[] = [];
-		let reloadRequired = false;
 		const dependencyHits = this.context.getDependencyEntrypoints?.(filePath) ?? new Set<string>();
 		const hasDependencyHit = dependencyHits.size > 0;
 		const impactedEntrypoints = hasDependencyHit
@@ -167,18 +167,35 @@ export class JsHmrStrategy extends HmrStrategy {
 			appLogger.debug('[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints');
 		}
 
+		if (impactedEntrypoints.length === 0) {
+			return { type: 'none' };
+		}
+
+		const buildResult = await this.bundleEntrypoints(impactedEntrypoints);
+
+		if (!buildResult.success) {
+			return { type: 'none' };
+		}
+
+		const updates: string[] = [];
+		let reloadRequired = false;
+
 		for (const entrypoint of impactedEntrypoints) {
 			const outputUrl = watchedFiles.get(entrypoint);
-			if (!outputUrl) {
-				continue;
+			if (!outputUrl) continue;
+
+			if (buildResult.dependencies && this.context.setEntrypointDependencies) {
+				const entrypointDeps = buildResult.dependencies.get(path.resolve(entrypoint)) ?? [];
+				this.context.setEntrypointDependencies(entrypoint, entrypointDeps);
 			}
 
-			const result = await this.bundleEntrypoint(entrypoint, outputUrl);
-			if (result.success) {
-				if (result.dependencies && this.context.setEntrypointDependencies) {
-					this.context.setEntrypointDependencies(entrypoint, result.dependencies);
-				}
+			const srcDir = this.context.getSrcDir();
+			const relativePath = path.relative(srcDir, entrypoint);
+			const relativePathJs = relativePath.replace(/\.(tsx?|jsx?)$/, '.js');
+			const outputPath = path.join(this.context.getDistDir(), relativePathJs);
 
+			const result = await this.processOutput(outputPath, outputUrl);
+			if (result.success) {
 				updates.push(outputUrl);
 				if (result.requiresReload) {
 					reloadRequired = true;
@@ -191,19 +208,15 @@ export class JsHmrStrategy extends HmrStrategy {
 				appLogger.debug(`[JsHmrStrategy] Full reload required (no HMR accept found)`);
 				return {
 					type: 'broadcast',
-					events: [
-						{
-							type: 'reload',
-						},
-					],
+					events: [{ type: 'reload' }],
 				};
 			}
 
 			return {
 				type: 'broadcast',
-				events: updates.map((path) => ({
+				events: updates.map((p) => ({
 					type: 'update',
-					path,
+					path: p,
 					timestamp: Date.now(),
 				})),
 			};
@@ -213,26 +226,19 @@ export class JsHmrStrategy extends HmrStrategy {
 	}
 
 	/**
-	 * Bundles a single entrypoint and processes the output.
-	 *
-	 * @param entrypointPath - Absolute path to the source file
-	 * @param outputUrl - URL path for the bundled file
-	 * @returns True if bundling was successful
+	 * Bundles one or more entrypoints in a single esbuild invocation.
+	 * Uses the source directory as the output base so that the directory structure
+	 * is preserved under the HMR dist folder.
 	 */
-	private async bundleEntrypoint(
-		entrypointPath: string,
-		outputUrl: string,
-	): Promise<{ success: boolean; requiresReload: boolean; dependencies?: string[] }> {
+	private async bundleEntrypoints(
+		entrypoints: string[],
+	): Promise<{ success: boolean; dependencies?: Map<string, string[]> }> {
 		try {
-			const srcDir = this.context.getSrcDir();
-			const relativePath = path.relative(srcDir, entrypointPath);
-			const relativePathJs = relativePath.replace(/\.(tsx?|jsx?)$/, '.js');
-			const outputPath = path.join(this.context.getDistDir(), relativePathJs);
-
 			const result = await defaultBuildAdapter.build({
-				entrypoints: [entrypointPath],
+				entrypoints,
 				outdir: this.context.getDistDir(),
-				naming: relativePathJs,
+				outbase: this.context.getSrcDir(),
+				naming: '[dir]/[name]',
 				...defaultBuildAdapter.getTranspileOptions('hmr-entrypoint'),
 				plugins: this.context.getPlugins(),
 				minify: false,
@@ -240,20 +246,21 @@ export class JsHmrStrategy extends HmrStrategy {
 			});
 
 			if (!result.success) {
-				appLogger.error(`[JsHmrStrategy] Failed to build ${entrypointPath}:`, result.logs);
-				return { success: false, requiresReload: false, dependencies: undefined };
+				appLogger.error('[JsHmrStrategy] Batched build failed:', result.logs);
+				return { success: false };
 			}
 
-			const dependencyGraph = result.dependencyGraph?.entrypoints?.[path.resolve(entrypointPath)] ?? [];
-			const output = await this.processOutput(outputPath, outputUrl);
+			const dependencies = new Map<string, string[]>();
+			if (result.dependencyGraph?.entrypoints) {
+				for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
+					dependencies.set(path.resolve(entrypoint), deps);
+				}
+			}
 
-			return {
-				...output,
-				dependencies: dependencyGraph,
-			};
+			return { success: true, dependencies };
 		} catch (error) {
-			appLogger.error(`[JsHmrStrategy] Error bundling ${entrypointPath}:`, error as Error);
-			return { success: false, requiresReload: false, dependencies: undefined };
+			appLogger.error('[JsHmrStrategy] Error in batched build:', error as Error);
+			return { success: false };
 		}
 	}
 

package/src/public-types.d.ts

@@ -178,10 +178,6 @@ export interface IHmrManager {
      * Returns whether HMR is enabled.
      */
     isEnabled(): boolean;
-    /**
-     * Returns true when a changed file matches a non-fallback HMR strategy.
-     */
-    canHandleFileChange(path: string): boolean;
     /**
      * Broadcasts an HMR event to connected clients.
      */

package/src/public-types.ts

@@ -209,11 +209,6 @@ export interface IHmrManager {
 	 */
 	isEnabled(): boolean;
 
-	/**
-	 * Returns true when a changed file matches a non-fallback HMR strategy.
-	 */
-	canHandleFileChange(path: string): boolean;
-
 	/**
 	 * Broadcasts an HMR event to connected clients.
 	 */

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

@@ -44,6 +44,7 @@ export declare class ProjectWatcher {
     private bridge;
     private watcher;
     private lastHandledChange;
+    private changeQueue;
     constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }: ProjectWatcherConfig);
     /**
      * Uncaches modules in the source directory to ensure fresh imports.
@@ -56,19 +57,37 @@ export declare class ProjectWatcher {
      * @param filePath - Absolute path of the changed file
      */
     private handlePublicDirFileChange;
+    /**
+     * Serializes file change handling so that concurrent chokidar events are
+     * processed one at a time, preventing overlapping builds and race conditions.
+     */
+    private enqueueChange;
     /**
      * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
      * Follows 4-rule priority:
-     * 0. Public directory match? → copy file and reload
-     * 1. additionalWatchPaths match? → reload
-     * 2. Processor extension match? → processor handles (skip HMR)
-     * 3. Otherwise → HMR strategies
+     * 0. Public directory match? -> copy file and reload
+     * 1. additionalWatchPaths match? -> reload
+     * 2. Processor-owned asset? -> processor already handled it via notification, skip HMR
+     * 3. 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
      */
     private handleFileChange;
+    /**
+     * 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.
+     */
+    private notifyProcessors;
+    private getProcessorHandler;
     /**
      * Checks if a file is in the public directory.
      */
@@ -77,14 +96,10 @@ export declare class ProjectWatcher {
      * Checks if file path matches any additionalWatchPaths patterns.
      */
     private matchesAdditionalWatchPaths;
-    /**
-     * Checks whether a file is watched by any processor, even if that processor
-     * does not own the file as a primary asset.
-     */
-    private isWatchedByProcessor;
     /**
      * Checks if a file is handled by a processor.
-     * Processors that declare extensions own those file types.
+     * Processors that declare asset capabilities own those file types.
+     * Processors without capabilities fall back to checking watch extensions.
      */
     private isHandledByProcessor;
     /**
@@ -100,23 +115,15 @@ export declare class ProjectWatcher {
      * @param {unknown} error - The error to handle
      */
     handleError(error: unknown): void;
-    /**
-     * Processes file changes for specific file extensions.
-     * Used by processors to handle their specific file types.
-     *
-     * @private
-     * @param {string} path - Path of the changed file
-     * @param {string[]} extensions - File extensions to process
-     * @param {(ctx: ProcessorWatchContext) => void} handler - Handler function for the file change
-     */
-    private shouldProcess;
     /**
      * Creates and configures the file system watcher.
      * This sets up:
-     * 1. Processor-specific file watching
-     * 2. Page file watching
-     * 3. Directory watching
-     * 4. Error handling
+     * 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.

package/src/watchers/project-watcher.js

@@ -17,6 +17,7 @@ class ProjectWatcher {
   bridge;
   watcher = null;
   lastHandledChange = /* @__PURE__ */ new Map();
+  changeQueue = Promise.resolve();
   constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }) {
     this.appConfig = config;
     this.refreshRouterRoutesCallback = refreshRouterRoutesCallback;
@@ -60,19 +61,32 @@ class ProjectWatcher {
       this.bridge.reload();
     }
   }
+  /**
+   * 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);
+  }
   /**
    * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
    * Follows 4-rule priority:
-   * 0. Public directory match? → copy file and reload
-   * 1. additionalWatchPaths match? → reload
-   * 2. Processor extension match? → processor handles (skip HMR)
-   * 3. Otherwise → HMR strategies
+   * 0. Public directory match? -> copy file and reload
+   * 1. additionalWatchPaths match? -> reload
+   * 2. Processor-owned asset? -> processor already handled it via notification, skip HMR
+   * 3. 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
    */
-  async handleFileChange(rawPath) {
+  async handleFileChange(rawPath, event = "change") {
     const filePath = path.resolve(rawPath);
     const now = Date.now();
     const lastHandledAt = this.lastHandledChange.get(filePath);
@@ -94,13 +108,10 @@ class ProjectWatcher {
         this.bridge.reload();
         return;
       }
+      await this.notifyProcessors(filePath, event);
       if (this.isHandledByProcessor(filePath)) {
         return;
       }
-      if (this.isWatchedByProcessor(filePath) && !this.hmrManager.canHandleFileChange(filePath)) {
-        this.hmrManager.broadcast({ type: "layout-update" });
-        return;
-      }
       await this.hmrManager.handleFileChange(filePath);
     } catch (error) {
       if (error instanceof Error) {
@@ -109,6 +120,37 @@ class ProjectWatcher {
       }
     }
   }
+  /**
+   * 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);
+      }
+    }
+  }
+  getProcessorHandler(watchConfig, event) {
+    switch (event) {
+      case "change":
+        return watchConfig.onChange;
+      case "add":
+        return watchConfig.onCreate;
+      case "unlink":
+        return watchConfig.onDelete;
+    }
+  }
   /**
    * Checks if a file is in the public directory.
    */
@@ -131,24 +173,10 @@ class ProjectWatcher {
     }
     return false;
   }
-  /**
-   * Checks whether a file is watched by any processor, even if that processor
-   * does not own the file as a primary asset.
-   */
-  isWatchedByProcessor(filePath) {
-    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))) {
-        return true;
-      }
-    }
-    return false;
-  }
   /**
    * Checks if a file is handled by a processor.
-   * Processors that declare extensions own those file types.
+   * Processors that declare asset capabilities own those file types.
+   * Processors without capabilities fall back to checking watch extensions.
    */
   isHandledByProcessor(filePath) {
     for (const processor of this.appConfig.processors.values()) {
@@ -192,27 +220,15 @@ class ProjectWatcher {
     }
     appLogger.error(`Watcher error: ${error}`);
   }
-  /**
-   * Processes file changes for specific file extensions.
-   * Used by processors to handle their specific file types.
-   *
-   * @private
-   * @param {string} path - Path of the changed file
-   * @param {string[]} extensions - File extensions to process
-   * @param {(ctx: ProcessorWatchContext) => void} handler - Handler function for the file change
-   */
-  shouldProcess(path2, extensions, handler) {
-    if (!extensions.length || extensions.some((ext) => path2.endsWith(ext))) {
-      handler({ path: path2, bridge: this.bridge });
-    }
-  }
   /**
    * Creates and configures the file system watcher.
    * This sets up:
-   * 1. Processor-specific file watching
-   * 2. Page file watching
-   * 3. Directory watching
-   * 4. Error handling
+   * 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.
@@ -243,20 +259,20 @@ class ProjectWatcher {
         }
       });
     }
+    this.watcher.add(this.appConfig.absolutePaths.srcDir);
+    this.watcher.on("change", (p) => this.enqueueChange(() => this.handleFileChange(p, "change"))).on("add", (p) => {
+      this.enqueueChange(() => this.handleFileChange(p, "add"));
+      this.triggerRouterRefresh(p);
+    }).on("addDir", (p) => this.triggerRouterRefresh(p)).on("unlink", (p) => {
+      this.enqueueChange(() => this.handleFileChange(p, "unlink"));
+      this.triggerRouterRefresh(p);
+    }).on("unlinkDir", (p) => this.triggerRouterRefresh(p)).on("error", (error) => this.handleError(error));
     for (const processor of this.appConfig.processors.values()) {
       const watchConfig = processor.getWatchConfig();
-      if (!watchConfig) continue;
-      const { extensions = [], onCreate, onChange, onDelete, onError } = watchConfig;
-      if (onCreate) this.watcher.on("add", (path2) => this.shouldProcess(path2, extensions, onCreate));
-      if (onChange) this.watcher.on("change", (path2) => this.shouldProcess(path2, extensions, onChange));
-      if (onDelete) this.watcher.on("unlink", (path2) => this.shouldProcess(path2, extensions, onDelete));
-      if (onError) this.watcher.on("error", onError);
+      if (watchConfig?.onError) {
+        this.watcher.on("error", watchConfig.onError);
+      }
     }
-    this.watcher.add(this.appConfig.absolutePaths.srcDir);
-    this.watcher.on("change", (path2) => this.handleFileChange(path2)).on("add", (path2) => {
-      this.handleFileChange(path2);
-      this.triggerRouterRefresh(path2);
-    }).on("addDir", (path2) => this.triggerRouterRefresh(path2)).on("unlink", (path2) => this.triggerRouterRefresh(path2)).on("unlinkDir", (path2) => this.triggerRouterRefresh(path2)).on("error", (error) => this.handleError(error));
     return this.watcher;
   }
 }

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

@@ -14,7 +14,6 @@ const createMockHmrManager = () => ({
   registerStrategy: vi.fn(() => {
   }),
   isEnabled: vi.fn(() => true),
-  canHandleFileChange: vi.fn(() => true),
   getOutputUrl: vi.fn(() => void 0),
   getWatchedFiles: vi.fn(() => /* @__PURE__ */ new Map()),
   getSpecifierMap: vi.fn(() => /* @__PURE__ */ new Map()),

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

@@ -12,7 +12,6 @@ export const createMockHmrManager = (): IHmrManager =>
 		registerSpecifierMap: vi.fn(() => {}),
 		registerStrategy: vi.fn(() => {}),
 		isEnabled: vi.fn(() => true),
-		canHandleFileChange: vi.fn(() => true),
 		getOutputUrl: vi.fn(() => undefined),
 		getWatchedFiles: vi.fn(() => new Map()),
 		getSpecifierMap: vi.fn(() => new Map()),

package/src/watchers/project-watcher.ts

@@ -3,7 +3,7 @@ import chokidar, { type FSWatcher } from 'chokidar';
 import { fileSystem } from '@ecopages/file-system';
 import { appLogger } from '../global/app-logger.ts';
 import type { EcoPagesAppConfig, IHmrManager, IClientBridge } from '../internal-types.ts';
-import type { ProcessorWatchContext } from '../plugins/processor.ts';
+import type { ProcessorWatchConfig, ProcessorWatchContext } from '../plugins/processor.ts';
 
 /**
  * Configuration options for the ProjectWatcher
@@ -50,6 +50,7 @@ export class ProjectWatcher {
 	private bridge: IClientBridge;
 	private watcher: FSWatcher | null = null;
 	private lastHandledChange = new Map<string, number>();
+	private changeQueue: Promise<void> = Promise.resolve();
 
 	constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }: ProjectWatcherConfig) {
 		this.appConfig = config;
@@ -101,19 +102,33 @@ export class ProjectWatcher {
 		}
 	}
 
+	/**
+	 * Serializes file change handling so that concurrent chokidar events are
+	 * processed one at a time, preventing overlapping builds and race conditions.
+	 */
+	private enqueueChange(task: () => Promise<void>): void {
+		const queuedTask = this.changeQueue.then(task, task);
+		this.changeQueue = queuedTask.catch(() => undefined);
+	}
+
 	/**
 	 * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
 	 * Follows 4-rule priority:
-	 * 0. Public directory match? → copy file and reload
-	 * 1. additionalWatchPaths match? → reload
-	 * 2. Processor extension match? → processor handles (skip HMR)
-	 * 3. Otherwise → HMR strategies
+	 * 0. Public directory match? -> copy file and reload
+	 * 1. additionalWatchPaths match? -> reload
+	 * 2. Processor-owned asset? -> processor already handled it via notification, skip HMR
+	 * 3. 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
 	 */
-	private async handleFileChange(rawPath: string): Promise<void> {
+	private async handleFileChange(rawPath: string, event: 'change' | 'add' | 'unlink' = 'change'): Promise<void> {
 		const filePath = path.resolve(rawPath);
 		const now = Date.now();
 		const lastHandledAt = this.lastHandledChange.get(filePath);
@@ -140,12 +155,9 @@ export class ProjectWatcher {
 				return;
 			}
 
-			if (this.isHandledByProcessor(filePath)) {
-				return;
-			}
+			await this.notifyProcessors(filePath, event);
 
-			if (this.isWatchedByProcessor(filePath) && !this.hmrManager.canHandleFileChange(filePath)) {
-				this.hmrManager.broadcast({ type: 'layout-update' });
+			if (this.isHandledByProcessor(filePath)) {
 				return;
 			}
 
@@ -158,6 +170,45 @@ export class ProjectWatcher {
 		}
 	}
 
+	/**
+	 * 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.
+	 */
+	private async notifyProcessors(filePath: string, event: 'change' | 'add' | 'unlink'): Promise<void> {
+		const ctx: ProcessorWatchContext = { 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);
+			}
+		}
+	}
+
+	private getProcessorHandler(
+		watchConfig: ProcessorWatchConfig,
+		event: 'change' | 'add' | 'unlink',
+	): ((ctx: ProcessorWatchContext) => Promise<void>) | undefined {
+		switch (event) {
+			case 'change':
+				return watchConfig.onChange;
+			case 'add':
+				return watchConfig.onCreate;
+			case 'unlink':
+				return watchConfig.onDelete;
+		}
+	}
+
 	/**
 	 * Checks if a file is in the public directory.
 	 */
@@ -183,27 +234,10 @@ export class ProjectWatcher {
 		return false;
 	}
 
-	/**
-	 * Checks whether a file is watched by any processor, even if that processor
-	 * does not own the file as a primary asset.
-	 */
-	private isWatchedByProcessor(filePath: string): boolean {
-		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))) {
-				return true;
-			}
-		}
-
-		return false;
-	}
-
 	/**
 	 * Checks if a file is handled by a processor.
-	 * Processors that declare extensions own those file types.
+	 * Processors that declare asset capabilities own those file types.
+	 * Processors without capabilities fall back to checking watch extensions.
 	 */
 	private isHandledByProcessor(filePath: string): boolean {
 		for (const processor of this.appConfig.processors.values()) {
@@ -258,28 +292,15 @@ export class ProjectWatcher {
 		appLogger.error(`Watcher error: ${error}`);
 	}
 
-	/**
-	 * Processes file changes for specific file extensions.
-	 * Used by processors to handle their specific file types.
-	 *
-	 * @private
-	 * @param {string} path - Path of the changed file
-	 * @param {string[]} extensions - File extensions to process
-	 * @param {(ctx: ProcessorWatchContext) => void} handler - Handler function for the file change
-	 */
-	private shouldProcess(path: string, extensions: string[], handler: (ctx: ProcessorWatchContext) => void) {
-		if (!extensions.length || extensions.some((ext) => path.endsWith(ext))) {
-			handler({ path, bridge: this.bridge });
-		}
-	}
-
 	/**
 	 * Creates and configures the file system watcher.
 	 * This sets up:
-	 * 1. Processor-specific file watching
-	 * 2. Page file watching
-	 * 3. Directory watching
-	 * 4. Error handling
+	 * 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.
@@ -315,30 +336,29 @@ export class ProjectWatcher {
 			});
 		}
 
-		for (const processor of this.appConfig.processors.values()) {
-			const watchConfig = processor.getWatchConfig();
-			if (!watchConfig) continue;
-			const { extensions = [], onCreate, onChange, onDelete, onError } = watchConfig;
-
-			if (onCreate) this.watcher.on('add', (path) => this.shouldProcess(path, extensions, onCreate));
-			if (onChange) this.watcher.on('change', (path) => this.shouldProcess(path, extensions, onChange));
-			if (onDelete) this.watcher.on('unlink', (path) => this.shouldProcess(path, extensions, onDelete));
-			if (onError) this.watcher.on('error', onError as (error: unknown) => void);
-		}
-
 		this.watcher.add(this.appConfig.absolutePaths.srcDir);
 
 		this.watcher
-			.on('change', (path) => this.handleFileChange(path))
-			.on('add', (path) => {
-				this.handleFileChange(path);
-				this.triggerRouterRefresh(path);
+			.on('change', (p) => this.enqueueChange(() => this.handleFileChange(p, 'change')))
+			.on('add', (p) => {
+				this.enqueueChange(() => this.handleFileChange(p, 'add'));
+				this.triggerRouterRefresh(p);
+			})
+			.on('addDir', (p) => this.triggerRouterRefresh(p))
+			.on('unlink', (p) => {
+				this.enqueueChange(() => this.handleFileChange(p, 'unlink'));
+				this.triggerRouterRefresh(p);
 			})
-			.on('addDir', (path) => this.triggerRouterRefresh(path))
-			.on('unlink', (path) => this.triggerRouterRefresh(path))
-			.on('unlinkDir', (path) => this.triggerRouterRefresh(path))
+			.on('unlinkDir', (p) => 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 as (error: unknown) => void);
+			}
+		}
+
 		return this.watcher;
 	}
 }