webpack 5.108.4 → 5.109.1

package/lib/html/HtmlParser.js

@@ -5,15 +5,6 @@
 "use strict";
 
 const Parser = require("../Parser");
-const {
-	TT_EOF,
-	TT_FUNCTION,
-	TT_STRING,
-	TT_URL,
-	TT_WHITESPACE,
-	TokenStream,
-	equalsLowerCase
-} = require("../css/syntax");
 const ConstDependency = require("../dependencies/ConstDependency");
 const HtmlEntryDependency = require("../dependencies/HtmlEntryDependency");
 const HtmlInlineHtmlDependency = require("../dependencies/HtmlInlineHtmlDependency");
@@ -25,6 +16,8 @@ const CommentCompilationWarning = require("../errors/CommentCompilationWarning")
 const ModuleDependencyError = require("../errors/ModuleDependencyError");
 const UnsupportedFeatureWarning = require("../errors/UnsupportedFeatureWarning");
 const WebpackError = require("../errors/WebpackError");
+const ResourceHintPlugin = require("../prefetch/ResourceHintPlugin");
+const parseResourceHintOptions = require("../prefetch/parseResourceHintOptions");
 const LazySet = require("../util/LazySet");
 const LocConverter = require("../util/LocConverter");
 const createHash = require("../util/createHash");
@@ -40,8 +33,13 @@ const {
 	NodeType,
 	SVG_TAG_ADJUST,
 	SourceProcessor,
-	decodeHtmlEntities,
-	decodeHtmlEntitiesWithMap,
+	decodeEntities,
+	escapeAttribute,
+	escapeText,
+	isAsciiWhitespace,
+	parseCssUrls,
+	parseMsapplicationTask,
+	parseSrc,
 	parseSrcset
 } = require("./syntax");
 
