@ecopages/core 0.2.0-alpha.24 → 0.2.0-alpha.26

package/src/adapters/node/create-app.js

@@ -0,0 +1,149 @@
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+import { appLogger } from "../../global/app-logger.js";
+import { SharedApplicationAdapter } from "../shared/application-adapter.js";
+import { createNodeServerAdapter } from "./server-adapter.js";
+class NodeEcopagesApp extends SharedApplicationAdapter {
+  serverAdapter;
+  server = null;
+  runtimeOrigin = "";
+  createServerAdapter(params) {
+    return createNodeServerAdapter(params);
+  }
+  async stop(force = true) {
+    if (!this.server) {
+      return;
+    }
+    const activeServer = this.server;
+    this.server = null;
+    await new Promise((resolve, reject) => {
+      activeServer.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+      if (force) {
+        activeServer.closeAllConnections();
+      }
+    });
+  }
+  async initializeServerAdapter() {
+    const { dev } = this.cliArgs;
+    const { port: cliPort, hostname: cliHostname } = this.cliArgs;
+    const envPort = process.env.ECOPAGES_PORT;
+    const envHostname = process.env.ECOPAGES_HOSTNAME;
+    const preferredPort = cliPort ?? (envPort ? Number(envPort) : void 0) ?? DEFAULT_ECOPAGES_PORT;
+    const preferredHostname = cliHostname ?? envHostname ?? DEFAULT_ECOPAGES_HOSTNAME;
+    this.runtimeOrigin = `http://${preferredHostname}:${preferredPort}`;
+    return this.createServerAdapter({
+      runtimeOrigin: this.runtimeOrigin,
+      appConfig: this.appConfig,
+      apiHandlers: this.apiHandlers,
+      staticRoutes: this.staticRoutes,
+      errorHandler: this.errorHandler,
+      options: { watch: dev },
+      serveOptions: {
+        port: preferredPort,
+        hostname: preferredHostname,
+        ...this.serverOptions
+      }
+    });
+  }
+  async start() {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    if (this.server) {
+      return this.server;
+    }
+    const { build, preview } = this.cliArgs;
+    if (build || preview) {
+      appLogger.debugTime("Building static pages");
+      await this.serverAdapter.buildStatic({ preview });
+      await this.stop(true);
+      appLogger.debugTimeEnd("Building static pages");
+      if (build) {
+        process.exit(0);
+      }
+      return;
+    }
+    const serveOptions = this.serverAdapter.getServerOptions();
+    const hostname = String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME);
+    const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+    this.runtimeOrigin = `http://${hostname}:${port}`;
+    this.server = createServer(async (req, res) => {
+      try {
+        const webRequest = this.createWebRequest(req);
+        const response = await this.serverAdapter.handleRequest(webRequest);
+        await this.sendNodeResponse(res, response);
+      } catch (error) {
+        appLogger.error("Node server adapter request failed", error);
+        res.statusCode = 500;
+        res.end("Internal Server Error");
+      }
+    });
+    await new Promise((resolve) => {
+      this.server.listen(port, hostname, () => resolve());
+    });
+    await this.serverAdapter.completeInitialization(this.server);
+    appLogger.info(`Node server running at ${this.runtimeOrigin}`);
+    return this.server;
+  }
+  createWebRequest(req) {
+    const url = new URL(req.url ?? "/", this.runtimeOrigin);
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          headers.append(key, item);
+        }
+        continue;
+      }
+      if (value !== void 0) {
+        headers.set(key, value);
+      }
+    }
+    const method = (req.method ?? "GET").toUpperCase();
+    const requestInit = {
+      method,
+      headers
+    };
+    if (method !== "GET" && method !== "HEAD") {
+      requestInit.body = Readable.toWeb(req);
+      requestInit.duplex = "half";
+    }
+    return new Request(url, requestInit);
+  }
+  async sendNodeResponse(res, response) {
+    res.statusCode = response.status;
+    response.headers.forEach((value, key) => {
+      res.setHeader(key, value);
+    });
+    if (!response.body) {
+      res.end();
+      return;
+    }
+    const body = Buffer.from(await response.arrayBuffer());
+    res.end(body);
+  }
+  async fetch(request) {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    return this.serverAdapter.handleRequest(request);
+  }
+}
+async function createNodeApp(options) {
+  return new NodeEcopagesApp(options);
+}
+async function createApp(options) {
+  return createNodeApp(options);
+}
+export {
+  NodeEcopagesApp,
+  createApp,
+  createNodeApp
+};

