From 6a1ae763643c728a93bb2e5b943fcebbe893ae7a Mon Sep 17 00:00:00 2001
From: Alexander Akait <sheo13666q@gmail.com>
Date: Fri, 18 Sep 2026 11:54:01 +0000
Subject: [PATCH 1/4] fix: client, overlay, progress and server lifecycle
 defects

Consolidates the actionable fixes from #5724, #5725, #5726, #5727, #5728,
#5729, #5730 and #5732.

Client:

- honor `client.progress: "linear" | "circular"`; the resource query only
  recognized `"true"`, so both visual modes were silently disabled
- parse the resource query with full `key=value` semantics (encoded keys,
  `+` as space, `=` inside values, malformed escapes ignored)
- decode credentials taken from the current script tag so `formatURL` does
  not encode them twice
- apply `client.overlay.warnings` / `.errors` filter functions to what the
  overlay renders, not only to the decision to render
- apply the reconnect limit before the first connection attempt, so
  `client.reconnect: false` no longer retries when the socket never opens

Overlay:

- reuse the Trusted Types policy instead of re-creating it per open, which
  throws under a `trusted-types` CSP
- keep only the newest queued render so messages are not duplicated when
  two batches arrive before the iframe loads
- re-register the Escape handler on open; it was removed on first dismiss
  and never restored
- encode the `open-editor` file name, render openable entries as buttons,
  and restore focus on dismiss

Progress:

- style the linear bar through `#progress`; the rules targeted `#bar`,
  which no template emits
- clear the `disappear` class and the pending hide timer when a new build
  starts, so the indicator reappears
- skip redundant `attributeChangedCallback` work and expose progressbar
  ARIA state and reduced-motion styles

Server:

- reject from `start()` on an occupied port or IPC path instead of
  throwing from an event handler, and release what setup allocated
- fix `bonjour` protocol reporting (`||` bound tighter than the ternary)
- only install the WebSocket `upgrade` listener in no-server mode, and
  remove it on close
- skip incomplete interfaces and CIDRs in `findIp`, and hand the listening
  socket an unbracketed IPv6 address
- wait for pending startup before shutting down in plugin mode
- build the asset report from `toJson` with only the fields it prints,
  construct the `serve-index` middleware once, and serialize each
  broadcast once instead of per client
- export `BaseServer` and type `webSocketServer.type` as its constructor

Examples:

- repair `api/plugin` (CommonJS in an ESM package), `ipc` (`http-proxy`),
  `proxy` and `general/proxy-simple` (options removed in v5)
- serve the shared layout assets through `express.static`, which also works
  for the `hono` example, and read each README relative to its own directory
- restore host and cross-origin checks in the `hono` example, whose
  `setupMiddlewares` replaces the built-in stack

Co-authored-by: Oskar Eichler <62393985+OskarEichler@users.noreply.github.com>
---
 .changeset/fix-client-and-server-defects.md   |   5 +
 client-src/index.js                           |  52 ++++--
 client-src/overlay.js                         | 124 +++++++--------
 client-src/progress.js                        |  65 +++++---
 client-src/socket.js                          |   8 +-
 examples/.assets/layout.html                  |  11 +-
 examples/.assets/style.css                    |  24 ++-
 examples/api/middleware/README.md             |   2 +-
 examples/api/middleware/webpack.config.js     |   9 ++
 examples/api/plugin/README.md                 |   2 +-
 examples/api/plugin/webpack.config.js         |  29 ++--
 examples/app/connect/README.md                |   6 +-
 examples/app/hono/README.md                   |  53 ++++++-
 examples/app/hono/webpack.config.js           |  37 +++++
 examples/compression/false/README.md          |   2 +-
 examples/default-cjs/webpack.config.cjs       |   7 +
 examples/dev-middleware/webpack.config.js     |   2 +-
 .../general/proxy-simple/webpack.config.js    |   4 +-
 examples/general/universal-config/client.js   |   2 +-
 examples/headers/array/README.md              |   2 +-
 examples/ipc/webpack.config.js                |  26 ++-
 examples/proxy/README.md                      |  43 ++++-
 examples/proxy/webpack.config.js              |  29 ++--
 examples/server/http2/README.md               |   6 +-
 examples/util.js                              |  97 +++---------
 lib/Server.js                                 | 149 +++++++++++-------
 lib/servers/WebsocketServer.js                |  18 ++-
 package.json                                  |   6 +
 scripts/finalize-cjs-build.mjs                |  15 +-
 test/client/index.test.js                     |  33 ++++
 test/client/overlay-lifecycle.test.js         |  97 ++++++++++++
 test/client/socket-helper.test.js             |  27 ++++
 test/client/utils/createSocketURL.test.js     |  15 ++
 .../__snapshots__/api.test.js.snap.webpack5   |   1 -
 .../overlay.test.js.snap.webpack5             |  79 +++++++++-
 test/e2e/api.test.js                          |  60 +++++--
 test/e2e/built-in-routes.test.js              |  27 ++++
 test/e2e/host.test.js                         | 107 ++++++-------
 test/server/find-ip.test.js                   |  46 ++++++
 types/lib/Server.d.ts                         |   7 +-
 40 files changed, 933 insertions(+), 401 deletions(-)
 create mode 100644 .changeset/fix-client-and-server-defects.md
 create mode 100644 test/client/overlay-lifecycle.test.js
 create mode 100644 test/server/find-ip.test.js

diff --git a/.changeset/fix-client-and-server-defects.md b/.changeset/fix-client-and-server-defects.md
new file mode 100644
index 0000000000..dbe1bdd06f
--- /dev/null
+++ b/.changeset/fix-client-and-server-defects.md
@@ -0,0 +1,5 @@
+---
+"webpack-dev-server": patch
+---
+
+Fix client progress modes, socket URL credentials, overlay and progress lifecycles, server startup error handling and local IP lookup; export `BaseServer`.
diff --git a/client-src/index.js b/client-src/index.js
index e8a650ea3d..cf6f88fc3a 100644
--- a/client-src/index.js
+++ b/client-src/index.js
@@ -34,7 +34,7 @@ import sendMessage from "./utils/sendMessage.js";
  * @typedef {object} Options
  * @property {boolean} hot true when hot enabled, otherwise false
  * @property {boolean} liveReload true when live reload enabled, otherwise false
- * @property {boolean} progress true when need to show progress, otherwise false
+ * @property {boolean | "linear" | "circular"} progress progress display mode
  * @property {boolean | OverlayOptions} overlay overlay options
  * @property {LogLevel=} logging logging level
  * @property {number=} reconnect count of allowed reconnection
