@adguard/agtree 3.4.3 → 4.0.1

package/dist/parser/cosmetic/selector/handlers/complex-selector-handler.js

@@ -0,0 +1,67 @@
+/*
+ * AGTree v4.0.1 (build date: Thu, 19 Feb 2026 05:13:05 GMT)
+ * (c) 2026 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { getFormattedTokenName } from '@adguard/css-tokenizer';
+import { sprintf } from 'sprintf-js';
+import { AdblockSyntaxError } from '../../../../errors/adblock-syntax-error.js';
+import { CompoundSelectorHandler } from './compound-selector-handler.js';
+
+/**
+ * Handles complex selector parsing in selector list.
+ */
+class ComplexSelectorHandler {
+    /**
+     * Finishes the current complex selector by:
+     * 1. Finishing current compound selector node via {@link CompoundSelectorHandler},
+     * 2. Validating current complex selector node,
+     * 3. Appending current complex selector node to the selector list node,
+     * If `isEof` is `false`:
+     * 4. Constructing next complex selector node.
+     *
+     * @param context Selector list parser context.
+     * @param isEof Indicates whether the end of the file has been reached.
+     *
+     * @throws If the current compound / complex selector has no simple selectors / compound selectors.
+     */
+    static handle(context, isEof = true) {
+        const { raw, options, baseOffset, stream, token, result, complexSelector, } = context;
+        // Get current complex selector end token
+        const currentEndToken = stream.lookbehindForNonWs();
+        // Finish current compound selector node
+        CompoundSelectorHandler.handle(context);
+        // Throw error if current complex selector node has no compound selector nodes (empty)
+        if (!currentEndToken || complexSelector.children.length === 0) {
+            throw new AdblockSyntaxError(sprintf("Unexpected token '%s' with value '%s'", getFormattedTokenName(token.type), raw.slice(token.start, token.end)), baseOffset + token.start, baseOffset + token.end);
+        }
+        // Include current complex selector node end location if needed
+        if (options.isLocIncluded) {
+            complexSelector.end = baseOffset + currentEndToken.end;
+        }
+        // Append current complex selector node to selector list node
+        result.children.push(complexSelector);
+        // If EOF is reached, just return, as we don't need to construct a next complex selector node
+        if (isEof) {
+            return;
+        }
+        // Get next complex selector node start token
+        const nextStartToken = stream.getOrFail();
+        // Construct next complex selector node
+        const nextComplexSelector = {
+            type: 'ComplexSelector',
+            children: [],
+        };
+        // Include next complex selector node start location if needed
+        if (options.isLocIncluded) {
+            nextComplexSelector.start = baseOffset + nextStartToken.start;
+        }
+        // Update context with new complex selector
+        context.complexSelector = nextComplexSelector;
+        // Reset type selector set tracker for new selector
+        context.isTypeSelectorSet = false;
+    }
+}
+
+export { ComplexSelectorHandler };

package/dist/parser/cosmetic/selector/handlers/compound-selector-handler.js