package/src/adapters/node/node-client-bridge.d.ts

@@ -0,0 +1,26 @@
+import type { WebSocket } from 'ws';
+import type { ClientBridgeEvent, IClientBridge } from '../../types/public-types.js';
+export declare class NodeClientBridge implements IClientBridge {
+    private subscribers;
+    private heartbeatTimer;
+    constructor();
+    /**
+     * Pings all open subscribers and removes any that are no longer in OPEN state.
+     * This prevents a slow memory leak caused by zombie connections that never
+     * send a close event (e.g. abruptly killed browsers, orphaned tabs, network drops).
+     */
+    private sweep;
+    subscribe(ws: WebSocket): void;
+    unsubscribe(ws: WebSocket): void;
+    broadcast(event: ClientBridgeEvent): void;
+    reload(): void;
+    cssUpdate(path: string): void;
+    update(path: string): void;
+    error(message: string): void;
+    get subscriberCount(): number;
+    /**
+     * Stops the heartbeat timer and clears all subscribers.
+     * Call this when the dev server is shutting down.
+     */
+    destroy(): void;
+}

package/src/adapters/node/node-client-bridge.js

@@ -0,0 +1,66 @@
+const HEARTBEAT_INTERVAL_MS = 3e4;
+class NodeClientBridge {
+  subscribers = /* @__PURE__ */ new Set();
+  heartbeatTimer = null;
+  constructor() {
+    this.heartbeatTimer = setInterval(() => this.sweep(), HEARTBEAT_INTERVAL_MS);
+    this.heartbeatTimer.unref?.();
+  }
+  /**
+   * Pings all open subscribers and removes any that are no longer in OPEN state.
+   * This prevents a slow memory leak caused by zombie connections that never
+   * send a close event (e.g. abruptly killed browsers, orphaned tabs, network drops).
+   */
+  sweep() {
+    for (const ws of this.subscribers) {
+      if (ws.readyState !== 1) {
+        this.subscribers.delete(ws);
+        continue;
+      }
+      ws.ping();
+    }
+  }
+  subscribe(ws) {
+    this.subscribers.add(ws);
+  }
+  unsubscribe(ws) {
+    this.subscribers.delete(ws);
+  }
+  broadcast(event) {
+    const payload = JSON.stringify(event);
+    for (const ws of this.subscribers) {
+      if (ws.readyState === 1) {
+        ws.send(payload);
+      }
+    }
+  }
+  reload() {
+    this.broadcast({ type: "reload" });
+  }
+  cssUpdate(path) {
+    this.broadcast({ type: "css-update", path, timestamp: Date.now() });
+  }
+  update(path) {
+    this.broadcast({ type: "update", path, timestamp: Date.now() });
+  }
+  error(message) {
+    this.broadcast({ type: "error", message });
+  }
+  get subscriberCount() {
+    return this.subscribers.size;
+  }
+  /**
+   * Stops the heartbeat timer and clears all subscribers.
+   * Call this when the dev server is shutting down.
+   */
+  destroy() {
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    this.subscribers.clear();
+  }
+}
+export {
+  NodeClientBridge
+};

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

