webpack 5.111.0 → 5.111.1

package/lib/prefetch/ResourceHintPlugin.js

@@ -385,10 +385,9 @@ const collectEntrypointHints = (compilation, entryName, hints) => {
 		if (dep.fetchPriority) h.fetchPriority = dep.fetchPriority;
 		push(h);
 	}
-	// `hostType`: `"html"` iff the entrypoint has an extracted HTML page
-	// (any `HtmlEntryDependency` with elementKind `script`/`script-module` on
-	// any HTML module points at this entryName); SSR frameworks reading
-	// `stats.entrypoints[name].resourceHints` see `"js"`.
+	// `hostType` is `"html"` only where the entrypoint has an extracted page, that
+	// is where some HTML module's script dependency names this entry. An SSR
+	// framework reading the stats sees `"js"`.
 	let hostType = /** @type {"html" | "js"} */ ("js");
 
 	outer: for (const module of compilation.modules) {
@@ -737,15 +736,14 @@ class ResourceHintPlugin {
 		const hints = this._hints;
 
 		compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
-			// Lazy-computed on first access — walk every HTML module's
-			// `HtmlEntryDependency`s, resolve each named entry, and collect
-			// every URL asset dep target reachable from its ordered chunks.
-			// One pass produces two views: a per-entry list (consumed by
-			// `HtmlEntryDependency.Template` to emit `<link>` tags) and a
-			// global `WeakSet` (consumed by `StartupAssetHintRuntimeModule`
-			// to skip the JS runtime `<link>` for the same asset).
-			// Deterministic (module graph is fixed by seal time) and cheap
-			// (only fires when a JS chunk actually produces hints).
+			// WHY: computed on first access. One walk of every HTML module's
+			// `HtmlEntryDependency`s — resolving each named entry and collecting every
+			// URL asset dep reachable from its ordered chunks — yields both views: a
+			// per-entry list, which `HtmlEntryDependency.Template` emits the `<link>`
+			// tags from, and a global `WeakSet`, which `StartupAssetHintRuntimeModule`
+			// reads to skip the JS runtime `<link>` for the same asset. Deterministic,
+			// the module graph being fixed by seal time, and cheap, since it only fires
+			// when a JS chunk actually produces hints.
 			/** @type {Map<string, HtmlHintedAsset[]> | undefined} */
 			let perEntry;
 			/** @type {WeakSet<Module> | undefined} */
@@ -773,10 +771,9 @@ class ResourceHintPlugin {
 						}
 						const entrypoint = compilation.entrypoints.get(dep.entryName);
 						if (!entrypoint) continue;
-						// Mirror `getEntrypointChunksInLoadOrder`: entry chunk +
-						// runtime chunk + all initial siblings (`entrypoint.chunks`
-						// includes splitChunks output). Async `import()` chunks
-						// stay on the on-demand runtime and are NOT HTML-hinted.
+						// Mirrors `getEntrypointChunksInLoadOrder`: the entry, runtime and
+						// every initial sibling. An async `import()` chunk stays on the
+						// on-demand runtime and is never HTML-hinted.
 						/** @type {Set<import("../Chunk")>} */
 						const chunks = new Set(entrypoint.chunks);
 						const entry = entrypoint.getEntrypointChunk();
@@ -864,10 +861,9 @@ class ResourceHintPlugin {
 					});
 			}
 
