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

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

@@ -0,0 +1,106 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import {
+  removeStaleHmrEntrypointOutput,
+  resolveHmrEntrypointOutputPaths
+} from "../../../hmr/hmr-entrypoint-output.js";
+class HmrEntrypointRegistrar {
+  options;
+  inFlight = /* @__PURE__ */ new Map();
+  registered = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.options = options;
+  }
+  getRegistered() {
+    return this.registered;
+  }
+  getWatchedFiles() {
+    const watchedFiles = /* @__PURE__ */ new Map();
+    for (const [sourcePath, entrypoint] of this.registered) {
+      watchedFiles.set(sourcePath, entrypoint.outputUrl);
+    }
+    return watchedFiles;
+  }
+  clearRegistration(entrypointPath) {
+    this.registered.delete(path.resolve(entrypointPath));
+  }
+  /**
+   * Registers an already-materialized HMR entrypoint without running the emit hook.
+   *
+   * @remarks
+   * Cold dev batches build entrypoints in grouped Rolldown passes and then seed
+   * the registrar so the first SSR can resolve the artifact without rebuilding.
+   * The source path is committed verbatim so `getResolvedScriptOutput()` and the
+   * file watcher see it as a regular watched entrypoint.
+   */
+  seedResolvedEntrypoint(resolved) {
+    this.registered.set(path.resolve(resolved.sourcePath), {
+      sourcePath: resolved.sourcePath,
+      outputPath: resolved.outputPath,
+      outputUrl: resolved.outputUrl
+    });
+  }
+  clearAll() {
+    this.inFlight.clear();
+    this.registered.clear();
+  }
+  /**
+   * Registers a single source entrypoint and returns its verified HMR artifact.
+   *
+   * Concurrent requests for the same normalized entrypoint share the same in-flight promise.
+   */
+  async registerEntrypoint(entrypointPath, registrationOptions) {
+    const normalizedEntrypoint = path.resolve(entrypointPath);
+    const existing = this.registered.get(normalizedEntrypoint);
+    if (existing && fileSystem.exists(existing.outputPath)) {
+      return existing;
+    }
+    const existingRegistration = this.inFlight.get(normalizedEntrypoint);
+    if (existingRegistration) {
+      return await existingRegistration;
+    }
+    const registration = this.registerEntrypointInternal(normalizedEntrypoint, registrationOptions);
+    this.inFlight.set(normalizedEntrypoint, registration);
+    try {
+      return await registration;
+    } catch (error) {
+      this.options.clearFailedRegistration?.(normalizedEntrypoint);
+      this.registered.delete(normalizedEntrypoint);
+      throw error;
+    } finally {
+      if (this.inFlight.get(normalizedEntrypoint) === registration) {
+        this.inFlight.delete(normalizedEntrypoint);
+      }
+    }
+  }
+  async registerEntrypointInternal(entrypointPath, registrationOptions) {
+    const previous = this.registered.get(entrypointPath);
+    const { outputPath, outputUrl } = resolveHmrEntrypointOutputPaths(
+      this.options.srcDir,
+      this.options.distDir,
+      entrypointPath
+    );
+    removeStaleHmrEntrypointOutput(outputPath, "HMR");
+    try {
+      await registrationOptions.emit(entrypointPath, outputPath);
+      if (!fileSystem.exists(outputPath)) {
+        throw registrationOptions.getMissingOutputError(entrypointPath, outputPath);
+      }
+      const resolved = {
+        sourcePath: entrypointPath,
+        outputPath,
+        outputUrl
+      };
+      this.registered.set(entrypointPath, resolved);
+      return resolved;
+    } catch (error) {
+      if (previous && fileSystem.exists(previous.outputPath)) {
+        this.registered.set(entrypointPath, previous);
+      }
+      throw error;
+    }
+  }
+}
+export {
+  HmrEntrypointRegistrar
+};

package/src/adapters/shared/{hmr-html-response.d.ts → hmr/hmr-html-response.d.ts}

@@ -1,4 +1,4 @@
-import type { IHmrManager } from '../../types/public-types.js';
+import type { IHmrManager } from '../../../types/public-types.js';
 /**
  * Returns whether a response is HTML and therefore eligible for development HMR
  * runtime injection.
@@ -11,7 +11,7 @@ export declare function isHtmlResponse(response: Response): boolean;
  * responses flow through different layers, but both need identical injection
  * behavior in watch mode.
  */