@@ -0,0 +1,133 @@
+import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge } from '../../types/internal-types.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import { type HmrStrategy } from '../../hmr/hmr-strategy.js';
+import type { ClientBridgeEvent } from '../../types/public-types.js';
+export interface NodeHmrManagerParams {
+    appConfig: EcoPagesAppConfig;
+    bridge: IClientBridge;
+}
+type HandleFileChangeOptions = {
+    broadcast?: boolean;
+};
+/**
+ * Node development HMR manager.
+ *
+ * @remarks
+ * This manager owns three separate concerns:
+ * - runtime websocket event fanout
+ * - entrypoint registration and dedupe
+ * - strategy coordination for rebuilds and invalidation
+ *
+ * The strict page-entrypoint contract lives here: `registerEntrypoint()` is
+ * reserved for integration-owned page bundles, while generic script assets must
+ * go through `registerScriptEntrypoint()`.
+ */
+export declare class NodeHmrManager implements IHmrManager {
+    private static readonly entrypointRegistrationTimeoutMs;
+    readonly appConfig: EcoPagesAppConfig;
+    private readonly bridge;
+    private watchers;
+    private watchedFiles;
+    private entrypointRegistrations;
+    private distDir;
+    private plugins;
+    private enabled;
+    private strategies;
+    private readonly entrypointRegistrar;
+    private readonly browserBundleService;
+    private readonly entrypointDependencyGraph;
+    private readonly runtimeSpecifierRegistry;
+    private readonly serverModuleTranspiler;
+    constructor({ appConfig, bridge }: NodeHmrManagerParams);
+    /**
+     * Ensures the HMR output directory exists.
+     *
+     * This must not remove the directory because multiple app processes
+     * can share the same dist path during e2e runs.
+     */
+    private cleanDistDir;
+    /**
+     * Returns whether the generic JS strategy is allowed to rebuild an entrypoint.
+     *
+     * @remarks
+     * Higher-priority integration strategies own framework page entrypoints. When
+     * one of them matches, the generic JS strategy must stay out of the way so a
+     * shared dependency invalidation does not overwrite framework-specific output.
+     */
+    private shouldJsStrategyProcessEntrypoint;
+    private initializeStrategies;
+    registerStrategy(strategy: HmrStrategy): void;
+    setPlugins(plugins: EcoBuildPlugin[]): void;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    /**
+     * Registers runtime bare-specifier mappings exposed by integrations.
+     *
+     * @remarks
+     * These mappings are consumed by framework-owned HMR strategies such as the
+     * React integration strategy when they rewrite browser bundles. The registry
+     * stays generic so the same mappings can support broader import-map-style
+     * runtime features later without moving integration semantics into core.
+     */
+    registerSpecifierMap(map: Record<string, string>): void;
+    buildRuntime(): Promise<void>;
+    getRuntimePath(): string;
+    broadcast(event: ClientBridgeEvent): void;
+    handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
+    getOutputUrl(entrypointPath: string): string | undefined;
+    getWatchedFiles(): Map<string, string>;
+    getSpecifierMap(): Map<string, string>;
+    getDistDir(): string;
+    getPlugins(): EcoBuildPlugin[];
+    getDefaultContext(): DefaultHmrContext;
+    private clearFailedEntrypointRegistration;
+    /**
+     * Registers one integration-owned page entrypoint.
+     *
+     * @remarks
+     * Concurrent callers share one in-flight registration. The registration is
+     * removed from the dedupe map once it resolves or fails so later requests do
+     * not inherit stale state.
+     */
+    registerEntrypoint(entrypointPath: string): Promise<string>;
+    /**
+     * Registers one generic script entrypoint.
+     *
+     * @remarks
+     * This path is intentionally separate from page entrypoints so non-framework
+     * scripts can still use the generic build fallback without weakening the page
+     * ownership contract.
+     */
+    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
+    /**
+     * Performs strict integration-owned entrypoint registration for one normalized source path.
+     *
+     * @remarks
+     * The flow is:
+     * 1. Reserve the output URL in the watched map.
+     * 2. Remove any stale emitted file from an earlier process or failed build.
+     * 3. Let the strategy chain try to emit the entrypoint without broadcasting.
+     * 4. Fail if the owning integration did not emit the expected output.
+     */
+    private emitStrictEntrypoint;
+    /**
+     * Performs registration for a generic script asset.
+     *
+     * @remarks
+     * This path performs a targeted browser bundle for the requested script
+     * entrypoint only. The resulting dependency graph is retained so later file
+     * changes can invalidate just the affected script entrypoints.
+     */
+    private emitScriptEntrypoint;
+    /**
+     * Stops active watchers and releases retained registration state.
+     *
+     * @remarks
+     * The manager intentionally does not remove emitted `_hmr` files from disk
+     * because multiple app processes may share the same dist directory during test
+     * runs. It does clear in-memory indexes so old entrypoints, dependencies, and
+     * specifier maps cannot leak across a reused manager instance.
+     */
+    stop(): void;
+}
+export {};

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