-			// SSR manifest: serialize each entrypoint's resolved hints to a JSON
-			// asset (the same descriptors as `stats.entrypoints[].resourceHints`)
-			// so an SSR server can inject the `<link>` tags itself. `"none"`
-			// yields empty lists (via `collectEntrypointHints`).
+			// The SSR manifest serializes each entrypoint's resolved hints to a JSON
+			// asset, the same descriptors the stats carry, so an SSR server can inject
+			// the tags itself. `"none"` yields empty lists.
 			const rhOptions = compilation.outputOptions.resourceHints;
 			const manifestPath = rhOptions && rhOptions.manifest;
 			if (manifestPath) {

package/lib/prefetch/StartupAssetHintRuntimeModule.js

@@ -47,16 +47,13 @@ class StartupAssetHintRuntimeModule extends RuntimeModule {
 		const compilation = /** @type {Compilation} */ (this.compilation);
 		const lines = this._lines;
 		if (lines.length === 0) return null;
-		// `__webpack_nonce__` set inside the entry module is too late — the
-		// entry hasn't run yet. Read the nonce off the `<script>` tag that
-		// loaded the bundle, so prefetch / preload links match a CSP that
-		// demands the same nonce as the script.
-		//
-		// - For classic script output, `document.currentScript` is the
-		//   loading `<script>` element while the runtime executes.
-		// - For ESM output (`output.module: true`), `document.currentScript`
-		//   is `null`; locate the loading `<script type="module">` by
-		//   matching `script.src` against `import.meta.url`.
+		// `__webpack_nonce__` set in the entry module comes too late, the entry not
+		// having run, so the nonce is read off the `<script>` that loaded the bundle
+		// and the links match a CSP demanding the script's own.
+
+		// Classic output finds it on `document.currentScript`. ESM output leaves that
+		// null, so the loading `<script type="module">` is found by matching its
+		// `src` against `import.meta.url`.
 		const { module: isModule, importMetaName } = compilation.outputOptions;
 		const nonceSetup = isModule
 			? [

package/lib/runtime/AsyncModuleRuntimeModule.js

@@ -239,11 +239,9 @@ class AsyncModuleRuntimeModule extends HelperRuntimeModule {
 						}`,
 						"err"
 					)}`,
-					// Track the async body's whole lifetime (evaluating +
-					// evaluating-async states) with a dedicated flag — the sync require
-					// wrapper clears `module.evaluating` as soon as `.a` returns, so a
-					// deferred namespace reaching this module through a cycle relies on
-					// `evaluatingAsync` to keep throwing until it is fully evaluated.
+					// The sync require wrapper clears `module.evaluating` the moment `.a`
+					// returns, so a deferred namespace reaching this module through a cycle
+					// needs `evaluatingAsync` to keep throwing until evaluation ends.
 					defer ? "module.evaluatingAsync = true;" : "",
 					"body(handle, done);",
 					`${runtimeTemplate.optionalChaining("queue", "d < 0")} && (queue.d = 0);`

package/lib/runtime/GetChunkFilenameRuntimeModule.js

@@ -105,10 +105,9 @@ class GetChunkFilenameRuntimeModule extends RuntimeModule {
 			return length ? hash.slice(0, length) : hash;
 		};
 
-		// `[fullhash:<digest>]`/`[hash:<digest>]` would resolve to a runtime
-		// `getFullHash()` expression that can't be re-encoded; instead this module is
-		// flagged `fullHash` and re-rendered after hashing, so we inline the
-		// re-encoded full hash here — byte-identical to the statically emitted file.
+		// A digest cannot be re-encoded from the runtime `getFullHash()` expression,
+		// so this module is flagged `fullHash` and re-rendered after hashing: the
+		// inlined value is byte-identical to the statically emitted file.
 		/** @type {HashWithDigestFunction} */
 		const fullHashWithDigest = (digest, length) => {
 			const fullHash = compilation.fullHash;

package/lib/runtime/GlobalRuntimeModule.js

@@ -62,10 +62,8 @@ class GlobalRuntimeModule extends RuntimeModule {
 					"if (typeof window === 'object') return window;"
 				),
 				"}"
-				// It can still be `undefined`, but nothing to do about it...
-				// We return `undefined`, instead of nothing here, so it's
-				// easier to handle this case:
-				//   if (!global) { … }
+				// It can still be `undefined`, and nothing here can help that. Returning
+				// `undefined` rather than nothing keeps `if (!global)` working.
 			]),
 			"})();"
 		]);

package/lib/runtime/MakeDeferredNamespaceObjectRuntime.js

