@linxiraos/pi-utils 1.1.27 → 1.2.0

package/src/dom/parser.ts

@@ -1,6 +1,14 @@
 import { Document, type DocumentFragment, Element, Text } from "./core";
 
-const RAW_TEXT_ELEMENTS: Record<string, true> = { script: true, style: true };
+/** Closing-tag patterns for raw-text elements, reused across parses (callers reset `lastIndex`). */
+const RAW_TEXT_CLOSE: Record<string, RegExp> = { script: /<\/script\s*>/gi, style: /<\/style\s*>/gi };
+const DOCTYPE_PATTERN = /<!doctype\b/iy;
+const TAG_NAME_PATTERN = /[^\s/>]+/y;
+const ATTRIBUTE_NAME_PATTERN = /[^\s=/>]+/y;
+const UNQUOTED_VALUE_PATTERN = /[^\s>]+/y;
+const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+
 const VOID_ELEMENTS: Record<string, true> = {
 	area: true,
 	base: true,
@@ -172,9 +180,12 @@ const NAMED_ENTITIES: Record<string, string> = {
 	yen: "¥",
 };
 
+const ENTITY_PATTERN = /&(#(?:x[0-9a-f]+|\d+)|[a-z][a-z0-9]+);/gi;
+
 /** Decode common named entities and all valid numeric character references. */
 export function decodeEntities(value: string): string {
-	return value.replace(/&(#(?:x[0-9a-f]+|\d+)|[a-z][a-z0-9]+);/gi, (whole, entity: string) => {
+	if (!value.includes("&")) return value;
+	return value.replace(ENTITY_PATTERN, (whole, entity: string) => {
 		if (entity[0] !== "#") return NAMED_ENTITIES[entity] ?? NAMED_ENTITIES[entity.toLowerCase()] ?? whole;
 		const hexadecimal = entity[1]?.toLowerCase() === "x";
 		const codePoint = Number.parseInt(entity.slice(hexadecimal ? 2 : 1), hexadecimal ? 16 : 10);
@@ -210,7 +221,8 @@ function parseStartTag(
 ): { name: string; attributes: Array<[string, string]>; selfClosing: boolean } | null {
 	let index = 0;
 	while (/\s/.test(source[index] ?? "")) index++;
-	const nameMatch = /^[^\s/>]+/.exec(source.slice(index));
+	TAG_NAME_PATTERN.lastIndex = index;
+	const nameMatch = TAG_NAME_PATTERN.exec(source);
 	if (!nameMatch) return null;
 	const name = nameMatch[0].toLowerCase();
 	index += nameMatch[0].length;
@@ -222,7 +234,8 @@ function parseStartTag(
 			selfClosing = true;
 			break;
 		}
-		const attributeMatch = /^[^\s=/>]+/.exec(source.slice(index));
+		ATTRIBUTE_NAME_PATTERN.lastIndex = index;
+		const attributeMatch = ATTRIBUTE_NAME_PATTERN.exec(source);
 		if (!attributeMatch) break;
 		const attributeName = attributeMatch[0];
 		index += attributeMatch[0].length;
@@ -243,7 +256,8 @@ function parseStartTag(
 					index = end + 1;
 				}
 			} else {
-				const valueMatch = /^[^\s>]+/.exec(source.slice(index));
+				UNQUOTED_VALUE_PATTERN.lastIndex = index;
+				const valueMatch = UNQUOTED_VALUE_PATTERN.exec(source);
 				value = valueMatch?.[0] ?? "";
 				index += value.length;
 			}
@@ -266,7 +280,8 @@ function closeOptionalElements(stack: Element[], incoming: string): void {
 	if (closeable?.includes(current.localName)) stack.pop();
 }
 
-function parseInto(html: string, document: Document, root: Document | DocumentFragment, contextTag?: string): void {
+/** Parse markup, appending the resulting nodes to `root` (a document, fragment, or element). */
+export function parseInto(html: string, document: Document, root: Document | DocumentFragment | Element): void {
 	const stack: Element[] = [];
 	const xmlLike = root instanceof Document && /^\s*(?:<\?xml[\s\S]*?\?>\s*)?<(?:feed|rss)\b/i.test(html);
 	let parent: Document | DocumentFragment | Element = root;
@@ -286,7 +301,7 @@ function parseInto(html: string, document: Document, root: Document | DocumentFr
 			index = end;
 			continue;
 		}
-		if (/^<!doctype\b/i.test(html.slice(index))) {
+		if (html[index + 1] === "!" && isDoctypeAt(html, index)) {
 			const end = html.indexOf(">", index + 2);
 			index = end < 0 ? html.length : end + 1;
 			continue;
@@ -325,12 +340,13 @@ function parseInto(html: string, document: Document, root: Document | DocumentFr
 		}
 		closeOptionalElements(stack, parsed.name);
 		parent = stack[stack.length - 1] ?? root;
+		// The root itself never supplies a namespace: fragments and documents are namespace-less, and
+		// element roots (innerHTML) parse their top-level nodes as HTML like a detached fragment would.
 		const namespace =
-			parent instanceof Element && parent.namespaceURI === "http://www.w3.org/2000/svg"
-				? "http://www.w3.org/2000/svg"
-				: parsed.name === "svg"
-					? "http://www.w3.org/2000/svg"
-					: "http://www.w3.org/1999/xhtml";
+			(parent !== root && parent instanceof Element && parent.namespaceURI === SVG_NAMESPACE) ||
+			parsed.name === "svg"
+				? SVG_NAMESPACE
+				: HTML_NAMESPACE;
 		const element = document.createElementNS(namespace, parsed.name);
 		for (let attributeIndex = parsed.attributes.length - 1; attributeIndex >= 0; attributeIndex--) {
 			const [name, value] = parsed.attributes[attributeIndex];
@@ -338,8 +354,11 @@ function parseInto(html: string, document: Document, root: Document | DocumentFr
 		}
 		parent.appendChild(element);
 		index = end + 1;
-		if (RAW_TEXT_ELEMENTS[parsed.name] && !parsed.selfClosing) {
-			const closePattern = new RegExp(`</${parsed.name}\\s*>`, "ig");
+		if (RAW_TEXT_CLOSE[parsed.name] && !parsed.selfClosing) {
+			// Prototype keys (e.g. `<constructor>`) were historically treated as raw text too; keep that.
+			const closePattern = Object.hasOwn(RAW_TEXT_CLOSE, parsed.name)
+				? RAW_TEXT_CLOSE[parsed.name]
+				: new RegExp(`</${parsed.name}\\s*>`, "ig");
 			closePattern.lastIndex = index;
 			const match = closePattern.exec(html);
 			const rawEnd = match?.index ?? html.length;
@@ -347,18 +366,22 @@ function parseInto(html: string, document: Document, root: Document | DocumentFr
 			index = match ? closePattern.lastIndex : html.length;
 			continue;
 		}
-		if (!VOID_ELEMENTS[parsed.name] && !(namespace === "http://www.w3.org/2000/svg" && parsed.selfClosing)) {
+		if (!VOID_ELEMENTS[parsed.name] && !(namespace === SVG_NAMESPACE && parsed.selfClosing)) {
 			stack.push(element);
 			parent = element;
 		}
 	}
-	void contextTag;
 }
 
-/** Parse markup into a document fragment. */
-export function parseFragment(html: string, document: Document, contextTag?: string): DocumentFragment {
+function isDoctypeAt(html: string, index: number): boolean {
+	DOCTYPE_PATTERN.lastIndex = index;
+	return DOCTYPE_PATTERN.test(html);
+}
+
+/** Parse markup into a document fragment. `_contextTag` is accepted for compatibility and ignored. */
+export function parseFragment(html: string, document: Document, _contextTag?: string): DocumentFragment {
 	const fragment = document.createDocumentFragment();
-	parseInto(html, document, fragment, contextTag);
+	parseInto(html, document, fragment);
 	return fragment;
 }
 

package/src/dom/selector.ts

@@ -1,10 +1,69 @@
 import { type Document, type DocumentFragment, Element, Node } from "./core";
 
+interface AttributeTest {
+	name: string;
+	operator: string | undefined;
+	value: string;
+	ignoreCase: boolean;
+}
+
+type NthTest =
+	| { kind: "odd" | "even" | "invalid" }
+	| { kind: "index"; index: number }
+	| { kind: "formula"; coefficient: number; offset: number };
+
+interface PseudoTest {
+	name: string;
+	/** Compiled argument for `:not`, `:is`, `:where`. */
+	list: SelectorList | null;
+	nth: NthTest | null;
+}
+
+interface CompoundSelector {
+	/** Lower-cased tag name, or null for any element. */
+	tag: string | null;
+	ids: string[];
+	classes: string[];
+	attributes: AttributeTest[];
+	pseudos: PseudoTest[];
+	/** Malformed or unsupported compounds never match. */
+	invalid: boolean;
+	/** Whether only `tag` (or nothing) constrains the compound. */
+	bare: boolean;
+}
+
 interface ComplexSelector {
-	simples: string[];
+	compounds: CompoundSelector[];
 	combinators: string[];
 }
 
+interface SelectorList {
+	/** A bare `*` part matches every element. */
+	universal: boolean;
+	/** Bare tag parts, matched by `localName`. */
+	tags: Set<string> | null;
+	complexes: ComplexSelector[];
+}
+
+const SUPPORTED_PSEUDOS: Record<string, true> = {
+	not: true,
+	is: true,
+	where: true,
+	"first-child": true,
+	"last-child": true,
+	"only-child": true,
+	empty: true,
+	root: true,
+	"nth-child": true,
+	"first-of-type": true,
+	"last-of-type": true,
+};
+const ATTRIBUTE_PATTERN =
+	/^\s*([^\s~|^$*!=]+)\s*(?:(\^=|\$=|\*=|~=|\|=|=)\s*(?:(["'])(.*?)\3|([^\s]+))\s*([isIS])?)?\s*$/;
+const IDENTIFIER_CHARACTER = /[a-zA-Z0-9_-]/;
+const MAX_CACHED_SELECTORS = 512;
+const compiledSelectors = new Map<string, SelectorList>();
+
 function splitTopLevel(value: string, delimiter: string): string[] {
 	const parts: string[] = [];
 	let start = 0;
@@ -31,7 +90,7 @@ function splitTopLevel(value: string, delimiter: string): string[] {
 	return parts.filter(Boolean);
 }
 
-function parseComplex(selector: string): ComplexSelector {
+function splitComplex(selector: string): { simples: string[]; combinators: string[] } {
 	const simples: string[] = [];
 	const combinators: string[] = [];
 	let current = "";
@@ -92,7 +151,7 @@ function readIdentifier(source: string, start: number): { value: string; end: nu
 			index += 2;
 			continue;
 		}
-		if (!/[a-zA-Z0-9_-]/.test(character)) break;
+		if (!IDENTIFIER_CHARACTER.test(character)) break;
 		value += character;
 		index++;
 	}
@@ -113,22 +172,166 @@ function findClosing(source: string, start: number, opener: string, closer: stri
 	return source.length - 1;
 }
 
-function matchAttribute(element: Element, expression: string): boolean {
-	const match = /^\s*([^\s~|^$*!=]+)\s*(?:(\^=|\$=|\*=|~=|\|=|=)\s*(?:(["'])(.*?)\3|([^\s]+))\s*([isIS])?)?\s*$/.exec(
-		expression,
-	);
-	if (!match) return false;
+function compileAttribute(expression: string): AttributeTest | null {
+	const match = ATTRIBUTE_PATTERN.exec(expression);
+	if (!match) return null;
 	const [, name, operator, , quotedValue, bareValue, flag] = match;
-	const actual = element.getAttribute(name);
-	if (!operator) return actual !== null;
-	if (actual === null) return false;
-	let left = actual;
-	let right = (quotedValue ?? bareValue ?? "").replace(/\\(.)/g, "$1");
-	if (flag?.toLowerCase() === "i") {
-		left = left.toLowerCase();
-		right = right.toLowerCase();
+	const ignoreCase = flag?.toLowerCase() === "i";
+	const value = (quotedValue ?? bareValue ?? "").replace(/\\(.)/g, "$1");
+	return { name, operator, value: ignoreCase ? value.toLowerCase() : value, ignoreCase };
+}
+
+function compileNth(expression: string): NthTest {
+	const normalized = expression.trim().toLowerCase().replace(/\s+/g, "");
+	if (normalized === "odd" || normalized === "even") return { kind: normalized };
+	if (/^[+-]?\d+$/.test(normalized)) return { kind: "index", index: Number(normalized) };
+	const match = /^([+-]?\d*)n([+-]\d+)?$/.exec(normalized);
+	if (!match) return { kind: "invalid" };
+	const coefficient = match[1] === "" || match[1] === "+" ? 1 : match[1] === "-" ? -1 : Number(match[1]);
+	return { kind: "formula", coefficient, offset: Number(match[2] ?? 0) };
+}
+
+function compilePseudo(name: string, argument: string | undefined): PseudoTest | null {
+	if (!SUPPORTED_PSEUDOS[name]) return null;
+	if (name === "not" || name === "is" || name === "where") {
+		return argument === undefined ? null : { name, list: compileSelector(argument), nth: null };
+	}
+	if (name === "nth-child") return argument === undefined ? null : { name, list: null, nth: compileNth(argument) };
+	return { name, list: null, nth: null };
+}
+
+function compileCompound(selector: string): CompoundSelector {
+	const compound: CompoundSelector = {
+		tag: null,
+		ids: [],
+		classes: [],
+		attributes: [],
+		pseudos: [],
+		invalid: false,
+		bare: false,
+	};
+	let index = 0;
+	if (selector[index] === "*") index++;
+	else if (/[a-zA-Z_]/.test(selector[index] ?? "")) {
+		const tag = readIdentifier(selector, index);
+		compound.tag = tag.value.toLowerCase();
+		index = tag.end;
+	}
+	while (index < selector.length) {
+		const marker = selector[index];
+		if (marker === "#" || marker === ".") {
+			const identifier = readIdentifier(selector, index + 1);
+			if (!identifier.value) {
+				compound.invalid = true;
+				break;
+			}
+			(marker === "#" ? compound.ids : compound.classes).push(identifier.value);
+			index = identifier.end;
+			continue;
+		}
+		if (marker === "[") {
+			const end = findClosing(selector, index, "[", "]");
+			const attribute = compileAttribute(selector.slice(index + 1, end));
+			if (!attribute) {
+				compound.invalid = true;
+				break;
+			}
+			compound.attributes.push(attribute);
+			index = end + 1;
+			continue;
+		}
+		if (marker === ":") {
+			const identifier = readIdentifier(selector, index + 1);
+			let argument: string | undefined;
+			index = identifier.end;
+			if (selector[index] === "(") {
+				const end = findClosing(selector, index, "(", ")");
+				argument = selector.slice(index + 1, end);
+				index = end + 1;
+			}
+			const pseudo = compilePseudo(identifier.value.toLowerCase(), argument);
+			if (!pseudo) {
+				compound.invalid = true;
+				break;
+			}
+			compound.pseudos.push(pseudo);
+			continue;
+		}
+		compound.invalid = true;
+		break;
+	}
+	compound.bare =
+		!compound.invalid &&
+		compound.ids.length === 0 &&
+		compound.classes.length === 0 &&
+		compound.attributes.length === 0 &&
+		compound.pseudos.length === 0;
+	return compound;
+}
+
+function compileSelector(selector: string): SelectorList {
+	const cached = compiledSelectors.get(selector);
+	if (cached) return cached;
+	const list: SelectorList = { universal: false, tags: null, complexes: [] };
+	for (const part of splitTopLevel(selector, ",")) {
+		const { simples, combinators } = splitComplex(part);
+		if (!simples.length) continue;
+		const compounds = simples.map(compileCompound);
+		const only = compounds[0];
+		if (compounds.length === 1 && only.bare) {
+			if (only.tag === null) list.universal = true;
+			else (list.tags ??= new Set()).add(only.tag);
+			continue;
+		}
+		list.complexes.push({ compounds, combinators });
+	}
+	if (compiledSelectors.size >= MAX_CACHED_SELECTORS) compiledSelectors.clear();
+	compiledSelectors.set(selector, list);
+	return list;
+}
+
+function isWhitespace(code: number): boolean {
+	return (
+		code === 0x20 ||
+		(code >= 0x09 && code <= 0x0d) ||
+		code === 0xa0 ||
+		code === 0x1680 ||
+		(code >= 0x2000 && code <= 0x200a) ||
+		code === 0x2028 ||
+		code === 0x2029 ||
+		code === 0x202f ||
+		code === 0x205f ||
+		code === 0x3000 ||
+		code === 0xfeff
+	);
+}
+
+/** Whether a whitespace-separated class string contains a token, without splitting it. */
+export function hasClassToken(className: string, token: string): boolean {
+	if (!token) return false;
+	for (let index = 0; index < token.length; index++) if (isWhitespace(token.charCodeAt(index))) return false;
+	let from = 0;
+	while (true) {
+		const found = className.indexOf(token, from);
+		if (found < 0) return false;
+		const end = found + token.length;
+		if (
+			(found === 0 || isWhitespace(className.charCodeAt(found - 1))) &&
+			(end === className.length || isWhitespace(className.charCodeAt(end)))
+		) {
+			return true;
+		}
+		from = found + 1;
 	}
-	switch (operator) {
+}
+
+function matchAttribute(element: Element, test: AttributeTest): boolean {
+	const actual = element.getAttribute(test.name);
+	if (!test.operator) return actual !== null;
+	if (actual === null) return false;
+	const left = test.ignoreCase ? actual.toLowerCase() : actual;
+	const right = test.value;
+	switch (test.operator) {
 		case "=":
 			return left === right;
 		case "^=":
@@ -146,41 +349,67 @@ function matchAttribute(element: Element, expression: string): boolean {
 	}
 }
 
-function matchNth(element: Element, expression: string): boolean {
-	const siblings = element.parentElement?.children ?? [];
-	const index = siblings.indexOf(element) + 1;
-	const normalized = expression.trim().toLowerCase().replace(/\s+/g, "");
-	if (normalized === "odd") return index % 2 === 1;
-	if (normalized === "even") return index % 2 === 0;
-	if (/^[+-]?\d+$/.test(normalized)) return index === Number(normalized);
-	const match = /^([+-]?\d*)n([+-]\d+)?$/.exec(normalized);
-	if (!match) return false;
-	const coefficient = match[1] === "" || match[1] === "+" ? 1 : match[1] === "-" ? -1 : Number(match[1]);
-	const offset = Number(match[2] ?? 0);
-	return coefficient === 0
-		? index === offset
-		: (index - offset) / coefficient >= 0 && Number.isInteger((index - offset) / coefficient);
+/** One-based position among element siblings, or 0 without a parent element. */
+function elementIndex(element: Element): number {
+	const parent = element.parentElement;
+	if (!parent) return 0;
+	let index = 0;
+	for (const sibling of parent.childNodes) {
+		if (!(sibling instanceof Element)) continue;
+		index++;
+		if (sibling === element) return index;
+	}
+	return 0;
+}
+
+function matchNth(element: Element, test: NthTest): boolean {
+	if (test.kind === "invalid") return false;
+	const index = elementIndex(element);
+	switch (test.kind) {
+		case "odd":
+			return index % 2 === 1;
+		case "even":
+			return index % 2 === 0;
+		case "index":
+			return index === test.index;
+		case "formula":
+			return test.coefficient === 0
+				? index === test.offset
+				: (index - test.offset) / test.coefficient >= 0 &&
+						Number.isInteger((index - test.offset) / test.coefficient);
+	}
+}
+
+function hasSingleElementChild(parent: Element): boolean {
+	let count = 0;
+	for (const child of parent.childNodes) if (child instanceof Element && ++count > 1) return false;
+	return count === 1;
 }
 
-function matchPseudo(element: Element, name: string, argument: string | undefined): boolean {
-	switch (name) {
+function matchPseudo(element: Element, pseudo: PseudoTest): boolean {
+	switch (pseudo.name) {
 		case "not":
-			return argument !== undefined && !matchesSelector(element, argument);
+			return !matchesList(element, pseudo.list as SelectorList);
 		case "is":
 		case "where":
-			return argument !== undefined && matchesSelector(element, argument);
+			return matchesList(element, pseudo.list as SelectorList);
 		case "first-child":
 			return element.parentElement?.firstElementChild === element;
 		case "last-child":
 			return element.parentElement?.lastElementChild === element;
-		case "only-child":
-			return element.parentElement?.children.length === 1;
+		case "only-child": {
+			const parent = element.parentElement;
+			return parent !== null && hasSingleElementChild(parent);
+		}
 		case "empty":
-			return element.childNodes.every(child => child.nodeType === Node.COMMENT_NODE || child.textContent === "");
+			return (
+				!element.hasChildNodes() ||
+				element.childNodes.every(child => child.nodeType === Node.COMMENT_NODE || child.textContent === "")
+			);
 		case "root":
 			return element.ownerDocument?.documentElement === element;
 		case "nth-child":
-			return argument !== undefined && matchNth(element, argument);
+			return matchNth(element, pseudo.nth as NthTest);
 		case "first-of-type": {
 			for (let sibling = element.previousElementSibling; sibling; sibling = sibling.previousElementSibling) {
 				if (sibling.tagName === element.tagName) return false;
@@ -198,57 +427,30 @@ function matchPseudo(element: Element, name: string, argument: string | undefine
 	}
 }
 
-function matchSimple(element: Element, selector: string): boolean {
-	let index = 0;
-	if (selector[index] === "*") index++;
-	else if (/[a-zA-Z_]/.test(selector[index] ?? "")) {
-		const tag = readIdentifier(selector, index);
-		if (element.localName !== tag.value.toLowerCase()) return false;
-		index = tag.end;
-	}
-	while (index < selector.length) {
-		const marker = selector[index];
-		if (marker === "#" || marker === ".") {
-			const identifier = readIdentifier(selector, index + 1);
-			if (!identifier.value) return false;
-			if (marker === "#" ? element.id !== identifier.value : !element.classList.contains(identifier.value))
-				return false;
-			index = identifier.end;
-			continue;
-		}
-		if (marker === "[") {
-			const end = findClosing(selector, index, "[", "]");
-			if (!matchAttribute(element, selector.slice(index + 1, end))) return false;
-			index = end + 1;
-			continue;
-		}
-		if (marker === ":") {
-			const identifier = readIdentifier(selector, index + 1);
-			let argument: string | undefined;
-			index = identifier.end;
-			if (selector[index] === "(") {
-				const end = findClosing(selector, index, "(", ")");
-				argument = selector.slice(index + 1, end);
-				index = end + 1;
-			}
-			if (!matchPseudo(element, identifier.value.toLowerCase(), argument)) return false;
-			continue;
-		}
-		return false;
+function matchCompound(element: Element, compound: CompoundSelector): boolean {
+	if (compound.invalid) return false;
+	if (compound.tag !== null && element.localName !== compound.tag) return false;
+	if (compound.bare) return true;
+	for (const id of compound.ids) if (element.id !== id) return false;
+	if (compound.classes.length) {
+		const className = element.className;
+		for (const token of compound.classes) if (!hasClassToken(className, token)) return false;
 	}
+	for (const attribute of compound.attributes) if (!matchAttribute(element, attribute)) return false;
+	for (const pseudo of compound.pseudos) if (!matchPseudo(element, pseudo)) return false;
 	return true;
 }
 
 function matchComplexAt(element: Element, complex: ComplexSelector, index: number): boolean {
-	if (!matchSimple(element, complex.simples[index])) return false;
+	if (!matchCompound(element, complex.compounds[index])) return false;
 	if (index === 0) return true;
 	const combinator = complex.combinators[index - 1] ?? " ";
 	if (combinator === ">")
 		return element.parentElement !== null && matchComplexAt(element.parentElement, complex, index - 1);
-	if (combinator === "+")
-		return (
-			element.previousElementSibling !== null && matchComplexAt(element.previousElementSibling, complex, index - 1)
-		);
+	if (combinator === "+") {
+		const previous = element.previousElementSibling;
+		return previous !== null && matchComplexAt(previous, complex, index - 1);
+	}
 	if (combinator === "~") {
 		for (let sibling = element.previousElementSibling; sibling; sibling = sibling.previousElementSibling) {
 			if (matchComplexAt(sibling, complex, index - 1)) return true;
@@ -261,30 +463,61 @@ function matchComplexAt(element: Element, complex: ComplexSelector, index: numbe
 	return false;
 }
 
+function matchesList(element: Element, list: SelectorList): boolean {
+	if (list.universal) return true;
+	if (list.tags?.has(element.localName)) return true;
+	for (const complex of list.complexes) {
+		if (matchComplexAt(element, complex, complex.compounds.length - 1)) return true;
+	}
+	return false;
+}
+
+function collectMatches(nodes: Node[], list: SelectorList, result: Element[]): void {
+	for (let index = 0; index < nodes.length; index++) {
+		const node = nodes[index];
+		if (node instanceof Element && matchesList(node, list)) result.push(node);
+		if (node.hasChildNodes()) collectMatches(node.childNodes, list, result);
+	}
+}
+
+function findMatch(nodes: Node[], list: SelectorList): Element | null {
+	for (let index = 0; index < nodes.length; index++) {
+		const node = nodes[index];
+		if (node instanceof Element && matchesList(node, list)) return node;
+		if (node.hasChildNodes()) {
+			const found = findMatch(node.childNodes, list);
+			if (found) return found;
+		}
+	}
+	return null;
+}
+
 /** Whether an element matches a CSS selector list. */
 export function matchesSelector(element: Element, selector: string): boolean {
-	for (const part of splitTopLevel(selector, ",")) {
-		const complex = parseComplex(part);
-		if (complex.simples.length && matchComplexAt(element, complex, complex.simples.length - 1)) return true;
+	return matchesList(element, compileSelector(selector));
+}
+
+/** Nearest inclusive ancestor of an element matching a CSS selector list. */
+export function closestMatching(element: Element, selector: string): Element | null {
+	const list = compileSelector(selector);
+	for (let current: Element | null = element; current; current = current.parentElement) {
+		if (matchesList(current, list)) return current;
 	}
-	return false;
+	return null;
 }
 
 /** Query descendants of a node in document order. */
 export function querySelectorAllFrom(
 	root: Document | DocumentFragment | Element,
 	selector: string,
-	includeRoot: boolean,
+	_includeRoot: boolean,
 ): Element[] {
 	const result: Element[] = [];
-	const visit = (node: Node): void => {
-		if (node instanceof Element && matchesSelector(node, selector)) result.push(node);
-		for (const child of node.childNodes) visit(child);
-	};
-	if (includeRoot) {
-		for (const child of root.childNodes) visit(child);
-	} else {
-		for (const child of root.childNodes) visit(child);
-	}
+	if (root.hasChildNodes()) collectMatches(root.childNodes, compileSelector(selector), result);
 	return result;
 }
+
+/** First descendant of a node in document order matching a selector, stopping at the first match. */
+export function querySelectorFrom(root: Document | DocumentFragment | Element, selector: string): Element | null {
+	return root.hasChildNodes() ? findMatch(root.childNodes, compileSelector(selector)) : null;
+}

package/src/fetch-retry.ts

@@ -382,6 +382,8 @@ export async function fetchWithRetry(
 		if (hint !== undefined && hint > maxDelayMs) return response;
 
 		const delayMs = Math.min(hint ?? resolveDefaultDelay(defaultDelayMs, attempt, maxDelayMs), maxDelayMs);
+		// The retried response is discarded; release its unread tee branch.
+		if (!response.bodyUsed) response.body?.cancel().catch(() => {});
 		await waitForRetry(delayMs, signal);
 	}
 }

package/src/format.ts

@@ -10,7 +10,11 @@ const DAY = 24 * HOUR;
 export function formatDuration(ms: number): string {
 	if (!Number.isFinite(ms) || ms <= 0) return "0ms";
 	if (ms < SEC) return `${Math.floor(ms)}ms`;
-	if (ms < MIN) return `${(ms / SEC).toFixed(1)}s`;
+	if (ms < MIN) {
+		// Round to tenths first: `toFixed(1)` alone turns 59.95s+ into an impossible `60.0s`.
+		const tenths = Math.round(ms / 100);
+		return tenths < 600 ? `${(tenths / 10).toFixed(1)}s` : "1m";
+	}
 	if (ms < HOUR) {
 		const mins = Math.floor(ms / MIN);
 		const secs = Math.floor((ms % MIN) / SEC);