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

package/package.json

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

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

@@ -24,6 +24,7 @@ import {
 } from "../shared/runtime-server-lifecycle.js";
 import { ClientBridge } from "./client-bridge.js";
 import { setAppDevClientBridge } from "../../dev/client-bridge-registry.js";
+import { setAppHmrManager } from "../../dev/hmr-manager-registry.js";
 import { HmrManager } from "./hmr-manager.js";
 import { BunStaticPreviewHost } from "./static-preview-host.js";
 class BunServerAdapter extends SharedServerAdapter {
@@ -600,6 +601,7 @@ async function createBunServerAdapter(params) {
   const bridge = params.bridge ?? new ClientBridge();
   const hmrManager = params.hmrManager ?? new HmrManager({ appConfig: params.appConfig, bridge });
   setAppDevClientBridge(params.appConfig, bridge);
+  setAppHmrManager(params.appConfig, hmrManager);
   const previewHost = params.previewHost ?? new BunStaticPreviewHost();
   const adapter = new BunServerAdapter({
     ...params,

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,14 @@
+export declare function encodeHmrDynamicSegments(filepath: string): string;
+/**
+ * Resolves the on-disk and browser URL targets for one HMR script entrypoint.
+ */
+export declare function resolveHmrEntrypointOutputPaths(srcDir: string, distDir: string, entrypointPath: string): {
+    outputPath: string;
+    outputUrl: string;
+};
+/**
+ * @remarks
+ * Rebuilds must delete the previous artifact so browser-hmr does not reuse a
+ * stale bundle when the source file changed.
+ */
+export declare function removeStaleHmrEntrypointOutput(outputPath: string, scope: string): void;

package/src/hmr/hmr-entrypoint-output.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { RESOLVED_ASSETS_DIR } from "../config/constants.js";
+import { appLogger } from "../global/app-logger.js";
+function encodeHmrDynamicSegments(filepath) {
+  return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
+}
+function resolveHmrEntrypointOutputPaths(srcDir, distDir, entrypointPath) {
+  const normalizedEntrypoint = path.resolve(entrypointPath);
+  const relativePath = path.relative(srcDir, normalizedEntrypoint);
+  const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
+  const encodedPathJs = encodeHmrDynamicSegments(relativePathJs);
+  const urlPath = encodedPathJs.split(path.sep).join("/");
+  return {
+    outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath).split(path.sep).join("/")}`,
+    outputPath: path.join(distDir, urlPath)
+  };
+}
+function removeStaleHmrEntrypointOutput(outputPath, scope) {
+  if (!fileSystem.exists(outputPath)) {
+    return;
+  }
+  try {
+    fileSystem.remove(outputPath);
+  } catch (error) {
+    appLogger.warn(
+      `[${scope}] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+export {
+  encodeHmrDynamicSegments,
+  removeStaleHmrEntrypointOutput,
+  resolveHmrEntrypointOutputPaths
+};

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

@@ -98,6 +98,7 @@ export declare class JsHmrStrategy extends HmrStrategy {
      * Matches if:
      * 1. There are registered entrypoints to rebuild
      * 2. The changed file is a JS/TS file in the src directory
+     * 3. Registered entrypoints always match, even when they share an integration template extension
      *
      * @param filePath - Absolute path to the changed file
      * @returns True if this file should trigger entrypoint rebuilds
@@ -116,6 +117,8 @@ export declare class JsHmrStrategy extends HmrStrategy {
      * @returns Action to broadcast update events
      */
     process(filePath: string): Promise<HmrAction>;
+    private resolveEntrypointOutputPath;
+    private removeStaleEntrypointOutput;
     /**
      * Bundles one or more entrypoints in a single build invocation.
      * Uses the source directory as the output base so that the directory structure

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

@@ -2,6 +2,7 @@ import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
 import { appLogger } from "../../global/app-logger.js";
+import { removeStaleHmrEntrypointOutput, resolveHmrEntrypointOutputPaths } from "../hmr-entrypoint-output.js";
 class JsHmrStrategy extends HmrStrategy {
   type = HmrStrategyType.SCRIPT;
   context;
@@ -15,27 +16,29 @@ class JsHmrStrategy extends HmrStrategy {
    * Matches if:
    * 1. There are registered entrypoints to rebuild
    * 2. The changed file is a JS/TS file in the src directory
+   * 3. Registered entrypoints always match, even when they share an integration template extension
    *
    * @param filePath - Absolute path to the changed file
    * @returns True if this file should trigger entrypoint rebuilds
    */
   matches(filePath) {
     const watchedFiles = this.context.getWatchedFiles();
-    const isJsTs = /\.(ts|tsx|js|jsx)$/.test(filePath);
-    const isInSrc = filePath.startsWith(this.context.getSrcDir());
-    const isIntegrationTemplate = this.context.getTemplateExtensions().some((extension) => filePath.endsWith(extension));
+    const resolvedPath = path.resolve(filePath);
+    const isJsTs = /\.(ts|tsx|js|jsx)$/.test(resolvedPath);
+    const isInSrc = resolvedPath.startsWith(this.context.getSrcDir());
+    const isIntegrationTemplate = this.context.getTemplateExtensions().some((extension) => resolvedPath.endsWith(extension));
     if (watchedFiles.size === 0) {
       return false;
     }
     if (!isJsTs || !isInSrc) {
       return false;
     }
+    if (watchedFiles.has(resolvedPath)) {
+      return true;
+    }
     if (isIntegrationTemplate) {
       return false;
     }
-    if (watchedFiles.has(filePath)) {
-      return true;
-    }
     return true;
   }
   /**
@@ -59,7 +62,7 @@ class JsHmrStrategy extends HmrStrategy {
     }
     const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
     const hasDependencyHit = dependencyHits.size > 0;
-    const impactedEntrypoints = hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(entrypoint)) : Array.from(watchedFiles.keys());
+    const impactedEntrypoints = hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(path.resolve(entrypoint))) : Array.from(watchedFiles.keys());
     const buildableEntrypoints = impactedEntrypoints.filter(
       (entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true
     );
@@ -69,6 +72,9 @@ class JsHmrStrategy extends HmrStrategy {
     if (buildableEntrypoints.length === 0) {
       return { type: "none" };
     }
+    for (const entrypoint of buildableEntrypoints) {
+      this.removeStaleEntrypointOutput(this.resolveEntrypointOutputPath(entrypoint));
+    }
     const buildResult = await this.bundleEntrypoints(buildableEntrypoints);
     if (!buildResult.success) {
       return { type: "none" };
@@ -82,10 +88,7 @@ class JsHmrStrategy extends HmrStrategy {
         const entrypointDeps = buildResult.dependencies.get(path.resolve(entrypoint)) ?? [];
         this.context.getEntrypointDependencyGraph().setEntrypointDependencies(entrypoint, entrypointDeps);
       }
-      const srcDir = this.context.getSrcDir();
-      const relativePath = path.relative(srcDir, entrypoint);
-      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
-      const outputPath = path.join(this.context.getDistDir(), relativePathJs);
+      const outputPath = this.resolveEntrypointOutputPath(entrypoint);
       const result = await this.processOutput(outputPath, outputUrl);
       if (result.success) {
         updates.push(outputUrl);
@@ -113,6 +116,12 @@ class JsHmrStrategy extends HmrStrategy {
     }
     return { type: "none" };
   }
+  resolveEntrypointOutputPath(entrypointPath) {
+    return resolveHmrEntrypointOutputPaths(this.context.getSrcDir(), this.context.getDistDir(), entrypointPath).outputPath;
+  }
+  removeStaleEntrypointOutput(outputPath) {
+    removeStaleHmrEntrypointOutput(outputPath, "JsHmrStrategy");
+  }
   /**
    * Bundles one or more entrypoints in a single build invocation.
    * Uses the source directory as the output base so that the directory structure
@@ -120,6 +129,30 @@ class JsHmrStrategy extends HmrStrategy {
    */
   async bundleEntrypoints(entrypoints) {
     try {
+      if (entrypoints.length === 1) {
+        const entrypoint = entrypoints[0];
+        const outputPath = this.resolveEntrypointOutputPath(entrypoint);
+        const naming = path.relative(this.context.getDistDir(), outputPath).split(path.sep).join("/");
+        const result2 = await this.context.getBrowserBundleService().bundle({
+          profile: "hmr-entrypoint",
+          entrypoints: [entrypoint],
+          outdir: this.context.getDistDir(),
+          naming,
+          plugins: this.context.getPlugins(),
+          minify: false
+        });
+        if (!result2.success) {
+          appLogger.error("[JsHmrStrategy] Entrypoint build failed:", result2.logs);
+          return { success: false };
+        }
+        const dependencies2 = /* @__PURE__ */ new Map();
+        if (result2.dependencyGraph?.entrypoints) {
+          for (const [resolvedEntrypoint, deps] of Object.entries(result2.dependencyGraph.entrypoints)) {
+            dependencies2.set(path.resolve(resolvedEntrypoint), deps);
+          }
+        }
+        return { success: true, dependencies: dependencies2 };
+      }
       const result = await this.context.getBrowserBundleService().bundle({
         profile: "hmr-entrypoint",
         entrypoints,