@@ -0,0 +1,311 @@
+import fs from "node:fs";
+import path from "node:path";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+import { getAppBuildExecutor } 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";
+import { HmrEntrypointRegistrar } from "../shared/hmr-entrypoint-registrar.js";
+import { BrowserBundleService } from "../../services/assets/browser-bundle.service.js";
+import { getAppServerModuleTranspiler } from "../../services/module-loading/app-server-module-transpiler.service.js";
+import {
+  getAppEntrypointDependencyGraph,
+  InMemoryEntrypointDependencyGraph,
+  setAppEntrypointDependencyGraph
+} from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
+import { getAppRuntimeSpecifierRegistry } from "../../services/runtime-state/runtime-specifier-registry.service.js";
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from "../../utils/resolve-work-dir.js";
+class NodeHmrManager {
+  static entrypointRegistrationTimeoutMs = 4e3;
+  appConfig;
+  bridge;
+  watchers = /* @__PURE__ */ new Map();
+  watchedFiles = /* @__PURE__ */ new Map();
+  entrypointRegistrations = /* @__PURE__ */ new Map();
+  distDir;
+  plugins = [];
+  enabled = true;
+  strategies = [];
+  entrypointRegistrar;
+  browserBundleService;
+  entrypointDependencyGraph;
+  runtimeSpecifierRegistry;
+  serverModuleTranspiler;
+  constructor({ appConfig, bridge }) {
+    this.appConfig = appConfig;
+    this.bridge = bridge;
+    this.distDir = path.join(resolveInternalWorkDir(this.appConfig), RESOLVED_ASSETS_DIR, "_hmr");
+    this.entrypointRegistrar = new HmrEntrypointRegistrar({
+      srcDir: this.appConfig.absolutePaths.srcDir,
+      distDir: this.distDir,
+      entrypointRegistrations: this.entrypointRegistrations,
+      watchedFiles: this.watchedFiles,
+      clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath),
+      registrationTimeoutMs: NodeHmrManager.entrypointRegistrationTimeoutMs
+    });
+    this.browserBundleService = new BrowserBundleService(appConfig);
+    const existingEntrypointDependencyGraph = getAppEntrypointDependencyGraph(appConfig);
+    this.entrypointDependencyGraph = existingEntrypointDependencyGraph instanceof InMemoryEntrypointDependencyGraph ? existingEntrypointDependencyGraph : new InMemoryEntrypointDependencyGraph();
+    setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
+    this.runtimeSpecifierRegistry = getAppRuntimeSpecifierRegistry(this.appConfig);
+    this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
+    this.cleanDistDir();
+    this.initializeStrategies();
+  }
+  /**
+   * Ensures the HMR output directory exists.
+   *
+   * This must not remove the directory because multiple app processes
+   * can share the same dist path during e2e runs.
+   */
+  cleanDistDir() {
+    fileSystem.ensureDir(this.distDir);
+  }
+  /**
+   * Returns whether the generic JS strategy is allowed to rebuild an entrypoint.
+   *
+   * @remarks
+   * Higher-priority integration strategies own framework page entrypoints. When
+   * one of them matches, the generic JS strategy must stay out of the way so a
+   * shared dependency invalidation does not overwrite framework-specific output.
+   */
+  shouldJsStrategyProcessEntrypoint(entrypointPath) {
+    return !this.strategies.some((strategy) => {
+      if (strategy.type !== HmrStrategyType.INTEGRATION || strategy.priority <= HmrStrategyType.SCRIPT) {
+        return false;
+      }
+      try {
+        return strategy.matches(entrypointPath);
+      } catch (error) {
+        appLogger.error(error);
+        return false;
+      }
+    });
+  }
+  initializeStrategies() {
+    const jsContext = {
+      getWatchedFiles: () => this.watchedFiles,
+      getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
+      getDistDir: () => this.distDir,
+      getPlugins: () => this.plugins,
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getTemplateExtensions: () => this.appConfig.templatesExt,
+      getBrowserBundleService: () => this.browserBundleService,
+      getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+      shouldProcessEntrypoint: (entrypointPath) => this.shouldJsStrategyProcessEntrypoint(entrypointPath)
+    };
+    this.strategies = [new JsHmrStrategy(jsContext), new DefaultHmrStrategy()];
+  }
+  registerStrategy(strategy) {
+    this.strategies.push(strategy);
+  }
+  setPlugins(plugins) {
+    this.plugins = [...plugins];
+  }
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * Registers runtime bare-specifier mappings exposed by integrations.
+   *
+   * @remarks
+   * These mappings are consumed by framework-owned HMR strategies such as the
+   * React integration strategy when they rewrite browser bundles. The registry
+   * stays generic so the same mappings can support broader import-map-style
+   * runtime features later without moving integration semantics into core.
+   */
+  registerSpecifierMap(map) {
+    this.runtimeSpecifierRegistry.register(map);
+  }
+  async buildRuntime() {
+    const runtimeSource = path.resolve(import.meta.dirname, "../../hmr/client/hmr-runtime.js");
+    try {
+      const result = await this.browserBundleService.bundle({
+        profile: "hmr-runtime",
+        entrypoints: [runtimeSource],
+        outdir: this.distDir,
+        naming: "_hmr_runtime.js",
+        minify: false,
+        plugins: this.plugins
+      });
+      if (!result.success) {
+        this.enabled = false;
+        appLogger.error("[HMR] Failed to build runtime script; continuing with HMR disabled.", result.logs);
+      }
+    } catch (error) {
+      this.enabled = false;
+      appLogger.error("[HMR] Failed to build runtime script; continuing with HMR disabled.", error);
+    }
+  }
+  getRuntimePath() {
+    return path.join(this.distDir, "_hmr_runtime.js");
+  }
+  broadcast(event) {
+    appLogger.debug(
+      `[HMR] Broadcasting ${event.type} event, path=${event.path || "all"}, subscribers=${this.bridge.subscriberCount}`
+    );
+    this.bridge.broadcast(event);
+  }
+  async handleFileChange(filePath, options = {}) {
+    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(err);
+        return false;
+      }
+    });
+    if (!strategy) {
+      appLogger.warn(`[HMR] No strategy found for ${filePath}`);
+      return;
+    }
+    appLogger.debug(`[NodeHmrManager] Selected strategy: ${strategy.constructor.name}`);
+    const action = await strategy.process(filePath);
+    const shouldBroadcast = options.broadcast ?? true;
+    if (shouldBroadcast && action.type === "broadcast") {
+      if (action.events) {
+        for (const event of action.events) {
+          this.broadcast(event);
+        }
+      }
+    }
+  }
+  getOutputUrl(entrypointPath) {
+    return this.watchedFiles.get(entrypointPath);
+  }
+  getWatchedFiles() {
+    return this.watchedFiles;
+  }
+  getSpecifierMap() {
+    return this.runtimeSpecifierRegistry.getAll();
+  }
+  getDistDir() {
+    return this.distDir;
+  }
+  getPlugins() {
+    return this.plugins;
+  }
+  getDefaultContext() {
+    return {
+      getWatchedFiles: () => this.watchedFiles,
+      getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
+      getDistDir: () => this.distDir,
+      getPlugins: () => this.plugins,
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getBuildExecutor: () => getAppBuildExecutor(this.appConfig),
+      getBrowserBundleService: () => this.browserBundleService,
+      importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
+        filePath,
+        outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
+        externalPackages: true
+      })
+    };
+  }
+  clearFailedEntrypointRegistration(entrypointPath) {
+    this.watchedFiles.delete(entrypointPath);
+    this.entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath);
+  }
+  /**
+   * Registers one integration-owned page entrypoint.
+   *
+   * @remarks
+   * Concurrent callers share one in-flight registration. The registration is
+   * removed from the dedupe map once it resolves or fails so later requests do
+   * not inherit stale state.
+   */
+  async registerEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint) => await this.emitStrictEntrypoint(normalizedEntrypoint),
+      getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(
+        `[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`
+      )
+    });
+  }
+  /**
+   * Registers one generic script entrypoint.
+   *
+   * @remarks
+   * This path is intentionally separate from page entrypoints so non-framework
+   * scripts can still use the generic build fallback without weakening the page
+   * ownership contract.
+   */
+  async registerScriptEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint, outputPath) => await this.emitScriptEntrypoint(normalizedEntrypoint, outputPath),
+      getMissingOutputError: (normalizedEntrypoint) => new Error(`[HMR] Failed to register script entrypoint: ${normalizedEntrypoint}`)
+    });
+  }
+  /**
+   * Performs strict integration-owned entrypoint registration for one normalized source path.
+   *
+   * @remarks
+   * The flow is:
+   * 1. Reserve the output URL in the watched map.
+   * 2. Remove any stale emitted file from an earlier process or failed build.
+   * 3. Let the strategy chain try to emit the entrypoint without broadcasting.
+   * 4. Fail if the owning integration did not emit the expected output.
+   */
+  async emitStrictEntrypoint(entrypointPath) {
+    await this.handleFileChange(entrypointPath, { broadcast: false });
+  }
+  /**
+   * Performs registration for a generic script asset.
+   *
+   * @remarks
+   * This path performs a targeted browser bundle for the requested script
+   * entrypoint only. The resulting dependency graph is retained so later file
+   * changes can invalidate just the affected script entrypoints.
+   */
+  async emitScriptEntrypoint(entrypointPath, outputPath) {
+    const naming = path.relative(this.distDir, outputPath).split(path.sep).join("/");
+    const buildResult = await this.browserBundleService.bundle({
+      profile: "hmr-entrypoint",
+      entrypoints: [entrypointPath],
+      outdir: this.distDir,
+      naming,
+      minify: false,
+      plugins: this.plugins
+    });
+    if (!buildResult.success) {
+      appLogger.error(`[HMR] Generic script entrypoint build failed for ${entrypointPath}:`, buildResult.logs);
+      return;
+    }
+    const entrypointDependencies = buildResult.dependencyGraph?.entrypoints?.[entrypointPath];
+    if (entrypointDependencies) {
+      this.entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, entrypointDependencies);
+    }
+  }
+  /**
+   * Stops active watchers and releases retained registration state.
+   *
+   * @remarks
+   * The manager intentionally does not remove emitted `_hmr` files from disk
+   * because multiple app processes may share the same dist directory during test
+   * runs. It does clear in-memory indexes so old entrypoints, dependencies, and
+   * specifier maps cannot leak across a reused manager instance.
+   */
+  stop() {
+    this.entrypointRegistrations.clear();
+    for (const watcher of this.watchers.values()) {
+      watcher.close();
+    }
+    this.watchers.clear();
+    this.watchedFiles.clear();
+    this.runtimeSpecifierRegistry.clear();
+    this.entrypointDependencyGraph.reset();
+    this.plugins = [];
+  }
+}
+export {
+  NodeHmrManager
+};