fix(hot): harden the SSE handshake and defer the overlay's Escape listener

The handshake now ends a response whose headers were already sent
instead of crashing on writeHead, and the middleware routes handshake
errors to next() — an exception there previously became an unhandled
rejection that killed the process.

The overlay's Escape listener on the host document is now attached
lazily inside ensureOverlay (once per page, through the shared state),
matching how webpack-dev-server registers it inside createOverlay, so
importing the client in a non-DOM environment (SSR bundle, worker) no
longer throws at evaluation time.

Author: bjohansebas

client-src/overlay.js

@@ -126,6 +126,7 @@ const colors = {
  * @property {HTMLIFrameElement | null} frame overlay iframe
  * @property {HTMLElement | null} card visible panel inside the iframe
  * @property {boolean} runtimeListenersAttached whether the window listeners are attached
+ * @property {boolean} hostKeydownAttached whether the host document's Escape listener is attached
  * @property {number} pageIndex page shown when paginating
  * @property {Record<string, { type: "errors" | "warnings", lines: string[] }>} problemsBySource each reporting source's problems
  * @property {{ type: "errors" | "warnings", lines: string[] } | null} currentProblems union of every source, as displayed
@@ -139,6 +140,7 @@ function createOverlayState() {
     frame: null,
     card: null,
     runtimeListenersAttached: false,
+    hostKeydownAttached: false,
     pageIndex: 0,
     problemsBySource: {},
     currentProblems: null,
@@ -329,13 +331,6 @@ function linkify(html) {
   });
 }
 
-// Dismiss the overlay when pressing Escape while the page has focus.
-document.addEventListener("keydown", (event) => {
-  if (event.key === "Escape") {
-    clear();
-  }
-});
-
 /**
  * Create (or return) the overlay iframe and the card inside it.
  * @returns {HTMLElement | null} the card element, or null when the frame
@@ -350,6 +345,19 @@ function ensureOverlay() {
     return null;
   }
 
+  // Dismiss the overlay when pressing Escape while the host page has focus —
+  // the frame's own keydown listener only fires when the frame is focused.
+  // Attached lazily on the first render (and once per page, the flag lives in
+  // the shared state) so importing the module stays free of DOM side effects.
+  if (!state.hostKeydownAttached) {
+    state.hostKeydownAttached = true;
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") {
+        clear();
+      }
+    });
+  }
+
   // Enable Trusted Types if they are available in the current browser.
   if (window.trustedTypes && !state.trustedTypesPolicy) {
     state.trustedTypesPolicy = window.trustedTypes.createPolicy(

src/hot.js

@@ -99,6 +99,15 @@ function createEventStream(heartbeat, logger) {
       clients = new Map();
     },
     handler(req, res) {
+      // A response another middleware already started can no longer become an
+      // SSE stream — end it instead of crashing on writeHead.
+      if (res.headersSent) {
+        if (!res.writableEnded) {
+          res.end();
+        }
+        return;
+      }
+
       /** @type {Record<string, string>} */
       const headers = {
         "Access-Control-Allow-Origin": "*",

src/middleware.js

@@ -380,7 +380,11 @@ function wrapper(context) {
   return async function middleware(req, res, next) {
     // Intercept Server-Sent Events handshake when the `hot` option is enabled.
     if (context.hot && hotPathMatch(getRequestURL(req), context.hot.path)) {
-      context.hot.handle(req, res);
+      try {
+        context.hot.handle(req, res);
+      } catch (error) {
+        return next(/** @type {NodeJS.ErrnoException} */ (error));
+      }
       return;
     }
 

test/hot.test.js

@@ -1,3 +1,5 @@
+import http from "node:http";
+
 import createHot, {
   createEventStream,
   formatErrors,
@@ -347,6 +349,39 @@ describe("createHot", () => {
     hot.close();
   });
 
+  it("ends a response whose headers were already sent instead of registering it", async () => {
+    const compiler = makeFakeCompiler();
+    const hot = createHot(compiler, {});
+
+    const server = http.createServer((req, res) => {
+      // Another middleware already started this response before the SSE
+      // handshake sees it.
+      res.writeHead(200, { "Content-Type": "text/plain" });
+      res.write("already-started");
+
+      hot.handle(req, res);
+      // Were the response wrongly registered as a client, this frame would
+      // show up in the body below.
+      hot.publish({ action: "custom" });
+    });
+
+    await new Promise((resolve) => {
+      server.listen(0, resolve);
+    });
+    const { port } = server.address();
+
+    const response = await fetch(`http://127.0.0.1:${port}/__webpack_hmr`);
+    const body = await response.text();
+
+    expect(response.headers.get("content-type")).toBe("text/plain");
+    expect(body).toBe("already-started");
+
+    hot.close();
+    await new Promise((resolve) => {
+      server.close(resolve);
+    });
+  });
+
   it("includes the compilation name in the building payload", () => {
     const compiler = makeFakeCompiler();
     compiler.name = "main";

test/middleware.test.js

@@ -7010,6 +7010,24 @@ describe.each([
       );
     });
 
+    it("routes SSE handshake errors to the framework error handler", async () => {
+      const compiler = getCompiler(webpackConfig);
+      [server, req, instance] = await frameworkFactory(
+        name,
+        framework,
+        compiler,
+        { hot: true },
+      );
+
+      instance.context.hot.handle = () => {
+        throw new Error("handshake failed");
+      };
+
+      const response = await req.get("/__webpack_hmr");
+
+      expect(response.statusCode).toBe(500);
+    });
+
     it("does not hang hot requests made after instance.close()", async () => {
       const compiler = getCompiler(webpackConfig);
       [server, req, instance] = await frameworkFactory(