@@ -0,0 +1,97 @@
+/*
+ * AGTree v4.0.1 (build date: Thu, 19 Feb 2026 05:13:05 GMT)
+ * (c) 2026 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { sprintf } from 'sprintf-js';
+import { getFormattedTokenName } from '@adguard/css-tokenizer';
+import { AdblockSyntaxError } from '../../../../errors/adblock-syntax-error.js';
+import { GREATER_THAN, PLUS, TILDE, COMMA, SPACE } from '../../../../utils/constants.js';
+
+/**
+ * Handles compound selector parsing in selector list.
+ */
+class CompoundSelectorHandler {
+    /**
+     * Set of allowed symbols between selectors (combinators + comma, except <space> combinator).
+     *
+     * @see {@link SelectorCombinatorValue}
+     */
+    static ALLOWED_SYMBOLS_BETWEEN_SELECTORS = new Set([
+        // div > span
+        GREATER_THAN,
+        // div + div
+        PLUS,
+        // div ~ div
+        TILDE,
+        // div, span
+        COMMA,
+    ]);
+    /**
+     * Finishes the current compound selector by:
+     * 1. Validating current compound selector node,
+     * 2. Constructing selector combinator node (if provided),
+     * 3. Appending selector combinator node to the complex selector (if provided).
+     *
+     * @param context Selector list parser context.
+     * @param combinator Optional combinator string.
+     *
+     * @throws If the current compound selector has no simple selectors.
+     */
+    static handle(context, combinator) {
+        const { raw, options, baseOffset, stream, token, complexSelector, } = context;
+        // Get current compound selector end token
+        const currentEndToken = stream.lookbehindForNonWs();
+        // Throw error if current compound selector has no simple selectors (empty)
+        if (
+        // Combinator shouldn't be the first token in the complex selector
+        !currentEndToken
+            || complexSelector.children.length === 0
+            // And the last token in the complex selector shouldn't be a combinator
+            || complexSelector.children[complexSelector.children.length - 1].type === 'SelectorCombinator') {
+            throw new AdblockSyntaxError(sprintf("Unexpected token '%s' with value '%s'", getFormattedTokenName(token.type), raw.slice(token.start, token.end)), baseOffset + token.start, baseOffset + token.end);
+        }
+        // Handle edge case for descendant combinator
+        if (combinator === SPACE) {
+            // Skip whitespaces before checking next token
+            stream.skipWhitespace();
+            // EOF - just skip, we shouldn't consider it as descendant combinator
+            if (!stream.get()) {
+                return;
+            }
+            // Combinator or Comma - just skip, we shouldn't consider it as descendant combinator
+            if (CompoundSelectorHandler.ALLOWED_SYMBOLS_BETWEEN_SELECTORS.has(stream.fragment())) {
+                return;
+            }
+        }
+        else {
+            // Advance selector combinator token
+            stream.advance();
+            // Skip whitespaces after selector combinator token
+            stream.skipWhitespace();
+        }
+        // If no combinator is provided, just return, as we don't need to create and append selector combinator node
+        if (!combinator) {
+            return;
+        }
+        // Next compound selector token should be defined
+        stream.getOrFail();
+        // Construct selector combinator node
+        const result = {
+            type: 'SelectorCombinator',
+            value: combinator,
+        };
+        // Include selector combinator node locations if needed
+        if (options.isLocIncluded) {
+            result.start = baseOffset + token.start;
+            result.end = baseOffset + token.start + combinator.length;
+        }
+        // Append selector combinator node to the current complex selector node
+        complexSelector.children.push(result);
+        // Reset type selector set tracker for next compound selector
+        context.isTypeSelectorSet = false;
+    }
+}
+
+export { CompoundSelectorHandler };

package/dist/parser/cosmetic/selector/handlers/id-selector-handler.js

@@ -0,0 +1,42 @@
+/*
+ * AGTree v4.0.1 (build date: Thu, 19 Feb 2026 05:13:05 GMT)
+ * (c) 2026 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+/**
+ * Handles ID selector parsing in selector list.
+ */
+class IdSelectorHandler {
+    /**
+     * Handles ID selector parsing by creating an ID selector node
+     * and appending it to the current complex selector node.
+     *
+     * @param context Selector list parser context.
+     *
+     * @throws If the ID selector is syntactically incorrect.
+     */
+    static handle(context) {
+        const { raw, options, baseOffset, stream, complexSelector, } = context;
+        // Get ID selector token
+        const token = stream.getOrFail();
+        // Extract ID selector value (`start + 1` - without hashmark)
+        const value = raw.slice(token.start + 1, token.end);
+        // Construct ID selector node
+        const result = {
+            type: 'IdSelector',
+            value,
+        };
+        // Include ID selector node locations if needed
+        if (options.isLocIncluded) {
+            result.start = baseOffset + token.start;
+            result.end = baseOffset + token.end;
+        }
+        // Append ID selector node to the current complex selector node
+        complexSelector.children.push(result);
+        // Advance ID selector token
+        stream.advance();
+    }
+}
+
+export { IdSelectorHandler };