@@ -69,31 +67,6 @@ const {
  */
 /** @typedef {(source: string, context: HtmlTemplateContext) => string} HtmlTemplateFunction */
 
-const HORIZONTAL_TAB = "\u0009".charCodeAt(0);
-const NEWLINE = "\u000A".charCodeAt(0);
-const FORM_FEED = "\u000C".charCodeAt(0);
-const CARRIAGE_RETURN = "\u000D".charCodeAt(0);
-const SPACE = "\u0020".charCodeAt(0);
-
-/**
- * @param {number} char char
- * @returns {boolean} true when ASCII whitespace, otherwise false
- */
-function isASCIIWhitespace(char) {
-	return (
-		// Horizontal tab
-		char === HORIZONTAL_TAB ||
-		// New line
-		char === NEWLINE ||
-		// Form feed
-		char === FORM_FEED ||
-		// Carriage return
-		char === CARRIAGE_RETURN ||
-		// Space
-		char === SPACE
-	);
-}
-
 /** @typedef {import("./syntax").ParsedSource} ParsedSource */
 
 // Cheap pre-filter for a `style="..."` attribute: only route it through the
@@ -116,6 +89,63 @@ const SRCDOC_ASSET_REGEXP = /[=]|url\(|@import/i;
 // base per the URL spec, so `<base href>` never rewrites it.
 const ABSOLUTE_URL_SCHEME_REGEXP = /^[a-zA-Z][a-zA-Z\d+\-.]*:/;
 
+// a `charset=` declaration inside an `http-equiv="content-type"` content value
+const CHARSET_DECLARATION_REGEXP = /charset\s*=/i;
+
+/**
+ * @param {string} name meta name
+ * @param {string} content meta content
+ * @returns {string} meta tag
+ */
+const metaTag = (name, content) => {
+	// og: uses property=; all others (including twitter:) use name=
+	const attr = name.startsWith("og:")
+		? `property="${escapeAttribute(name)}"`
+		: `name="${escapeAttribute(name)}"`;
+	return `<meta ${attr} content="${escapeAttribute(content)}">`;
+};
+
+/**
+ * @param {string | { href: string, target?: string }} base base option
+ * @returns {string} base tag
+ */
+const baseTag = (base) => {
+	const href = typeof base === "string" ? base : base.href;
+	const targetAttr =
+		typeof base === "object" && base.target
+			? ` target="${escapeAttribute(base.target)}"`
+			: "";
+	return `<base href="${escapeAttribute(href)}"${targetAttr}>`;
+};
+
+/**
+ * Serializes every head tag an `output.html` options object asks for, in
+ * spec order: charset, base, meta tags, title. Used where a page is created
+ * from scratch (HtmlModulesPlugin's synthetic entry wrapper); authored pages
+ * instead merge the options against their existing tags during `parse` —
+ * existing tags win.
+ * @param {import("../../declarations/WebpackOptions").OutputHtmlOptions} opts html options
+ * @returns {string} head tags string
+ */
+const buildHeadTags = (opts) => {
+	let out = "";
+	const meta = opts.meta;
+	if (meta && meta.charset) {
+		out += `<meta charset="${escapeAttribute(meta.charset)}">`;
+	}
+	if (opts.base) out += baseTag(opts.base);
+	if (meta) {
+		for (const [name, content] of Object.entries(meta)) {
+			if (name === "charset") continue;
+			out += metaTag(name, content);
+		}
+	}
+	if (opts.title) {
+		out += `<title>${escapeText(opts.title)}</title>`;
+	}
+	return out;
+};
+
 // CSP/fetch attributes copied verbatim onto a synthesized sibling `<link>` /
 // `<script>` (`HtmlEntryDependency`). Fixed output order, independent of
 // source order.
@@ -147,124 +177,34 @@ const attrSourceSpan = (path, source, attr) => {
 	return source.slice(path.attributeNameStart(attr) - 1, end);
 };
 
-// eslint-disable-next-line no-control-regex
-const IGNORE_CHARS_REGEXP = /[\u0000-\u001F\u007F-\u009F\u00A0]/g;
-
 /**
- * @param {string} input input
- * @returns {ParsedSource[]} parsed src
+ * Source span of a tag's `integrity` attribute (offsets relative to
+ * `elementStart`, leading whitespace and quotes included), so the template can
+ * drop the content-specific author value without re-parsing. Null when absent.
+ * @param {import("./syntax").HtmlPath} path walk path (for attribute reads)
+ * @param {string} source HTML source
+ * @param {number} elementStart offset of the tag's opening `<`
+ * @returns {Range | null} the span, or null when there is no `integrity`
  */
-const parseSrc = (input) => {
-	const len = input.length;
-	if (len === 0) throw new Error("Must be non-empty");
-
-	let start = 0;
-	let end = len;
-
-	while (start < end) {
-		const code = input.charCodeAt(start);
-		if (code > 32 && code !== 160) break;
-		start++;
-	}
-
-	if (start === end) throw new Error("Must be non-empty");
-
-	while (end > start) {
-		const code = input.charCodeAt(end - 1);
-		if (code > 32 && code !== 160) break;
-		end--;
-	}
-
-	let value = input.slice(start, end);
-
-	if (IGNORE_CHARS_REGEXP.test(value)) {
-		value = value.replace(IGNORE_CHARS_REGEXP, "");
-		if (value.length === 0) throw new Error("Must be non-empty");
+const captureIntegrityRange = (path, source, elementStart) => {
+	const integrityAttr = path.findAttribute("integrity");
+	if (integrityAttr === 0 || path.attributeNameStart(integrityAttr) < 0) {
+		return null;
 	}
-
-	return [[value, start, end]];
-};
-
-/**
- * Extracts the `icon-uri` value of an `msapplication-task` meta content
- * (`name=…;action-uri=…;icon-uri=…`) — the other parts are page URLs, not assets.
- * @param {string} input input
- * @returns {ParsedSource[]} parsed icon-uri
- */
-const parseMsapplicationTask = (input) => {
-	const len = input.length;
-	let pos = 0;
-	while (pos < len) {
-		let sep = input.indexOf(";", pos);
-		if (sep === -1) sep = len;
-		const eq = input.indexOf("=", pos);
-		if (eq !== -1 && eq < sep) {
-			const key = input.slice(pos, eq).trim().toLowerCase();
-			if (key === "icon-uri") {
-				let start = eq + 1;
-				let end = sep;
-				while (start < end && isASCIIWhitespace(input.charCodeAt(start))) {
-					start++;
-				}
-				while (end > start && isASCIIWhitespace(input.charCodeAt(end - 1))) {
-					end--;
-				}
-				if (start === end) return [];
-				return [[input.slice(start, end), start, end]];
-			}
-		}
-		pos = sep + 1;
+	let rs = path.attributeNameStart(integrityAttr);
+	while (rs > 0 && isAsciiWhitespace(source.charCodeAt(rs - 1))) {
+		rs--;
 	}
-	return [];
-};
-
-/**
- * Extracts `url(...)` references from a CSS value (an SVG presentation
- * attribute). Reuses webpack's CSS lexer so quoting/escaping match the CSS
- * spec; returns the `parseSrc` shape so the shared emit path maps and rewrites
- * the spans. Unquoted `url(path)` rewrites the content span; quoted
- * `url("path")` rewrites the inner string span (quotes preserved).
- * @param {string} input attribute value (a CSS component-value list)
- * @returns {ParsedSource[]} url references
- */
-const parseCssUrls = (input) => {
-	const ts = new TokenStream(input);
-	/** @type {ParsedSource[]} */
-	const result = [];
-	for (;;) {
-		const t = ts.consume();
-		if (t.type === TT_EOF) break;
-		if (t.type === TT_URL) {
-			if (t.contentEnd > t.contentStart) {
-				result.push([
-					input.slice(t.contentStart, t.contentEnd),
-					t.contentStart,
-					t.contentEnd
-				]);
-			}
-		} else if (
-			t.type === TT_FUNCTION &&
-			equalsLowerCase(input.slice(t.start, t.end - 1), "url")
-		) {
-			let s = ts.consume();
-			while (s.type === TT_WHITESPACE) s = ts.consume();
-			if (s.type === TT_STRING) {
-				const quote = input.charCodeAt(s.start);
-				const innerStart = s.start + 1;
-				// Drop the closing quote, unless the string is unterminated at EOF.
-				const innerEnd =
-					input.charCodeAt(s.end - 1) === quote ? s.end - 1 : s.end;
-				if (innerEnd > innerStart) {
-					result.push([
-						input.slice(innerStart, innerEnd),
-						innerStart,
-						innerEnd
-					]);
-				}
-			}
-		}
+	let re;
+	const ivs = path.attributeValueStart(integrityAttr);
+	if (ivs === -1) {
+		re = path.attributeNameEnd(integrityAttr);
+	} else {
+		const q = source.charCodeAt(ivs - 1);
+		const ive = path.attributeValueEnd(integrityAttr);
+		re = q === CC_QUOTATION || q === CC_APOSTROPHE ? ive + 1 : ive;
 	}
-	return result;
+	return [rs - elementStart, re - elementStart];
 };
 
 /**
@@ -290,6 +230,8 @@ const META = new Map([
 			"msapplication-task",
 			"twitter:image",
 			"twitter:image:src",
+			// Twitter player card: URL to the raw video/media stream
+			"twitter:player:stream",
 			// Legacy preview-image hint
 			"thumbnail"
 		])
@@ -345,9 +287,7 @@ const ALLOWED_LINK_RELS = new Set([
 	"apple-touch-icon",
 	"apple-touch-icon-precomposed",
 	"apple-touch-startup-image",
-	// TODO the manifest file is emitted as an asset, but its JSON
-	// `icons`/`screenshots`/`shortcuts[].icons` URLs aren't parsed — needs a
-	// dedicated webmanifest module type (parser + generator), not a table entry.
+	// Routed to the `asset/webmanifest` module type, which parses its icon URLs.
 	"manifest",
 	"prefetch",
 	"preload",
@@ -458,14 +398,17 @@ const isLinkStylesheet = (attributes) => {
 	return rel.trim().toLowerCase().split(/\s+/).includes("stylesheet");
 };
 
-/** @typedef {"src" | "srcset" | "css-url" | "msapplication-task" | "script" | "script-module" | "modulepreload" | "stylesheet" | "stylesheet-style" | "stylesheet-style-attribute" | "srcdoc"} SourceType */
+/** @typedef {"src" | "srcset" | "css-url" | "msapplication-task" | "script" | "script-module" | "modulepreload" | "stylesheet" | "html" | "preload" | "prefetch" | "stylesheet-style" | "stylesheet-style-attribute" | "srcdoc"} SourceType */
 /** Entry types: a `type` whose value is loaded as its own compilation entry chunk. */
-/** @typedef {"script" | "script-module" | "modulepreload" | "stylesheet"} EntrySourceType */
+/** @typedef {"script" | "script-module" | "modulepreload" | "stylesheet" | "html" | "preload" | "prefetch"} EntrySourceType */
 /** @typedef {SourceType | ((attrs: Map<string, string>, css: boolean) => SourceType)} SourceTypeOrResolver */
 /** @typedef {(attributes: Map<string, string>, value: string) => boolean} SourceFilter */
 /** @typedef {{ tag?: string, attribute: string, type: SourceType, filter?: SourceFilter }} SourceEntry */
 /** A `type` plus optional gates: `filter` (the decoded attribute map + the decoded value; return false to skip — covers both cross-attribute checks and cheap value checks) and `namespace` (restrict to an element namespace, e.g. SVG). */
 /** @typedef {{ type: SourceTypeOrResolver, filter?: SourceFilter, namespace?: number }} SourceItem */
+/** A tag→attribute lookup; a `undefined` value marks a built-in source disabled via `sources` (`type: false`). */
+/** @typedef {Record<string, SourceItem | undefined>} SourceBucket */
+/** @typedef {Record<string, SourceBucket>} SourceTable */
 /** A source whose value is the element's text content (a `<style>`/`<script>` body) rather than an attribute. */
 /** @typedef {{ type: SourceTypeOrResolver, filter?: (attributes: Map<string, string>) => boolean }} ContentSourceItem */
 
@@ -501,6 +444,24 @@ const LINK_HREF = {
 	type: (attrs, css) => {
 		if (isLinkModulePreload(attrs)) return "modulepreload";
 		if (css && isLinkStylesheet(attrs)) return "stylesheet";
+		// `rel="preload"/"prefetch"` with `as="script"` (or `as="style"` when
+		// `experiments.css` is on) becomes a bundled, non-executing entry whose
+		// `href` is rewritten to the built chunk; other `as` targets (image,
+		// font, fetch, …) stay plain asset URLs.
+		const rel = getAttributeValue(attrs, "rel");
+		if (rel) {
+			const rels = rel.trim().toLowerCase().split(/\s+/);
+			const kind = rels.includes("preload")
+				? "preload"
+				: rels.includes("prefetch")
+					? "prefetch"
+					: undefined;
+			if (kind) {
+				const as = getAttributeValue(attrs, "as");
+				const asLower = as ? as.trim().toLowerCase() : "";
+				if (asLower === "script" || (css && asLower === "style")) return kind;
+			}
+		}
 		return "src";
 	},
 	filter: filterLinkUnion
@@ -588,15 +549,22 @@ const DEFAULT_SOURCES_BY_TAG = dict({
 	// `xlink:href` reference another element/resource; fragment-only `#id`
 	// values are left untouched, so only external `file.svg#id` is rewritten.
 	// `color-profile`'s `xlink:href` points at an external ICC profile file.
+	// `cursor`/`font-face-uri` point at an external image/font file; `altGlyph`/
+	// `glyphRef`/`tref` are legacy element references (removed in SVG 2).
+	altGlyph: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
 	"color-profile": dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
+	cursor: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
 	feImage: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
 	filter: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
+	"font-face-uri": dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
+	glyphRef: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
 	image: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
 	linearGradient: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
 	mpath: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
 	pattern: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
 	radialGradient: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
 	textPath: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
+	tref: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC }),
 	use: dict({ "xlink:href": PLAIN_SRC, href: PLAIN_SRC })
 	// CSS `url(...)` references in SVG presentation attributes (fill, stroke,
 	// clip-path, …) are handled separately during the walk (`parseCssUrls`).
@@ -657,9 +625,9 @@ const ANY_TAG = "";
  * Folds the any-tag sources into every per-tag bucket (tag-specific entries
  * win) and stores them under `ANY_TAG`, so the whole source model is one
  * object and the walk's per-attribute lookup is a single property read.
- * @param {Record<string, Record<string, SourceItem>>} byTag per-tag sources
- * @param {Record<string, SourceItem>} any any-tag sources
- * @returns {Record<string, Record<string, SourceItem>>} folded table
+ * @param {SourceTable} byTag per-tag sources
+ * @param {SourceBucket} any any-tag sources
+ * @returns {SourceTable} folded table
  */
 const foldAnySources = (byTag, any) => {
 	for (const tag of Object.keys(byTag)) {
@@ -672,12 +640,12 @@ const foldAnySources = (byTag, any) => {
 // Default table (per-tag defaults + any-tag sources folded in) and the
 // `sources: false` table (only the always-on `style=""` attribute). Both are
 // precomputed so the common cases reference them with zero per-parser work.
-/** @type {Record<string, Record<string, SourceItem>>} */
+/** @type {SourceTable} */
 const DEFAULT_SOURCES_FOLDED = foldAnySources(
 	dict(DEFAULT_SOURCES_BY_TAG),
 	DEFAULT_ANY_SOURCES
 );
-/** @type {Record<string, Record<string, SourceItem>>} */
+/** @type {SourceTable} */
 const DISABLED_SOURCES_FOLDED = foldAnySources(dict(), ALWAYS_ANY_SOURCES);
 
 /**
@@ -734,9 +702,21 @@ class HtmlParser extends Parser {
 		// the module source before it is stored and parsed.
 		/** @type {HtmlTemplateFunction | undefined} */
 		this.template = options.template;
+		/** @type {import("../../declarations/WebpackOptions").UrlHintRule[] | undefined} */
+		this._urlHints = options.urlHints;
+		// `as` selects the parse mode — the HTML analog of the CSS parser's `as`.
+		// `"document"` (default) parses a full page; any other value is the
+		// context element whose inner HTML the source is parsed as (a fragment),
+		// so context-sensitive tags (`<tr>`, `<td>`, `<option>`, …) in a partial
+		// are kept, not dropped. `"template"` is the neutral generic fragment.
+		/** @type {string | undefined} */
+		this.fragmentContext =
+			options.as === undefined || options.as === "document"
+				? undefined
+				: options.as;
 		// One source model: a per-tag table that also holds the any-tag sources
 		// under `ANY_TAG`. The common cases reference precomputed tables.
-		/** @type {Record<string, Record<string, SourceItem>>} */
+		/** @type {SourceTable} */
 		this.sourcesByTag = DEFAULT_SOURCES_FOLDED;
 
 		const sources = options.sources;
@@ -755,19 +735,25 @@ class HtmlParser extends Parser {
 		// User entries override regardless of position. `dict()` keeps every
 		// table null-prototype (see its doc), and per-tag writes rebuild the
 		// bucket so the aliased default buckets stay intact.
-		/** @type {Record<string, Record<string, SourceItem>>} */
+		/** @type {SourceTable} */
 		const byTag = sources.includes("...")
 			? dict(DEFAULT_SOURCES_BY_TAG)
 			: dict();
-		/** @type {Record<string, SourceItem>} */
+		/** @type {SourceBucket} */
 		const any = dict(DEFAULT_ANY_SOURCES);
 		for (const entry of sources) {
 			if (entry === "...") continue;
-			/** @type {SourceItem} */
-			const item = {
-				type: entry.type,
-				filter: typeof entry.filter === "function" ? entry.filter : undefined
-			};
+			// `type: false` disables a built-in source: writing `undefined` over the
+			// attribute makes the walk's `sources[name]` lookup skip it (see below).
+			/** @type {SourceItem | undefined} */
+			const item =
+				entry.type === false
+					? undefined
+					: {
+							type: entry.type,
+							filter:
+								typeof entry.filter === "function" ? entry.filter : undefined
+						};
 			const attr = entry.attribute.toLowerCase();
 			if (entry.tag === undefined) {
 				any[attr] = item;
@@ -782,7 +768,7 @@ class HtmlParser extends Parser {
 				}
 			}
 		}
-		/** @type {Record<string, Record<string, SourceItem>>} */
+		/** @type {SourceTable} */
 		this.sourcesByTag = foldAnySources(byTag, any);
 	}
 
@@ -871,6 +857,7 @@ class HtmlParser extends Parser {
 		const { hashFunction, module: outputModule } = compilation.outputOptions;
 		const context = compilation.compiler.context;
 		const css = Boolean(compilation.options.experiments.css);
+		const urlHints = this._urlHints;
 
 		// Stable, per-HTML-module prefix used when generating entry names for
 		// script src / modulepreload references so they don't collide across
@@ -888,6 +875,43 @@ class HtmlParser extends Parser {
 			.digest("hex")
 			.slice(0, 8);
 
+		// `output.html` head injection: facts are collected during the walk and
+		// become presentational dependencies afterwards — no later asset pass has
+		// to re-parse the page. `data:` documents are skipped: synthetic entry
+		// wrappers already carry the tags and iframe srcdoc pages must stay
+		// untouched.
+		const htmlOutputOptions =
+			compilation.options && compilation.options.output
+				? compilation.options.output.html
+				: undefined;
+		const headOptions =
+			typeof htmlOutputOptions === "object" &&
+			(htmlOutputOptions.title !== undefined ||
+				htmlOutputOptions.meta !== undefined ||
+				htmlOutputOptions.base !== undefined) &&
+			!resource.startsWith("data:")
+				? htmlOutputOptions
+				: undefined;
+		let doctypeEnd = -1;
+		let htmlTagEnd = -1;
+		// insertion offsets just inside the (possibly implicit) head
+		let headStart = 0;
+		let headLastEnd = 0;
+		let headSeen = false;
+		let inHead = false;
+		// `<template>` contents are inert
+		let headTemplateDepth = 0;
+		// Depth of open `<template>` elements anywhere in the tree. Template
+		// content is an inert, separate fragment per spec, so a `<base>` inside
+		// it must NOT set the document base (`headTemplateDepth` only covers
+		// templates seen while in `<head>`, so it can't guard body templates).
+		let templateDepth = 0;
+		let headHasTitle = false;
+		let headHasBase = false;
+		let headCharsetEnd = -1;
+		/** @type {Set<string> | undefined} */
+		let headMetaNames;
+
 		// Script src / modulepreload references are collected per-type
 		// during the walk; HtmlModulesPlugin later turns them into real
 		// entries. `script` and `script-module` entries are chained via a
@@ -896,23 +920,37 @@ class HtmlParser extends Parser {
 		// must preload without running, so they can never become a runtime
 		// leader that other entries would import.
 		/**
-		 * @typedef {object} EntryScriptInfo
+		 * @typedef {object} HtmlEntryInfo
 		 * @property {string} request
 		 * @property {string} entryName
-		 * @property {"script" | "script-module" | "modulepreload" | "stylesheet"} type
+		 * @property {"script" | "script-module" | "modulepreload" | "stylesheet" | "html" | "preload" | "prefetch"} type
+		 * @property {boolean=} css entry emits a CSS chunk (`<link rel="preload" as="style">`), so it needs the CSS filename template
 		 */
-		/** @type {EntryScriptInfo[]} */
+		/** @type {HtmlEntryInfo[]} */
 		const scriptEntries = [];
-		/** @type {EntryScriptInfo[]} */
+		/** @type {HtmlEntryInfo[]} */
 		const scriptModuleEntries = [];
-		/** @type {EntryScriptInfo[]} */
+		/** @type {HtmlEntryInfo[]} */
 		const modulePreloadEntries = [];
-		/** @type {EntryScriptInfo[]} */
+		/** @type {HtmlEntryInfo[]} */
 		const stylesheetEntries = [];
-
-		// Offset of the first script tag; anchors injected stylesheet `<link>`s
-		// before it so a later entry's CSS still loads ahead of every script.
-		let firstScriptStart = -1;
+		// `type: "html"` links — each referenced `.html` becomes its own page
+		// entry (`<a href="page.html">`), independent (no dependOn).
+		/** @type {HtmlEntryInfo[]} */
+		const htmlLinkEntries = [];
+		// `<link rel="preload"/"prefetch">` of a bundled resource: each becomes an
+		// independent, non-executing entry whose `href` is rewritten to the built
+		// chunk's URL (JS for `as="script"`, CSS for `as="style"`).
+		/** @type {HtmlEntryInfo[]} */
+		const preloadEntries = [];
+		/** @type {HtmlEntryInfo[]} */
+		const prefetchEntries = [];
+
+		// Offset of the first classic blocking script tag; injected stylesheet
+		// `<link>`s stay ahead of it. `defer`/`async`/module scripts don't
+		// anchor — they execute after parsing (and after pending stylesheets),
+		// so CSS may follow their tags (the order Vite emits).
+		let firstBlockingScriptStart = -1;
 
 		let nextEntryIndex = 0;
 
@@ -940,6 +978,14 @@ class HtmlParser extends Parser {
 		 * @type {boolean | undefined}
 		 */
 		let pendingWebpackIgnore;
+		/** @type {boolean | undefined} */
+		let pendingWebpackInline;
+		/**
+		 * Tracks the resource-hint values from the most recent `<!-- webpackPrefetch: … -->`
+		 * (etc.) comment so the next asset URL attribute picks them up.
+		 * @type {import("../prefetch/parseResourceHintOptions").ResourceHintOptions | undefined}
+		 */
+		let pendingHints;
 
 		const magicCommentContext = this.magicCommentContext;
 
@@ -979,7 +1025,7 @@ class HtmlParser extends Parser {
 				let attrStart = path.attributeNameStart(typeAttr);
 				if (
 					attrStart > 0 &&
-					isASCIIWhitespace(input.charCodeAt(attrStart - 1))
+					isAsciiWhitespace(input.charCodeAt(attrStart - 1))
 				) {
 					attrStart -= 1;
 				}
@@ -1016,10 +1062,7 @@ class HtmlParser extends Parser {
 		 * @param {import("./syntax").HtmlAttributeRef} hrefAttr the base's href attribute
 		 */
 		const resolveDocumentBase = (path, hrefAttr) => {
-			documentBase = decodeHtmlEntities(
-				path.attributeValue(hrefAttr),
-				true
-			).trim();
+			documentBase = decodeEntities(path.attributeValue(hrefAttr), true).trim();
 			if (!documentBase) return;
 			if (
 				ABSOLUTE_URL_SCHEME_REGEXP.test(documentBase) ||
@@ -1074,7 +1117,7 @@ class HtmlParser extends Parser {
 				// the browser sees (e.g. `rel="&#105;con"` means `icon`)
 				currentAttributesMap.set(
 					path.attributeName(attr),
-					decodeHtmlEntities(path.attributeValue(attr), true)
+					decodeEntities(path.attributeValue(attr), true)
 				);
 			}
 			return currentAttributesMap;
@@ -1089,6 +1132,10 @@ class HtmlParser extends Parser {
 				[NodeType.Comment]: (path) => {
 					const start = path.start();
 					const end = path.end();
+					// comments count toward the head-end insertion anchor
+					if (inHead && headTemplateDepth === 0 && end > headLastEnd) {
+						headLastEnd = end;
+					}
 					// Only proper `<!-- ... -->` comments carry magic comments.
 					if (
 						end - start < 7 ||
@@ -1101,11 +1148,15 @@ class HtmlParser extends Parser {
 						source.charCodeAt(end - 3) !== 0x2d
 					) {
 						pendingWebpackIgnore = undefined;
+						pendingWebpackInline = undefined;
+						pendingHints = undefined;
 						return;
 					}
 					const value = path.data();
 					if (!webpackCommentRegExp.test(value)) {
 						pendingWebpackIgnore = undefined;
+						pendingWebpackInline = undefined;
+						pendingHints = undefined;
 						return;
 					}
 					/** @type {Record<string, EXPECTED_ANY>} */
@@ -1127,13 +1178,26 @@ class HtmlParser extends Parser {
 							)
 						);
 						pendingWebpackIgnore = undefined;
+						pendingWebpackInline = undefined;
+						pendingHints = undefined;
 						return;
 					}
-					if (options.webpackIgnore === undefined) {
+					if (
+						options.webpackIgnore === undefined &&
+						options.webpackInline === undefined &&
+						options.webpackPrefetch === undefined &&
+						options.webpackPreload === undefined &&
+						options.webpackFetchPriority === undefined
+					) {
 						pendingWebpackIgnore = undefined;
+						pendingWebpackInline = undefined;
+						pendingHints = undefined;
 						return;
 					}
-					if (typeof options.webpackIgnore !== "boolean") {
+					if (
+						options.webpackIgnore !== undefined &&
+						typeof options.webpackIgnore !== "boolean"
+					) {
 						const { line: sl, column: sc } = locConverter.get(start);
 						const { line: el, column: ec } = locConverter.get(end);
 						module.addWarning(
@@ -1146,12 +1210,59 @@ class HtmlParser extends Parser {
 							)
 						);
 						pendingWebpackIgnore = undefined;
+						pendingWebpackInline = undefined;
+						pendingHints = undefined;
+						return;
+					}
+					if (
+						options.webpackInline !== undefined &&
+						typeof options.webpackInline !== "boolean"
+					) {
+						const { line: sl, column: sc } = locConverter.get(start);
+						const { line: el, column: ec } = locConverter.get(end);
+						module.addWarning(
+							new UnsupportedFeatureWarning(
+								`\`webpackInline\` expected a boolean, but received: ${options.webpackInline}.`,
+								{
+									start: { line: sl, column: sc },
+									end: { line: el, column: ec }
+								}
+							)
+						);
+						pendingWebpackIgnore = undefined;
+						pendingWebpackInline = undefined;
+						pendingHints = undefined;
 						return;
 					}
 					pendingWebpackIgnore = options.webpackIgnore;
+					pendingWebpackInline = options.webpackInline;
+					if (
+						options.webpackPrefetch !== undefined ||
+						options.webpackPreload !== undefined ||
+						options.webpackFetchPriority !== undefined
+					) {
+						const s = locConverter.get(start);
+						const e = locConverter.get(end);
+						const parsedHints = parseResourceHintOptions(options, module, {
+							start: { line: s.line, column: s.column },
+							end: { line: e.line, column: e.column }
+						});
+						pendingHints =
+							parsedHints.prefetch !== undefined ||
+							parsedHints.preload !== undefined ||
+							parsedHints.fetchPriority !== undefined
+								? parsedHints
+								: undefined;
+					} else {
+						pendingHints = undefined;
+					}
 				},
-				[NodeType.Doctype]: () => {
+				[NodeType.Doctype]: (path) => {
+					// only visited when head injection is active (see `skip` below)
+					if (doctypeEnd === -1) doctypeEnd = path.end();
 					pendingWebpackIgnore = undefined;
+					pendingWebpackInline = undefined;
+					pendingHints = undefined;
 				},
 				[NodeType.Element]: {
 					// Children (and `<template>` content) are walked by the
@@ -1159,7 +1270,115 @@ class HtmlParser extends Parser {
 					// `webpackIgnore` once they're done.
 					enter: (path) => {
 						const ignore = pendingWebpackIgnore === true;
+						const forceInline = pendingWebpackInline === true;
 						pendingWebpackIgnore = undefined;
+						pendingWebpackInline = undefined;
+
+						// `<head>` anchors are collected for every page — they place
+						// `inject: "head"` siblings and resource hints; the
+						// title/meta/base facts only when configured. Structural, so it
+						// runs even for `webpackIgnore`d elements.
+						{
+							const name = path.tagName();
+							if (name === "template" && path.namespace() === NS_HTML) {
+								templateDepth++;
+							}
+							if (headTemplateDepth > 0) {
+								if (name === "template" && path.namespace() === NS_HTML) {
+									headTemplateDepth++;
+								}
+							} else if (inHead) {
+								if (headOptions !== undefined && path.namespace() === NS_HTML) {
+									switch (name) {
+										case "title":
+											headHasTitle = true;
+											break;
+										case "base":
+											headHasBase = true;
+											break;
+										case "meta": {
+											if (path.findAttribute("charset") !== 0) {
+												headCharsetEnd = path.tagEnd();
+											} else {
+												const httpEquiv = path.findAttribute("http-equiv");
+												const contentAttr =
+													httpEquiv !== 0 &&
+													decodeEntities(
+														path.attributeValue(httpEquiv),
+														true
+													).toLowerCase() === "content-type"
+														? path.findAttribute("content")
+														: 0;
+												if (
+													contentAttr !== 0 &&
+													CHARSET_DECLARATION_REGEXP.test(
+														decodeEntities(
+															path.attributeValue(contentAttr),
+															true
+														)
+													)
+												) {
+													headCharsetEnd = path.tagEnd();
+												}
+											}
+											const nameAttr = path.findAttribute("name");
+											const propertyAttr = path.findAttribute("property");
+											if (nameAttr !== 0 || propertyAttr !== 0) {
+												if (headMetaNames === undefined) {
+													headMetaNames = new Set();
+												}
+												if (nameAttr !== 0) {
+													headMetaNames.add(
+														decodeEntities(
+															path.attributeValue(nameAttr),
+															true
+														).toLowerCase()
+													);
+												}
+												if (propertyAttr !== 0) {
+													headMetaNames.add(
+														decodeEntities(
+															path.attributeValue(propertyAttr),
+															true
+														).toLowerCase()
+													);
+												}
+											}
+											break;
+										}
+										case "template":
+											headTemplateDepth++;
+											break;
+									}
+								} else if (
+									name === "template" &&
+									path.namespace() === NS_HTML
+								) {
+									headTemplateDepth++;
+								}
+								if (path.end() > headLastEnd) headLastEnd = path.end();
+							} else if (!headSeen && path.namespace() === NS_HTML) {
+								if (name === "html") {
+									htmlTagEnd = path.tagEnd();
+								} else if (name === "head") {
+									headSeen = true;
+									inHead = true;
+									// explicit head has real offsets; an implicit one (head
+									// tags are optional in HTML5) anchors after `<html>`,
+									// the doctype, or the document start
+									const tagEnd = path.tagEnd();
+									headStart =
+										tagEnd > 0
+											? tagEnd
+											: htmlTagEnd > 0
+												? htmlTagEnd
+												: doctypeEnd > 0
+													? doctypeEnd
+													: 0;
+									headLastEnd = headStart;
+								}
+							}
+						}
 
 						if (ignore) {
 							return;
@@ -1171,9 +1390,12 @@ class HtmlParser extends Parser {
 						const tagEnd = path.tagEnd();
 						const nameEnd = path.nameEnd();
 
-						// The first `<base href>` freezes the base for later URLs.
+						// The first `<base href>` freezes the base for later URLs — but
+						// only one in the real document tree, not inside an inert
+						// `<template>` (whose contents are a separate fragment).
 						if (
 							documentBase === undefined &&
+							templateDepth === 0 &&
 							elementName === "base" &&
 							path.namespace() === NS_HTML
 						) {
@@ -1246,7 +1468,7 @@ class HtmlParser extends Parser {
 									// The filter also sees the decoded value (the browser tokenizes it
 									// decoded, e.g. `&#117;rl(`), so a value-only check needn't re-read it.
 									const decoded = value.includes("&")
-										? decodeHtmlEntities(value, true)
+										? decodeEntities(value, true)
 										: value;
 									if (!filter(getAttributesMap(), decoded)) continue;
 								}
@@ -1266,9 +1488,7 @@ class HtmlParser extends Parser {
 								case "stylesheet-style":
 								case "stylesheet-style-attribute": {
 									if (!css) break;
-									const cssText = content
-										? value
-										: decodeHtmlEntities(value, true);
+									const cssText = content ? value : decodeEntities(value, true);
 									if (cssText.trim() === "") break;
 									const dep = new HtmlInlineStyleDependency(
 										dataUri("text/css", cssText),
@@ -1287,7 +1507,7 @@ class HtmlParser extends Parser {
 								// whose URL is `about:srcdoc`, so its base URL is inherited from
 								// this document — asset URLs resolve against this file's context.
 								case "srcdoc": {
-									const htmlText = decodeHtmlEntities(value, true);
+									const htmlText = decodeEntities(value, true);
 									// Only spin up a nested module when there is markup that can
 									// reference an asset; text/formatting-only markup is identical
 									// after rewriting (see `SRCDOC_ASSET_REGEXP`).
@@ -1346,7 +1566,10 @@ class HtmlParser extends Parser {
 								case "css-url":
 								case "msapplication-task":
 								case "modulepreload":
-								case "stylesheet": {
+								case "stylesheet":
+								case "html":
+								case "preload":
+								case "prefetch": {
 									// Parse the value into one or more URLs (decoding character
 									// references, mapping spans back to raw offsets), then emit a plain
 									// asset reference or an entry chunk per URL.
@@ -1362,7 +1585,7 @@ class HtmlParser extends Parser {
 									/** @type {number[] | undefined} */
 									let map;
 									if (value.includes("&")) {
-										({ text, map } = decodeHtmlEntitiesWithMap(value, true));
+										({ text, map } = decodeEntities(value, true, true));
 										if (!/\S/.test(text)) break;
 									}
 									/** @type {ParsedSource[] | undefined} */
@@ -1408,6 +1631,70 @@ class HtmlParser extends Parser {
 										}
 										const s = start + (map ? map[us] : us);
 										const e = start + (map ? map[ue] : ue);
+										// `html` links the URL as its own emitted page: the same
+										// `HtmlEntryDependency` as `<script src>` / `<link>`, but the `html`
+										// kind rewrites to the page's filename and emits no sibling tags.
+										// Recorded as an independent entry (no `dependOn`), like an entry point.
+										if (type === "html") {
+											const entryName = `__html_${moduleHash}_${nextEntryIndex++}`;
+											const dep = new HtmlEntryDependency(
+												request,
+												[s, e],
+												entryName,
+												undefined,
+												"html"
+											);
+											setLoc(dep, s, e);
+											module.addPresentationalDependency(dep);
+											htmlLinkEntries.push({ request, entryName, type });
+											continue;
+										}
+										// `rel="preload"/"prefetch"` of a bundled resource: an
+										// independent, non-executing entry whose `href` is rewritten to
+										// the built chunk's URL (CSS for `as="style"`, JS otherwise). No
+										// sibling tags — a resource hint references exactly one URL.
+										if (type === "preload" || type === "prefetch") {
+											const as = getAttributeValue(getAttributesMap(), "as");
+											const asStyle = as
+												? as.trim().toLowerCase() === "style"
+												: false;
+											const entryName = `__html_${moduleHash}_${nextEntryIndex++}`;
+											// Tag metadata so the template can mirror `crossorigin`/
+											// `integrity` onto a native `preload` `<link>` (integrity-
+											// eligible per the SRI spec). `prefetch` gets none — the spec
+											// doesn't list it — so its `integrity` is left uncaptured.
+											const isNativeLink = elementName === "link";
+											const dep = new HtmlEntryDependency(
+												request,
+												[s, e],
+												entryName,
+												asStyle ? "css-import" : undefined,
+												type,
+												elementStart,
+												tagEnd,
+												isNativeLink,
+												"",
+												nameEnd,
+												isNativeLink && path.findAttribute("crossorigin") !== 0,
+												-1,
+												type === "preload" && isNativeLink
+													? captureIntegrityRange(path, source, elementStart)
+													: null,
+												null
+											);
+											setLoc(dep, s, e);
+											module.addPresentationalDependency(dep);
+											(type === "preload"
+												? preloadEntries
+												: prefetchEntries
+											).push({
+												request,
+												entryName,
+												type,
+												css: asStyle
+											});
+											continue;
+										}
 										// `src`/`srcset`/`css-url`/`msapplication-task` are plain assets;
 										// the rest are narrowed to entry types here and share one
 										// `HtmlEntryDependency`, recorded for HtmlModulesPlugin.
@@ -1461,63 +1748,49 @@ class HtmlParser extends Parser {
 													}
 												}
 											}
+											// Blocking-ness of the tag as *emitted*:
+											// `reconcileScriptTypeAttr` upgrades every script entry
+											// to `type="module"` under `output.module` and strips an
+											// authored `type="module"` otherwise — so only non-module
+											// output without `defer`/`async` blocks. Non-native
+											// elements anchor conservatively (their synthesized
+											// siblings may be plain blocking `<script>`s).
 											if (
-												firstScriptStart === -1 &&
-												(type === "script" || type === "script-module")
+												firstBlockingScriptStart === -1 &&
+												(type === "script" || type === "script-module") &&
+												!outputModule &&
+												(elementName !== nativeTag ||
+													(path.findAttribute("defer") === 0 &&
+														path.findAttribute("async") === 0))
 											) {
-												firstScriptStart = elementStart;
+												firstBlockingScriptStart = elementStart;
 											}
 											// Sibling-clone attribute edits, captured from the parsed
 											// attributes (offsets relative to the tag) so the template
 											// needn't re-parse the tag text: `integrity` is dropped
 											// (content-specific) and `script-module` clones are forced
 											// to `type="module"` (its value range, else inserted).
-											/** @type {Range | null} */
-											let integrityRange = null;
+											const integrityRange =
+												elementStart >= 0 && elementName === nativeTag
+													? captureIntegrityRange(path, source, elementStart)
+													: null;
 											/** @type {Range | null} */
 											let typeValueRange = null;
-											if (elementStart >= 0 && elementName === nativeTag) {
-												const integrityAttr = path.findAttribute("integrity");
+											if (
+												elementStart >= 0 &&
+												elementName === nativeTag &&
+												elementKind === "script-module"
+											) {
+												const typeAttr = path.findAttribute("type");
 												if (
-													integrityAttr !== 0 &&
-													path.attributeNameStart(integrityAttr) >= 0
+													typeAttr !== 0 &&
+													path.attributeValueStart(typeAttr) >= 0
 												) {
-													let rs = path.attributeNameStart(integrityAttr);
-													while (
-														rs > 0 &&
-														isASCIIWhitespace(source.charCodeAt(rs - 1))
-													) {
-														rs--;
-													}
-													let re;
-													const ivs = path.attributeValueStart(integrityAttr);
-													if (ivs === -1) {
-														re = path.attributeNameEnd(integrityAttr);
-													} else {
-														const q = source.charCodeAt(ivs - 1);
-														const ive = path.attributeValueEnd(integrityAttr);
-														re =
-															q === CC_QUOTATION || q === CC_APOSTROPHE
-																? ive + 1
-																: ive;
-													}
-													integrityRange = [
-														rs - elementStart,
-														re - elementStart
+													typeValueRange = [
+														path.attributeValueStart(typeAttr) - elementStart,
+														path.attributeValueEnd(typeAttr) - elementStart
 													];
 												}
-												if (elementKind === "script-module") {
-													const typeAttr = path.findAttribute("type");
-													if (
-														typeAttr !== 0 &&
-														path.attributeValueStart(typeAttr) >= 0
-													) {
-														typeValueRange = [
-															path.attributeValueStart(typeAttr) - elementStart,
-															path.attributeValueEnd(typeAttr) - elementStart
-														];
-													}
-												}
 											}
 											const dep = new HtmlEntryDependency(
 												request,
@@ -1531,9 +1804,12 @@ class HtmlParser extends Parser {
 												copyableAttrsText,
 												nameEnd,
 												hasOwnCrossOrigin,
-												firstScriptStart,
+												firstBlockingScriptStart,
 												integrityRange,
-												typeValueRange
+												typeValueRange,
+												forceInline,
+												headSeen && headStart > 0 ? headStart : -1,
+												headSeen && headLastEnd > 0 ? headLastEnd : -1
 											);
 											setLoc(dep, s, e);
 											module.addPresentationalDependency(dep);
@@ -1559,6 +1835,16 @@ class HtmlParser extends Parser {
 											).push({ request, entryName, type });
 										} else {
 											const dep = new HtmlSourceDependency(request, [s, e]);
+											ResourceHintPlugin.applyDefaults(
+												dep,
+												ResourceHintPlugin.matchUrlHints(urlHints, request)
+											);
+											// `<!-- webpackPrefetch: true -->` (etc.) immediately
+											// before this tag wins over the project-wide default.
+											if (pendingHints) {
+												ResourceHintPlugin.applyParsedHints(dep, pendingHints);
+												pendingHints = undefined;
+											}
 											setLoc(dep, s, e);
 											module.addDependency(dep);
 											module.addCodeGenerationDependency(dep);
@@ -1569,15 +1855,76 @@ class HtmlParser extends Parser {
 							}
 						}
 					},
-					exit: () => {
+					exit: (path) => {
+						if (path.namespace() === NS_HTML) {
+							const name = path.tagName();
+							if (name === "template") {
+								if (templateDepth > 0) templateDepth--;
+								if (headTemplateDepth > 0) headTemplateDepth--;
+							} else if (name === "head") {
+								inHead = false;
+							}
+						}
 						pendingWebpackIgnore = undefined;
+						pendingWebpackInline = undefined;
+						pendingHints = undefined;
 					}
 				}
 			})
 			// Skip AST output this walk never reads: `text` (script/style bodies are
-			// read by offset via `contentEnd`) and `doctype`; keep `comments` for
+			// read by offset via `contentEnd`) and `doctype` — unless head injection
+			// needs the doctype as an insertion anchor; keep `comments` for
 			// magic comments (`webpackIgnore`).
-			.process(source, { skip: { text: true, doctype: true } });
+			.process(source, {
+				fragmentContext: this.fragmentContext,
+				skip: { text: true, doctype: headOptions === undefined }
+			});
+
+		// `output.html` head injection: existing tags win, injected values are
+		// escaped, insertions at the same offset are merged to keep their order.
+		if (headOptions !== undefined && headSeen) {
+			const { title, meta, base } = headOptions;
+			let startTags = "";
+			if (meta && meta.charset && headCharsetEnd === -1) {
+				startTags += `<meta charset="${escapeAttribute(meta.charset)}">`;
+			}
+			// <base> must follow the charset declaration per spec
+			let baseAfterCharset = "";
+			if (base && !headHasBase) {
+				if (headCharsetEnd !== -1) baseAfterCharset = baseTag(base);
+				else startTags += baseTag(base);
+			}
+			let endTags = "";
+			if (meta) {
+				for (const [name, value] of Object.entries(meta)) {
+					if (
+						name === "charset" ||
+						(headMetaNames !== undefined &&
+							headMetaNames.has(name.toLowerCase()))
+					) {
+						continue;
+					}
+					endTags += metaTag(name, value);
+				}
+			}
+			if (title && !headHasTitle) {
+				endTags += `<title>${escapeText(title)}</title>`;
+			}
+			/** @type {[number, string][]} */
+			const inserts = [];
+			if (startTags) inserts.push([headStart, startTags]);
+			if (baseAfterCharset) inserts.push([headCharsetEnd, baseAfterCharset]);
+			if (endTags) inserts.push([headLastEnd, endTags]);
+			inserts.sort((a, b) => a[0] - b[0]);
+			for (let i = 0; i < inserts.length; i++) {
+				const at = inserts[i][0];
+				let tags = inserts[i][1];
+				while (i + 1 < inserts.length && inserts[i + 1][0] === at) {
+					tags += inserts[++i][1];
+				}
+				module.addPresentationalDependency(new ConstDependency(tags, at));
+			}
+		}
 
 		const buildInfo = /** @type {HtmlModuleBuildInfo} */ (module.buildInfo);
 		buildInfo.strict = true;
@@ -1587,18 +1934,25 @@ class HtmlParser extends Parser {
 		// and `script-module` groups are chained via a leader-only dependOn
 		// so they share a runtime; `modulepreload` and `stylesheet` entries
 		// are emitted as independent entries since `<link rel=modulepreload>`
-		// must preload without running and stylesheets have no runtime.
+		// must preload without running and stylesheets have no runtime. `html`
+		// links are independent page entries too.
 		if (
 			scriptEntries.length > 0 ||
 			scriptModuleEntries.length > 0 ||
 			modulePreloadEntries.length > 0 ||
-			stylesheetEntries.length > 0
+			stylesheetEntries.length > 0 ||
+			htmlLinkEntries.length > 0 ||
+			preloadEntries.length > 0 ||
+			prefetchEntries.length > 0
 		) {
-			buildInfo.htmlEntryScripts = {
+			buildInfo.htmlEntries = {
 				script: scriptEntries,
 				"script-module": scriptModuleEntries,
 				modulepreload: modulePreloadEntries,
-				stylesheet: stylesheetEntries
+				stylesheet: stylesheetEntries,
+				html: htmlLinkEntries,
+				preload: preloadEntries,
+				prefetch: prefetchEntries
 			};
 		}
 
@@ -1611,4 +1965,6 @@ class HtmlParser extends Parser {
 	}
 }
 
+HtmlParser.buildHeadTags = buildHeadTags;
+
 module.exports = HtmlParser;