webpack 5.108.3 → 5.108.4

package/lib/css/syntax.js

@@ -297,6 +297,15 @@ const _isSpace = (cc) => cc === CC_SPACE || cc === CC_TAB;
 // rarer tab / newline tests.
 const _isWhiteSpace = (cc) => _isSpace(cc) || _isNewline(cc);
 
+// Whitespace membership table for the run-consumption loop — one load instead
+// of up to five compares per char. EOF (NaN) / non-ASCII index to undefined.
+const _wsTable = new Uint8Array(128);
+_wsTable[CC_SPACE] = 1;
+_wsTable[CC_TAB] = 1;
+_wsTable[CC_LINE_FEED] = 1;
+_wsTable[CC_CARRIAGE_RETURN] = 1;
+_wsTable[CC_FORM_FEED] = 1;
+
 /**
  * @param {number} cc char code
  * @returns {boolean} true, if cc is a digit
@@ -612,7 +621,7 @@ const fill = (out, type, start, end) => {
  */
 function consumeSpace(input, pos, out) {
 	const start = pos - 1;
-	while (_isWhiteSpace(input.charCodeAt(pos))) pos++;
+	while (_wsTable[input.charCodeAt(pos)] === 1) pos++;
 	return fill(out, TT_WHITESPACE, start, pos);
 }
 