package/dist/parser/cosmetic/selector/handlers/pseudo-class-selector-handler.js

@@ -0,0 +1,128 @@
+/*
+ * AGTree v4.0.1 (build date: Thu, 19 Feb 2026 05:13:05 GMT)
+ * (c) 2026 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { TokenType, getFormattedTokenName } from '@adguard/css-tokenizer';
+import { sprintf } from 'sprintf-js';
+import { AdblockSyntaxError } from '../../../../errors/adblock-syntax-error.js';
+import { EMPTY } from '../../../../utils/constants.js';
+import { ValueParser } from '../../../misc/value-parser.js';
+
+/**
+ * Handles pseudo-class selector parsing in selector list.
+ */
+class PseudoClassSelectorHandler {
+    /**
+     * Handles pseudo-class selector parsing by creating a pseudo-class selector node
+     * and appending it to the current complex selector node.
+     *
+     * @param context Selector list parser context.
+     *
+     * @throws If the pseudo-class selector is syntactically incorrect.
+     */
+    static handle(context) {
+        const { raw, options, baseOffset, stream, complexSelector, } = context;
+        // Get colon token
+        let token = stream.getOrFail();
+        // Save pseudo-class selector node start position
+        const { start } = token;
+        // Advance colon token
+        stream.advance();
+        // Get pseudo-class selector name token
+        token = stream.getOrFail();
+        // It should be a function or identifier
+        const isFunction = token.type === TokenType.Function;
+        if (!isFunction && token.type !== TokenType.Ident) {
+            throw new AdblockSyntaxError(sprintf(
+            // eslint-disable-next-line max-len
+            `Expected '${getFormattedTokenName(TokenType.Ident)}' or '${getFormattedTokenName(TokenType.Function)}' as pseudo-class selector name, but got '%s' with value '%s'`, getFormattedTokenName(token.type), stream.fragment()), baseOffset + token.start, baseOffset + token.end);
+        }
+        // Extract pseudo-class selector name raw value
+        let nameRaw;
+        if (!isFunction) {
+            nameRaw = raw.slice(token.start, token.end);
+        }
+        else {
+            nameRaw = raw.slice(token.start, token.end - 1); // Exclude '('
+        }
+        // Construct pseudo-class selector node
+        const result = {
+            type: 'PseudoClassSelector',
+            name: ValueParser.parse(nameRaw, options, baseOffset + token.start),
+        };
+        // Include pseudo-class selector node start location if needed
+        if (options.isLocIncluded) {
+            result.start = baseOffset + start;
+        }
+        // If it's a function, parse its argument
+        if (isFunction) {
+            // Advance pseudo-class selector name token
+            stream.advance();
+            // Get pseudo-class selector argument token
+            token = stream.getOrFail();
+            // Construct empty pseudo-class selector argument node by default
+            result.argument = {
+                type: 'Value',
+                value: EMPTY,
+            };
+            // Include pseudo-class selector argument node location if needed
+            if (options.isLocIncluded) {
+                result.argument.start = baseOffset + token.start;
+                result.argument.end = baseOffset + token.start;
+            }
+            // Skip whitespaces after opening parenthesis
+            stream.skipWhitespace();
+            // Get pseudo-class selector argument or closing parenthesis token
+            token = stream.getOrFail();
+            // Check if there is any argument part
+            if (token.type !== TokenType.CloseParenthesis) {
+                // Save the balance level to find the matching closing parenthesis
+                const balance = stream.getBalance();
+                // Skip leading whitespace
+                stream.skipWhitespace();
+                // Get argument token
+                token = stream.getOrFail();
+                // Save pseudo-class selector argument start position
+                const argumentStart = token.start;
+                // Track last non-whitespace token to handle trailing whitespace
+                let lastNonWsToken;
+                // Skip to the closing parenthesis at the matching balance level
+                while (stream.get()?.balance !== balance - 1) {
+                    const currentToken = stream.get();
+                    if (currentToken && currentToken.type !== TokenType.Whitespace) {
+                        lastNonWsToken = currentToken;
+                    }
+                    stream.advance();
+                }
+                // Get closing parenthesis token
+                token = stream.getOrFail();
+                // Save pseudo-class selector argument end position (after last non-whitespace token)
+                const argumentEnd = lastNonWsToken ? lastNonWsToken.end : token.start;
+                // Extract pseudo-class selector argument raw value (trimmed)
+                // TODO: Consider parsing inner selectors (like :not(.class))
+                const argumentRaw = raw.slice(argumentStart, argumentEnd);
+                // Specify pseudo-class selector argument node value
+                result.argument.value = argumentRaw;
+                // Include pseudo-class selector argument node location if needed
+                if (options.isLocIncluded) {
+                    result.argument.start = baseOffset + argumentStart;
+                    result.argument.end = baseOffset + argumentStart + argumentRaw.length;
+                }
+            }
+            // Expect close parenthesis token
+            stream.expect(TokenType.CloseParenthesis);
+        }
+        // Include pseudo-class selector end location if needed
+        if (options.isLocIncluded) {
+            result.end = baseOffset + token.end;
+        }
+        // Append pseudo-class selector node to the current complex selector node
+        complexSelector.children.push(result);
+        // Advance pseudo-class selector name token (if ident) or closing parenthesis token (if function)
+        stream.advance();
+    }
+}
+
+export { PseudoClassSelectorHandler };