@@ -129,10 +129,17 @@ const parseURL = (resourceQuery) => {
     const searchParams = resourceQuery.slice(1).split("&");
 
     for (let i = 0; i < searchParams.length; i++) {
-      const pair = searchParams[i].split("=");
-
-      /** @type {EXPECTED_ANY} */
-      (result)[pair[0]] = decodeURIComponent(pair[1]);
+      const parameter = searchParams[i].replace(/\+/g, " ");
+      const separator = parameter.indexOf("=");
+      const key = separator === -1 ? parameter : parameter.slice(0, separator);
+      const value = separator === -1 ? "" : parameter.slice(separator + 1);
+
+      try {
+        /** @type {EXPECTED_ANY} */
+        (result)[decodeURIComponent(key)] = decodeURIComponent(value);
+      } catch {
+        // Ignore malformed percent escapes without preventing client startup.
+      }
     }
   } else {
     // Else, get the url from the <script> this file was called with.
@@ -189,8 +196,15 @@ if (parsedResourceQuery["live-reload"] === "true") {
   enabledFeatures["Live Reloading"] = true;
 }
 
-if (parsedResourceQuery.progress === "true") {
-  options.progress = true;
+if (
+  parsedResourceQuery.progress === "true" ||
+  parsedResourceQuery.progress === "linear" ||
+  parsedResourceQuery.progress === "circular"
+) {
+  options.progress =
+    parsedResourceQuery.progress === "true"
+      ? true
+      : parsedResourceQuery.progress;
   enabledFeatures.Progress = true;
 }
 
@@ -440,7 +454,7 @@ const onSocketMessage = {
     options.reconnect = value;
   },
   /**
-   * @param {boolean} value progress value
+   * @param {boolean | "linear" | "circular"} value progress value
    */
   progress(value) {
     options.progress = value;
@@ -534,7 +548,7 @@ const onSocketMessage = {
         overlay.send({
           type: "BUILD_ERROR",
           level: "warning",
-          messages: warnings,
+          messages: warningsToDisplay,
         });
       }
     }
@@ -578,7 +592,7 @@ const onSocketMessage = {
         overlay.send({
           type: "BUILD_ERROR",
           level: "error",
-          messages: errors,
+          messages: errorsToDisplay,
         });
       }
     }
@@ -710,16 +724,30 @@ const createSocketURL = (parsedURL) => {
 
   let socketURLAuth = "";
 
+  /**
+   * @param {string} value credential
+   * @returns {string} decoded credential
+   */
+  const decodeAuth = (value) => {
+    if (!parsedURL.fromCurrentScript) return value;
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      // URL accepts literal percent signs that are not valid escape sequences.
+      return value;
+    }
+  };
+
   // `new URL(urlString, [baseURLstring])` doesn't have `auth` property
   // Parse authentication credentials in case we need them
   if (parsedURL.username) {
-    socketURLAuth = parsedURL.username;
+    socketURLAuth = decodeAuth(parsedURL.username);
 
     // Since HTTP basic authentication does not allow empty username,
     // we only include password if the username is not empty.
     if (parsedURL.password) {
       // Result: <username>:<password>
-      socketURLAuth = socketURLAuth.concat(":", parsedURL.password);
+      socketURLAuth = socketURLAuth.concat(":", decodeAuth(parsedURL.password));
     }
   }
 
diff --git a/client-src/overlay.js b/client-src/overlay.js
index 6003b6194b..9ec8ce64ae 100644
--- a/client-src/overlay.js
+++ b/client-src/overlay.js
@@ -5,50 +5,6 @@ import ansiHTML from "ansi-html-community";
 
 /** @typedef {import("./index.js").EXPECTED_ANY} EXPECTED_ANY */
 
-/**
- * @type {(input: string, position: number) => number | undefined}
- */
-// @ts-expect-error
-const getCodePoint = String.prototype.codePointAt
-  ? // @ts-expect-error
-    (input, position) => input.codePointAt(position)
-  : (input, position) =>
-      (input.charCodeAt(position) - 0xd800) * 0x400 +
-      input.charCodeAt(position + 1) -
-      0xdc00 +
-      0x10000;
-
-/**
- * @param {string} macroText macro text
- * @param {RegExp} macroRegExp macro reg exp
- * @param {(input: string) => string} macroReplacer macro replacer
- * @returns {string} result
- */
-const replaceUsingRegExp = (macroText, macroRegExp, macroReplacer) => {
-  macroRegExp.lastIndex = 0;
-  let replaceMatch = macroRegExp.exec(macroText);
-  let replaceResult;
-  if (replaceMatch) {
-    replaceResult = "";
-    let replaceLastIndex = 0;
-    do {
-      if (replaceLastIndex !== replaceMatch.index) {
-        replaceResult += macroText.slice(replaceLastIndex, replaceMatch.index);
-      }
-      const replaceInput = replaceMatch[0];
-      replaceResult += macroReplacer(replaceInput);
-      replaceLastIndex = replaceMatch.index + replaceInput.length;
-    } while ((replaceMatch = macroRegExp.exec(macroText)));
-
-    if (replaceLastIndex !== macroText.length) {
-      replaceResult += macroText.slice(replaceLastIndex);
-    }
-  } else {
-    replaceResult = macroText;
-  }
-  return replaceResult;
-};
-
 const references = {
   "<": "&lt;",
   ">": "&gt;",
@@ -66,15 +22,10 @@ function encode(text) {
     return "";
   }
 
-  return replaceUsingRegExp(text, /[<>'"&]/g, (input) => {
-    let result = references[/** @type {keyof typeof references} */ (input)];
-    if (!result) {
-      const code =
-        input.length > 1 ? getCodePoint(input, 0) : input.charCodeAt(0);
-      result = `&#${code};`;
-    }
-    return result;
-  });
+  return text.replace(
+    /[<>'"&]/g,
+    (input) => references[/** @type {keyof typeof references} */ (input)],
+  );
 }
 
 /**
@@ -450,8 +401,10 @@ const createOverlay = (options) => {
   let containerElement;
   /** @type {HTMLDivElement | null | undefined} */
   let headerElement;
-  /** @type {((element: HTMLDivElement) => void)[]} */
-  let onLoadQueue = [];
+  /** @type {((element: HTMLDivElement) => void) | undefined} */
+  let onLoad;
+  /** @type {Element | null | undefined} */
+  let previousActiveElement;
   /** @type {Omit<TrustedTypePolicy, "createScript" | "createScriptURL"> | undefined} */
   let overlayTrustedTypesPolicy;
 
@@ -474,7 +427,7 @@ const createOverlay = (options) => {
    */
   function createContainer(trustedTypesPolicyName) {
     // Enable Trusted Types if they are available in the current browser.
-    if (window.trustedTypes) {
+    if (window.trustedTypes && !overlayTrustedTypesPolicy) {
       overlayTrustedTypesPolicy = window.trustedTypes.createPolicy(
         trustedTypesPolicyName || "webpack-dev-server#overlay",
         {
@@ -485,9 +438,14 @@ const createOverlay = (options) => {
 
     iframeContainerElement = document.createElement("iframe");
     iframeContainerElement.id = "webpack-dev-server-client-overlay";
+    iframeContainerElement.title = "Webpack development server errors";
     iframeContainerElement.src = "about:blank";
     applyStyle(iframeContainerElement, iframeStyle);
 
+    previousActiveElement = document.activeElement;
+    // eslint-disable-next-line no-use-before-define
+    window.addEventListener("keydown", handleEscapeKey);
+
     iframeContainerElement.onload = () => {
       const contentElement =
         /** @type {Document} */
@@ -531,10 +489,21 @@ const createOverlay = (options) => {
         (iframeContainerElement).contentDocument
       ).body.appendChild(contentElement);
 
-      onLoadQueue.forEach((onLoad) => {
-        onLoad(/** @type {HTMLDivElement} */ (contentElement));
-      });
-      onLoadQueue = [];
+      const iframeDocument = /** @type {Document} */ (
+        /** @type {HTMLIFrameElement} */ (iframeContainerElement)
+          .contentDocument
+      );
+      iframeDocument.documentElement.lang =
+        document.documentElement.lang || "en";
+      // eslint-disable-next-line no-use-before-define
+      iframeDocument.addEventListener("keydown", handleEscapeKey);
+
+      if (onLoad) {
+        onLoad(contentElement);
+        onLoad = undefined;
+      }
+
+      closeButtonElement.focus();
 
       /** @type {HTMLIFrameElement} */
       (iframeContainerElement).onload = null;
@@ -559,7 +528,8 @@ const createOverlay = (options) => {
       return;
     }
 
-    onLoadQueue.push(callback);
+    // Each callback renders the complete current message list.
+    onLoad = callback;
 
     if (iframeContainerElement) {
       return;
@@ -578,10 +548,24 @@ const createOverlay = (options) => {
     }
 
     // Clean up and reset internal state.
+    iframeContainerElement.onload = null;
+    iframeContainerElement.contentDocument?.removeEventListener(
+      "keydown",
+      // eslint-disable-next-line no-use-before-define
+      handleEscapeKey,
+    );
+    const restoreFocus = document.activeElement === iframeContainerElement;
     document.body.removeChild(iframeContainerElement);
 
     iframeContainerElement = null;
     containerElement = null;
+    headerElement = null;
+    onLoad = undefined;
+
+    if (restoreFocus && previousActiveElement instanceof HTMLElement) {
+      previousActiveElement.focus();
+    }
+    previousActiveElement = null;
   }
 
   // Compilation with errors (e.g. syntax error or missing modules).
@@ -608,19 +592,29 @@ const createOverlay = (options) => {
           padding: "1rem 1rem 1.5rem 1rem",
         });
 
-        const typeElement = document.createElement("div");
+        const canOpen = typeof message !== "string" && message.moduleIdentifier;
+        const typeElement = document.createElement(canOpen ? "button" : "div");
         const { header, body } = formatProblem(type, message);
 
         typeElement.innerText = header;
         applyStyle(typeElement, msgTypeStyle);
 
-        if (typeof message !== "string" && message.moduleIdentifier) {
-          applyStyle(typeElement, { cursor: "pointer" });
+        if (canOpen) {
+          typeElement.setAttribute("type", "button");
+          applyStyle(typeElement, {
+            cursor: "pointer",
+            background: "none",
+            border: "none",
+            padding: "0",
+            textAlign: "left",
+            display: "block",
+            lineHeight: "inherit",
+          });
           // element.dataset not supported in IE
           typeElement.setAttribute("data-can-open", "true");
           typeElement.addEventListener("click", () => {
             fetch(
-              `/webpack-dev-server/open-editor?fileName=${message.moduleIdentifier}`,
+              `/webpack-dev-server/open-editor?fileName=${encodeURIComponent(canOpen)}`,
             );
           });
         }
diff --git a/client-src/progress.js b/client-src/progress.js
index acac9ed77a..e643537cf5 100644
--- a/client-src/progress.js
+++ b/client-src/progress.js
@@ -38,9 +38,7 @@ export function defineProgressElement() {
       (this.shadowRoot).innerHTML = innerHTML;
 
       const progressValue = this.getAttribute("progress");
-      this.initialProgress = progressValue ? Number(progressValue) : 0;
-
-      this.#update(this.initialProgress);
+      this.#update(progressValue ? Number(progressValue) : 0);
     }
 
     static #circularTemplate() {
@@ -98,6 +96,11 @@ export function defineProgressElement() {
         .hidden {
             display: none;
         }
+
+        @media (prefers-reduced-motion: reduce) {
+            :host { transition: none; }
+            .disappear { animation: none; }
+        }
         </style>
         <svg id="progress" class="hidden noselect" viewBox="0 0 80 80">
         <circle cx="50%" cy="50%" r="35"></circle>
@@ -123,7 +126,7 @@ export function defineProgressElement() {
             z-index: 2147483645;
         }
 
-        #bar {
+        #progress {
             width: 0%;
             height: 4px;
             background-color: rgb(186, 223, 172);
@@ -143,15 +146,28 @@ export function defineProgressElement() {
         .hidden {
             display: none;
         }
+
+        @media (prefers-reduced-motion: reduce) {
+            .disappear { animation: none; }
+        }
         </style>
         <div id="progress"></div>
         `;
     }
 
     connectedCallback() {
+      this.setAttribute("role", "progressbar");
+      this.setAttribute("aria-label", "Compilation progress");
+      this.setAttribute("aria-valuemin", "0");
+      this.setAttribute("aria-valuemax", "100");
       this.#reset();
     }
 
+    disconnectedCallback() {
+      clearTimeout(this.animationTimer);
+      this.animationTimer = null;
+    }
+
     static get observedAttributes() {
       return ["progress", "type"];
     }
@@ -162,6 +178,10 @@ export function defineProgressElement() {
      * @param {string} newValue new value
      */
     attributeChangedCallback(name, oldValue, newValue) {
+      if (!this.isConnected || oldValue === newValue) {
+        return;
+      }
+
       if (name === "progress") {
         this.#update(Number(newValue));
       } else if (name === "type") {
@@ -173,6 +193,8 @@ export function defineProgressElement() {
      * @param {number} percent percent
      */
     #update(percent) {
+      // cspell:ignore valuenow
+      this.setAttribute("aria-valuenow", String(percent));
       const shadowRoot = /** @type {ShadowRoot} */ (this.shadowRoot);
       const element =
         /** @type {HTMLElement} */
@@ -194,43 +216,36 @@ export function defineProgressElement() {
 
       if (percent >= 100) {
         this.#hide();
-      } else if (percent > 0) {
+      } else {
         this.#show();
       }
     }
 
     #show() {
+      clearTimeout(this.animationTimer);
+      this.animationTimer = null;
       const shadowRoot = /** @type {ShadowRoot} */ (this.shadowRoot);
       const element =
         /** @type {HTMLElement} */
         (shadowRoot.querySelector("#progress"));
-      element.classList.remove("hidden");
+      element.classList.remove("hidden", "disappear");
     }
 
     #hide() {
+      if (this.animationTimer !== null) {
+        return;
+      }
+
       const shadowRoot = /** @type {ShadowRoot} */ (this.shadowRoot);
       const element =
         /** @type {HTMLElement} */
         (shadowRoot.querySelector("#progress"));
-      if (this.type === "circular") {
-        element.classList.add("disappear");
-        element.addEventListener(
-          "animationend",
-          () => {
-            element.classList.add("hidden");
-            this.#update(0);
-          },
-          { once: true },
-        );
-      } else if (this.type === "linear") {
-        element.classList.add("disappear");
-        this.animationTimer = setTimeout(() => {
-          element.classList.remove("disappear");
-          element.classList.add("hidden");
-          element.style.width = "0%";
-          this.animationTimer = null;
-        }, 800);
-      }
+      element.classList.add("disappear");
+      this.animationTimer = setTimeout(() => {
+        element.classList.remove("disappear");
+        element.classList.add("hidden");
+        this.animationTimer = null;
+      }, 800);
     }
   }
 
diff --git a/client-src/socket.js b/client-src/socket.js
index c44e633a3e..92b39c75f6 100644
--- a/client-src/socket.js
+++ b/client-src/socket.js
@@ -39,6 +39,10 @@ let timeout;
  * @param {number=} reconnect count of reconnections
  */
 function socket(url, handlers, reconnect) {
+  if (typeof reconnect !== "undefined") {
+    maxRetries = reconnect;
+  }
+
   client = new Client(url);
 
   client.onOpen(() => {
@@ -47,10 +51,6 @@ function socket(url, handlers, reconnect) {
     if (timeout) {
       clearTimeout(timeout);
     }
-
-    if (typeof reconnect !== "undefined") {
-      maxRetries = reconnect;
-    }
   });
 
   client.onClose(() => {
diff --git a/examples/.assets/layout.html b/examples/.assets/layout.html
index 1350dc5f3a..983ce8e9c2 100644
--- a/examples/.assets/layout.html
+++ b/examples/.assets/layout.html
@@ -1,22 +1,23 @@
 <!doctype html>
-<html>
+<html lang="en">
   <head>
     <title>WDS ▻ <%= htmlWebpackPlugin.options.title %></title>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <link rel="shortcut icon" href=".assets/favicon.ico" />
+    <link rel="shortcut icon" href="/.assets/favicon.ico" />
     <link
       rel="stylesheet"
       href="https://fonts.googleapis.com/css?family=Source+Code+Pro:400,600|Source+Sans+Pro:400,400i,500,600"
     />
-    <link rel="stylesheet" href=".assets/style.css" />
+    <link rel="stylesheet" href="/.assets/style.css" />
   </head>
   <body>
     <main>
       <header>
         <h1>
           <img
-            src=".assets/icon-square.svg"
+            src="/.assets/icon-square.svg"
+            alt=""
             style="width: 35px; height: 35px"
           />
           webpack-dev-server
@@ -24,7 +25,7 @@ <h1>
       </header>
       <section>
         <h2><%= htmlWebpackPlugin.options.title %></h2>
-        <div id="target"></div>
+        <div id="target" role="status"></div>
       </section>
     </main>
   </body>
diff --git a/examples/.assets/style.css b/examples/.assets/style.css
index ebce115f15..b7dc9a0bf7 100644
--- a/examples/.assets/style.css
+++ b/examples/.assets/style.css
@@ -3,8 +3,8 @@
   font-style: normal;
   font-weight: 600;
   src:
-    url("assets/geomanist-medium.woff2") format("woff2"),
-    url("assets/geomanist-medium.woff") format("woff");
+    url("geomanist-medium.woff2") format("woff2"),
+    url("geomanist-medium.woff") format("woff");
 }
 
 html,
@@ -27,8 +27,8 @@ body {
 }
 
 a {
-  color: #2086d7;
-  text-decoration: none;
+  color: #1a6aab;
+  text-decoration: underline;
   transition: color 250ms;
 }
 
@@ -36,7 +36,19 @@ a:hover {
   color: #1a6aab;
 }
 
+a:focus-visible {
+  outline: 2px solid currentcolor;
+  outline-offset: 3px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  a {
+    transition: none;
+  }
+}
+
 main {
+  box-sizing: border-box;
   width: 100%;
   max-width: 94.2rem;
   margin: 0px auto;
@@ -91,7 +103,7 @@ code {
   background: #dcf2fd;
   border: 0.1rem solid #618ca0;
   border-radius: 0.3rem;
-  color: #618ca0;
+  color: #356074;
   margin: 2rem 0;
   padding: 2rem;
 }
@@ -105,7 +117,7 @@ code {
 #target.pass {
   background: #f2f9f4;
   border: 0.1rem solid #4db277;
-  color: #4db277;
+  color: #287847;
 }
 
 #target.fail {
diff --git a/examples/api/middleware/README.md b/examples/api/middleware/README.md
index 988e597d8d..3f30c06a0c 100644
--- a/examples/api/middleware/README.md
+++ b/examples/api/middleware/README.md
@@ -2,7 +2,7 @@
 
 While it's recommended to run `webpack-dev-server` via the CLI, you may also
 choose to start a server via the API. This example demonstrates using one of the
-few custom middleware options; `before`.
+custom middleware options, `setupMiddlewares`.
 
 ```console
 node server.js
diff --git a/examples/api/middleware/webpack.config.js b/examples/api/middleware/webpack.config.js
index 2a3bc16cc8..6ec8f07bc0 100644
--- a/examples/api/middleware/webpack.config.js
+++ b/examples/api/middleware/webpack.config.js
@@ -12,6 +12,15 @@ export default setup(
     stats: {
       colors: true,
     },
+    devServer: {
+      setupMiddlewares: (middlewares) => {
+        middlewares.unshift((req, res, next) => {
+          console.log(`Using middleware for ${req.url}`);
+          next();
+        });
+        return middlewares;
+      },
+    },
   },
   import.meta.url,
 );
diff --git a/examples/api/plugin/README.md b/examples/api/plugin/README.md
index 019dfaebcd..739d3be42b 100644
--- a/examples/api/plugin/README.md
+++ b/examples/api/plugin/README.md
@@ -31,7 +31,7 @@ npx webpack --watch
 
 ## What should happen
 
-1. Open `http://localhost:8080/` in your preferred browser.
+1. Open `http://localhost:8090/` in your preferred browser.
 2. You should see the text on the page itself change to read `Success!`.
 3. Press `Ctrl+C` in the terminal — `webpack-cli` closes the compiler, which
    fires the plugin's `shutdown` hook, stopping the dev server cleanly.
diff --git a/examples/api/plugin/webpack.config.js b/examples/api/plugin/webpack.config.js
index b31e67e125..75be95b840 100644
--- a/examples/api/plugin/webpack.config.js
+++ b/examples/api/plugin/webpack.config.js
@@ -1,20 +1,21 @@
-"use strict";
-
-const WebpackDevServer = require("../../../lib/Server");
+import WebpackDevServer from "../../../lib/Server.js";
 // our setup function adds behind-the-scenes bits to the config that all of our
 // examples need
-const { setup } = require("../../util");
+import { setup } from "../../util.js";
 
-const config = setup({
-  context: __dirname,
-  entry: "./app.js",
-  output: {
-    filename: "bundle.js",
-  },
-  stats: {
-    colors: true,
+const config = setup(
+  {
+    context: import.meta.dirname,
+    entry: "./app.js",
+    output: {
+      filename: "bundle.js",
+    },
+    stats: {
+      colors: true,
+    },
   },
-});
+  import.meta.url,
+);
 
 // `setup()` populates `config.devServer.setupMiddlewares` so that the example
 // layout assets (CSS, favicon, icons under `.assets/`) are served by the dev
@@ -24,4 +25,4 @@ config.plugins.push(
   new WebpackDevServer({ ...config.devServer, port: 8090, open: true }),
 );
 
-module.exports = config;
+export default config;
diff --git a/examples/app/connect/README.md b/examples/app/connect/README.md
index b2074b1718..06ebbf282b 100644
--- a/examples/app/connect/README.md
+++ b/examples/app/connect/README.md
@@ -10,14 +10,12 @@ const connect = require("connect");
 module.exports = {
   // ...
   devServer: {
-    server: {
-      app: () => connect(),
-    },
+    app: () => connect(),
   },
 };
 ```
 
 ## What Should Happen
 
-1. The script should open `https://localhost:8080/` in your default browser.
+1. The script should open `http://localhost:8080/` in your default browser.
 2. You should see the text on the page itself change to read `Success!`.
diff --git a/examples/app/hono/README.md b/examples/app/hono/README.md
index 54b9cbe199..378db68a8c 100644
--- a/examples/app/hono/README.md
+++ b/examples/app/hono/README.md
@@ -5,19 +5,62 @@ Serve using [`hono`](https://github.com/honojs/hono) as an application.
 **webpack.config.js**
 
 ```js
-const connect = require("connect");
+import { createAdaptorServer } from "@hono/node-server";
+import { Hono } from "hono";
+import wdm from "webpack-dev-middleware";
 
-module.exports = {
+export default {
   // ...
   devServer: {
-    server: {
-      app: () => connect(),
+    app: () => new Hono(),
+    server: (_, app) => createAdaptorServer({ fetch: app.fetch }),
+    setupMiddlewares: (_, devServer) => {
+      const hostCheck = async (context, next) => {
+        const headers = context.env.incoming.headers;
+        const headerName = headers[":authority"] ? ":authority" : "host";
+
+        if (!devServer.isValidHost(headers, headerName)) {
+          return context.text("Invalid Host header", 403);
+        }
+
+        await next();
+      };
+      const crossOriginCheck = async (context, next) => {
+        const headers = context.env.incoming.headers;
+        const headerName = headers[":authority"] ? ":authority" : "host";
+
+        if (
+          !devServer.isValidHost(headers, headerName, false) &&
+          headers["sec-fetch-mode"] === "no-cors" &&
+          headers["sec-fetch-site"] === "cross-site"
+        ) {
+          return context.text("Cross-Origin request blocked", 403);
+        }
+
+        if (
+          devServer.options.allowedHosts !== "all" &&
+          !devServer.isUserCORSWildcardEnabled()
+        ) {
+          context.header("Cross-Origin-Resource-Policy", "same-origin");
+        }
+
+        await next();
+      };
+
+      return [
+        { middleware: hostCheck },
+        { middleware: crossOriginCheck },
+        { middleware: wdm.honoWrapper(devServer.compiler) },
+      ];
     },
   },
 };
 ```
 
+Custom applications replace the default middleware stack, so they must provide
+equivalent host and cross-origin protections.
+
 ## What Should Happen
 
-1. The script should open `https://localhost:8080/` in your default browser.
+1. The script should open `http://localhost:8080/` in your default browser.
 2. You should see the text on the page itself change to read `Success!`.
diff --git a/examples/app/hono/webpack.config.js b/examples/app/hono/webpack.config.js
index 7a9682ea46..0dc9e34625 100644
--- a/examples/app/hono/webpack.config.js
+++ b/examples/app/hono/webpack.config.js
@@ -17,6 +17,43 @@ export default setup(
       // You always need to set up middlewares which you required for your app,
       // built-in middlewares (like `history-api-fallback`/etc) doesn't work by default with `hono`
       setupMiddlewares: (_, devServer) => [
+        {
+          name: "host-header-check",
+          middleware: async (context, next) => {
+            const headers = context.env.incoming.headers;
+            const headerName = headers[":authority"] ? ":authority" : "host";
+
+            if (!devServer.isValidHost(headers, headerName)) {
+              return context.text("Invalid Host header", 403);
+            }
+
+            await next();
+          },
+        },
+        {
+          name: "cross-origin-header-check",
+          middleware: async (context, next) => {
+            const headers = context.env.incoming.headers;
+            const headerName = headers[":authority"] ? ":authority" : "host";
+
+            if (
+              !devServer.isValidHost(headers, headerName, false) &&
+              headers["sec-fetch-mode"] === "no-cors" &&
+              headers["sec-fetch-site"] === "cross-site"
+            ) {
+              return context.text("Cross-Origin request blocked", 403);
+            }
+
+            if (
+              devServer.options.allowedHosts !== "all" &&
+              !devServer.isUserCORSWildcardEnabled()
+            ) {
+              context.header("Cross-Origin-Resource-Policy", "same-origin");
+            }
+
+            await next();
+          },
+        },
         {
           name: "webpack-dev-middleware",
           middleware: wdm.honoWrapper(devServer.compiler),
diff --git a/examples/compression/false/README.md b/examples/compression/false/README.md
index 4d3db1e3f2..ba408d6c06 100644
--- a/examples/compression/false/README.md
+++ b/examples/compression/false/README.md
@@ -27,7 +27,7 @@ npx webpack serve --open --no-compress
 ### What should happen
 
 1. The script should open `http://localhost:8080/`.
-2. Files being sent to the browser from the `webpack` bundle should be gzipped.
+2. Files being sent to the browser from the `webpack` bundle should not be gzipped.
 3. Open the console in your browser's devtools and select the _Network_ tab.
 4. Find `main.js`. The response headers should not contain `Content-Encoding: gzip`.
 
diff --git a/examples/default-cjs/webpack.config.cjs b/examples/default-cjs/webpack.config.cjs
index 7533a297b6..0a2e768b8f 100644
--- a/examples/default-cjs/webpack.config.cjs
+++ b/examples/default-cjs/webpack.config.cjs
@@ -29,4 +29,11 @@ module.exports = {
   stats: {
     colors: true,
   },
+  devServer: {
+    static: {
+      directory: path.join(__dirname, "../.assets"),
+      publicPath: "/.assets",
+      watch: false,
+    },
+  },
 };
diff --git a/examples/dev-middleware/webpack.config.js b/examples/dev-middleware/webpack.config.js
index bcd8cd0ed0..e19c50315e 100644
--- a/examples/dev-middleware/webpack.config.js
+++ b/examples/dev-middleware/webpack.config.js
@@ -8,7 +8,7 @@ export default setup(
     entry: "./app.js",
     devServer: {
       devMiddleware: {
-        index: false,
+        index: true,
         headers: {
           "X-Custom-Header": "yes",
         },
diff --git a/examples/general/proxy-simple/webpack.config.js b/examples/general/proxy-simple/webpack.config.js
index 44c1237201..61946ad7b9 100644
--- a/examples/general/proxy-simple/webpack.config.js
+++ b/examples/general/proxy-simple/webpack.config.js
@@ -7,9 +7,7 @@ export default setup(
     context: import.meta.dirname,
     entry: "./app.js",
     devServer: {
-      proxy: {
-        "/api": "http://127.0.0.1:50545",
-      },
+      proxy: [{ context: "/api", target: "http://127.0.0.1:50545" }],
     },
   },
   import.meta.url,
diff --git a/examples/general/universal-config/client.js b/examples/general/universal-config/client.js
index a3c4af2f8d..0fe5ee3986 100644
--- a/examples/general/universal-config/client.js
+++ b/examples/general/universal-config/client.js
@@ -11,7 +11,7 @@ if (!globalThis.fetch) {
     })
     .then((res) => res.text())
     .then((res) => {
-      if (res.includes("console.log('webpack-dev-server/server');")) {
+      if (res.includes("webpack-dev-server/server")) {
         target.classList.add("pass");
         target.innerHTML = "[client.js, server.js]: Success!";
       }
diff --git a/examples/headers/array/README.md b/examples/headers/array/README.md
index 3ef60579b1..166cf3e495 100644
--- a/examples/headers/array/README.md
+++ b/examples/headers/array/README.md
@@ -1,4 +1,4 @@
-# headers option as an object
+# headers option as an array
 
 Adds headers to all responses.
 
diff --git a/examples/ipc/webpack.config.js b/examples/ipc/webpack.config.js
index 32df532c3b..3eace11aa3 100644
--- a/examples/ipc/webpack.config.js
+++ b/examples/ipc/webpack.config.js
@@ -1,5 +1,5 @@
 import http from "node:http";
-import httpProxy from "http-proxy";
+import { createProxyServer } from "httpxy";
 // our setup function adds behind-the-scenes bits to the config that all of our
 // examples need
 import { setup } from "../util.js";
@@ -9,25 +9,41 @@ export default setup(
     context: import.meta.dirname,
     entry: "./app.js",
     devServer: {
+      ipc: true,
       webSocketServer: "ws",
-      onAfterSetupMiddleware: (server) => {
+      onListening: (server) => {
         const proxyPort = 8080;
         const proxyHost = "127.0.0.1";
-        const proxy = httpProxy.createProxyServer({
+        const proxy = createProxyServer({
           target: { socketPath: server.options.ipc },
         });
 
         const proxyServer = http.createServer((request, response) => {
           // You can define here your custom logic to handle the request
           // and then proxy the request.
-          proxy.web(request, response);
+          proxy.web(request, response).catch(() => {
+            response.writeHead(502);
+            response.end("Proxy request failed");
+          });
         });
+        const upgradedSockets = new Set();
 
         proxyServer.on("upgrade", (request, socket, head) => {
-          proxy.ws(request, socket, head);
+          upgradedSockets.add(socket);
+          socket.once("close", () => upgradedSockets.delete(socket));
+          proxy
+            .ws(request, socket, undefined, head)
+            .catch(() => socket.destroy());
         });
 
         proxyServer.listen(proxyPort, proxyHost);
+        server.server.once("close", () => {
+          proxyServer.close();
+          proxyServer.closeAllConnections();
+          for (const socket of upgradedSockets) {
+            socket.destroy();
+          }
+        });
       },
     },
   },
diff --git a/examples/proxy/README.md b/examples/proxy/README.md
index dd6dc5fb9c..18d68d7454 100644
--- a/examples/proxy/README.md
+++ b/examples/proxy/README.md
@@ -5,14 +5,45 @@ Proxying some URLs can be useful when you have a separate API backend developmen
 **webpack.config.js**
 
 ```js
-module.exports = {
+import { once } from "node:events";
+import express from "express";
+
+function listenProxyServer() {
+  const proxyApp = express();
+
+  proxyApp.get("/proxy", (req, res) => {
+    res.send("response from proxy");
+  });
+
+  return proxyApp.listen(0, "127.0.0.1");
+}
+
+let proxyServer;
+let proxyServerReady;
+
+export default {
   // ...
   devServer: {
-    proxy: {
-      "/proxy": {
-        target: "http://localhost:5000",
-      },
+    setupMiddlewares: (middlewares, devServer) => {
+      proxyServer = listenProxyServer();
+      proxyServerReady = once(proxyServer, "listening");
+      devServer.server.once("close", () => {
+        proxyServer.close();
+        proxyServer.closeAllConnections();
+      });
+      return middlewares;
     },
+    proxy: [
+      {
+        context: "/proxy",
+        target: "http://127.0.0.1",
+        router: async () => {
+          await proxyServerReady;
+          const { port } = proxyServer.address();
+          return `http://127.0.0.1:${port}`;
+        },
+      },
+    ],
   },
 };
 ```
@@ -25,6 +56,6 @@ npx webpack serve --open
 
 ## What Should Happen
 
-1. The script start a proxy server on `http://localhost:5000/` and open `http://localhost:8080/` in your default browser.
+1. The script starts a backend on an available loopback port and opens `http://localhost:8080/` in your default browser. The example's `router` function directs proxy requests to that backend, avoiding conflicts with services already using port 5000.
 2. You should see the text on the page itself change to read `Success! Now visit /proxy`.
 3. Now visit the `/proxy` route by clicking on the `/proxy` text, you should see the text on the page itself change to read `response from proxy`.
diff --git a/examples/proxy/webpack.config.js b/examples/proxy/webpack.config.js
index e73519b971..367be0c4b2 100644
--- a/examples/proxy/webpack.config.js
+++ b/examples/proxy/webpack.config.js
@@ -1,3 +1,4 @@
+import { once } from "node:events";
 import express from "express";
 // our setup function adds behind-the-scenes bits to the config that all of our
 // examples need
@@ -6,32 +7,42 @@ import { setup } from "../util.js";
 /**
  *
  */
-async function listenProxyServer() {
+function listenProxyServer() {
   const proxyApp = express();
 
   proxyApp.get("/proxy", (req, res) => {
     res.send("response from proxy");
   });
 
-  await new Promise((resolve) => {
-    proxyApp.listen(5000, () => {
-      resolve();
-    });
-  });
+  return proxyApp.listen(0, "127.0.0.1");
 }
 
+let proxyServer;
+let proxyServerReady;
+
 export default setup(
   {
     context: import.meta.dirname,
     entry: "./app.js",
     devServer: {
-      onBeforeSetupMiddleware: async () => {
-        await listenProxyServer();
+      setupMiddlewares: (middlewares, devServer) => {
+        proxyServer = listenProxyServer();
+        proxyServerReady = once(proxyServer, "listening");
+        devServer.server.once("close", () => {
+          proxyServer.close();
+          proxyServer.closeAllConnections();
+        });
+        return middlewares;
       },
       proxy: [
         {
           context: "/proxy",
-          target: "http://localhost:5000",
+          target: "http://127.0.0.1",
+          router: async () => {
+            await proxyServerReady;
+            const address = proxyServer.address();
+            return `http://127.0.0.1:${address.port}`;
+          },
         },
       ],
     },
diff --git a/examples/server/http2/README.md b/examples/server/http2/README.md
index fd2ae94430..1d4f2c0df0 100644
--- a/examples/server/http2/README.md
+++ b/examples/server/http2/README.md
@@ -8,10 +8,8 @@ const connect = require("connect");
 module.exports = {
   // ...
   devServer: {
-    server: {
-      server: "http2",
-      app: () => connect(),
-    },
+    server: "http2",
+    app: () => connect(),
   },
 };
 ```
diff --git a/examples/util.js b/examples/util.js
index 83a741dc6d..51bdbd73ce 100644
--- a/examples/util.js
+++ b/examples/util.js
@@ -1,9 +1,9 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import express from "express";
 import fs from "graceful-fs";
 import HtmlWebpackPlugin from "html-webpack-plugin";
 import { marked } from "marked";
-import mime from "mime";
 
 const __dirname = import.meta.dirname;
 
@@ -13,69 +13,15 @@ const __dirname = import.meta.dirname;
  * @returns {object} normalized webpack config
  */
 export function setup(config, callerUrl) {
-  const defaults = { mode: "development", plugins: [], devServer: {} };
-
-  if (config.entry) {
-    if (typeof config.entry === "string") {
-      config.entry = path.resolve(config.entry);
-    } else if (Array.isArray(config.entry)) {
-      config.entry = config.entry.map((entry) => path.resolve(entry));
-    } else if (typeof config.entry === "object") {
-      for (const [key, value] of Object.entries(config.entry)) {
-        config.entry[key] = path.resolve(value);
-      }
-    }
-  }
-
+  const context = path.dirname(fileURLToPath(callerUrl));
+  const defaults = { mode: "development", context, plugins: [], devServer: {} };
   const result = { ...defaults, ...config };
-  const onBeforeSetupMiddleware = ({ app }) => {
-    app.use("/.assets/", (req, res, next) => {
-      if (req.method !== "GET" && req.method !== "HEAD") {
-        next();
-        return;
-      }
-
-      res.setHeader("Content-Type", mime.lookup(req.url));
-
-      const filename = path.join(__dirname, "/.assets/", req.url);
-      const stream = fs.createReadStream(filename);
-
-      stream.pipe(res);
-    });
-  };
-  const renderer = new marked.Renderer();
-  const { heading } = renderer;
-  const markedOptions = {
-    gfm: true,
-    tables: true,
-    breaks: false,
-    pedantic: false,
-    sanitize: false,
-    sanitizer: null,
-    mangle: true,
-    smartLists: false,
-    silent: false,
-    langPrefix: "lang-",
-    smartypants: false,
-    headerPrefix: "",
-    renderer,
-    xhtml: false,
-  };
-  const readme = fs.readFileSync("README.md", "utf8");
-
-  let exampleTitle = "";
-
-  renderer.heading = function headingProxy(text, level, raw, slugger) {
-    if (level === 1 && !exampleTitle) {
-      exampleTitle = text;
-    }
-
-    return heading.call(this, text, level, raw, slugger);
-  };
-
-  marked.setOptions(markedOptions);
-
-  marked(readme, { renderer });
+  const readme = fs.readFileSync(path.join(context, "README.md"), "utf8");
+  const exampleTitle =
+    marked
+      .lexer(readme)
+      .find((token) => token.type === "heading" && token.depth === 1)?.text ||
+    "";
 
   result.plugins.push(
     new HtmlWebpackPlugin({
@@ -85,21 +31,20 @@ export function setup(config, callerUrl) {
     }),
   );
 
-  if (result.devServer.setupMiddlewares) {
-    const proxy = result.devServer.setupMiddlewares;
-    result.devServer.setupMiddlewares = (middlewares, devServer) => {
-      onBeforeSetupMiddleware(devServer);
-      return proxy(middlewares, devServer);
-    };
-  } else {
-    result.devServer.setupMiddlewares = (middlewares, devServer) => {
-      onBeforeSetupMiddleware(devServer);
-      return middlewares;
-    };
-  }
+  const { setupMiddlewares } = result.devServer;
+  result.devServer.setupMiddlewares = (middlewares, devServer) => {
+    middlewares.unshift({
+      name: "example-assets",
+      path: "/.assets",
+      middleware: express.static(path.join(__dirname, ".assets")),
+    });
+    return setupMiddlewares
+      ? setupMiddlewares(middlewares, devServer)
+      : middlewares;
+  };
 
   const output = {
-    path: path.join(path.dirname(fileURLToPath(callerUrl)), "dist"),
+    path: path.join(context, "dist"),
     publicPath: "/",
   };
 
diff --git a/lib/Server.js b/lib/Server.js
index 38577856c9..6123722f9b 100644
--- a/lib/Server.js
+++ b/lib/Server.js
@@ -138,7 +138,7 @@ function loadWebpackPeer() {
 
 /**
  * @typedef {object} WebSocketServerConfiguration
- * @property {("ws" | string | (() => WebSocketServerConfiguration))=} type type
+ * @property {("ws" | string | typeof import("./servers/BaseServer.js").default)=} type type
  * @property {Record<string, EXPECTED_ANY>=} options options
  */
 
@@ -197,8 +197,8 @@ function loadWebpackPeer() {
 /**
  * @typedef {object} ClientConfiguration
  * @property {"log" | "info" | "warn" | "error" | "none" | "verbose"=} logging logging
- * @property {(boolean | { warnings?: OverlayMessageOptions, errors?: OverlayMessageOptions, runtimeErrors?: OverlayMessageOptions })=} overlay overlay
- * @property {boolean=} progress progress
+ * @property {(boolean | { warnings?: OverlayMessageOptions, errors?: OverlayMessageOptions, runtimeErrors?: OverlayMessageOptions, trustedTypesPolicyName?: string })=} overlay overlay
+ * @property {(boolean | "linear" | "circular")=} progress progress
  * @property {(boolean | number)=} reconnect reconnect
  * @property {("ws" | string)=} webSocketTransport web socket transport
  * @property {(string | WebSocketURL)=} webSocketURL web socket URL
@@ -429,24 +429,21 @@ class Server {
    */
   static findIp(gatewayOrFamily, isInternal) {
     if (gatewayOrFamily === "v4" || gatewayOrFamily === "v6") {
-      let host;
-
-      const networks = Object.values(os.networkInterfaces())
-        .flatMap((networks) => networks ?? [])
-        .filter((network) => {
+      for (const networks of Object.values(os.networkInterfaces())) {
+        for (const network of networks ?? []) {
           if (!network || !network.address) {
-            return false;
+            continue;
           }
 
           if (network.family !== `IP${gatewayOrFamily}`) {
-            return false;
+            continue;
           }
 
           if (
             typeof isInternal !== "undefined" &&
             network.internal !== isInternal
           ) {
-            return false;
+            continue;
           }
 
           if (gatewayOrFamily === "v6") {
@@ -457,33 +454,29 @@ class Server {
               range !== "uniqueLocal" &&
               range !== "loopback"
             ) {
-              return false;
+              continue;
             }
           }
 
-          return network.address;
-        });
-
-      if (networks.length > 0) {
-        // Take the first network found
-        host = networks[0].address;
-
-        if (host.includes(":")) {
-          host = `[${host}]`;
+          return network.address.includes(":")
+            ? `[${network.address}]`
+            : network.address;
         }
       }
 
-      return host;
+      return undefined;
     }
 
     const gatewayIp = ipaddr.parse(gatewayOrFamily);
 
     // Look for the matching interface in all local interfaces.
     for (const addresses of Object.values(os.networkInterfaces())) {
-      for (const { cidr } of /** @type {NetworkInterfaceInfo[]} */ (
-        addresses
-      )) {
-        const net = ipaddr.parseCIDR(/** @type {string} */ (cidr));
+      for (const network of addresses ?? []) {
+        if (!network?.cidr) {
+          continue;
+        }
+
+        const net = ipaddr.parseCIDR(network.cidr);
 
         if (
           net[0] &&
@@ -504,12 +497,14 @@ class Server {
   static async getHostname(hostname) {
     if (hostname === "local-ip") {
       return (
-        Server.findIp("v4", false) || Server.findIp("v6", false) || "0.0.0.0"
+        Server.findIp("v4", false) ||
+        Server.findIp("v6", false)?.slice(1, -1) ||
+        "0.0.0.0"
       );
     } else if (hostname === "local-ipv4") {
       return Server.findIp("v4", false) || "0.0.0.0";
     } else if (hostname === "local-ipv6") {
-      return Server.findIp("v6", false) || "::";
+      return Server.findIp("v6", false)?.slice(1, -1) || "::";
     }
 
     return hostname;
@@ -2171,14 +2166,22 @@ class Server {
             '<!DOCTYPE html><html><head><meta charset="utf-8"/></head><body>',
           );
 
+          const isMultiStats =
+            typeof (/** @type {MultiStats} */ (stats).stats) !== "undefined";
+          const jsonStats = /** @type {Stats | MultiStats} */ (stats).toJson({
+            all: false,
+            children: isMultiStats,
+            assets: true,
+            publicPath: true,
+          });
+
           /**
            * @type {StatsCompilation[]}
            */
-          const statsForPrint =
-            typeof (/** @type {MultiStats} */ (stats).stats) !== "undefined"
-              ? /** @type {NonNullable<StatsCompilation["children"]>} */
-                (/** @type {MultiStats} */ (stats).toJson().children)
-              : [/** @type {Stats} */ (stats).toJson()];
+          const statsForPrint = isMultiStats
+            ? /** @type {NonNullable<StatsCompilation["children"]>} */
+              (jsonStats.children)
+            : [jsonStats];
 
           res.write("<h1>Assets Report:</h1>");
 
@@ -2411,6 +2414,11 @@ class Server {
       for (const staticOption of staticOptions) {
         for (const publicPath of staticOption.publicPath) {
           if (staticOption.serveIndex) {
+            const serveIndexMiddleware = serveIndex(
+              staticOption.directory,
+              staticOption.serveIndex,
+            );
+
             middlewares.push({
               name: "serve-index",
               path: publicPath,
@@ -2426,11 +2434,7 @@ class Server {
                   return next();
                 }
 
-                serveIndex(
-                  staticOption.directory,
-                  /** @type {ServeIndexOptions} */
-                  (staticOption.serveIndex),
-                )(req, res, next);
+                serveIndexMiddleware(req, res, next);
               },
             });
           }
@@ -2570,17 +2574,6 @@ class Server {
         });
       },
     );
-
-    /** @type {S} */
-    (this.server).on(
-      "error",
-      /**
-       * @param {Error} error error
-       */
-      (error) => {
-        throw error;
-      },
-    );
   }
 
   /**
@@ -3005,7 +2998,7 @@ class Server {
     if (this.options.bonjour) {
       const bonjourProtocol =
         /** @type {BonjourOptions} */
-        (this.options.bonjour).type || this.isTlsServer ? "https" : "http";
+        (this.options.bonjour).type || (this.isTlsServer ? "https" : "http");
 
       this.logger.info(
         `Broadcasting "${bonjourProtocol}" with subtype of "webpack" via ZeroConf DNS (Bonjour)`,
@@ -3339,10 +3332,14 @@ class Server {
    * @param {EXPECTED_ANY=} params params
    */
   sendMessage(clients, type, data, params) {
+    /** @type {string | undefined} */
+    let message;
+
     for (const client of clients) {
       // `ws` uses `WebSocket.OPEN`, which is `1`
       if (client.readyState === 1) {
-        client.send(JSON.stringify({ type, data, params }));
+        message ??= JSON.stringify({ type, data, params });
+        client.send(message);
       }
     }
   }
@@ -3514,8 +3511,18 @@ class Server {
    * @returns {Promise<void>}
    */
   async start() {
-    await this.setup();
-    await this.listen();
+    try {
+      await this.setup();
+      await this.listen();
+    } catch (error) {
+      try {
+        await this.stop();
+      } catch {
+        // Report the startup failure, not a follow-up cleanup failure.
+      }
+
+      throw error;
+    }
   }
 
   /**
@@ -3558,7 +3565,8 @@ class Server {
           socket.connect(
             { path: /** @type {string} */ (this.options.ipc) },
             () => {
-              throw new Error(`IPC "${this.options.ipc}" is already used`);
+              socket.destroy();
+              reject(new Error(`IPC "${this.options.ipc}" is already used`));
             },
           );
         })
@@ -3586,9 +3594,23 @@ class Server {
       : { host: this.options.host, port: this.options.port };
 
     await /** @type {Promise<void>} */ (
-      new Promise((resolve) => {
-        /** @type {S} */
-        (this.server).listen(listenOptions, () => {
+      new Promise((resolve, reject) => {
+        const server = /** @type {S} */ (this.server);
+
+        server.once("error", reject);
+        server.listen(listenOptions, () => {
+          server.removeListener("error", reject);
+          // Keep an `error` listener so a late failure is reported instead of
+          // crashing the process with an unhandled `error` event.
+          server.on(
+            "error",
+            /**
+             * @param {Error} error error
+             */
+            (error) => {
+              this.logger.error(error);
+            },
+          );
           resolve();
         });
       })
@@ -3748,6 +3770,8 @@ class Server {
 
     /** @type {Promise<void> | undefined} */
     let setupPromise;
+    /** @type {Promise<void> | undefined} */
+    let listenPromise;
     let inWatchMode = false;
     let listening = false;
     let stopped = false;
@@ -3787,10 +3811,12 @@ class Server {
     hooks.done.tap(pluginName, () => {
       // `done` also fires for a one-shot `compiler.run()` build, where no
       // `watchRun` ran; staying passive lets that build finish and exit.
-      if (listening || !inWatchMode) return;
+      if (listening || !inWatchMode || stopped) return;
       listening = true;
-      ensureSetup()
-        .then(() => this.listen())
+      listenPromise = ensureSetup()
+        .then(() => {
+          if (!stopped) return this.listen();
+        })
         .catch((error) => {
           this.logger.error(error);
         });
@@ -3802,6 +3828,9 @@ class Server {
     const onShutdown = async () => {
       if (stopped) return;
       stopped = true;
+      // Startup errors are reported by watchRun or the done handler above.
+      // Wait for pending startup before releasing the resources it creates.
+      await Promise.allSettled([setupPromise, listenPromise]);
       await this.stop();
     };
 
diff --git a/lib/servers/WebsocketServer.js b/lib/servers/WebsocketServer.js
index cc3f7b635b..e07b5dc1dd 100644
--- a/lib/servers/WebsocketServer.js
+++ b/lib/servers/WebsocketServer.js
@@ -29,15 +29,16 @@ export default class WebsocketServer extends BaseServer {
 
     this.implementation = new WsServer(options);
 
-    /** @type {import("http").Server} */
-    (this.server.server).on(
-      "upgrade",
+    if (isNoServerMode) {
+      const httpServer = /** @type {import("http").Server} */ (
+        this.server.server
+      );
       /**
        * @param {import("http").IncomingMessage} req request
        * @param {import("stream").Duplex} sock socket
        * @param {Buffer} head head
        */
-      (req, sock, head) => {
+      const handleUpgrade = (req, sock, head) => {
         if (!this.implementation.shouldHandle(req)) {
           return;
         }
@@ -45,8 +46,13 @@ export default class WebsocketServer extends BaseServer {
         this.implementation.handleUpgrade(req, sock, head, (connection) => {
           this.implementation.emit("connection", connection, req);
         });
-      },
-    );
+      };
+
+      httpServer.on("upgrade", handleUpgrade);
+      this.implementation.on("close", () => {
+        httpServer.removeListener("upgrade", handleUpgrade);
+      });
+    }
 
     this.implementation.on(
       "error",
diff --git a/package.json b/package.json
index 38fbb1dd59..2c3b186d88 100644
--- a/package.json
+++ b/package.json
@@ -20,6 +20,12 @@
       "default": "./lib/Server.js"
     },
     "./client/*": "./client/*",
+    "./lib/servers/BaseServer.js": {
+      "types": "./types/lib/servers/BaseServer.d.ts",
+      "import": "./lib/servers/BaseServer.js",
+      "require": "./dist/servers/BaseServer.js",
+      "default": "./lib/servers/BaseServer.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/Server.js",
diff --git a/scripts/finalize-cjs-build.mjs b/scripts/finalize-cjs-build.mjs
index ef4b61c818..6a7ea31be0 100644
--- a/scripts/finalize-cjs-build.mjs
+++ b/scripts/finalize-cjs-build.mjs
@@ -12,9 +12,8 @@ import { fileURLToPath } from "node:url";
 //    files in `dist/` as CommonJS regardless of the package's root
 //    `"type": "module"`.
 // 2. Babel emits the loader as `exports.default`. Append the `module.exports`
-//    unwrap so `require("webpack-dev-server")` returns the `Server` class
-//    directly (parity with the pre-ESM `module.exports = Server`), while
-//    `.default` keeps pointing at it for interop.
+//    unwrap so the public Server and BaseServer entrypoints return their
+//    classes directly, while `.default` keeps pointing at them for interop.
 
 const CJS_DIR = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -27,7 +26,9 @@ await writeFile(
   `${JSON.stringify({ type: "commonjs" }, null, 2)}\n`,
 );
 
-await appendFile(
-  path.join(CJS_DIR, "Server.js"),
-  "module.exports = exports.default;\nmodule.exports.default = exports.default;\n",
-);
+for (const entry of ["Server.js", "servers/BaseServer.js"]) {
+  await appendFile(
+    path.join(CJS_DIR, entry),
+    "module.exports = exports.default;\nmodule.exports.default = exports.default;\n",
+  );
+}
diff --git a/test/client/index.test.js b/test/client/index.test.js
index f659350500..bc155e067b 100644
--- a/test/client/index.test.js
+++ b/test/client/index.test.js
@@ -191,6 +191,39 @@ describe("index", () => {
     });
   });
 
+  it("should send only overlay messages accepted by a filter", () => {
+    onSocketMessage.overlay({
+      warnings: (warning) => warning === "visible warning",
+      errors: (error) => error === "visible error",
+    });
+
+    onSocketMessage.warnings(["hidden warning", "visible warning"]);
+    expect(overlay.send).toHaveBeenLastCalledWith({
+      type: "BUILD_ERROR",
+      level: "warning",
+      messages: ["visible warning"],
+    });
+
+    onSocketMessage.errors(["hidden error", "visible error"]);
+    expect(overlay.send).toHaveBeenLastCalledWith({
+      type: "BUILD_ERROR",
+      level: "error",
+      messages: ["visible error"],
+    });
+  });
+
+  it("should ignore malformed resource query parameters", async () => {
+    socket.mockReset();
+    log.setLogLevel.mockReset();
+    globalThis.__resourceQuery = "?%ZZ=x&logging=warn&overlay=%ZZ";
+
+    const indexUrl = import.meta.resolve("../../client-src/index.js");
+    await import(`${indexUrl}?t=${Date.now()}-${Math.random()}`);
+
+    expect(socket).toHaveBeenCalledTimes(1);
+    expect(log.setLogLevel).toHaveBeenCalledWith("warn");
+  });
+
   it("should parse overlay options from resource query", async () => {
     // Re-evaluate client-src/index.js fresh after mutating __resourceQuery so
     // top-level option parsing runs again.
diff --git a/test/client/overlay-lifecycle.test.js b/test/client/overlay-lifecycle.test.js
new file mode 100644
index 0000000000..9b754789df
--- /dev/null
+++ b/test/client/overlay-lifecycle.test.js
@@ -0,0 +1,97 @@
+import "../helpers/jsdom-setup.js";
+
+import { afterEach, describe, it } from "node:test";
+import { expect } from "expect";
+import { fn } from "jest-mock";
+import { createOverlay } from "../../client-src/overlay.js";
+
+const buildError = (messages) => ({
+  type: "BUILD_ERROR",
+  level: "error",
+  messages,
+});
+
+const loadOverlay = () => {
+  const iframe = document.querySelector("#webpack-dev-server-client-overlay");
+
+  expect(iframe).not.toBeNull();
+  iframe.onload();
+
+  return iframe;
+};
+
+describe("overlay lifecycle", () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    globalThis.fetch = originalFetch;
+    delete globalThis.trustedTypes;
+  });
+
+  it("renders only the latest complete message list while loading", () => {
+    const overlay = createOverlay({});
+
+    overlay.send(buildError(["first error"]));
+    overlay.send(buildError(["second error"]));
+
+    const iframe = loadOverlay();
+    const text = iframe.contentDocument.body.textContent;
+
+    expect(text).toContain("first error");
+    expect(text).toContain("second error");
+    expect(text.match(/first error/g)).toHaveLength(1);
+    expect(text.match(/second error/g)).toHaveLength(1);
+
+    overlay.send({ type: "DISMISS" });
+  });
+
+  it("discards a pending render when dismissed and supports reopening", () => {
+    const overlay = createOverlay({});
+
+    overlay.send(buildError(["stale error"]));
+    const staleIframe = document.querySelector(
+      "#webpack-dev-server-client-overlay",
+    );
+
+    overlay.send({ type: "DISMISS" });
+    expect(staleIframe.onload).toBeNull();
+    expect(document.body.contains(staleIframe)).toBe(false);
+
+    overlay.send(buildError(["current error"]));
+    const iframe = loadOverlay();
+    expect(iframe.contentDocument.body.textContent).toContain("current error");
+
+    iframe.contentDocument.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Escape" }),
+    );
+    expect(document.body.contains(iframe)).toBe(false);
+  });
+
+  it("reuses its Trusted Types policy and encodes editor paths", () => {
+    const createPolicy = fn(() => ({ createHTML: (value) => value }));
+    globalThis.trustedTypes = { createPolicy };
+    const fetchMock = fn(() => Promise.resolve());
+    globalThis.fetch = fetchMock;
+    const overlay = createOverlay({ trustedTypesPolicyName: "overlay-policy" });
+    const message = {
+      message: "broken",
+      moduleIdentifier: "src/a&b.js",
+    };
+
+    overlay.send(buildError([message]));
+    let iframe = loadOverlay();
+    iframe.contentDocument.querySelector("[data-can-open]").click();
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/webpack-dev-server/open-editor?fileName=src%2Fa%26b.js",
+    );
+
+    overlay.send({ type: "DISMISS" });
+    overlay.send(buildError([message]));
+    iframe = loadOverlay();
+
+    expect(createPolicy).toHaveBeenCalledTimes(1);
+    overlay.send({ type: "DISMISS" });
+  });
+});
diff --git a/test/client/socket-helper.test.js b/test/client/socket-helper.test.js
index a8371a5546..dd339499dc 100644
--- a/test/client/socket-helper.test.js
+++ b/test/client/socket-helper.test.js
@@ -121,4 +121,31 @@ describe("socket", () => {
     expect(typeof initializedInstance.onMessage).toBe("function");
     expect(typeof initializedInstance.onOpen).toBe("function");
   });
+
+  it("should honor a zero reconnect limit before the initial connection opens", async () => {
+    const MockClient = createMockClient();
+    const webSocketClientMock = mock.module(
+      "../../client-src/clients/WebSocketClient.js",
+      {
+        defaultExport: MockClient,
+      },
+    );
+
+    try {
+      const freshSocket = (
+        await import(
+          `../../client-src/socket.js?t=${Date.now()}-${Math.random()}`
+        )
+      ).default;
+      const close = fn();
+
+      freshSocket("my.url", { close }, 0);
+      MockClient.mock.instances[0].onClose.mock.calls[0][0]();
+
+      expect(close).toHaveBeenCalledTimes(1);
+      expect(MockClient.mock.calls).toHaveLength(1);
+    } finally {
+      webSocketClientMock.restore();
+    }
+  });
 });
diff --git a/test/client/utils/createSocketURL.test.js b/test/client/utils/createSocketURL.test.js
index 71a9c84b7b..20a4f63b11 100644
--- a/test/client/utils/createSocketURL.test.js
+++ b/test/client/utils/createSocketURL.test.js
@@ -19,6 +19,16 @@ describe("'createSocketURL' function", () => {
     ["?protocol=https:", "https://example.com", "wss://example.com/ws"],
     ["?protocol=http:", "https://example.com", "ws://example.com/ws"],
     ["?hostname=example.com", "http://example.com", "ws://example.com/ws"],
+    [
+      "?%68%6f%73%74%6e%61%6d%65=example.com&username=first+last&password=a%3Db%2Bc",
+      "http://example.com",
+      "ws://first%20last:a%3Db%2Bc@example.com/ws",
+    ],
+    [
+      "?hostname=example.com&username=user&password=a=b",
+      "http://example.com",
+      "ws://user:a%3Db@example.com/ws",
+    ],
     [
       "?username=username&password=password",
       "http://example.com",
@@ -92,6 +102,11 @@ describe("'createSocketURL' function", () => {
       "http://user:password@localhost:8080/",
       "ws://user:password@localhost:8080/ws",
     ],
+    [
+      null,
+      "http://user%40name:p%3Dword@localhost/",
+      "ws://user%40name:p%3Dword@localhost/ws",
+    ],
     [null, "https://localhost:8080", "wss://localhost:8080/ws"],
     [null, "http://127.0.0.1", "ws://127.0.0.1/ws"],
     [null, "http://127.0.0.1:8080", "ws://127.0.0.1:8080/ws"],
diff --git a/test/e2e/__snapshots__/api.test.js.snap.webpack5 b/test/e2e/__snapshots__/api.test.js.snap.webpack5
index bfe2263c6c..d72b6eac4f 100644
--- a/test/e2e/__snapshots__/api.test.js.snap.webpack5
+++ b/test/e2e/__snapshots__/api.test.js.snap.webpack5
@@ -46,7 +46,6 @@ exports[`API > Server.checkHostHeader > should allow URLs with scheme for checki
   "WebSocket connection to 'ws://test.host:8157/ws' failed: Error in connection establishment: net::ERR_NAME_NOT_RESOLVED",
   "[webpack-dev-server] JSHandle@object",
   "[webpack-dev-server] Disconnected!",
-  "[webpack-dev-server] Trying to reconnect...",
 ]
 `;
 
diff --git a/test/e2e/__snapshots__/overlay.test.js.snap.webpack5 b/test/e2e/__snapshots__/overlay.test.js.snap.webpack5
index cc27c7c873..5ae87c4454 100644
--- a/test/e2e/__snapshots__/overlay.test.js.snap.webpack5
+++ b/test/e2e/__snapshots__/overlay.test.js.snap.webpack5
@@ -45,6 +45,7 @@ exports[`overlay > should not show initially, then show on an error and allow to
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -123,7 +124,8 @@ exports[`overlay > should not show initially, then show on an error and allow to
           padding: 1rem 1rem 1.5rem;
         "
       >
-        <div
+        <button
+          type="button"
           data-can-open="true"
           style="
             color: rgb(232, 59, 70);
@@ -131,10 +133,19 @@ exports[`overlay > should not show initially, then show on an error and allow to
             margin-bottom: 1rem;
             font-family: sans-serif;
             cursor: pointer;
+            background: none;
+            border-width: medium;
+            border-style: none;
+            border-color: currentcolor;
+            border-image: none;
+            padding: 0px;
+            text-align: left;
+            display: block;
+            line-height: inherit;
           "
         >
           ERROR in ./foo.js 1:1
-        </div>
+        </button>
         <div
           style="
             line-height: 1.5;
@@ -177,6 +188,7 @@ exports[`overlay > should not show initially, then show on an error, then hide o
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -255,7 +267,8 @@ exports[`overlay > should not show initially, then show on an error, then hide o
           padding: 1rem 1rem 1.5rem;
         "
       >
-        <div
+        <button
+          type="button"
           data-can-open="true"
           style="
             color: rgb(232, 59, 70);
@@ -263,10 +276,19 @@ exports[`overlay > should not show initially, then show on an error, then hide o
             margin-bottom: 1rem;
             font-family: sans-serif;
             cursor: pointer;
+            background: none;
+            border-width: medium;
+            border-style: none;
+            border-color: currentcolor;
+            border-image: none;
+            padding: 0px;
+            text-align: left;
+            display: block;
+            line-height: inherit;
           "
         >
           ERROR in ./foo.js 1:1
-        </div>
+        </button>
         <div
           style="
             line-height: 1.5;
@@ -309,6 +331,7 @@ exports[`overlay > should not show initially, then show on an error, then show o
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -387,7 +410,8 @@ exports[`overlay > should not show initially, then show on an error, then show o
           padding: 1rem 1rem 1.5rem;
         "
       >
-        <div
+        <button
+          type="button"
           data-can-open="true"
           style="
             color: rgb(232, 59, 70);
@@ -395,10 +419,19 @@ exports[`overlay > should not show initially, then show on an error, then show o
             margin-bottom: 1rem;
             font-family: sans-serif;
             cursor: pointer;
+            background: none;
+            border-width: medium;
+            border-style: none;
+            border-color: currentcolor;
+            border-image: none;
+            padding: 0px;
+            text-align: left;
+            display: block;
+            line-height: inherit;
           "
         >
           ERROR in ./foo.js 1:1
-        </div>
+        </button>
         <div
           style="
             line-height: 1.5;
@@ -425,6 +458,7 @@ exports[`overlay > should not show initially, then show on an error, then show o
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -503,7 +537,8 @@ exports[`overlay > should not show initially, then show on an error, then show o
           padding: 1rem 1rem 1.5rem;
         "
       >
-        <div
+        <button
+          type="button"
           data-can-open="true"
           style="
             color: rgb(232, 59, 70);
@@ -511,10 +546,19 @@ exports[`overlay > should not show initially, then show on an error, then show o
             margin-bottom: 1rem;
             font-family: sans-serif;
             cursor: pointer;
+            background: none;
+            border-width: medium;
+            border-style: none;
+            border-color: currentcolor;
+            border-image: none;
+            padding: 0px;
+            text-align: left;
+            display: block;
+            line-height: inherit;
           "
         >
           ERROR in ./foo.js 1:1
-        </div>
+        </button>
         <div
           style="
             line-height: 1.5;
@@ -557,6 +601,7 @@ exports[`overlay > should show a warning after invalidation 1`] = `
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -668,6 +713,7 @@ exports[`overlay > should show a warning and error for initial compilation 1`] =
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -887,6 +933,7 @@ exports[`overlay > should show a warning and error for initial compilation and p
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -1025,6 +1072,7 @@ exports[`overlay > should show a warning and hide them after closing connection
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -1144,6 +1192,7 @@ exports[`overlay > should show a warning for initial compilation 1`] = `
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -1255,6 +1304,7 @@ exports[`overlay > should show a warning when \"client.overlay.errors\" is \"tru
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -1366,6 +1416,7 @@ exports[`overlay > should show a warning when \"client.overlay.warnings\" is \"t
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -1477,6 +1528,7 @@ exports[`overlay > should show a warning when \"client.overlay\" is \"true\" 1`]
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -1588,6 +1640,7 @@ exports[`overlay > should show an ansi formatted error for initial compilation 1
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -1710,6 +1763,7 @@ exports[`overlay > should show an error after invalidation 1`] = `
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -1821,6 +1875,7 @@ exports[`overlay > should show an error for initial compilation 1`] = `
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -1932,6 +1987,7 @@ exports[`overlay > should show an error when \"client.overlay.errors\" is \"true
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -2043,6 +2099,7 @@ exports[`overlay > should show an error when \"client.overlay.warnings\" is \"tr
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -2154,6 +2211,7 @@ exports[`overlay > should show an error when \"client.overlay\" is \"true\" 1`]
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -2440,6 +2498,7 @@ exports[`overlay > should show error when it is not filtered 1`] = `
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -2551,6 +2610,7 @@ exports[`overlay > should show overlay when Trusted Types are enabled 1`] = `
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -2662,6 +2722,7 @@ exports[`overlay > should show overlay when Trusted Types are enabled and the \"
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -2773,6 +2834,7 @@ exports[`overlay > should show overlay when \"Content-Security-Policy\" is \"def
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
@@ -2884,6 +2946,7 @@ exports[`overlay > should show warning when it is not filtered 1`] = `
 
   <iframe
     id="webpack-dev-server-client-overlay"
+    title="Webpack development server errors"
     src="about:blank"
     style="
       position: fixed;
diff --git a/test/e2e/api.test.js b/test/e2e/api.test.js
index f8928ded60..5b698de436 100644
--- a/test/e2e/api.test.js
+++ b/test/e2e/api.test.js
@@ -2,7 +2,7 @@ import path from "node:path";
 import { afterEach, beforeEach, describe, it, mock } from "node:test";
 import { fileURLToPath } from "node:url";
 import { expect } from "expect";
-import { fn } from "jest-mock";
+import { fn, spyOn } from "jest-mock";
 import webpack from "webpack";
 import Server from "../../lib/Server.js";
 import config from "../fixtures/client-config/webpack.config.js";
@@ -193,6 +193,43 @@ describe("API", () => {
       });
     });
 
+    it("should clean up initialized resources when listening fails", async () => {
+      const compiler = webpack(config);
+      const server = new Server({ port }, compiler);
+      const listenError = new Error("listen failed");
+      const listenSpy = spyOn(server, "listen").mockRejectedValue(listenError);
+      const stopSpy = spyOn(server, "stop");
+
+      await expect(server.start()).rejects.toBe(listenError);
+
+      expect(stopSpy).toHaveBeenCalledTimes(1);
+      expect(server.server).toBeUndefined();
+
+      listenSpy.mockRestore();
+      stopSpy.mockRestore();
+    });
+
+    it("should clean up initialized resources when setup fails", async () => {
+      const compiler = webpack(config);
+      const server = new Server({ port }, compiler);
+      const setupError = new Error("setup failed");
+      const close = fn((callback) => callback());
+      const setupSpy = spyOn(server, "setup").mockImplementation(async () => {
+        server.server = { close };
+        throw setupError;
+      });
+      const stopSpy = spyOn(server, "stop");
+
+      await expect(server.start()).rejects.toBe(setupError);
+
+      expect(stopSpy).toHaveBeenCalledTimes(1);
+      expect(close).toHaveBeenCalledTimes(1);
+      expect(server.server).toBeUndefined();
+
+      setupSpy.mockRestore();
+      stopSpy.mockRestore();
+    });
+
     it("should work when using configured manually", async (t) => {
       const compiler = webpack({
         ...config,
@@ -927,28 +964,25 @@ describe("API", () => {
         session.on("Network.webSocketCreated", (test) => {
           webSocketRequests.push(test);
         });
+        const webSocketClosed = new Promise((resolve) => {
+          session.once("Network.webSocketClosed", resolve);
+        });
 
         try {
           const response = await page.goto(`http://localhost:${port}/`, {
             waitUntil: "networkidle0",
           });
+          await webSocketClosed;
 
           if (!server.isValidHost(headers, "origin")) {
             throw new Error("Validation didn't fail");
           }
 
-          await new Promise((resolve) => {
-            const interval = setInterval(() => {
-              const needFinish = consoleMessages.filter((message) =>
-                /Trying to reconnect/.test(message.text()),
-              );
-
-              if (needFinish.length > 0) {
-                clearInterval(interval);
-                resolve();
-              }
-            }, 100);
-          });
+          expect(
+            consoleMessages.some((message) =>
+              /Trying to reconnect/.test(message.text()),
+            ),
+          ).toBe(false);
 
           t.assert.snapshot(webSocketRequests[0].url);
 
diff --git a/test/e2e/built-in-routes.test.js b/test/e2e/built-in-routes.test.js
index 9432839afb..544c74fe77 100644
--- a/test/e2e/built-in-routes.test.js
+++ b/test/e2e/built-in-routes.test.js
@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, it } from "node:test";
 import { expect } from "expect";
+import { spyOn } from "jest-mock";
 import webpack from "webpack";
 import Server from "../../lib/Server.js";
 import config from "../fixtures/client-config/webpack.config.js";
@@ -61,6 +62,11 @@ describe("Built in routes", () => {
     });
 
     it("should handle GET request to directory index and list all middleware directories", async (t) => {
+      const stats = await new Promise((resolve) => {
+        server.middleware.waitUntilValid(resolve);
+      });
+      const toJsonSpy = spyOn(stats, "toJson");
+
       page
         .on("console", (message) => {
           consoleMessages.push(message);
@@ -85,6 +91,14 @@ describe("Built in routes", () => {
       t.assert.snapshot(consoleMessages.map((message) => message.text()));
 
       t.assert.snapshot(pageErrors);
+
+      expect(toJsonSpy).toHaveBeenCalledWith({
+        all: false,
+        children: false,
+        assets: true,
+        publicPath: true,
+      });
+      toJsonSpy.mockRestore();
     });
 
     it("should handle HEAD request to directory index", async (t) => {
@@ -191,6 +205,11 @@ describe("Built in routes", () => {
     });
 
     it("should handle GET request to directory index and list all middleware directories", async (t) => {
+      const stats = await new Promise((resolve) => {
+        server.middleware.waitUntilValid(resolve);
+      });
+      const toJsonSpy = spyOn(stats, "toJson");
+
       page
         .on("console", (message) => {
           consoleMessages.push(message);
@@ -215,6 +234,14 @@ describe("Built in routes", () => {
       t.assert.snapshot(consoleMessages.map((message) => message.text()));
 
       t.assert.snapshot(pageErrors);
+
+      expect(toJsonSpy).toHaveBeenCalledWith({
+        all: false,
+        children: true,
+        assets: true,
+        publicPath: true,
+      });
+      toJsonSpy.mockRestore();
     });
   });
 });
diff --git a/test/e2e/host.test.js b/test/e2e/host.test.js
index 2aca81935f..dc4fc5047f 100644
--- a/test/e2e/host.test.js
+++ b/test/e2e/host.test.js
@@ -11,6 +11,31 @@ const port = portsMap.host;
 
 const ipv4 = Server.findIp("v4", false);
 const ipv6 = Server.findIp("v6", false);
+const unbracketedIpv6 = ipv6?.slice(1, -1);
+
+function getRequestHostname(host) {
+  if (host === "<not-specified>" || typeof host === "undefined") {
+    return ipv6 ? "[::1]" : ipv4 || "localhost";
+  } else if (host === "0.0.0.0") {
+    return "127.0.0.1";
+  } else if (host === "::") {
+    return "[::1]";
+  } else if (host === "::1") {
+    return "[::1]";
+  } else if (host === "local-ip") {
+    return ipv4 || ipv6 || "127.0.0.1";
+  } else if (host === "local-ipv4") {
+    return ipv4 || "127.0.0.1";
+  } else if (host === "local-ipv6") {
+    return ipv6 || "[::1]";
+  }
+
+  return host;
+}
+
+function isLocalNetworkHost(host) {
+  return host === "local-ip" || host === "local-ipv4" || host === "local-ipv6";
+}
 
 async function getAddress(host, hostname) {
   let address;
@@ -48,8 +73,12 @@ async function getAddress(host, hostname) {
         resolve();
       });
     });
+  } else if (host === "local-ip") {
+    address = ipv4 || unbracketedIpv6 || "0.0.0.0";
+  } else if (host === "local-ipv4") {
+    address = ipv4 || "0.0.0.0";
   } else if (host === "local-ipv6") {
-    address = "::";
+    address = unbracketedIpv6 || "::";
   } else {
     address = hostname;
   }
@@ -93,24 +122,7 @@ describe("host", () => {
 
       const server = new Server(devServerOptions, compiler);
 
-      let hostname = host;
-
-      if (hostname === "<not-specified>" || typeof hostname === "undefined") {
-        // If host is omitted, the server will accept connections on the unspecified IPv6 address (::) when IPv6 is available, or the unspecified IPv4 address (0.0.0.0) otherwise.
-        hostname = ipv6 ? `[${ipv6}]` : ipv4;
-      } else if (hostname === "0.0.0.0") {
-        hostname = ipv4;
-      } else if (hostname === "::") {
-        // In most operating systems, listening to the unspecified IPv6 address (::) may cause the net.Server to also listen on the unspecified IPv4 address (0.0.0.0).
-        hostname = ipv6 ? `[${ipv6}]` : ipv4;
-      } else if (hostname === "::1") {
-        hostname = "[::1]";
-      } else if (hostname === "local-ip" || hostname === "local-ipv4") {
-        hostname = ipv4;
-      } else if (hostname === "local-ipv6") {
-        // For test env where network ipv6 doesn't work
-        hostname = ipv6 ? `[${ipv6}]` : "[::1]";
-      }
+      const hostname = getRequestHostname(host);
 
       await server.start();
 
@@ -118,6 +130,13 @@ describe("host", () => {
         await getAddress(host, hostname),
       );
 
+      // Binding is the behavior under test for discovered network addresses.
+      // VPN and container interfaces are not necessarily browser-routable.
+      if (isLocalNetworkHost(host)) {
+        await server.stop();
+        return;
+      }
+
       const { page, browser } = await runBrowser();
 
       try {
@@ -165,24 +184,7 @@ describe("host", () => {
 
       const server = new Server(devServerOptions, compiler);
 
-      let hostname = host;
-
-      if (hostname === "<not-specified>" || typeof hostname === "undefined") {
-        // If host is omitted, the server will accept connections on the unspecified IPv6 address (::) when IPv6 is available, or the unspecified IPv4 address (0.0.0.0) otherwise.
-        hostname = ipv6 ? `[${ipv6}]` : ipv4;
-      } else if (hostname === "0.0.0.0") {
-        hostname = ipv4;
-      } else if (hostname === "::") {
-        // In most operating systems, listening to the unspecified IPv6 address (::) may cause the net.Server to also listen on the unspecified IPv4 address (0.0.0.0).
-        hostname = ipv6 ? `[${ipv6}]` : ipv4;
-      } else if (hostname === "::1") {
-        hostname = "[::1]";
-      } else if (hostname === "local-ip" || hostname === "local-ipv4") {
-        hostname = ipv4;
-      } else if (hostname === "local-ipv6") {
-        // For test env where network ipv6 doesn't work
-        hostname = ipv6 ? `[${ipv6}]` : "[::1]";
-      }
+      const hostname = getRequestHostname(host);
 
       await server.start();
 
@@ -190,6 +192,11 @@ describe("host", () => {
         await getAddress(host, hostname),
       );
 
+      if (isLocalNetworkHost(host)) {
+        await server.stop();
+        return;
+      }
+
       const { page, browser } = await runBrowser();
 
       try {
@@ -240,24 +247,7 @@ describe("host", () => {
 
       const server = new Server(devServerOptions, compiler);
 
-      let hostname = host;
-
-      if (hostname === "<not-specified>" || typeof hostname === "undefined") {
-        // If host is omitted, the server will accept connections on the unspecified IPv6 address (::) when IPv6 is available, or the unspecified IPv4 address (0.0.0.0) otherwise.
-        hostname = ipv6 ? `[${ipv6}]` : ipv4;
-      } else if (hostname === "0.0.0.0") {
-        hostname = ipv4;
-      } else if (hostname === "::") {
-        // In most operating systems, listening to the unspecified IPv6 address (::) may cause the net.Server to also listen on the unspecified IPv4 address (0.0.0.0).
-        hostname = ipv6 ? `[${ipv6}]` : ipv4;
-      } else if (hostname === "::1") {
-        hostname = "[::1]";
-      } else if (hostname === "local-ip" || hostname === "local-ipv4") {
-        hostname = ipv4;
-      } else if (hostname === "local-ipv6") {
-        // For test env where network ipv6 doesn't work
-        hostname = ipv6 ? `[${ipv6}]` : "[::1]";
-      }
+      const hostname = getRequestHostname(host);
 
       await server.start();
 
@@ -266,6 +256,13 @@ describe("host", () => {
       );
 
       const address = server.server.address();
+
+      if (isLocalNetworkHost(host)) {
+        delete process.env.WEBPACK_DEV_SERVER_BASE_PORT;
+        await server.stop();
+        return;
+      }
+
       const { page, browser } = await runBrowser();
 
       try {
diff --git a/test/server/find-ip.test.js b/test/server/find-ip.test.js
new file mode 100644
index 0000000000..f76ece799c
--- /dev/null
+++ b/test/server/find-ip.test.js
@@ -0,0 +1,46 @@
+import os from "node:os";
+import { describe, it } from "node:test";
+import { expect } from "expect";
+import { spyOn } from "jest-mock";
+import Server from "../../lib/Server.js";
+
+describe("Server.findIp", () => {
+  it("skips incomplete interfaces and returns the first matching address", async () => {
+    const networkInterfacesMock = spyOn(
+      os,
+      "networkInterfaces",
+    ).mockImplementation(() => ({
+      missing: undefined,
+      incomplete: [null, { address: "", cidr: null }],
+      primary: [
+        {
+          address: "192.168.1.10",
+          family: "IPv4",
+          internal: false,
+          cidr: "192.168.1.10/24",
+        },
+        {
+          address: "192.168.1.11",
+          family: "IPv4",
+          internal: false,
+          cidr: "192.168.1.11/24",
+        },
+        {
+          address: "fd00::10",
+          family: "IPv6",
+          internal: false,
+          cidr: "fd00::10/64",
+        },
+      ],
+    }));
+
+    try {
+      expect(Server.findIp("v4", false)).toBe("192.168.1.10");
+      expect(Server.findIp("v6", false)).toBe("[fd00::10]");
+      expect(Server.findIp("192.168.1.42")).toBe("192.168.1.10");
+      await expect(Server.getHostname("local-ipv6")).resolves.toBe("fd00::10");
+    } finally {
+      networkInterfacesMock.mockRestore();
+    }
+  });
+});
diff --git a/types/lib/Server.d.ts b/types/lib/Server.d.ts
index 476d53ea36..04040c2822 100644
--- a/types/lib/Server.d.ts
+++ b/types/lib/Server.d.ts
@@ -157,7 +157,9 @@ export type WebSocketServerConfiguration = {
   /**
    * type
    */
-  type?: ("ws" | string | (() => WebSocketServerConfiguration)) | undefined;
+  type?:
+    | ("ws" | string | typeof import("./servers/BaseServer.js").default)
+    | undefined;
   /**
    * options
    */
@@ -248,13 +250,14 @@ export type ClientConfiguration = {
             warnings?: OverlayMessageOptions;
             errors?: OverlayMessageOptions;
             runtimeErrors?: OverlayMessageOptions;
+            trustedTypesPolicyName?: string;
           }
       )
     | undefined;
   /**
    * progress
    */
-  progress?: boolean | undefined;
+  progress?: (boolean | "linear" | "circular") | undefined;
   /**
    * reconnect
    */

From 3a27cbb774a3ded7b5c1b9f3f98c8d8145b84ac8 Mon Sep 17 00:00:00 2001
From: Alexander Akait <sheo13666q@gmail.com>
Date: Fri, 18 Sep 2026 12:27:25 +0000
Subject: [PATCH 2/4] fix: address review on the hono example and changeset
 bump

- the example's cross-origin middleware must return early for a valid
  host, matching the built-in one; it was tagging every response with
  `Cross-Origin-Resource-Policy: same-origin`
- bump `minor`: exporting `BaseServer` adds public API

Co-authored-by: Oskar Eichler <62393985+OskarEichler@users.noreply.github.com>
---
 .changeset/fix-client-and-server-defects.md | 2 +-
 examples/app/hono/README.md                 | 6 +++++-
 examples/app/hono/webpack.config.js         | 6 +++++-
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/.changeset/fix-client-and-server-defects.md b/.changeset/fix-client-and-server-defects.md
index dbe1bdd06f..04e996c606 100644
--- a/.changeset/fix-client-and-server-defects.md
+++ b/.changeset/fix-client-and-server-defects.md
@@ -1,5 +1,5 @@
 ---
-"webpack-dev-server": patch
+"webpack-dev-server": minor
 ---
 
 Fix client progress modes, socket URL credentials, overlay and progress lifecycles, server startup error handling and local IP lookup; export `BaseServer`.
diff --git a/examples/app/hono/README.md b/examples/app/hono/README.md
index 378db68a8c..b9ed33bed9 100644
--- a/examples/app/hono/README.md
+++ b/examples/app/hono/README.md
@@ -29,8 +29,12 @@ export default {
         const headers = context.env.incoming.headers;
         const headerName = headers[":authority"] ? ":authority" : "host";
 
+        if (devServer.isValidHost(headers, headerName, false)) {
+          await next();
+          return;
+        }
+
         if (
-          !devServer.isValidHost(headers, headerName, false) &&
           headers["sec-fetch-mode"] === "no-cors" &&
           headers["sec-fetch-site"] === "cross-site"
         ) {
diff --git a/examples/app/hono/webpack.config.js b/examples/app/hono/webpack.config.js
index 0dc9e34625..ff561e3c1f 100644
--- a/examples/app/hono/webpack.config.js
+++ b/examples/app/hono/webpack.config.js
@@ -36,8 +36,12 @@ export default setup(
             const headers = context.env.incoming.headers;
             const headerName = headers[":authority"] ? ":authority" : "host";
 
+            if (devServer.isValidHost(headers, headerName, false)) {
+              await next();
+              return;
+            }
+
             if (
-              !devServer.isValidHost(headers, headerName, false) &&
               headers["sec-fetch-mode"] === "no-cors" &&
               headers["sec-fetch-site"] === "cross-site"
             ) {

From d0dba66868294a03b49271b0f4c401e1e030ecd1 Mon Sep 17 00:00:00 2001
From: Alexander Akait <sheo13666q@gmail.com>
Date: Fri, 18 Sep 2026 12:55:48 +0000
Subject: [PATCH 3/4] test: cover the client fixes in a real browser
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six puppeteer cases, each verified to fail against main's client:

- linear progress renders a 4px green bar (main: 0px — the rules were
  keyed on `#bar`, which no template emits) and reports itself enabled
  in the startup banner (main: "Progress disabled")
- circular progress renders the ring and its ARIA state
- the indicator comes back on a later rebuild instead of staying faded
- Escape dismisses a second overlay: `invalid` fires a DISMISS on every
  rebuild, so on main the first fix-then-break cycle tore down the key
  handler for the rest of the session
- the overlay reopens under an enforced `trusted-types` policy name,
  where asking for the same name twice is a TypeError
- a warning filter decides what the overlay renders, not just whether
  it opens

Co-authored-by: Oskar Eichler <62393985+OskarEichler@users.noreply.github.com>
---
 test/e2e/overlay.test.js  | 158 ++++++++++++++++++++++++++++++
 test/e2e/progress.test.js | 197 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 355 insertions(+)

diff --git a/test/e2e/overlay.test.js b/test/e2e/overlay.test.js
index 0861c62771..a175beec83 100644
--- a/test/e2e/overlay.test.js
+++ b/test/e2e/overlay.test.js
@@ -1906,4 +1906,162 @@ describe("overlay", () => {
       await server.stop();
     }
   });
+
+  it("should allow dismissing with Escape more than once", async () => {
+    const compiler = webpack(config);
+    const server = new Server({ port }, compiler);
+
+    await server.start();
+
+    const { page, browser } = await runBrowser();
+
+    try {
+      await page.goto(`http://localhost:${port}/`, {
+        waitUntil: "networkidle0",
+      });
+
+      fs.writeFileSync(pathToOverlayFixture, "`;");
+      await page.waitForSelector("#webpack-dev-server-client-overlay");
+
+      await page.keyboard.press("Escape");
+      await page.waitForSelector("#webpack-dev-server-client-overlay", {
+        hidden: true,
+      });
+
+      fs.writeFileSync(pathToOverlayFixture, overlayFixtureCode);
+      await delay(1000);
+      fs.writeFileSync(pathToOverlayFixture, "`;");
+      await page.waitForSelector("#webpack-dev-server-client-overlay");
+
+      // Dismissing used to remove the key handler for good, so the second
+      // overlay of a session could not be closed with the keyboard at all.
+      await page.keyboard.press("Escape");
+      await page.waitForSelector("#webpack-dev-server-client-overlay", {
+        hidden: true,
+      });
+
+      expect(await page.$("#webpack-dev-server-client-overlay")).toBeNull();
+
+      fs.writeFileSync(pathToOverlayFixture, overlayFixtureCode);
+    } finally {
+      await browser.close();
+      await server.stop();
+    }
+  });
+
+  it("should reopen when a Trusted Types policy name is enforced", async () => {
+    const compiler = webpack(trustedTypesConfig);
+    const server = new Server(
+      {
+        port,
+        headers: [
+          {
+            key: "Content-Security-Policy",
+            // Without `allow-duplicates`, asking for a policy name twice is a
+            // TypeError, so the overlay must keep the one it already made.
+            value: "trusted-types webpack webpack#dev-overlay",
+          },
+        ],
+        client: {
+          overlay: { trustedTypesPolicyName: "webpack#dev-overlay" },
+        },
+      },
+      compiler,
+    );
+
+    await server.start();
+
+    const { page, browser } = await runBrowser();
+
+    try {
+      const pageErrors = [];
+
+      page.on("pageerror", (error) => {
+        pageErrors.push(error);
+      });
+
+      await page.goto(`http://localhost:${port}/`, {
+        waitUntil: "networkidle0",
+      });
+
+      fs.writeFileSync(pathToOverlayFixture, "`;");
+      await page.waitForSelector("#webpack-dev-server-client-overlay");
+
+      await page.keyboard.press("Escape");
+      await page.waitForSelector("#webpack-dev-server-client-overlay", {
+        hidden: true,
+      });
+
+      fs.writeFileSync(pathToOverlayFixture, overlayFixtureCode);
+      await delay(1000);
+      fs.writeFileSync(pathToOverlayFixture, "`;");
+
+      await page.waitForSelector("#webpack-dev-server-client-overlay");
+
+      const overlayHandle = await page.$("#webpack-dev-server-client-overlay");
+      const overlayFrame = await overlayHandle.contentFrame();
+
+      expect(
+        await overlayFrame.evaluate(() => document.body.textContent),
+      ).toContain("Compiled with problems");
+      expect(
+        pageErrors.filter((error) =>
+          /trusted type policy/i.test(error.message),
+        ),
+      ).toHaveLength(0);
+
+      fs.writeFileSync(pathToOverlayFixture, overlayFixtureCode);
+    } finally {
+      await browser.close();
+      await server.stop();
+    }
+  });
+
+  it("should render only the overlay messages a filter accepts", async () => {
+    const compiler = webpack(config);
+
+    new WarningPlugin("Shown warning").apply(compiler);
+    new WarningPlugin("Hidden warning").apply(compiler);
+
+    const server = new Server(
+      {
+        port,
+        client: {
+          overlay: {
+            warnings: (error) => {
+              const message = typeof error === "string" ? error : error.message;
+              return message !== "Hidden warning";
+            },
+          },
+        },
+      },
+      compiler,
+    );
+
+    await server.start();
+
+    const { page, browser } = await runBrowser();
+
+    try {
+      await page.goto(`http://localhost:${port}/`, {
+        waitUntil: "networkidle0",
+      });
+
+      await page.waitForSelector("#webpack-dev-server-client-overlay");
+
+      const overlayHandle = await page.$("#webpack-dev-server-client-overlay");
+      const overlayFrame = await overlayHandle.contentFrame();
+      const overlayText = await overlayFrame.evaluate(
+        () => document.body.textContent,
+      );
+
+      expect(overlayText).toContain("Shown warning");
+      // The filter used to decide only whether to open the overlay; every
+      // message was then rendered, filtered out or not.
+      expect(overlayText).not.toContain("Hidden warning");
+    } finally {
+      await browser.close();
+      await server.stop();
+    }
+  });
 });
diff --git a/test/e2e/progress.test.js b/test/e2e/progress.test.js
index c6d7d4dfa3..4a151d908d 100644
--- a/test/e2e/progress.test.js
+++ b/test/e2e/progress.test.js
@@ -17,6 +17,73 @@ const cssFilePath = path.resolve(
   "../fixtures/reload-config-2/main.css",
 );
 
+// Drives the `wds-progress` element the client created and reads back what the
+// browser actually renders for the inner indicator.
+const readIndicator = (page, percent) =>
+  page.evaluate((value) => {
+    const host = document.querySelector("wds-progress");
+
+    host.setAttribute("progress", String(value));
+
+    const element = host.shadowRoot.querySelector("#progress");
+    const style = getComputedStyle(element);
+
+    return {
+      type: host.getAttribute("type"),
+      role: host.getAttribute("role"),
+      // cspell:ignore valuenow
+      ariaValueNow: host.getAttribute("aria-valuenow"),
+      classes: [...element.classList],
+      width: style.width,
+      height: style.height,
+      backgroundColor: style.backgroundColor,
+      display: style.display,
+      percentText: host.shadowRoot.querySelector("#percent-value")?.textContent,
+    };
+  }, percent);
+
+/**
+ * @param {import("puppeteer").Page} page page
+ * @param {"linear" | "circular"} type progress type
+ * @returns {Promise<() => Promise<void>>} triggers one rebuild and waits for it
+ */
+async function setupRebuilds(page, type) {
+  let hotUpdates = 0;
+
+  page.on("request", (interceptedRequest) => {
+    if (interceptedRequest.isInterceptResolutionHandled()) return;
+
+    if (/\.hot-update\.(json|js)$/.test(interceptedRequest.url())) {
+      hotUpdates += 1;
+    }
+  });
+
+  await page.goto(`http://localhost:${port}/`, { waitUntil: "networkidle0" });
+
+  let color = 0;
+
+  return async () => {
+    const seen = hotUpdates;
+
+    color += 1;
+    fs.writeFileSync(
+      cssFilePath,
+      `body { background-color: rgb(${color}, 0, 0); }`,
+    );
+
+    await new Promise((resolve) => {
+      const timer = setInterval(() => {
+        if (hotUpdates > seen) {
+          clearInterval(timer);
+          resolve();
+        }
+      }, 100);
+    });
+
+    await page.waitForSelector(`wds-progress[type="${type}"]`);
+  };
+}
+
 describe("progress", () => {
   it("should work and log progress in a browser console", async () => {
     fs.writeFileSync(cssFilePath, "body { background-color: rgb(0, 0, 255); }");
@@ -87,4 +154,134 @@ describe("progress", () => {
       await server.stop();
     }
   });
+
+  it('should render a visible bar when "progress" is "linear"', async () => {
+    fs.writeFileSync(cssFilePath, "body { background-color: rgb(0, 0, 255); }");
+
+    const compiler = webpack(reloadConfig);
+    const server = new Server(
+      { port, client: { progress: "linear" } },
+      compiler,
+    );
+
+    await server.start();
+
+    const { page, browser } = await runBrowser();
+
+    try {
+      const consoleMessages = [];
+
+      page.on("console", (message) => {
+        consoleMessages.push(message.text());
+      });
+
+      const rebuild = await setupRebuilds(page, "linear");
+
+      await rebuild();
+
+      // The resource query only recognized "true", so a visual mode was
+      // reported as disabled until the socket resent it.
+      expect(
+        consoleMessages.find((message) => /Server started:/.test(message)),
+      ).toContain("Progress enabled");
+
+      const running = await readIndicator(page, 40);
+
+      expect(running.type).toBe("linear");
+      expect(running.classes).not.toContain("hidden");
+      // The linear rules used to be keyed on `#bar`, which no template emits,
+      // so the element rendered with no size and no color at all.
+      expect(running.height).toBe("4px");
+      expect(running.backgroundColor).toBe("rgb(186, 223, 172)");
+      expect(running.width).not.toBe("0px");
+      expect(running.role).toBe("progressbar");
+      expect(running.ariaValueNow).toBe("40");
+
+      const done = await readIndicator(page, 100);
+
+      expect(done.ariaValueNow).toBe("100");
+      expect(done.classes).toContain("disappear");
+    } finally {
+      await browser.close();
+      fs.unlinkSync(cssFilePath);
+      await server.stop();
+    }
+  });
+
+  it('should render a ring when "progress" is "circular"', async () => {
+    fs.writeFileSync(cssFilePath, "body { background-color: rgb(0, 0, 255); }");
+
+    const compiler = webpack(reloadConfig);
+    const server = new Server(
+      { port, client: { progress: "circular" } },
+      compiler,
+    );
+
+    await server.start();
+
+    const { page, browser } = await runBrowser();
+
+    try {
+      const rebuild = await setupRebuilds(page, "circular");
+
+      await rebuild();
+
+      const running = await readIndicator(page, 60);
+
+      expect(running.type).toBe("circular");
+      expect(running.role).toBe("progressbar");
+      expect(running.ariaValueNow).toBe("60");
+      expect(running.percentText).toBe("60");
+      expect(running.classes).not.toContain("hidden");
+      expect(running.display).not.toBe("none");
+    } finally {
+      await browser.close();
+      fs.unlinkSync(cssFilePath);
+      await server.stop();
+    }
+  });
+
+  it("should show the indicator again on a later rebuild", async () => {
+    fs.writeFileSync(cssFilePath, "body { background-color: rgb(0, 0, 255); }");
+
+    const compiler = webpack(reloadConfig);
+    const server = new Server(
+      { port, client: { progress: "linear" } },
+      compiler,
+    );
+
+    await server.start();
+
+    const { page, browser } = await runBrowser();
+
+    try {
+      const rebuild = await setupRebuilds(page, "linear");
+
+      await rebuild();
+
+      // Completing a build leaves the fade-out running; the next build has to
+      // clear it, or the indicator stays invisible for the rest of the session.
+      await readIndicator(page, 100);
+
+      const restarted = await readIndicator(page, 10);
+
+      expect(restarted.classes).not.toContain("disappear");
+      expect(restarted.classes).not.toContain("hidden");
+      expect(restarted.display).not.toBe("none");
+      expect(
+        await page.evaluate(
+          () =>
+            getComputedStyle(
+              document
+                .querySelector("wds-progress")
+                .shadowRoot.querySelector("#progress"),
+            ).opacity,
+        ),
+      ).toBe("1");
+    } finally {
+      await browser.close();
+      fs.unlinkSync(cssFilePath);
+      await server.stop();
+    }
+  });
 });

From 9191d4adc4a9611ed4b1cf8ec99675ee5e6489f0 Mon Sep 17 00:00:00 2001
From: Alexander Akait <sheo13666q@gmail.com>
Date: Fri, 18 Sep 2026 12:58:53 +0000
Subject: [PATCH 4/4] test: stop the heartbeat case racing its own compilation

The 100ms sweep terminates a client that has not ponged yet, and a
compilation can block the event loop for longer than that, so a healthy
client was dropped before the `ok` stats message reached it. Seen on the
macOS Node 24 shard; the same file was stabilized for neighbouring races
in #5733. Wait for the build to settle before connecting.

Co-authored-by: Oskar Eichler <62393985+OskarEichler@users.noreply.github.com>
---
 test/e2e/web-socket-communication.test.js | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/test/e2e/web-socket-communication.test.js b/test/e2e/web-socket-communication.test.js
index 16cf6affd7..6e5989eb47 100644
--- a/test/e2e/web-socket-communication.test.js
+++ b/test/e2e/web-socket-communication.test.js
@@ -173,6 +173,13 @@ describe("web socket communication", () => {
 
     await server.start();
 
+    // The sweep terminates a client that has not ponged within 100ms, and a
+    // compilation can block the event loop for longer than that, so let the
+    // build settle before connecting rather than racing it.
+    await new Promise((resolve) => {
+      server.middleware.waitUntilValid(resolve);
+    });
+
     server.webSocketServer.heartbeatInterval = 100;
 
     let opened = false;