@@ -263,11 +263,9 @@ class MakeOptimizedDeferredNamespaceObjectRuntimeModule extends HelperRuntimeMod
 				Template.indent([
 					"get a() {",
 					Template.indent([
-						// Forcing evaluation of a module that is currently evaluating
-						// (a cycle reached through a deferred import) must throw rather
-						// than expose its partial exports. `syncDeps` (present only for
-						// cyclic deferred modules) carries the transitive static closure,
-						// so an evaluating dependency is caught before any evaluation.
+						// Forcing a module that is already evaluating, a cycle reached
+						// through a deferred import, must throw rather than expose partial
+						// exports. `syncDeps` carries the closure that catches it first.
 						`${cst} cachedModule = __webpack_module_cache__[moduleId];`,
 						'if (cachedModule !== undefined && (cachedModule.evaluating || cachedModule.evaluatingAsync)) throw new TypeError("Cannot access a deferred module namespace while the module is being evaluated");',
 						"if (syncDeps) for (var i = 0; i < syncDeps.length; i++) {",
@@ -354,28 +352,20 @@ class MakeDeferredNamespaceObjectRuntimeModule extends HelperRuntimeModule {
 		return `${fn} = ${runtimeTemplate.basicFunction(
 			"moduleId, mode, exportNames",
 			[
-				// Per the TC39 import-defer spec, deferred namespaces are
-				// distinct from their eager counterparts and the same module
-				// referenced from multiple defer-import sites must yield the
-				// same object. Cache the Proxy / fake namespace per-moduleId so
-				// repeated calls (including across files) share identity.
+				// WHY: the TC39 import-defer spec makes a deferred namespace distinct
+				// from its eager counterpart, and one module reached from several defer
+				// sites must yield the same object, so the Proxy is cached per moduleId.
 				//
-				// Bit 16 (`createFakeNamespaceObject`'s "return value when
-				// it's Promise-like" flag added by
-				// `RuntimeTemplate.moduleNamespacePromise` for dynamic
-				// imports) is irrelevant for deferred namespaces — the value
-				// passed into `createFakeNamespaceObject` here is always the
-				// resolved module exports (after unwrapping the async-module
-				// export symbol when present), never a Promise. Strip it
-				// once so all downstream behavior, the cache key, and the
-				// `createFakeNamespaceObject` call below see the same shape
-				// mode. This keeps static defer (mode 8) and dynamic
-				// `await import.defer` (mode 8 | 16) sharing the same
-				// Deferred Module Namespace object, while still keying by
-				// `(moduleId, mode)` so distinct exports-type shapes
-				// (e.g. one importer treats a CJS module as
-				// "default-with-named", another as "namespace") get
-				// distinct cache entries.
+				// Bit 16 is `createFakeNamespaceObject`'s "return value when it's
+				// Promise-like" flag, which `RuntimeTemplate.moduleNamespacePromise` adds
+				// for a dynamic import. It is irrelevant here: what is passed in is
+				// always the resolved module exports, after unwrapping the async-module
+				// export symbol where there is one, and never a Promise. Stripping it
+				// once leaves the cache key, the call below and everything downstream on
+				// one shape mode, so static defer (mode 8) and `await import.defer`
+				// (mode 8 | 16) share the same object. The key stays `(moduleId, mode)`
+				// so two importers reading one CJS module differently — as
+				// "default-with-named" against "namespace" — still get distinct entries.
 				"mode &= ~16;",
 				// Only a real ES module namespace has the spec's exotic shape; a
 				// synthesized one (JSON, asset, CommonJS interop) keeps the old form.
@@ -417,23 +407,16 @@ class MakeDeferredNamespaceObjectRuntimeModule extends HelperRuntimeModule {
 						? "if (mode & 8 || mode & 4 && ns.__esModule && typeof ns === 'object') {"
 						: "",
 					Template.indent([
-						// Drop only the read-side traps after init: with the
-						// resolved namespace's own keys mirrored onto
-						// `ns_target` below, the default `Reflect` behavior
-						// returns the right values via the live-binding
-						// getters, so we no longer need to intercept `get` /
-						// `has` / `ownKeys` / `getOwnPropertyDescriptor`.
-						//
-						// The mutation traps (`set`, `deleteProperty`,
-						// `defineProperty`) are kept because per the TC39
-						// import-defer spec, `[[Set]]` / `[[Delete]]` /
-						// `[[DefineOwnProperty]]` on a Deferred Module
-						// Namespace Exotic Object never succeed — and the
-						// proxy target itself remains extensible
-						// (architecturally we cannot freeze it up-front),
-						// so without these traps `ns.notExported = "x"`
-						// after evaluation would silently create a property
-						// on the target instead of returning false.
+						// Drop only the read traps after init: with the namespace's own keys
+						// mirrored onto `ns_target`, default `Reflect` behavior already
+						// returns the right values through the live-binding getters.
+
+						// WHY: the spec makes `[[Set]]`, `[[Delete]]` and
+						// `[[DefineOwnProperty]]` on a Deferred Module Namespace always
+						// fail, yet the target stays extensible because it cannot be frozen
+						// up front — so without the mutation traps `ns.notExported = "x"`
+						// would silently create a property instead of returning false.
+
 						// A sealed target holds placeholder values, so the read traps stay to
 						// keep the live bindings visible.
 						sealed && synthesized ? "if (!exportNames) {" : "",
@@ -454,18 +437,12 @@ class MakeDeferredNamespaceObjectRuntimeModule extends HelperRuntimeModule {
 							])
 						: "",
 					synthesized ? "}" : "",
-					// Mirror own properties from the resolved namespace onto the proxy
-					// target so that proxy invariants hold for callers that structurally
-					// introspect via `Object.keys` / `Object.getOwnPropertyNames` /
-					// `Object.getOwnPropertyDescriptor`: when our trap reports a
-					// non-configurable descriptor for a key, the target must also have
-					// that key with a matching descriptor.
-					//
-					// `__esModule` and `Symbol.toStringTag` are intentionally skipped:
-					// the proxy synthesizes "Deferred Module" / true regardless of what
-					// the underlying namespace exposes (per the TC39 import-defer
-					// proposal, the [[StringTag]] of a Deferred Module Namespace
-					// Exotic Object is "Deferred Module"), and the target was already
+					// Mirror the resolved namespace's own properties onto the target, or
+					// the proxy invariants break: where a trap reports a non-configurable
+					// descriptor, the target must carry a matching one.
+
+					// `__esModule` and `Symbol.toStringTag` are skipped: the proxy
+					// synthesizes them whatever the namespace exposes, and the target is
 					// pre-populated with those values below.
 					synthesized
 						? `${cst} keys = ${sealed ? "exportNames ? [] : " : ""}Reflect.ownKeys(ns);`
@@ -485,23 +462,23 @@ class MakeDeferredNamespaceObjectRuntimeModule extends HelperRuntimeModule {
 					synthesized ? "}" : ""
 				])};`,
 				"",
-				// The proxy target is a fresh placeholder, separate from
-				// `__webpack_module_deferred_exports__[moduleId]` (which is reused
-				// by `__webpack_require__` as `module.exports` for deferred-loaded
-				// modules and would conflict with our pre-populated synthetic
-				// `__esModule` / `Symbol.toStringTag` non-configurable properties).
-				// Using a dedicated target keeps the proxy invariant-compliant
-				// without interfering with the module's own exports object.
+				// WHY: the proxy target is a fresh placeholder, separate from
+				// `__webpack_module_deferred_exports__[moduleId]`, which
+				// `__webpack_require__` reuses as `module.exports` for a deferred-loaded
+				// module and would conflict with the pre-populated synthetic `__esModule`
+				// and `Symbol.toStringTag` non-configurable properties. A dedicated
+				// target keeps the proxy invariant-compliant without interfering with the
+				// module's own exports object.
 				`${cst} ns_target = { __proto__: null };`,
 				// With the export list known at build time the target carries the spec's
 				// keys and is sealed, so `[[IsExtensible]]` is false up front.
 				sealed
 					? `${synthesized ? "if (exportNames) " : ""}for (var e = 0; e < exportNames.length; e++) ns_target[exportNames[e]] = undefined;`
 					: "",
-				// Pre-populate the synthetic deferred-namespace properties with
-				// fully non-configurable, non-writable, non-enumerable descriptors
-				// (matching the TC39 import-defer spec for Module Namespace
-				// Exotic Objects). The trap returns the same descriptors below.
+				// Pre-populate the synthetic properties with the non-configurable,
+				// non-writable, non-enumerable descriptors the spec gives a Module
+				// Namespace, which the trap below returns unchanged.
+
 				// `__esModule` is not one of the spec's keys, so a sealed namespace omits
 				// it; the synthesized form keeps it for interop.
 				synthesized
@@ -515,12 +492,9 @@ class MakeDeferredNamespaceObjectRuntimeModule extends HelperRuntimeModule {
 				`${cst} handler = {`,
 				Template.indent([
 					"__proto__: null,",
-					// Per the TC39 import-defer proposal, `IsSymbolLikeNamespaceKey`
-					// returns true for any Symbol-keyed access (and for "then"); such
-					// accesses go through `OrdinaryGetOwnProperty` and must not
-					// trigger evaluation of the deferred module. The Symbol checks
-					// below short-circuit to the pre-populated target without
-					// running `init()`.
+					// `IsSymbolLikeNamespaceKey` holds for any Symbol key and for `then`,
+					// and such a read must not evaluate the deferred module, so the checks
+					// below reach the pre-populated target without running `init()`.
 					`${runtimeTemplate.method("get", "_, name", [
 						"switch (name) {",
 						Template.indent([
@@ -589,10 +563,9 @@ class MakeDeferredNamespaceObjectRuntimeModule extends HelperRuntimeModule {
 					`${runtimeTemplate.method("getOwnPropertyDescriptor", "_, name", [
 						"switch (name) {",
 						Template.indent([
-							// Match the descriptors actually defined on `ns_target`
-							// (non-configurable, non-writable, non-enumerable) so the
-							// proxy invariant holds for both the trap result and any
-							// post-init forwarding via the deleted-handler path.
+							// Match the descriptors actually defined on `ns_target`, so the
+							// proxy invariant holds both for this result and for the
+							// post-init forwarding through the deleted-handler path.
 							synthesized
 								? `case "__esModule": ${sealed ? "if (!exportNames) " : ""}return { value: true, writable: false, enumerable: false, configurable: false };${sealed ? " break;" : ""}`
 								: "",
@@ -617,20 +590,17 @@ class MakeDeferredNamespaceObjectRuntimeModule extends HelperRuntimeModule {
 						synthesized ? "}" : "",
 						synthesized ? "return desc;" : ""
 					])},`,
-					// `defineProperty` always rejects, but per the TC39 spec it
-					// must still trigger evaluation for string keys (the spec
-					// algorithm calls `[[GetOwnProperty]]` first, which forces
-					// evaluation on a deferred namespace). Symbol keys go through
-					// OrdinaryDefineOwnProperty and do not trigger eval.
+					// `defineProperty` always rejects, yet must still evaluate on a string
+					// key, since the spec calls `[[GetOwnProperty]]` first. A Symbol key
+					// takes OrdinaryDefineOwnProperty and evaluates nothing.
 					`${runtimeTemplate.method("defineProperty", "_, name", [
 						'if (typeof name === "symbol" || name === "then") return false;',
 						init,
 						"return false;"
 					])},`,
-					// `deleteProperty` rejects, but per the TC39 spec it must
-					// still trigger evaluation for string keys (the spec
-					// algorithm calls `GetModuleExportsList` for non-symbol-like
-					// keys, forcing evaluation on a deferred namespace).
+					// `deleteProperty` rejects too, and likewise still evaluates on a
+					// string key: the spec calls `GetModuleExportsList` for every
+					// non-symbol-like key.
 					`${runtimeTemplate.method("deleteProperty", "_, name", [
 						'if (typeof name === "symbol" || name === "then") return false;',
 						init,

package/lib/schemes/DataUriPlugin.js

@@ -34,12 +34,9 @@ class DataUriPlugin {
 							);
 							resourceData.data.encodedContent = match[4] || "";
 						}
-						// Inherit the issuer's resolution context so any nested
-						// dependencies discovered while parsing the data URI's body
-						// (e.g. `url(...)` / `@import` inside an inline CSS data
-						// URI) resolve relative to where the URI was referenced
-						// from, instead of against the synthetic `data:.../` path
-						// that `getContext("data:…")` would otherwise infer.
+						// Inherit the issuer's resolution context, so a dependency found
+						// inside the data URI's body resolves against where the URI was
+						// referenced, not the synthetic `data:…` path.
 						if (
 							resourceData.context === undefined &&
 							resolveData.context !== undefined

package/lib/schemes/VirtualUrlPlugin.js

@@ -36,7 +36,7 @@ const PLUGIN_NAME = "VirtualUrlPlugin";
 /**
  * Defines the loader context type used by this module.
  * @template T
- * @typedef {import("../../declarations/LoaderContext").LoaderContext<T>} LoaderContext
+ * @typedef {import("../NormalModule").LoaderContext<T>} LoaderContext
  */
 
 /**

package/lib/serialization/BinaryMiddleware.js

@@ -2,15 +2,6 @@
 	MIT License http://www.opensource.org/licenses/mit-license.php
 */
 
-"use strict";
-
-const { deserialize: v8Deserialize, serialize: v8Serialize } = require("v8");
-const memoize = require("../util/memoize");
-const SerializerMiddleware = require("./SerializerMiddleware");
-
-/** @typedef {import("./types").PrimitiveSerializableType} PrimitiveSerializableType */
-/** @import { BufferSerializableType } from "./types" */
-
 /*
 Format:
 
@@ -28,6 +19,15 @@ ValuesHeaderByte -> 0xf1
 LazyHeaderByte -> 0xf2
 */
 
+"use strict";
+
+const { deserialize: v8Deserialize, serialize: v8Serialize } = require("v8");
+const memoize = require("../util/memoize");
+const SerializerMiddleware = require("./SerializerMiddleware");
+
+/** @typedef {import("./types").PrimitiveSerializableType} PrimitiveSerializableType */
+/** @import { BufferSerializableType } from "./types" */
+
 const VALUES_HEADER = 0xf1;
 const LAZY_HEADER = 0xf2;
 

package/lib/serialization/FileMiddleware.js

@@ -2,6 +2,22 @@
 	MIT License http://www.opensource.org/licenses/mit-license.php
 */
 
+/*
+Format:
+
+File -> Header Section*
+
+Version -> u32
+AmountOfSections -> u32
+SectionSize -> i32 (if less than zero represents lazy value)
+
+Header -> Version AmountOfSections SectionSize*
+
+Buffer -> n bytes
+Section -> Buffer
+
+*/
+
 "use strict";
 
 const { constants } = require("buffer");
@@ -35,22 +51,6 @@ const SerializerMiddleware = require("./SerializerMiddleware");
 /** @import { IStats, IntermediateFileSystem } from "../util/fs" */
 /** @import { BufferSerializableType } from "./types" */
 
-/*
-Format:
-
-File -> Header Section*
-
-Version -> u32
-AmountOfSections -> u32
-SectionSize -> i32 (if less than zero represents lazy value)
-
-Header -> Version AmountOfSections SectionSize*
-
-Buffer -> n bytes
-Section -> Buffer
-
-*/
-
 // "wpc" + 1 in little-endian
 const VERSION = 0x01637077;
 const WRITE_LIMIT_TOTAL = 0x7fff0000;

package/lib/serialization/ObjectMiddleware.js

@@ -2,6 +2,28 @@
 	MIT License http://www.opensource.org/licenses/mit-license.php
 */
 
+/*
+
+Format:
+
+File -> Section*
+Section -> ObjectSection | ReferenceSection | EscapeSection | OtherSection
+
+ObjectSection -> ESCAPE (
+	number:relativeOffset (number > 0) |
+	string:request (string|null):export
+) Section:value* ESCAPE ESCAPE_END_OBJECT
+ReferenceSection -> ESCAPE number:relativeOffset (number < 0)
+EscapeSection -> ESCAPE ESCAPE_ESCAPE_VALUE (escaped value ESCAPE)
+EscapeSection -> ESCAPE ESCAPE_UNDEFINED (escaped value ESCAPE)
+OtherSection -> any (except ESCAPE)
+
+Why using null as escape value?
+Multiple null values can merged by the BinaryMiddleware, which makes it very efficient
+Technically any value can be used.
+
+*/
+
 "use strict";
 
 const { DEFAULTS } = require("../config/defaults");
@@ -29,28 +51,6 @@ const SetObjectSerializer = require("./SetObjectSerializer");
 
 /** @typedef {new (...params: EXPECTED_ANY[]) => EXPECTED_ANY} Constructor */
 
-/*
-
-Format:
-
-File -> Section*
-Section -> ObjectSection | ReferenceSection | EscapeSection | OtherSection
-
-ObjectSection -> ESCAPE (
-	number:relativeOffset (number > 0) |
-	string:request (string|null):export
-) Section:value* ESCAPE ESCAPE_END_OBJECT
-ReferenceSection -> ESCAPE number:relativeOffset (number < 0)
-EscapeSection -> ESCAPE ESCAPE_ESCAPE_VALUE (escaped value ESCAPE)
-EscapeSection -> ESCAPE ESCAPE_UNDEFINED (escaped value ESCAPE)
-OtherSection -> any (except ESCAPE)
-
-Why using null as escape value?
-Multiple null values can merged by the BinaryMiddleware, which makes it very efficient
-Technically any value can be used.
-
-*/
-
 /**
  * Defines the object serializer snapshot type used by this module.
  * @typedef {object} ObjectSerializerSnapshot
@@ -183,9 +183,8 @@ if (typeof AggregateError !== "undefined") {
 	);
 }
 
-// If in a sandboxed environment (e.g. jest), this escapes the sandbox and registers
-// real Object and Array types to. These types may occur in the wild too, e.g. when
-// using Structured Clone in postMessage.
+// In a sandboxed environment such as jest, this escapes the sandbox to register
+// the real Object and Array too, which reach us through a structured clone.
 // eslint-disable-next-line n/exports-style
 if (exports.constructor !== Object) {
 	// eslint-disable-next-line n/exports-style
@@ -772,10 +771,9 @@ class ObjectMiddleware extends SerializerMiddleware {
 
 			throw err;
 		} finally {
-			// Get rid of these references to avoid leaking memory
-			// This happens because the optimized code v8 generates
-			// is optimized for our "ctx.write" method so it will reference
-			// it from e. g. Dependency.prototype.serialize -(IC)-> ctx.write
+			// Drop these references, which would otherwise leak: v8 optimizes the
+			// generated code for this `ctx.write`, so an inline cache on
+			// `Dependency.prototype.serialize` keeps pointing at it.
 			data =
 				result =
 				referenceable =
@@ -974,10 +972,9 @@ class ObjectMiddleware extends SerializerMiddleware {
 			}
 			return result;
 		} finally {
-			// Get rid of these references to avoid leaking memory
-			// This happens because the optimized code v8 generates
-			// is optimized for our "ctx.read" method so it will reference
-			// it from e. g. Dependency.prototype.deserialize -(IC)-> ctx.read
+			// Drop these references, which would otherwise leak: v8 optimizes the
+			// generated code for this `ctx.read`, so an inline cache on
+			// `Dependency.prototype.deserialize` keeps pointing at it.
 			result =
 				referenceable =
 				data =

package/lib/stats/DefaultStatsFactoryPlugin.js

@@ -1274,10 +1274,9 @@ const SIMPLE_EXTRACTORS = {
 			{ name, chunkGroup },
 			{ compilation }
 		) => {
-			// SSR frameworks consume this to inject the initial-chunk +
-			// URL-asset `<link>` tags into their server-rendered HTML without
-			// having to walk the chunk graph themselves. Only entrypoints
-			// carry hints; split-chunk / async chunk groups are skipped.
+			// An SSR framework reads this to inject the `<link>` tags into its own
+			// HTML without walking the chunk graph. Only entrypoints carry hints, so
+			// split-chunk and async groups are skipped.
 			if (!compilation.entrypoints.get(name)) return;
 
 			const ResourceHintPlugin = require("../prefetch/ResourceHintPlugin");

package/lib/typescript/TypeScriptPlugin.js

@@ -122,9 +122,8 @@ const composeWithLoaderSourceMap = (
  */
 const stripTypes = (input) => {
 	try {
-		// Pass only `mode`. `sourceUrl` would emit a `//# sourceURL=…` pragma
-		// into the output (V8 debugger hint), and `sourceMap: true` is
-		// rejected in strip mode — we build the source map by hand instead.
+		// Only `mode`: `sourceUrl` would emit a `//# sourceURL=` pragma, and
+		// `sourceMap: true` is rejected in strip mode, so the map is built by hand.
 		// eslint-disable-next-line n/no-unsupported-features/node-builtins
 		return mod.stripTypeScriptTypes(input, { mode: "strip" });
 	} catch (err) {

package/lib/url/URLParserPlugin.js

@@ -257,10 +257,9 @@ class URLParserPlugin {
 					relative
 				);
 				dep.loc = parser.getLocation(expr);
-				// `parser.javascript.urlHints` provides project-wide defaults
-				// (resolved per-request, with `test` / `include` / `exclude`
-				// matching); a per-URL magic comment for the same hint wins
-				// when both are set.
+				// `parser.javascript.urlHints` gives the project-wide defaults,
+				// resolved per request; a per-URL magic comment for the same hint
+				// wins where both are set.
 				ResourceHintPlugin.applyResourceHints(
 					dep,
 					this.options.urlHints,
@@ -270,10 +269,9 @@ class URLParserPlugin {
 					parser.getLocation(expr)
 				);
 				parser.state.current.addDependency(dep);
-				// For ESM module output the template embeds the asset's resolved
-				// filename, so the asset must be code-generated first. Only added in
-				// that mode — a code-gen dependency on an asset that a later watch
-				// rebuild leaves unaffected can otherwise deadlock the scheduler.
+				// The ESM template embeds the asset's resolved filename, so the asset
+				// must be code-generated first. Added in that mode only: elsewhere the
+				// extra code-gen dependency can deadlock a watch rebuild.
 				if (parser.state.compilation.options.output.module) {
 					parser.state.module.addCodeGenerationDependency(dep);
 				}