package/dist/parser/cosmetic/selector/handlers/type-selector-handler.js

@@ -0,0 +1,58 @@
+/*
+ * AGTree v4.0.1 (build date: Thu, 19 Feb 2026 05:13:05 GMT)
+ * (c) 2026 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { AdblockSyntaxError } from '../../../../errors/adblock-syntax-error.js';
+
+/**
+ * Handles type selector parsing in selector list.
+ */
+class TypeSelectorHandler {
+    /**
+     * Handles type selector parsing by creating a type selector node
+     * and appending it to the current complex selector node.
+     *
+     * @param context Selector list parser context.
+     *
+     * @throws If the type selector is syntactically incorrect.
+     */
+    static handle(context) {
+        const { options, baseOffset, stream, complexSelector, isTypeSelectorSet, } = context;
+        // Get type selector token
+        const token = stream.getOrFail();
+        // Throw error if type selector is already set
+        if (isTypeSelectorSet) {
+            throw new AdblockSyntaxError('Type selector is already set for the compound selector', baseOffset + token.start, baseOffset + token.end);
+        }
+        // Throw error if type selector isn't first in the given compound selector
+        if (
+        // It should be first on current complex selector
+        complexSelector.children.length !== 0
+            // Or should be first on current compound selector (after combinator)
+            && complexSelector.children[complexSelector.children.length - 1].type !== 'SelectorCombinator') {
+            throw new AdblockSyntaxError('Type selector must be first in the compound selector', baseOffset + token.start, baseOffset + token.end);
+        }
+        // Extract type selector value
+        const value = stream.fragment();
+        // Construct type selector node
+        const result = {
+            type: 'TypeSelector',
+            value,
+        };
+        // Include type selector node locations if needed
+        if (options.isLocIncluded) {
+            result.start = baseOffset + token.start;
+            result.end = baseOffset + token.start + value.length;
+        }
+        // Append type selector node to the current complex selector node
+        complexSelector.children.push(result);
+        // Advance type selector token
+        stream.advance();
+        // Mark that type name is set
+        context.isTypeSelectorSet = true;
+    }
+}
+
+export { TypeSelectorHandler };

package/dist/parser/cosmetic/selector/selector-list-parser.js