@@ -1166,7 +1175,10 @@ const NodeType = {
 	Declaration: 23,
 	AtRule: 24,
 	QualifiedRule: 25,
-	Stylesheet: 26
+	Stylesheet: 26,
+	// Comments are never tree nodes; this type exists only so a `NodeType.Comment`
+	// visitor can be registered (fired during tokenization — see `grammar`).
+	Comment: 27
 };
 const {
 	Ident: T_IDENT,
@@ -1194,7 +1206,8 @@ const {
 	Declaration: T_DECLARATION,
 	AtRule: T_AT_RULE,
 	QualifiedRule: T_QUALIFIED_RULE,
-	Stylesheet: T_STYLESHEET
+	Stylesheet: T_STYLESHEET,
+	Comment: T_COMMENT
 } = NodeType;
 
 /**
@@ -1594,6 +1607,23 @@ _ttToNodeType[TT_CDC] = T_CDC;
 // Current loc converter for the active parse (object backend reads it).
 let _lc = /** @type {LocConverter} */ (/** @type {unknown} */ (null));
 
+// Active skip state (from `CssProcessOptions.skip`), applied by the grammar.
+// `_skipTypes` is indexed by `NodeType` (1 = skip): drop that component-value
+// leaf / container from declaration value and function-arg lists. The two
+// prelude flags scan a rule's prelude without materializing its tree (url tokens
+// / functions kept, so `url()` in a selector or `@import url(…)` still resolves).
+// A skipped node is still tokenized (positions stay correct) but never pushed,
+// so it is never walked or read — the caller must only skip what nothing reads.
+// `useObjectBackend` restores the defaults so `parseA*` build the full tree.
+const _NO_SKIP_TYPES = new Uint8Array(32);
+/** @type {Uint8Array} */
+let _skipTypes = _NO_SKIP_TYPES;
+// Fast-path flag: true only when a real skip set is active, so the (dominant)
+// no-skip parses pay one boolean test instead of a node-type lookup per value.
+let _skipActive = false;
+let _skipSelectorPrelude = false;
+let _skipAtRulePrelude = false;
+
 /** @type {(type: number, start: number, end: number) => Node} */
 let _mkLeaf;
 /** @type {(start: number, end: number, contentStart: number, contentEnd: number) => Node} */
@@ -1656,6 +1686,11 @@ const _objStylesheet = (start) => {
 /** @param {LocConverter} lc loc converter for this parse */
 const useObjectBackend = (lc) => {
 	_lc = lc;
+	// `parseA*` return the full tree, so nothing is skipped.
+	_skipTypes = _NO_SKIP_TYPES;
+	_skipActive = false;
+	_skipSelectorPrelude = false;
+	_skipAtRulePrelude = false;
 	_mkLeaf = _objLeaf;
 	_mkUrl = _objUrl;
 	_mkContainer = _objContainer;
@@ -1773,18 +1808,26 @@ const _soaGrow = (need) => {
 const _soaAlloc = (type, start, end) => {
 	// Ids are 1-based: a node ref is used in truthiness checks (`if (!parent)`),
 	// so 0 must stay reserved for "no node".
+	// Leaves never read the flag / list slots — `_soaAllocContainer` clears
+	// them instead, keeping the dominant leaf allocation at three writes.
 	const i = _soaN + 1;
 	if (i >= _soaCap) _soaGrow(i + 1);
 	_soaTy[i] = type;
 	_soaSt[i] = start;
 	_soaEn[i] = end;
+	_soaN = i;
+	return _ref(i);
+};
+/** @type {(type: number, start: number, end: number) => Node} */
+const _soaAllocContainer = (type, start, end) => {
+	const r = _soaAlloc(type, start, end);
+	const i = _ix(r);
 	_soaFl[i] = 0;
 	// Clear list slots so a reused id never exposes a previous node's children.
 	_soaL0[i] = null;
 	_soaL1[i] = null;
 	_soaL2[i] = null;
-	_soaN = i;
-	return _ref(i);
+	return r;
 };
 // Raw token value (the lazy `Token.value` form): hash / at-keyword drop their
 // one-char prefix, url uses its content range. Shared by the parser's
@@ -1816,8 +1859,8 @@ const useSoaBackend = (input, lc) => {
 		_soaA1[_ix(r)] = ce;
 		return r;
 	};
-	_mkContainer = (type, start, end) => _soaAlloc(type, start, end);
-	_mkStylesheet = (start) => _soaAlloc(T_STYLESHEET, start, start);
+	_mkContainer = (type, start, end) => _soaAllocContainer(type, start, end);
+	_mkStylesheet = (start) => _soaAllocContainer(T_STYLESHEET, start, start);
 	// name / nameStart are derived from start + nameEnd; only nameEnd is stored.
 	_setName = (r, v, ns, ne) => {
 		_soaA0[_ix(r)] = ne;
@@ -1918,12 +1961,12 @@ class TokenStream {
 		/** @type {number} */
 		this._commentHigh = pos;
 		// Single reused token the lexer writes into on the `next` path — see
-		// `MutableToken`. `_next` points at it when a token is cached, else
-		// `undefined` (re-tokenize on next read).
+		// `MutableToken`. `_hasNext` marks it cached — a boolean instead of an
+		// object slot, so caching a token never pays a GC write barrier.
 		/** @type {MutableToken} */
 		this._tok = createToken();
-		/** @type {MutableToken | undefined} the next token, lazily tokenized */
-		this._next = undefined;
+		/** @type {boolean} whether `_tok` holds the (lazily tokenized) next token */
+		this._hasNext = false;
 		/** @type {number[]} byte offsets to rewind to */
 		this._marks = [];
 	}
@@ -1937,14 +1980,14 @@ class TokenStream {
 	 * @returns {MutableToken} the next token
 	 */
 	next() {
-		if (this._next === undefined) {
+		if (!this._hasNext) {
 			const input = this.input;
 			const tok = this._tok;
 			let pos = this._pos;
 			for (;;) {
 				const t = readToken(input, pos, tok);
 				if (t === undefined) {
-					this._next = fill(tok, TT_EOF, input.length, input.length);
+					fill(tok, TT_EOF, input.length, input.length);
 					break;
 				}
 				if (t.type === TT_COMMENT) {
@@ -1955,11 +1998,11 @@ class TokenStream {
 					pos = t.end;
 					continue;
 				}
-				this._next = t;
 				break;
 			}
+			this._hasNext = true;
 		}
-		return /** @type {MutableToken} */ (this._next);
+		return this._tok;
 	}
 
 	/**
@@ -1972,7 +2015,7 @@ class TokenStream {
 		const t = this.next();
 		if (t.type !== TT_EOF) {
 			this._pos = t.end;
-			this._next = undefined;
+			this._hasNext = false;
 		}
 		return t;
 	}
@@ -1986,7 +2029,7 @@ class TokenStream {
 		const t = this.next();
 		if (t.type !== TT_EOF) {
 			this._pos = t.end;
-			this._next = undefined;
+			this._hasNext = false;
 		}
 	}
 
@@ -2006,7 +2049,7 @@ class TokenStream {
 	 */
 	restoreMark() {
 		this._pos = /** @type {number} */ (this._marks.pop());
-		this._next = undefined;
+		this._hasNext = false;
 	}
 
 	/**
@@ -2305,6 +2348,11 @@ const consumeAnAtRule = (ts, nested = false) => {
 	// declarations / childRules / blockStart (-1) / blockEnd (-1) keep their
 	// defaults (no block: the `;` / EOF / nested-`}` at-rule forms).
 
+	// Like `consumeAQualifiedRule`: skip mode scans the prelude without
+	// materializing it (url tokens / functions kept so `@import url(…)` still
+	// resolves); the block boundary is found by scanning, not the prelude nodes.
+	const skip = _skipAtRulePrelude;
+
 	// Process input
 	for (;;) {
 		const t = ts.next();
@@ -2325,7 +2373,8 @@ const consumeAnAtRule = (ts, nested = false) => {
 				_setEnd(rule, t.start);
 				return rule;
 			}
-			prelude.push(consumeATokenAsNode(ts));
+			const node = consumeATokenAsNode(ts);
+			if (!skip) prelude.push(node);
 			continue;
 		}
 		// <{-token>
@@ -2340,7 +2389,12 @@ const consumeAnAtRule = (ts, nested = false) => {
 
 		// anything else
 		// Consume a component value from input and append the returned value to rule’s prelude.
-		prelude.push(consumeAComponentValue(ts, t));
+		const node = consumeAComponentValue(ts, t);
+		if (!skip) {
+			prelude.push(node);
+		} else if (_nType(node) === T_FUNCTION || _nType(node) === T_URL) {
+			prelude.push(node);
+		}
 	}
 };
 
@@ -2376,6 +2430,13 @@ const consumeAQualifiedRule = (ts, stopToken, nested = false) => {
 	// declarations / childRules / blockStart (-1) / blockEnd (-1) keep their
 	// defaults (no block until a `{` is reached).
 
+	// Skip mode leaves `prelude` empty (selector text is recovered from the
+	// rule's byte range, not its nodes); `first`/`second` still track the first
+	// two non-whitespace tokens the `--foo: {` disambiguation below needs.
+	const skip = _skipSelectorPrelude;
+	let first = /** @type {Node} */ (/** @type {unknown} */ (0));
+	let second = /** @type {Node} */ (/** @type {unknown} */ (0));
+
 	// Process input
 	for (;;) {
 		const t = ts.next();
@@ -2389,7 +2450,13 @@ const consumeAQualifiedRule = (ts, stopToken, nested = false) => {
 		// This is a parse error. If nested is true, return nothing. Otherwise, consume a token and append the result to rule’s prelude.
 		else if (t.type === TT_RIGHT_CURLY_BRACKET) {
 			if (nested) return undefined;
-			prelude.push(consumeATokenAsNode(ts));
+			const node = consumeATokenAsNode(ts);
+			if (skip) {
+				if (!first) first = node;
+				else if (!second) second = node;
+			} else {
+				prelude.push(node);
+			}
 			continue;
 		}
 		// <{-token>
@@ -2399,23 +2466,25 @@ const consumeAQualifiedRule = (ts, stopToken, nested = false) => {
 		// (This disambiguates custom-property declarations from nested qualified rules — `--foo: { … }` at top level of a block is a declaration, not a rule.)
 		// Otherwise, consume a block from input, and let child rules be the result.
 		else if (t.type === TT_LEFT_CURLY_BRACKET) {
-			let firstIdx = 0;
-			/* istanbul ignore next -- @preserve: leading whitespace is discarded before the rule, so the prelude never starts with it */
-			while (
-				firstIdx < prelude.length &&
-				_nType(prelude[firstIdx]) === T_WHITESPACE
-			) {
-				firstIdx++;
-			}
-			let secondIdx = firstIdx + 1;
-			while (
-				secondIdx < prelude.length &&
-				_nType(prelude[secondIdx]) === T_WHITESPACE
-			) {
-				secondIdx++;
+			if (!skip) {
+				let firstIdx = 0;
+				/* istanbul ignore next -- @preserve: leading whitespace is discarded before the rule, so the prelude never starts with it */
+				while (
+					firstIdx < prelude.length &&
+					_nType(prelude[firstIdx]) === T_WHITESPACE
+				) {
+					firstIdx++;
+				}
+				let secondIdx = firstIdx + 1;
+				while (
+					secondIdx < prelude.length &&
+					_nType(prelude[secondIdx]) === T_WHITESPACE
+				) {
+					secondIdx++;
+				}
+				first = prelude[firstIdx];
+				second = prelude[secondIdx];
 			}
-			const first = prelude[firstIdx];
-			const second = prelude[secondIdx];
 			if (
 				first &&
 				_nType(first) === T_IDENT &&
@@ -2442,7 +2511,21 @@ const consumeAQualifiedRule = (ts, stopToken, nested = false) => {
 
 		// anything else
 		// Consume a component value from input and append the result to rule’s prelude.
-		prelude.push(consumeAComponentValue(ts, t));
+		const node = consumeAComponentValue(ts, t);
+		if (skip) {
+			// Keep only url-bearing nodes (url tokens, or functions that may hold a
+			// url like `:unknown(url(x))`) so the url visitor still rewrites them;
+			// other selector tokens have no non-modules consumer, so drop them.
+			const ty = _nType(node);
+			if (ty === T_FUNCTION || ty === T_URL) prelude.push(node);
+			// Track the first two non-whitespace tokens for the disambiguation above.
+			if (t.type !== TT_WHITESPACE) {
+				if (!first) first = node;
+				else if (!second) second = node;
+			}
+		} else {
+			prelude.push(node);
+		}
 	}
 };
 
@@ -2466,7 +2549,8 @@ const consumeABlock = (ts) => {
 };
 
 /**
- * 2-token lookahead: is the next non-whitespace pair `<ident> <colon>` (the prerequisite for consume-a-declaration steps 1 + 3)? Used by `consumeABlocksContents` to skip a declaration attempt that would otherwise call consume-the-remnants-of-a-bad-declaration and be undone by `restoreMark`. A webpack fast-path, not a spec algorithm — so the implementation is free to peek cheaply. It scans raw code points after the cached ident for the next significant one (skipping whitespace + comments) rather than tokenizing them, and never advances the stream: the ident stays cached in `_next` for `consumeADeclaration` to reuse instead of re-tokenizing the property name. Comments skipped here fire `onComment` later, when the chosen consume algorithm tokenizes past them (once, in source order, as before).
+ * 2-token lookahead: is the next non-whitespace pair `<ident> <colon>`?
+ * Peeks raw code points without advancing; comments still fire `onComment` later.
  * @param {TokenStream} ts token stream
  * @returns {boolean} true if consume-a-declaration's step 1 + step 3 would both succeed on the current input
  */
@@ -2710,12 +2794,28 @@ const consumeAListOfComponentValues = (ts, stopToken, nested = false) => {
 		// Otherwise, this is a parse error. Consume a token from input and append the result to values.
 		if (t.type === TT_RIGHT_CURLY_BRACKET) {
 			if (nested) return values;
-			values.push(consumeATokenAsNode(ts));
+			const closer = consumeATokenAsNode(ts);
+			// Keep unless the type is explicitly marked skip (1); an out-of-range
+			// lookup on a short `skip.types` yields `undefined`, which must not drop.
+			if (!_skipActive || _skipTypes[_nType(closer)] !== 1) values.push(closer);
 			continue;
 		}
 		// anything else
 		// Consume a component value from input, and append the result to values.
-		values.push(consumeAComponentValue(ts, t));
+		// Skipped leaf types short-circuit before materializing: no SoA slot is
+		// written and no node is built (blocks / functions never skip here).
+		const tt = t.type;
+		if (
+			_skipActive &&
+			tt !== TT_FUNCTION &&
+			!(tt >= TT_LEFT_PARENTHESIS && tt <= TT_LEFT_CURLY_BRACKET) &&
+			_skipTypes[_ttToNodeType[tt]] === 1
+		) {
+			ts.consume();
+			continue;
+		}
+		const node = consumeAComponentValue(ts, t);
+		if (!_skipActive || _skipTypes[_nType(node)] !== 1) values.push(node);
 	}
 };
 
@@ -2821,7 +2921,19 @@ const consumeAFunction = (ts) => {
 
 		// anything else
 		// Consume a component value from input and append the result to function’s value.
-		val.push(consumeAComponentValue(ts, t));
+		// Same pre-materialization skip as `consumeAListOfComponentValues`.
+		const tt = t.type;
+		if (
+			_skipActive &&
+			tt !== TT_FUNCTION &&
+			!(tt >= TT_LEFT_PARENTHESIS && tt <= TT_LEFT_CURLY_BRACKET) &&
+			_skipTypes[_ttToNodeType[tt]] === 1
+		) {
+			ts.consume();
+			continue;
+		}
+		const node = consumeAComponentValue(ts, t);
+		if (!_skipActive || _skipTypes[_nType(node)] !== 1) val.push(node);
 	}
 };
 
@@ -2999,11 +3111,10 @@ const unescapeIdentifier = makeCacheable(_unescapeIdentifier);
 // CSS-typed views over the generic visitor machinery (`util/SourceProcessor`),
 // re-exported so consumers keep importing them from this module.
 /**
- * @typedef {import("../util/SourceProcessor").VisitorContext} VisitorContext
- * @typedef {import("../util/SourceProcessor").VisitorFn<Node>} VisitorFn
- * @typedef {import("../util/SourceProcessor").VisitorBucket<Node>} VisitorBucket
- * @typedef {import("../util/SourceProcessor").VisitorMap<Node>} VisitorMap
- * @typedef {import("../util/SourceProcessor").CompiledVisitorMap<Node>} CompiledVisitorMap
+ * @typedef {import("../util/SourceProcessor").VisitorFn<CssPath>} VisitorFn
+ * @typedef {import("../util/SourceProcessor").VisitorBucket<CssPath>} VisitorBucket
+ * @typedef {import("../util/SourceProcessor").VisitorMap<CssPath>} VisitorMap
+ * @typedef {import("../util/SourceProcessor").CompiledVisitorMap<CssPath>} CompiledVisitorMap
  */
 
 /**
@@ -3027,9 +3138,17 @@ const TOP_LEVEL_CONSUMERS = {
 /**
  * @typedef {object} CssProcessOptions
  * @property {LocConverter=} locConverter shared loc converter (default a fresh one over the input)
- * @property {((input: string, start: number, end: number) => number)=} comment comment-token callback
  * @property {boolean=} recurseBlocks walk into block bodies' nested rules (default true)
  * @property {("stylesheet" | "block-contents")=} as which top-level production to consume the source as (see `TOP_LEVEL_CONSUMERS`): `"stylesheet"` (default) or `"block-contents"` (a block's contents, e.g. an HTML `style` attribute)
+ * @property {SkipOptions=} skip what the grammar may leave un-materialized to go faster — safe only for parts nothing reads in the active parse; default skip nothing
+ */
+
+/**
+ * `CssProcessOptions.skip`: two independent axes, so each reads unambiguously.
+ * @typedef {object} SkipOptions
+ * @property {Uint8Array=} types component-value node types to drop from declaration value / function-arg lists (indexed by `NodeType`, 1 = skip; build with `buildSkipSet`)
+ * @property {boolean=} selectorPrelude drop qualified-rule (selector) preludes — the rule and its block are still produced (default false)
+ * @property {boolean=} atRulePrelude drop at-rule preludes — the at-rule and its block are still produced (default false)
  */
 
 /**
@@ -3043,18 +3162,36 @@ const TOP_LEVEL_CONSUMERS = {
  * @param {CssProcessOptions} options process options
  */
 const grammar = (input, visitors, options) => {
-	const { comment } = options;
 	const locConverter = options.locConverter || new LocConverter(input);
 	useSoaBackend(input, locConverter);
+	const skip = options.skip;
+	_skipTypes = (skip && skip.types) || _NO_SKIP_TYPES;
+	_skipActive = _skipTypes !== _NO_SKIP_TYPES;
+	_skipSelectorPrelude = skip !== undefined && skip.selectorPrelude === true;
+	_skipAtRulePrelude = skip !== undefined && skip.atRulePrelude === true;
 	const recurseBlocks = options.recurseBlocks !== false;
 
-	// Babel's `path.skip()`, children-only. Reset per `enter` dispatch.
-	let skipFlag = false;
-	const visitorCtx = {
-		skipChildren() {
-			skipFlag = true;
-		}
-	};
+	// Comments reach the visitor map through `NodeType.Comment` instead of a
+	// side callback. They fire during tokenization — in source order among
+	// comments, not interleaved with the node walk — on a transient SoA node so
+	// `A.start`/`end`/`loc`/`source` work. No comment visitor → no callback →
+	// the tokenizer skips comments with zero overhead.
+	const commentBucket = visitors[T_COMMENT];
+	const onComment =
+		commentBucket === undefined
+			? undefined
+			: /** @type {(input: string, start: number, end: number) => number} */ (
+					(_input, start, end) => {
+						const node = _soaAlloc(T_COMMENT, start, end);
+						_curNode = node;
+						_curParent = null;
+						const e = commentBucket.enter;
+						for (let i = 0; i < e.length; i++) e[i](A);
+						const x = commentBucket.exit;
+						for (let i = 0; i < x.length; i++) x[i](A);
+						return end;
+					}
+				);
 
 	/**
 	 * Walk a component-value subtree; children are already materialized. Fetches
@@ -3068,19 +3205,24 @@ const grammar = (input, visitors, options) => {
 		const b = visitors[ty];
 		let skip = false;
 		if (b !== undefined && b.enter.length !== 0) {
-			skipFlag = false;
+			_walkSkip = false;
+			_curNode = node;
+			_curParent = parent;
 			const e = b.enter;
-			for (let i = 0; i < e.length; i++) e[i](node, parent, visitorCtx);
-			skip = skipFlag;
-			skipFlag = false;
+			for (let i = 0; i < e.length; i++) e[i](A);
+			skip = _walkSkip;
+			_walkSkip = false;
 		}
 		if (!skip && (ty === T_FUNCTION || ty === T_SIMPLE_BLOCK)) {
 			const v = /** @type {Node[]} */ (_soaL0[_ix(node)]);
 			for (let i = 0; i < v.length; i++) walkValue(v[i], node);
 		}
 		if (b !== undefined) {
+			// Rebind: descending into children moved the path.
+			_curNode = node;
+			_curParent = parent;
 			const x = b.exit;
-			for (let i = 0; i < x.length; i++) x[i](node, parent, visitorCtx);
+			for (let i = 0; i < x.length; i++) x[i](A);
 		}
 	};
 
@@ -3096,11 +3238,13 @@ const grammar = (input, visitors, options) => {
 		const b = visitors[ty];
 		let skip = false;
 		if (b !== undefined && b.enter.length !== 0) {
-			skipFlag = false;
+			_walkSkip = false;
+			_curNode = node;
+			_curParent = parent;
 			const e = b.enter;
-			for (let i = 0; i < e.length; i++) e[i](node, parent, visitorCtx);
-			skip = skipFlag;
-			skipFlag = false;
+			for (let i = 0; i < e.length; i++) e[i](A);
+			skip = _walkSkip;
+			_walkSkip = false;
 		}
 		if (!skip) {
 			if (ty === T_AT_RULE || ty === T_QUALIFIED_RULE) {
@@ -3121,22 +3265,35 @@ const grammar = (input, visitors, options) => {
 			}
 		}
 		if (b !== undefined) {
+			// Rebind: descending into children moved the path.
+			_curNode = node;
+			_curParent = parent;
 			const x = b.exit;
-			for (let i = 0; i < x.length; i++) x[i](node, parent, visitorCtx);
+			for (let i = 0; i < x.length; i++) x[i](A);
 		}
 	};
 
 	// Stream each top-level node (selected by `as`) to the walker the moment it's
 	// consumed, rather than collecting them first — so the whole AST is never
 	// held at once; peak heap is ~one top-level node's subtree.
-	const ts = new TokenStream(input, 0, locConverter, comment);
+	const ts = new TokenStream(input, 0, locConverter, onComment);
 	const consume =
 		TOP_LEVEL_CONSUMERS[options.as || "stylesheet"] ||
 		consumeAStylesheetsContents;
-	consume(ts, (node) => {
-		walkRule(node, null);
-		_soaN = 0;
-	});
+	try {
+		consume(ts, (node) => {
+			walkRule(node, null);
+			_soaN = 0;
+		});
+	} finally {
+		// Drop the module-level SoA references so the last parsed source (and
+		// its LocConverter / child lists) don't stay alive between parses.
+		_soaInput = "";
+		_soaLC = /** @type {LocConverter} */ (/** @type {unknown} */ (null));
+		_soaL0.length = 0;
+		_soaL1.length = 0;
+		_soaL2.length = 0;
+	}
 };
 
 /**
@@ -3144,17 +3301,55 @@ const grammar = (input, visitors, options) => {
  * `grammar`. Babel-style usage:
  *
  * ```
- * processor.use({ [NodeType.AtRule]: (at) => {}, [NodeType.Declaration]: { enter, exit } });
- * processor.process(source);
+ * new SourceProcessor({ skip }).use({ [NodeType.AtRule]: (path) => {} }).process(source);
  * ```
- * @extends {GenericSourceProcessor<Node, CssProcessOptions>}
+ * @extends {GenericSourceProcessor<CssPath, CssProcessOptions>}
  */
 class SourceProcessor extends GenericSourceProcessor {
-	constructor() {
-		super(grammar);
+	/**
+	 * @param {CssProcessOptions=} options default process options (`skip`, `as`, …) for every `process` call
+	 */
+	constructor(options) {
+		super(grammar, options);
 	}
 }
 
+/**
+ * Build a `SkipOptions.types` set (drop these component-value node types from
+ * value / function-arg lists) from a list of `NodeType`s. Preludes are separate
+ * (`SkipOptions.selectorPrelude` / `atRulePrelude`). The caller owns the safety
+ * contract: only pass types nothing reads in the intended parse. Two
+ * grammar-internal caveats beyond consumer needs: dropping both `Delim` and
+ * `Ident` loses `!important` detection, and dropping `SimpleBlock` loses the
+ * custom-property `{}`-value check (and its subtree). Precompute once per
+ * configuration and reuse across parses.
+ * @param {number[]} nodeTypes component-value node types to drop
+ * @returns {Uint8Array} skip-types set indexed by `NodeType`
+ */
+const buildSkipSet = (nodeTypes) => {
+	const set = new Uint8Array(32);
+	for (let i = 0; i < nodeTypes.length; i++) set[nodeTypes[i]] = 1;
+	return set;
+};
+
+/* eslint-disable jsdoc/require-template -- `A` below is the accessor const, not a type parameter */
+/**
+ * The CSS path (Babel's `path` shape): the AST accessor with the walk's
+ * current position on it — the single argument every visitor receives.
+ * @typedef {typeof A} CssPath
+ */
+/* eslint-enable jsdoc/require-template */
+
+// Babel's `path.skip()`, children-only: set by `A.skipChildren()` during an
+// `enter` dispatch, consumed by the walk.
+let _walkSkip = false;
+// The walk's current position (`A.node` / `A.parent` read these; module-level
+// so the accessor methods' defaults avoid self-referential `this` typing).
+/** @type {Node} */
+let _curNode = /** @type {Node} */ (/** @type {unknown} */ (0));
+/** @type {Node | null} */
+let _curParent = null;
+
 // AST field-access seam. Every AST-node field read by `CssParser` goes through
 // one of these accessors so the node representation can change underneath the
 // consumer without touching it. Today they are backed by the `Node` / `Token` /
@@ -3163,19 +3358,58 @@ class SourceProcessor extends GenericSourceProcessor {
 // consumer edit. `value` is the leaf-token string; container child lists are
 // `children` / `prelude` / `declarations` / `childRules`.
 const A = {
-	/** @type {(n: Node) => number} */
-	type: (n) => _soaTy[_ix(n)],
-	/** @type {(n: Node) => number} */
-	start: (n) => _soaSt[_ix(n)],
-	/** @type {(n: Node) => number} */
-	end: (n) => _soaEn[_ix(n)],
-	/** @type {(n: Node) => [number, number]} */
-	range: (n) => {
+	// === path position (rebound by the walk before every visitor call) ===
+	/**
+	 * @returns {Node} current node — only valid during a visitor callback
+	 */
+	get node() {
+		return _curNode;
+	},
+	/**
+	 * @returns {Node | null} enclosing node (null = a top-level node)
+	 */
+	get parent() {
+		return _curParent;
+	},
+	/** Stop the walk descending into the current node (enter only). */
+	skipChildren() {
+		_walkSkip = true;
+	},
+	// === field reads — `n` defaults to the current node ===
+	/**
+	 * @param {Node=} n node
+	 * @returns {number} node type
+	 */
+	type(n = _curNode) {
+		return _soaTy[_ix(n)];
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {number} start offset
+	 */
+	start(n = _curNode) {
+		return _soaSt[_ix(n)];
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {number} end offset
+	 */
+	end(n = _curNode) {
+		return _soaEn[_ix(n)];
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {[number, number]} start / end offsets
+	 */
+	range(n = _curNode) {
 		const i = _ix(n);
 		return [_soaSt[i], _soaEn[i]];
 	},
-	/** @type {(n: Node) => { start: { line: number, column: number }, end: { line: number, column: number } }} */
-	loc: (n) => {
+	/**
+	 * @param {Node=} n node
+	 * @returns {{ start: { line: number, column: number }, end: { line: number, column: number } }} source location
+	 */
+	loc(n = _curNode) {
 		const i = _ix(n);
 		const lc = _soaLC;
 		const s = lc.get(_soaSt[i]);
@@ -3187,23 +3421,37 @@ const A = {
 			end: { line: e.line, column: e.column }
 		};
 	},
-	/** @type {(n: Node) => string} */
-	source: (n) => {
+	/**
+	 * @param {Node=} n node
+	 * @returns {string} raw source slice
+	 */
+	source(n = _curNode) {
 		const i = _ix(n);
 		return _soaInput.slice(_soaSt[i], _soaEn[i]);
 	},
-	/** @type {(n: Node) => string} */
-	value: (n) => _soaValueOf(_ix(n)),
-	/** @type {(n: Node) => string} */
-	unescaped: (n) => {
+	/**
+	 * @param {Node=} n node
+	 * @returns {string} raw token value
+	 */
+	value(n = _curNode) {
+		return _soaValueOf(_ix(n));
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {string} unescaped token value
+	 */
+	unescaped(n = _curNode) {
 		const i = _ix(n);
 		const v = _soaValueOf(i);
 		return _soaTy[i] === T_STRING
 			? unescapeIdentifier(v.slice(1, -1))
 			: unescapeIdentifier(v);
 	},
-	/** @type {(n: Node) => string} */
-	typeFlag: (n) => {
+	/**
+	 * @param {Node=} n node
+	 * @returns {string} hash / numeric type flag
+	 */
+	typeFlag(n = _curNode) {
 		const i = _ix(n);
 		if (_soaTy[i] === T_HASH) {
 			const input = _soaInput;
@@ -3223,48 +3471,122 @@ const A = {
 			_soaTy[i] === T_DIMENSION ? v.slice(0, _consumeANumber(v, 0)) : v
 		);
 	},
-	/** @type {(n: Node) => number} */
-	contentStart: (n) => _soaA0[_ix(n)],
-	/** @type {(n: Node) => number} */
-	contentEnd: (n) => _soaA1[_ix(n)],
-	/** @type {(n: Node) => string} */
-	name: (n) => {
+	/**
+	 * @param {Node=} n node
+	 * @returns {number} url content start offset
+	 */
+	contentStart(n = _curNode) {
+		return _soaA0[_ix(n)];
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {number} url content end offset
+	 */
+	contentEnd(n = _curNode) {
+		return _soaA1[_ix(n)];
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {string} rule / declaration / function name
+	 */
+	name(n = _curNode) {
 		const i = _ix(n);
 		return _soaTy[i] === T_AT_RULE
 			? _soaInput.slice(_soaSt[i] + 1, _soaA0[i])
 			: _soaInput.slice(_soaSt[i], _soaA0[i]);
 	},
-	/** @type {(n: Node) => number} */
-	nameStart: (n) => _soaSt[_ix(n)],
-	/** @type {(n: Node) => number} */
-	nameEnd: (n) => _soaA0[_ix(n)],
-	/** @type {(n: Node) => string} */
-	unescapedName: (n) => unescapeIdentifier(A.name(n)),
-	/** @type {(n: Node) => ComponentValue[]} */
-	children: (n) => /** @type {ComponentValue[]} */ (_soaL0[_ix(n)]),
-	/** @type {(n: Node) => ComponentValue[]} */
-	prelude: (n) => /** @type {ComponentValue[]} */ (_soaL0[_ix(n)]),
-	/** @type {(n: Node) => Declaration[] | null} */
-	declarations: (n) => /** @type {Declaration[] | null} */ (_soaL1[_ix(n)]),
-	/** @type {(n: Node) => Rule[] | null} */
-	childRules: (n) => /** @type {Rule[] | null} */ (_soaL2[_ix(n)]),
-	/** @type {(n: Node) => number} */
-	blockStart: (n) => _soaA1[_ix(n)],
-	/** @type {(n: Node) => number} */
-	blockEnd: (n) => _soaA2[_ix(n)],
-	/** @type {(n: Node) => boolean} */
-	important: (n) => (_soaFl[_ix(n)] & 1) !== 0,
-	/** @type {(n: Node) => SimpleBlockToken} */
-	blockToken: (n) =>
-		/** @type {SimpleBlockToken} */ (_soaInput[_soaSt[_ix(n)]]),
+	/**
+	 * @param {Node=} n node
+	 * @returns {number} name start offset
+	 */
+	nameStart(n = _curNode) {
+		return _soaSt[_ix(n)];
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {number} name end offset
+	 */
+	nameEnd(n = _curNode) {
+		return _soaA0[_ix(n)];
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {string} unescaped name
+	 */
+	unescapedName(n = _curNode) {
+		return unescapeIdentifier(A.name(n));
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {ComponentValue[]} function / block children
+	 */
+	children(n = _curNode) {
+		return /** @type {ComponentValue[]} */ (_soaL0[_ix(n)]);
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {ComponentValue[]} rule prelude
+	 */
+	prelude(n = _curNode) {
+		return /** @type {ComponentValue[]} */ (_soaL0[_ix(n)]);
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {Declaration[] | null} block declarations
+	 */
+	declarations(n = _curNode) {
+		return /** @type {Declaration[] | null} */ (_soaL1[_ix(n)]);
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {Rule[] | null} block child rules
+	 */
+	childRules(n = _curNode) {
+		return /** @type {Rule[] | null} */ (_soaL2[_ix(n)]);
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {number} block start offset
+	 */
+	blockStart(n = _curNode) {
+		return _soaA1[_ix(n)];
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {number} block end offset
+	 */
+	blockEnd(n = _curNode) {
+		return _soaA2[_ix(n)];
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {boolean} `!important` flag
+	 */
+	important(n = _curNode) {
+		return (_soaFl[_ix(n)] & 1) !== 0;
+	},
+	/**
+	 * @param {Node=} n node
+	 * @returns {SimpleBlockToken} block opening token
+	 */
+	blockToken(n = _curNode) {
+		return /** @type {SimpleBlockToken} */ (_soaInput[_soaSt[_ix(n)]]);
+	},
 	// Writers — `CssParser` rewrites a rule's end / block-end when it folds an
-	// inline ICSS `:import` / `:export` body into a single dependency.
-	/** @type {(n: Node, v: number) => void} */
-	setEnd: (n, v) => {
+	// inline ICSS `:import` / `:export` body into a single dependency. The
+	// node stays explicit here: writes should never be implicit on position.
+	/**
+	 * @param {Node} n node
+	 * @param {number} v new end offset
+	 */
+	setEnd(n, v) {
 		_soaEn[_ix(n)] = v;
 	},
-	/** @type {(n: Node, v: number) => void} */
-	setBlockEnd: (n, v) => {
+	/**
+	 * @param {Node} n node
+	 * @param {number} v new block end offset
+	 */
+	setBlockEnd(n, v) {
 		_soaA2[_ix(n)] = v;
 	}
 };
@@ -3307,6 +3629,7 @@ module.exports.TT_URL = TT_URL;
 module.exports.TT_WHITESPACE = TT_WHITESPACE;
 module.exports.Token = Token;
 module.exports.TokenStream = TokenStream;
+module.exports.buildSkipSet = buildSkipSet;
 module.exports.equalsLowerCase = equalsLowerCase;
 module.exports.escapeIdentifier = escapeIdentifier;
 module.exports.parseABlocksContents = parseABlocksContents;