:watch-attrs(...)

Procedural-cosmetic-filters.md

@@ -85,6 +85,27 @@ Use to negate other procedural selectors. For example `:not(:has(.foo))` will ma
 Note that if _arg_ is valid CSS selector, uBO will not consider the `:not` operator to be a procedural one, it will rather consider the operator as being part of a CSS selector. Thus this ensure compatibility with the existing
 [CSS `:not(...)` pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/:not).
 
+### `subject:watch-attrs(arg)`
+
+Experimental.
+
+- Description: Pass-through filter used to modify behavior of the procedural cosmetic filter engine by forcing re-evaluation when one or more attribute changes on the matching elements.
+- Chainable: Yes.
+- _subject_: Can be a plain CSS selector, or a procedural cosmetic filter.
+- _arg_: comma-separate list of attribute names. No argument means watch changes of any one attribute.
+
+Introduced in uBO [1.17.5rc3](https://github.com/gorhill/uBlock/commit/8a88e9d93174badd6855c0e782737158c9ccd6f8) 
+
+Solves [uBlockOrigin/uBlock-issues#341 (comment)](https://github.com/uBlockOrigin/uBlock-issues/issues/341#issuecomment-449764612) (overlay dialog used for two purposes, differ only by class name in child node).
+
+By default hiding by procedural filters is reevaluated only when nodes in sub-tree are added or removed - uBO does not watch for attribute changes for performance reasons. This filter instructs uBO procedural filtering engine to watch for changes in specific attributes.
+
+Example:
+
+- `vivrehome.pl##.js-popup-register:has(.js-title-default.is-hidden:watch-attributes(class))` blocks the "Register" overlay when first visiting the site, but yet allow the "Register" overlay when clicking "rejestracja".
+- `ameshkov.github.io###testdiv:watch-attrs(id):has(p)` demo, detects `id` changes.
+
+
 ### `subject:xpath(arg)`
 
 - Description: Create a new set of elements by evaluating a XPath using _subject_ as the context node (optional) and _arg_ as the expression.