-export declare function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>): boolean;
+export declare function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>, hostOwnsDevClient?: boolean): boolean;
 /**
  * Injects the development HMR runtime script into an HTML response if it is not
  * already present.

package/src/adapters/shared/{hmr-html-response.js → hmr/hmr-html-response.js}

@@ -4,7 +4,10 @@ function isHtmlResponse(response) {
   const contentType = response.headers.get("Content-Type");
   return contentType !== null && contentType.startsWith("text/html");
 }
-function shouldInjectHmrHtmlResponse(watch, hmrManager) {
+function shouldInjectHmrHtmlResponse(watch, hmrManager, hostOwnsDevClient = false) {
+  if (hostOwnsDevClient) {
+    return false;
+  }
   return watch && hmrManager?.isEnabled() === true;
 }
 async function injectHmrRuntimeIntoHtmlResponse(response) {

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

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import { type ResolvedHmrEntrypoint } from '../../../hmr/hmr-entrypoint-output.js';
+import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge } from '../../../types/internal-types.js';
+import { type HmrStrategy } from '../../../hmr/hmr-strategy.js';
+import { DevelopmentInvalidationService } from '../../../services/invalidation/development-invalidation.service.js';
+import type { ClientBridgeEvent, HmrFileChangeOptions } from '../../../types/public-types.js';
+import { HmrEntrypointRegistrar } from './hmr-entrypoint-registrar.js';
+import { BrowserBundleService } from '../../../services/assets/browser-bundle.service.js';
+import { type EntrypointDependencyGraph } from '../../../services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { ServerModuleTranspiler } from '../../../services/module-loading/server-module-transpiler.service.js';
+type HandleFileChangeOptions = HmrFileChangeOptions;
+type SharedHmrManagerParams = {
+    appConfig: EcoPagesAppConfig;
+    bridge: IClientBridge;
+};
+export declare abstract class SharedHmrManager implements IHmrManager {
+    readonly appConfig: EcoPagesAppConfig;
+    protected readonly bridge: IClientBridge;
+    protected watchers: Map<string, fs.FSWatcher>;
+    protected distDir: string;
+    protected enabled: boolean;
+    protected strategies: HmrStrategy[];
+    protected readonly entrypointRegistrar: HmrEntrypointRegistrar;
+    protected readonly browserBundleService: BrowserBundleService;
+    protected readonly invalidationService: DevelopmentInvalidationService;
+    protected readonly entrypointDependencyGraph: EntrypointDependencyGraph;
+    protected readonly serverModuleTranspiler: ServerModuleTranspiler;
+    private runtimeBuildPromise;
+    private runtimeReady;
+    constructor({ appConfig, bridge }: SharedHmrManagerParams);
+    protected abstract createEntrypointDependencyGraph(existingEntrypointDependencyGraph: EntrypointDependencyGraph): EntrypointDependencyGraph;
+    protected shouldSkipMissingFileChange(_filePath: string): boolean;
+    protected onRuntimeBundleFailure(error: unknown): void;
+    protected ensureDistDir(): void;
+    protected shouldJsStrategyProcessEntrypoint(entrypointPath: string): boolean;
+    protected initializeStrategies(): void;
+    registerStrategy(strategy: HmrStrategy): void;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    isRuntimeReady(): boolean;
+    /**
+     * Builds the browser HMR runtime once per manager session and reuses the in-flight build for concurrent callers.
+     */
+    ensureRuntimeReady(): Promise<boolean>;
+    buildRuntime(): Promise<void>;
+    getRuntimePath(): string;
+    private buildRuntimeInternal;
+    broadcast(event: ClientBridgeEvent): void;
+    handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
+    private getStrategiesByPriority;
+    private selectChangeStrategy;
+    private selectEntrypointEmitter;
+    protected createUnownedEntrypointError(entrypointPath: string): Error;
+    /**
+     * Materializes one integration-owned page entrypoint during cold registration.
+     *
+     * @remarks
+     * Registration uses {@link HmrStrategy.canEmitEntrypoint} / {@link HmrStrategy.emitEntrypoint},
+     * not {@link HmrStrategy.matches} / {@link HmrStrategy.process}. File-change handling stays
+     * on `handleFileChange()`.
+     */
+    emitIntegrationEntrypoint(entrypointPath: string, outputPath: string): Promise<void>;
+    /**
+     * Runs server invalidation and integration hooks before rebuilding a registered script entrypoint.
+     *
+     * @remarks
+     * Browser-only `*.script.ts` entrypoints skip server module invalidation and bypass-cache
+     * import; only integration change handlers and the downstream strategy rebuild run.
+     */
+    private prepareRegisteredScriptChange;
+    getOutputUrl(entrypointPath: string): string | undefined;
+    /**
+     * Registers an already-materialized HMR entrypoint without rebuilding it.
+     *
+     * @remarks
+     * Cold dev batches build grouped Rolldown passes up front and then seed the
+     * registrar so the first SSR resolves the artifact from disk. The entrypoint
+     * is also added to the watched files so subsequent source edits still rebuild.
+     */
+    seedResolvedEntrypoint(resolved: ResolvedHmrEntrypoint): void;
+    /**
+     * Returns the emitted HMR script output when the entrypoint is already registered
+     * and its browser bundle exists on disk.
+     *
+     * @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): ResolvedHmrEntrypoint | undefined;
+    getWatchedFiles(): Map<string, string>;
+    tryHandleAssetRequest(request: Request): Response | null;
+    getDistDir(): string;
+    getDefaultContext(): DefaultHmrContext;
+    stop(): void;
+    protected clearFailedEntrypointRegistration(entrypointPath: string): void;
+    registerEntrypoint(entrypointPath: string): Promise<string>;
+    registerScriptEntrypoint(entrypointPath: string): Promise<ResolvedHmrEntrypoint>;
+    protected emitScriptEntrypoint(entrypointPath: string, outputPath: string): Promise<void>;
+    [Symbol.dispose](): void;
+}
+export {};

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

@@ -0,0 +1,432 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { RESOLVED_ASSETS_DIR } from "../../../config/constants.js";
+import {
+  removeStaleHmrEntrypointOutput,
+  isRegisteredScriptEntrypoint,
+  isBrowserOnlyRegisteredScriptEntrypoint
+} from "../../../hmr/hmr-entrypoint-output.js";
+import { requireBuildRuntime } from "../../../build/runtime/build-runtime.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 { ServerRenderedTemplateHmrStrategy } from "../../../hmr/strategies/server-rendered-template-hmr-strategy.js";
+import { DevelopmentInvalidationService } from "../../../services/invalidation/development-invalidation.service.js";
+import { appLogger } from "../../../global/app-logger.js";
+import { HmrEntrypointRegistrar } from "./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,
+  setAppEntrypointDependencyGraph
+} from "../../../services/runtime-state/entrypoint-dependency-graph.service.js";
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from "../../../utils/resolve-work-dir.js";
+class SharedHmrManager {
+  appConfig;
+  bridge;
+  watchers = /* @__PURE__ */ new Map();
+  distDir;
+  enabled = false;
+  strategies = [];
+  entrypointRegistrar;
+  browserBundleService;
+  invalidationService;
+  entrypointDependencyGraph;
+  serverModuleTranspiler;
+  runtimeBuildPromise = null;
+  runtimeReady = false;
+  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,
+      clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath)
+    });
+    this.browserBundleService = new BrowserBundleService(appConfig);
+    this.invalidationService = new DevelopmentInvalidationService(appConfig);
+    this.entrypointDependencyGraph = this.createEntrypointDependencyGraph(
+      getAppEntrypointDependencyGraph(appConfig)
+    );
+    setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
+    this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
+    this.ensureDistDir();
+    this.initializeStrategies();
+  }
+  shouldSkipMissingFileChange(_filePath) {
+    return false;
+  }
+  onRuntimeBundleFailure(error) {
+    appLogger.error("[HMR] Failed to build runtime script:", error);
+  }
+  ensureDistDir() {
+    fileSystem.ensureDir(this.distDir);
+  }
+  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.entrypointRegistrar.getWatchedFiles(),
+      getDistDir: () => this.distDir,
+      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 ServerRenderedTemplateHmrStrategy(this.invalidationService),
+      new DefaultHmrStrategy()
+    ];
+  }
+  registerStrategy(strategy) {
+    this.strategies.push(strategy);
+  }
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  isRuntimeReady() {
+    return this.runtimeReady && fileSystem.exists(this.getRuntimePath());
+  }
+  /**
+   * Builds the browser HMR runtime once per manager session and reuses the in-flight build for concurrent callers.
+   */
+  async ensureRuntimeReady() {
+    if (this.runtimeReady) {
+      return true;
+    }
+    if (this.runtimeBuildPromise) {
+      return this.runtimeBuildPromise;
+    }
+    this.runtimeBuildPromise = this.buildRuntimeInternal();
+    try {
+      const ready = await this.runtimeBuildPromise;
+      this.runtimeReady = ready;
+      return ready;
+    } finally {
+      this.runtimeBuildPromise = null;
+    }
+  }
+  async buildRuntime() {
+    await this.ensureRuntimeReady();
+  }
+  getRuntimePath() {
+    return path.join(this.distDir, "_hmr_runtime.js");
+  }
+  async buildRuntimeInternal() {
+    const runtimeSource = fileURLToPath(import.meta.resolve("@ecopages/core/hmr/client/hmr-runtime"));
+    const runtimePath = this.getRuntimePath();
+    removeStaleHmrEntrypointOutput(runtimePath, "HMR");
+    try {
+      const result = await this.browserBundleService.bundle({
+        profile: "hmr-runtime",
+        entrypoints: [runtimeSource],
+        outdir: this.distDir,
+        naming: "_hmr_runtime.js",
+        minify: false
+      });
+      if (!result.success) {
+        this.onRuntimeBundleFailure(result.logs);
+        return false;
+      }
+      const emittedRuntime = result.outputs.find(
+        (output) => path.resolve(output.path) === path.resolve(runtimePath)
+      );
+      if (!emittedRuntime || !fileSystem.exists(runtimePath)) {
+        this.onRuntimeBundleFailure(
+          new Error(`[HMR] Runtime bundle missing expected output at ${runtimePath}`)
+        );
+        return false;
+      }
+      return true;
+    } catch (error) {
+      this.onRuntimeBundleFailure(error);
+      return false;
+    }
+  }
+  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 resolvedFilePath = path.resolve(filePath);
+    if (this.shouldSkipMissingFileChange(filePath) && !fileSystem.exists(filePath)) {
+      appLogger.debug(`[${this.constructor.name}] Skipping missing file change: ${filePath}`);
+      this.clearFailedEntrypointRegistration(filePath);
+      return;
+    }
+    if (isRegisteredScriptEntrypoint(this.entrypointRegistrar.getRegistered(), resolvedFilePath)) {
+      await this.prepareRegisteredScriptChange(resolvedFilePath);
+    }
+    const shouldBroadcast = options.broadcast ?? true;
+    const strategy = this.selectChangeStrategy(filePath);
+    if (!strategy) {
+      appLogger.warn(`[HMR] No strategy found for ${filePath}`);
+      return;
+    }
+    appLogger.debug(`[${this.constructor.name}] Selected strategy: ${strategy.constructor.name}`);
+    const action = await strategy.process(filePath);
+    if (shouldBroadcast && action.type === "broadcast" && action.events) {
+      if (this.bridge.subscriberCount === 0) {
+        appLogger.debug(
+          `[${this.constructor.name}] Deferring HMR client broadcast for ${filePath} until a subscriber connects`
+        );
+        return;
+      }
+      for (const event of action.events) {
+        const graphIdentities = event.graphIdentities ?? options.graphIdentities;
+        this.broadcast(graphIdentities === void 0 ? event : { ...event, graphIdentities });
+      }
+    }
+  }
+  getStrategiesByPriority() {
+    return [...this.strategies].sort((left, right) => right.priority - left.priority);
+  }
+  selectChangeStrategy(filePath) {
+    return this.getStrategiesByPriority().find((candidate) => {
+      try {
+        return candidate.matches(filePath);
+      } catch (error) {
+        appLogger.error(error);
+        return false;
+      }
+    });
+  }
+  selectEntrypointEmitter(entrypointPath) {
+    return this.getStrategiesByPriority().find((candidate) => {
+      if (candidate.type !== HmrStrategyType.INTEGRATION) {
+        return false;
+      }
+      try {
+        return candidate.canEmitEntrypoint(entrypointPath);
+      } catch (error) {
+        appLogger.error(error);
+        return false;
+      }
+    });
+  }
+  createUnownedEntrypointError(entrypointPath) {
+    return new Error(
+      `[HMR] No integration owns entrypoint ${entrypointPath}. Page entrypoints must be emitted by their owning integration.`
+    );
+  }
+  /**
+   * Materializes one integration-owned page entrypoint during cold registration.
+   *
+   * @remarks
+   * Registration uses {@link HmrStrategy.canEmitEntrypoint} / {@link HmrStrategy.emitEntrypoint},
+   * not {@link HmrStrategy.matches} / {@link HmrStrategy.process}. File-change handling stays
+   * on `handleFileChange()`.
+   */
+  async emitIntegrationEntrypoint(entrypointPath, outputPath) {
+    const emitter = this.selectEntrypointEmitter(entrypointPath);
+    if (!emitter) {
+      throw this.createUnownedEntrypointError(entrypointPath);
+    }
+    appLogger.debug(`[${this.constructor.name}] Selected entrypoint emitter: ${emitter.constructor.name}`);
+    await emitter.emitEntrypoint(entrypointPath, outputPath);
+  }
+  /**
+   * Runs server invalidation and integration hooks before rebuilding a registered script entrypoint.
+   *
+   * @remarks
+   * Browser-only `*.script.ts` entrypoints skip server module invalidation and bypass-cache
+   * import; only integration change handlers and the downstream strategy rebuild run.
+   */
+  async prepareRegisteredScriptChange(filePath) {
+    const isBrowserOnlyRegisteredScript = isBrowserOnlyRegisteredScriptEntrypoint(filePath);
+    if (!isBrowserOnlyRegisteredScript) {
+      this.invalidationService.invalidateServerModules([filePath]);
+    }
+    const handlers = this.appConfig.runtime?.registeredScriptEntrypointChangeHandlers ?? [];
+    for (const handler of handlers) {
+      try {
+        await handler(filePath);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : `Failed to handle registered script entrypoint change for ${filePath}: ${String(error)}`;
+        this.broadcast({ type: "error", message });
+        throw error;
+      }
+    }
+    if (isBrowserOnlyRegisteredScript) {
+      return;
+    }
+    const appModuleLoader = this.appConfig.runtime?.appModuleLoader;
+    if (!appModuleLoader) {
+      return;
+    }
+    await appModuleLoader.importModule({
+      filePath,
+      rootDir: this.appConfig.rootDir,
+      outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
+      externalPackages: true,
+      bypassCache: true
+    });
+  }
+  getOutputUrl(entrypointPath) {
+    return this.entrypointRegistrar.getRegistered().get(path.resolve(entrypointPath))?.outputUrl;
+  }
+  /**
+   * Registers an already-materialized HMR entrypoint without rebuilding it.
+   *
+   * @remarks
+   * Cold dev batches build grouped Rolldown passes up front and then seed the
+   * registrar so the first SSR resolves the artifact from disk. The entrypoint
+   * is also added to the watched files so subsequent source edits still rebuild.
+   */
+  seedResolvedEntrypoint(resolved) {
+    this.entrypointRegistrar.seedResolvedEntrypoint(resolved);
+  }
+  /**
+   * Returns the emitted HMR script output when the entrypoint is already registered
+   * and its browser bundle exists on disk.
+   *
+   * @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 registered = this.entrypointRegistrar.getRegistered().get(normalizedEntrypoint);
+    if (!registered || !fileSystem.exists(registered.outputPath)) {
+      return void 0;
+    }
+    return registered;
+  }
+  getWatchedFiles() {
+    return this.entrypointRegistrar.getWatchedFiles();
+  }
+  tryHandleAssetRequest(request) {
+    const url = new URL(request.url);
+    if (url.pathname === "/_hmr_runtime.js") {
+      const runtimePath = this.getRuntimePath();
+      if (fileSystem.exists(runtimePath)) {
+        return new Response(fileSystem.readFileAsBuffer(runtimePath), {
+          headers: {
+            "Content-Type": "application/javascript",
+            "Cache-Control": "no-store, must-revalidate"
+          }
+        });
+      }
+    }
+    if (url.pathname.startsWith("/assets/_hmr/")) {
+      const relativePath = url.pathname.slice("/assets/_hmr/".length);
+      const assetPath = path.join(this.distDir, relativePath);
+      if (fileSystem.exists(assetPath)) {
+        return new Response(fileSystem.readFileAsBuffer(assetPath), {
+          headers: {
+            "Content-Type": "application/javascript",
+            "Cache-Control": "no-store, must-revalidate"
+          }
+        });
+      }
+    }
+    return null;
+  }
+  getDistDir() {
+    return this.distDir;
+  }
+  getDefaultContext() {
+    return {
+      getWatchedFiles: () => this.entrypointRegistrar.getWatchedFiles(),
+      getDistDir: () => this.distDir,
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getBuildExecutor: () => requireBuildRuntime(this.appConfig).getProfile("browser-hmr"),
+      getBrowserBundleService: () => this.browserBundleService,
+      getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+      seedResolvedEntrypoint: (resolved) => this.seedResolvedEntrypoint(resolved),
+      importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
+        filePath,
+        outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
+        externalPackages: true
+      })
+    };
+  }
+  stop() {
+    this.runtimeReady = false;
+    this.entrypointRegistrar.clearAll();
+    for (const watcher of this.watchers.values()) {
+      watcher.close();
+    }
+    this.watchers.clear();
+    this.entrypointDependencyGraph.reset();
+  }
+  clearFailedEntrypointRegistration(entrypointPath) {
+    this.entrypointRegistrar.clearRegistration(entrypointPath);
+    this.entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath);
+  }
+  async registerEntrypoint(entrypointPath) {
+    const resolved = await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint, outputPath) => await this.emitIntegrationEntrypoint(normalizedEntrypoint, outputPath),
+      getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(
+        `[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`
+      )
+    });
+    return resolved.outputUrl;
+  }
+  async registerScriptEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint, outputPath) => await this.emitScriptEntrypoint(normalizedEntrypoint, outputPath),
+      getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(`[HMR] Failed to register script entrypoint: ${normalizedEntrypoint} to ${outputPath}`)
+    });
+  }
+  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
+    });
+    if (!buildResult.success) {
+      throw new Error(
+        `[HMR] Generic script entrypoint build failed for ${entrypointPath}: ${JSON.stringify(buildResult.logs)}`
+      );
+    }
+    if (!fileSystem.exists(outputPath) && buildResult.outputs.length > 0) {
+      const resolvedOutputPath = path.resolve(outputPath);
+      const emittedOutput = buildResult.outputs.find((output) => path.resolve(output.path) === resolvedOutputPath)?.path ?? buildResult.outputs.find((output) => path.basename(output.path) === path.basename(outputPath))?.path;
+      if (emittedOutput && fileSystem.exists(emittedOutput)) {
+        fileSystem.ensureDir(path.dirname(outputPath));
+        if (path.resolve(emittedOutput) !== resolvedOutputPath) {
+          fileSystem.copyFile(emittedOutput, outputPath);
+        }
+      }
+    }
+    const entrypointDependencies = buildResult.dependencyGraph?.entrypoints?.[entrypointPath];
+    if (entrypointDependencies) {
+      this.entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, entrypointDependencies);
+    }
+  }
+  [Symbol.dispose]() {
+    this.stop();
+  }
+}
+export {
+  SharedHmrManager
+};

package/src/adapters/shared/http/api-request-pipeline.d.ts

@@ -0,0 +1,23 @@
+import type { SchemaValidationService } from '../../../services/validation/schema-validation-service.js';
+import type { ApiHandler, CacheInvalidator, ErrorHandler, RenderContext } from '../../../types/public-types.js';
+export type ApiRequestPipelineOptions = {
+    schemaValidator: SchemaValidationService;
+    getRenderContext: () => RenderContext;
+    getCacheService: () => CacheInvalidator | null;
+};
+export declare class ApiRequestPipeline<TRequest extends Request = Request, TServer = unknown> {
+    private readonly schemaValidator;
+    private readonly getRenderContext;
+    private readonly getCacheService;
+    constructor(options: ApiRequestPipelineOptions);
+    match(request: TRequest, apiHandlers: ApiHandler<string, TRequest, TServer>[]): {
+        routeConfig: ApiHandler<string, TRequest, TServer>;
+        params: Record<string, string | string[]>;
+    } | null;
+    tryHandle(request: TRequest, apiHandlers: ApiHandler<string, TRequest, TServer>[], serverInstance: TServer | undefined, errorHandler?: ErrorHandler<TRequest, TServer>): Promise<Response | null>;
+    execute(request: TRequest, params: Record<string, string | string[]>, routeConfig: ApiHandler<string, TRequest, TServer>, serverInstance: TServer | undefined, errorHandler?: ErrorHandler<TRequest, TServer>): Promise<Response>;
+    private createContext;
+    private normalizeParams;
+    private applyRequestSchema;
+    private runMiddlewareChain;
+}