@@ -0,0 +1,164 @@
+/*
+ * AGTree v4.0.1 (build date: Thu, 19 Feb 2026 05:13:05 GMT)
+ * (c) 2026 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { getFormattedTokenName, TokenType } from '@adguard/css-tokenizer';
+import { sprintf } from 'sprintf-js';
+import { AdblockSyntaxError } from '../../../errors/adblock-syntax-error.js';
+import { SPACE, TILDE, PLUS, GREATER_THAN, DOT, ASTERISK } from '../../../utils/constants.js';
+import { BaseParser } from '../../base-parser.js';
+import { CssTokenStream } from '../../css/css-token-stream.js';
+import { defaultParserOptions } from '../../options.js';
+import { TypeSelectorHandler } from './handlers/type-selector-handler.js';
+import { IdSelectorHandler } from './handlers/id-selector-handler.js';
+import { AttributeSelectorHandler } from './handlers/attribute-selector-handler.js';
+import { PseudoClassSelectorHandler } from './handlers/pseudo-class-selector-handler.js';
+import { ClassSelectorHandler } from './handlers/class-selector-handler.js';
+import { CompoundSelectorHandler } from './handlers/compound-selector-handler.js';
+import { ComplexSelectorHandler } from './handlers/complex-selector-handler.js';
+
+/**
+ * Class responsible for parsing selector lists.
+ *
+ * Please note that the parser will parse any selector list if it is syntactically correct.
+ * For example, it will parse this:
+ * ```adblock
+ * div[attr1="value1"] > h1[attr2="value2"], span[attr3="value3"]
+ * ```
+ *
+ * but it didn't check if the given attribute or pseudo-class is valid or not.
+ *
+ * @see {@link https://www.w3.org/TR/selectors-4/#selector-list}'
+ */
+class SelectorListParser extends BaseParser {
+    /**
+     * Common error messages used in the parser for unexpected tokens.
+     */
+    static UNEXPECTED_TOKEN_WITH_VALUE_ERROR = "Unexpected token '%s' with value '%s'";
+    /**
+     * Parses a selector list.
+     *
+     * @param raw Raw input to parse.
+     * @param options Global parser options.
+     * @param baseOffset Starting offset of the input. Node locations are calculated relative to this offset.
+     *
+     * @returns Node of the parsed selector list.
+     *
+     * @throws If the selector list is syntactically incorrect.
+     *
+     * @example
+     * ```
+     * div[attr1="value1"] > h1[attr2="value2"], span[attr3="value3"]
+     * ```
+     */
+    static parse(raw, options = defaultParserOptions, baseOffset = 0) {
+        // Construct the stream
+        const stream = new CssTokenStream(raw, baseOffset);
+        // Skip whitespaces before first token
+        stream.skipWhitespace();
+        // Construct selector list parser context
+        const context = {
+            raw,
+            options,
+            baseOffset,
+            stream,
+            // Get first token
+            token: stream.getOrFail(),
+            // Construct selector list node
+            result: {
+                type: 'SelectorList',
+                children: [],
+            },
+            // Construct first complex selector node
+            complexSelector: {
+                type: 'ComplexSelector',
+                children: [],
+            },
+            // Track if type selector set in the current compound selector
+            isTypeSelectorSet: false,
+        };
+        // Include locations for (if needed):
+        // - start and end for the selector list node
+        // - start for the first complex selector node
+        if (options.isLocIncluded) {
+            context.result.start = baseOffset;
+            context.result.end = baseOffset + raw.length;
+            context.complexSelector.start = baseOffset + context.token.start;
+        }
+        // Traverse the stream
+        while (!stream.isEof()) {
+            // Get next token
+            context.token = stream.getOrFail();
+            switch (context.token.type) {
+                // Tag selector
+                case TokenType.Ident: {
+                    TypeSelectorHandler.handle(context);
+                    break;
+                }
+                // ID selector
+                case TokenType.Hash: {
+                    IdSelectorHandler.handle(context);
+                    break;
+                }
+                // Attribute selector
+                case TokenType.OpenSquareBracket: {
+                    AttributeSelectorHandler.handle(context);
+                    break;
+                }
+                // Pseudo-class selector
+                case TokenType.Colon: {
+                    PseudoClassSelectorHandler.handle(context);
+                    break;
+                }
+                // Universal type selector ('*'), Class selector ('.'), Combinators ('>', '+', '~')
+                case TokenType.Delim: {
+                    // Get delimiter value
+                    const delimiter = stream.fragment();
+                    switch (delimiter) {
+                        // Universal type selector ('*')
+                        case ASTERISK: {
+                            TypeSelectorHandler.handle(context);
+                            break;
+                        }
+                        // Class selector ('.)
+                        case DOT: {
+                            ClassSelectorHandler.handle(context);
+                            break;
+                        }
+                        // Combinators ('>', '+', '~')
+                        case GREATER_THAN:
+                        case PLUS:
+                        case TILDE: {
+                            CompoundSelectorHandler.handle(context, delimiter);
+                            break;
+                        }
+                        default: {
+                            throw new AdblockSyntaxError(sprintf(SelectorListParser.UNEXPECTED_TOKEN_WITH_VALUE_ERROR, getFormattedTokenName(context.token.type), delimiter), baseOffset + context.token.start, baseOffset + context.token.end);
+                        }
+                    }
+                    break;
+                }
+                // End of current compound selector (whitespace combinator - descendant)
+                case TokenType.Whitespace: {
+                    CompoundSelectorHandler.handle(context, SPACE);
+                    break;
+                }
+                // End of current complex selector
+                case TokenType.Comma: {
+                    ComplexSelectorHandler.handle(context, false);
+                    break;
+                }
+                default: {
+                    throw new AdblockSyntaxError(sprintf(SelectorListParser.UNEXPECTED_TOKEN_WITH_VALUE_ERROR, getFormattedTokenName(context.token.type), stream.fragment()), baseOffset + context.token.start, baseOffset + context.token.end);
+                }
+            }
+        }
+        // Finish last complex selector
+        ComplexSelectorHandler.handle(context);
+        return context.result;
+    }
+}
+
+export { SelectorListParser };

package/dist/parser/css/adg-css-injection-parser.js

@@ -1,10 +1,11 @@
 /*
- * AGTree v3.4.3 (build date: Thu, 11 Dec 2025 13:43:19 GMT)
- * (c) 2025 Adguard Software Ltd.
+ * AGTree v4.0.1 (build date: Thu, 19 Feb 2026 05:13:05 GMT)
+ * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
  */
 import { TokenType } from '@adguard/css-tokenizer';
+import { REMOVE_PROPERTY, REMOVE_VALUE } from '../../converter/data/css.js';
 import { AdblockSyntaxError } from '../../errors/adblock-syntax-error.js';
 import { CSS_MEDIA_MARKER, EMPTY } from '../../utils/constants.js';
 import { CssTokenStream } from './css-token-stream.js';
@@ -14,8 +15,6 @@ import { BaseParser } from '../base-parser.js';
 /**
  * @file Parser for AdGuard CSS injections.
  */
-const REMOVE_PROPERTY = 'remove';
-const REMOVE_VALUE = 'true';
 const ERROR_MESSAGES = {
     MEDIA_QUERY_LIST_IS_EMPTY: 'Media query list is empty',
     SELECTOR_LIST_IS_EMPTY: 'Selector list is empty',
@@ -205,4 +204,4 @@ class AdgCssInjectionParser extends BaseParser {
     }
 }
 
-export { AdgCssInjectionParser, ERROR_MESSAGES, REMOVE_PROPERTY, REMOVE_VALUE };
+export { AdgCssInjectionParser, ERROR_MESSAGES };

package/dist/parser/css/balancing.js

@@ -1,6 +1,6 @@
 /*
- * AGTree v3.4.3 (build date: Thu, 11 Dec 2025 13:43:19 GMT)
- * (c) 2025 Adguard Software Ltd.
+ * AGTree v4.0.1 (build date: Thu, 19 Feb 2026 05:13:05 GMT)
+ * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
  */

package/dist/parser/css/constants.js

@@ -1,6 +1,6 @@
 /*
- * AGTree v3.4.3 (build date: Thu, 11 Dec 2025 13:43:19 GMT)
- * (c) 2025 Adguard Software Ltd.
+ * AGTree v4.0.1 (build date: Thu, 19 Feb 2026 05:13:05 GMT)
+ * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
  */