@duckduckgo/autoconsent 14.82.0 → 14.83.0

package/AGENTS.md

@@ -107,6 +107,7 @@ shadow root or same-origin iframe.
 - **Paywalls do not need to be handled.** If the website presents the choice to pay or agree to cookies, the correct solution is to disable the feature on that site, so no code changes required in this case.
 - If the pop-up has an explicit "reject"-like button, you should first consider why HEURISTIC rule didn't handle it. A fix to the heuristic rule is always preferred to a new rule, as long as it doesn't cause potential false-positives on other sites.
 - **Watch out for race conditions**. A common pitfall is that a rule starts clicking before JS handlers are ready. If you detect this, add an appropriate wait step before the click, preferably based on a specific DOM state. Unconditional `wait` is a LAST RESORT because it leads to a poor UX.
+- **Watch out for false positive detections**. Always verify that the rule does NOT match after the popup is dismissed and the page is reloaded. Over-detection can lead to reload loops.
 - **selfTests are optional.** It is okay to NOT have a self-test, or have it failing as long as the popup is handled correctly. Confirm this with screenshots.
 - If you cover a new CMP or a new flavor of the existing CMP, ALWAYS try to look for more examples of that case, and add to the spec file.
 - `detectCmp` and `detectPopup` must be fast. Do NOT use waiting steps — the engine retries automatically.
@@ -157,4 +158,5 @@ After creating or modifying a rule:
 2. `npm run rule-syntax-check` — validate rule JSON against schema
 3. `npx playwright test tests/<name>.spec.ts` — run the E2E test
 4. `npm run prepublish` — full build including extension bundle
-5. Check the rule works across geographic regions using available regional-testing tooling.
+5. Validate that the rule stops matching after the popup is dismissed and the page is reloaded (unless it's a cosmetic rule).
+6. Check the rule works across geographic regions using available regional-testing tooling.

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# v14.83.0 (Sat May 16 2026)
+
+#### 🚀 Enhancement
+
+- Add a hint about reload loops [#1352](https://github.com/duckduckgo/autoconsent/pull/1352) ([@muodov](https://github.com/muodov))
+- Use MutationObserver in waitForPopup to avoid premature timeout [#1207](https://github.com/duckduckgo/autoconsent/pull/1207) ([@cursoragent](https://github.com/cursoragent) [@muodov](https://github.com/muodov))
+
+#### Authors: 2
+
+- Cursor Agent ([@cursoragent](https://github.com/cursoragent))
+- Maxim Tsoy ([@muodov](https://github.com/muodov))
+
+---
+
 # v14.82.0 (Fri May 15 2026)
 
 #### 🚀 Enhancement

package/dist/addon-firefox/background.bundle.js

@@ -697,6 +697,7 @@
       enableGeneratedRules: true,
       enableHeuristicDetection: false,
       enableHeuristicAction: false,
+      enablePopupMutationObserver: false,
       detectRetries: 20,
       isMainWorld: false,
       prehideTimeout: 2e3,
@@ -726,6 +727,12 @@
     if (!storedConfig.enableHeuristicDetection) {
       storedConfig.enableHeuristicDetection = true;
     }
+    if (storedConfig.enablePopupMutationObserver === void 0) {
+      storedConfig.enablePopupMutationObserver = true;
+    }
+    if (storedConfig.enableHeuristicAction === void 0) {
+      storedConfig.enableHeuristicAction = true;
+    }
     if (!storedConfig.logs) {
       storedConfig.logs = {
         lifecycle: true,

package/dist/addon-firefox/content.bundle.js

@@ -693,6 +693,7 @@
       enableGeneratedRules: true,
       enableHeuristicDetection: false,
       enableHeuristicAction: false,
+      enablePopupMutationObserver: false,
       detectRetries: 20,
       isMainWorld: false,
       prehideTimeout: 2e3,
@@ -3695,16 +3696,29 @@
       this.updateState({ selfTest: selfTestResult });
       return selfTestResult;
     }
-    // TODO: use MutationObserver like in findCmp()
     async waitForPopup(cmp, retries = 10, interval = 500) {
       const logsConfig = this.config.logs;
       logsConfig.lifecycle && console.log("checking if popup is open...", cmp.name);
+      let mutationObserver = null;
+      if (this.config.enablePopupMutationObserver) {
+        mutationObserver = this.domActions.waitForMutation("html", 1e4);
+        mutationObserver.catch(() => {
+        });
+      }
       const isOpen = await cmp.detectPopup().catch((e) => {
         logsConfig.errors && console.warn(`error detecting popup for ${cmp.name}`, e);
         return false;
       });
       if (!isOpen && retries > 0) {
-        await this.domActions.wait(interval);
+        if (mutationObserver) {
+          try {
+            await Promise.all([this.domActions.wait(interval), mutationObserver]);
+          } catch (e) {
+            logsConfig.lifecycle && console.log(cmp.name, "popup detection timed out waiting for DOM mutation");
+          }
+        } else {
+          await this.domActions.wait(interval);
+        }
         return this.waitForPopup(cmp, retries - 1, interval);
       }
       logsConfig.lifecycle && console.log(cmp.name, `popup is ${isOpen ? "open" : "not open"}`);

package/dist/addon-firefox/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Autoconsent",
-  "version": "2026.5.14",
+  "version": "2026.5.15",
   "background": {
     "scripts": [
       "background.bundle.js"

package/dist/addon-firefox/popup.bundle.js

@@ -524,6 +524,7 @@
       enableGeneratedRules: true,
       enableHeuristicDetection: false,
       enableHeuristicAction: false,
+      enablePopupMutationObserver: false,
       detectRetries: 20,
       isMainWorld: false,
       prehideTimeout: 2e3,
@@ -553,6 +554,12 @@
     if (!storedConfig.enableHeuristicDetection) {
       storedConfig.enableHeuristicDetection = true;
     }
+    if (storedConfig.enablePopupMutationObserver === void 0) {
+      storedConfig.enablePopupMutationObserver = true;
+    }
+    if (storedConfig.enableHeuristicAction === void 0) {
+      storedConfig.enableHeuristicAction = true;
+    }
     if (!storedConfig.logs) {
       storedConfig.logs = {
         lifecycle: true,
@@ -654,6 +661,8 @@
     const heuristicActionOffRadio = document.querySelector("input#heuristic-action-off");
     const visualTestOnRadio = document.querySelector("input#visual-test-on");
     const visualTestOffRadio = document.querySelector("input#visual-test-off");
+    const popupMutationOnRadio = document.querySelector("input#popup-mutation-on");
+    const popupMutationOffRadio = document.querySelector("input#popup-mutation-off");
     const retriesInput = document.querySelector("input#retries");
     const logsLifecycleCheckbox = document.querySelector("input#logs-lifecycle");
     const logsRulestepsCheckbox = document.querySelector("input#logs-rulesteps");
@@ -739,6 +748,11 @@
     } else {
       visualTestOffRadio.checked = true;
     }
+    if (autoconsentConfig.enablePopupMutationObserver) {
+      popupMutationOnRadio.checked = true;
+    } else {
+      popupMutationOffRadio.checked = true;
+    }
     enabledCheckbox.addEventListener("change", async () => {
       await setIsEnabledForDomain(currentDomain, enabledCheckbox.checked);
     });
@@ -789,6 +803,12 @@
     }
     visualTestOnRadio.addEventListener("change", visualTestChange);
     visualTestOffRadio.addEventListener("change", visualTestChange);
+    function popupMutationChange() {
+      autoconsentConfig.enablePopupMutationObserver = popupMutationOnRadio.checked;
+      storageSet({ config: autoconsentConfig });
+    }
+    popupMutationOnRadio.addEventListener("change", popupMutationChange);
+    popupMutationOffRadio.addEventListener("change", popupMutationChange);
     function updateLogsConfig() {
       autoconsentConfig.logs = {
         lifecycle: logsLifecycleCheckbox.checked,

package/dist/addon-firefox/popup.html

@@ -123,6 +123,20 @@
             </div>
         </fieldset>
 
+        <fieldset>
+            <legend>Popup mutation observer</legend>
+
+            <div>
+                <input type="radio" id="popup-mutation-on" name="popup-mutation" value="true" />
+                <label for="popup-mutation-on">On</label>
+            </div>
+
+            <div>
+                <input type="radio" id="popup-mutation-off" name="popup-mutation" value="false" checked />
+                <label for="popup-mutation-off">Off</label>
+            </div>
+        </fieldset>
+
         <fieldset>
             <legend>Debug logging</legend>
             <div>

package/dist/addon-mv3/background.bundle.js

@@ -697,6 +697,7 @@
       enableGeneratedRules: true,
       enableHeuristicDetection: false,
       enableHeuristicAction: false,
+      enablePopupMutationObserver: false,
       detectRetries: 20,
       isMainWorld: false,
       prehideTimeout: 2e3,
@@ -726,6 +727,12 @@
     if (!storedConfig.enableHeuristicDetection) {
       storedConfig.enableHeuristicDetection = true;
     }
+    if (storedConfig.enablePopupMutationObserver === void 0) {
+      storedConfig.enablePopupMutationObserver = true;
+    }
+    if (storedConfig.enableHeuristicAction === void 0) {
+      storedConfig.enableHeuristicAction = true;
+    }
     if (!storedConfig.logs) {
       storedConfig.logs = {
         lifecycle: true,

package/dist/addon-mv3/content.bundle.js

@@ -693,6 +693,7 @@
       enableGeneratedRules: true,
       enableHeuristicDetection: false,
       enableHeuristicAction: false,
+      enablePopupMutationObserver: false,
       detectRetries: 20,
       isMainWorld: false,
       prehideTimeout: 2e3,
@@ -3695,16 +3696,29 @@
       this.updateState({ selfTest: selfTestResult });
       return selfTestResult;
     }
-    // TODO: use MutationObserver like in findCmp()
     async waitForPopup(cmp, retries = 10, interval = 500) {
       const logsConfig = this.config.logs;
       logsConfig.lifecycle && console.log("checking if popup is open...", cmp.name);
+      let mutationObserver = null;
+      if (this.config.enablePopupMutationObserver) {
+        mutationObserver = this.domActions.waitForMutation("html", 1e4);
+        mutationObserver.catch(() => {
+        });
+      }
       const isOpen = await cmp.detectPopup().catch((e) => {
         logsConfig.errors && console.warn(`error detecting popup for ${cmp.name}`, e);
         return false;
       });
       if (!isOpen && retries > 0) {
-        await this.domActions.wait(interval);
+        if (mutationObserver) {
+          try {
+            await Promise.all([this.domActions.wait(interval), mutationObserver]);
+          } catch (e) {
+            logsConfig.lifecycle && console.log(cmp.name, "popup detection timed out waiting for DOM mutation");
+          }
+        } else {
+          await this.domActions.wait(interval);
+        }
         return this.waitForPopup(cmp, retries - 1, interval);
       }
       logsConfig.lifecycle && console.log(cmp.name, `popup is ${isOpen ? "open" : "not open"}`);

package/dist/addon-mv3/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Autoconsent",
-  "version": "2026.5.14",
+  "version": "2026.5.15",
   "background": {
     "service_worker": "background.bundle.js"
   },

package/dist/addon-mv3/popup.bundle.js

@@ -524,6 +524,7 @@
       enableGeneratedRules: true,
       enableHeuristicDetection: false,
       enableHeuristicAction: false,
+      enablePopupMutationObserver: false,
       detectRetries: 20,
       isMainWorld: false,
       prehideTimeout: 2e3,
@@ -553,6 +554,12 @@
     if (!storedConfig.enableHeuristicDetection) {
       storedConfig.enableHeuristicDetection = true;
     }
+    if (storedConfig.enablePopupMutationObserver === void 0) {
+      storedConfig.enablePopupMutationObserver = true;
+    }
+    if (storedConfig.enableHeuristicAction === void 0) {
+      storedConfig.enableHeuristicAction = true;
+    }
     if (!storedConfig.logs) {
       storedConfig.logs = {
         lifecycle: true,
@@ -654,6 +661,8 @@
     const heuristicActionOffRadio = document.querySelector("input#heuristic-action-off");
     const visualTestOnRadio = document.querySelector("input#visual-test-on");
     const visualTestOffRadio = document.querySelector("input#visual-test-off");
+    const popupMutationOnRadio = document.querySelector("input#popup-mutation-on");
+    const popupMutationOffRadio = document.querySelector("input#popup-mutation-off");
     const retriesInput = document.querySelector("input#retries");
     const logsLifecycleCheckbox = document.querySelector("input#logs-lifecycle");
     const logsRulestepsCheckbox = document.querySelector("input#logs-rulesteps");
@@ -739,6 +748,11 @@
     } else {
       visualTestOffRadio.checked = true;
     }
+    if (autoconsentConfig.enablePopupMutationObserver) {
+      popupMutationOnRadio.checked = true;
+    } else {
+      popupMutationOffRadio.checked = true;
+    }
     enabledCheckbox.addEventListener("change", async () => {
       await setIsEnabledForDomain(currentDomain, enabledCheckbox.checked);
     });
@@ -789,6 +803,12 @@
     }
     visualTestOnRadio.addEventListener("change", visualTestChange);
     visualTestOffRadio.addEventListener("change", visualTestChange);
+    function popupMutationChange() {
+      autoconsentConfig.enablePopupMutationObserver = popupMutationOnRadio.checked;
+      storageSet({ config: autoconsentConfig });
+    }
+    popupMutationOnRadio.addEventListener("change", popupMutationChange);
+    popupMutationOffRadio.addEventListener("change", popupMutationChange);
     function updateLogsConfig() {
       autoconsentConfig.logs = {
         lifecycle: logsLifecycleCheckbox.checked,

package/dist/addon-mv3/popup.html

@@ -123,6 +123,20 @@
             </div>
         </fieldset>
 
+        <fieldset>
+            <legend>Popup mutation observer</legend>
+
+            <div>
+                <input type="radio" id="popup-mutation-on" name="popup-mutation" value="true" />
+                <label for="popup-mutation-on">On</label>
+            </div>
+
+            <div>
+                <input type="radio" id="popup-mutation-off" name="popup-mutation" value="false" checked />
+                <label for="popup-mutation-off">Off</label>
+            </div>
+        </fieldset>
+
         <fieldset>
             <legend>Debug logging</legend>
             <div>

package/dist/autoconsent.cjs.js

@@ -728,6 +728,7 @@ function normalizeConfig(providedConfig) {
     enableGeneratedRules: true,
     enableHeuristicDetection: false,
     enableHeuristicAction: false,
+    enablePopupMutationObserver: false,
     detectRetries: 20,
     isMainWorld: false,
     prehideTimeout: 2e3,
@@ -3963,16 +3964,29 @@ var AutoConsent = class {
     this.updateState({ selfTest: selfTestResult });
     return selfTestResult;
   }
-  // TODO: use MutationObserver like in findCmp()
   async waitForPopup(cmp, retries = 10, interval = 500) {
     const logsConfig = this.config.logs;
     logsConfig.lifecycle && console.log("checking if popup is open...", cmp.name);
+    let mutationObserver = null;
+    if (this.config.enablePopupMutationObserver) {
+      mutationObserver = this.domActions.waitForMutation("html", 1e4);
+      mutationObserver.catch(() => {
+      });
+    }
     const isOpen = await cmp.detectPopup().catch((e) => {
       logsConfig.errors && console.warn(`error detecting popup for ${cmp.name}`, e);
       return false;
     });
     if (!isOpen && retries > 0) {
-      await this.domActions.wait(interval);
+      if (mutationObserver) {
+        try {
+          await Promise.all([this.domActions.wait(interval), mutationObserver]);
+        } catch (e) {
+          logsConfig.lifecycle && console.log(cmp.name, "popup detection timed out waiting for DOM mutation");
+        }
+      } else {
+        await this.domActions.wait(interval);
+      }
       return this.waitForPopup(cmp, retries - 1, interval);
     }
     logsConfig.lifecycle && console.log(cmp.name, `popup is ${isOpen ? "open" : "not open"}`);

package/dist/autoconsent.esm.js

@@ -698,6 +698,7 @@ function normalizeConfig(providedConfig) {
     enableGeneratedRules: true,
     enableHeuristicDetection: false,
     enableHeuristicAction: false,
+    enablePopupMutationObserver: false,
     detectRetries: 20,
     isMainWorld: false,
     prehideTimeout: 2e3,
@@ -3933,16 +3934,29 @@ var AutoConsent = class {
     this.updateState({ selfTest: selfTestResult });
     return selfTestResult;
   }
-  // TODO: use MutationObserver like in findCmp()
   async waitForPopup(cmp, retries = 10, interval = 500) {
     const logsConfig = this.config.logs;
     logsConfig.lifecycle && console.log("checking if popup is open...", cmp.name);
+    let mutationObserver = null;
+    if (this.config.enablePopupMutationObserver) {
+      mutationObserver = this.domActions.waitForMutation("html", 1e4);
+      mutationObserver.catch(() => {
+      });
+    }
     const isOpen = await cmp.detectPopup().catch((e) => {
       logsConfig.errors && console.warn(`error detecting popup for ${cmp.name}`, e);
       return false;
     });
     if (!isOpen && retries > 0) {
-      await this.domActions.wait(interval);
+      if (mutationObserver) {
+        try {
+          await Promise.all([this.domActions.wait(interval), mutationObserver]);
+        } catch (e) {
+          logsConfig.lifecycle && console.log(cmp.name, "popup detection timed out waiting for DOM mutation");
+        }
+      } else {
+        await this.domActions.wait(interval);
+      }
       return this.waitForPopup(cmp, retries - 1, interval);
     }
     logsConfig.lifecycle && console.log(cmp.name, `popup is ${isOpen ? "open" : "not open"}`);

package/dist/autoconsent.extra.cjs.js

@@ -11291,6 +11291,7 @@ function normalizeConfig(providedConfig) {
     enableGeneratedRules: true,
     enableHeuristicDetection: false,
     enableHeuristicAction: false,
+    enablePopupMutationObserver: false,
     detectRetries: 20,
     isMainWorld: false,
     prehideTimeout: 2e3,
@@ -14961,16 +14962,29 @@ var AutoConsent = class {
     this.updateState({ selfTest: selfTestResult });
     return selfTestResult;
   }
-  // TODO: use MutationObserver like in findCmp()
   async waitForPopup(cmp, retries = 10, interval = 500) {
     const logsConfig = this.config.logs;
     logsConfig.lifecycle && console.log("checking if popup is open...", cmp.name);
+    let mutationObserver = null;
+    if (this.config.enablePopupMutationObserver) {
+      mutationObserver = this.domActions.waitForMutation("html", 1e4);
+      mutationObserver.catch(() => {
+      });
+    }
     const isOpen = await cmp.detectPopup().catch((e) => {
       logsConfig.errors && console.warn(`error detecting popup for ${cmp.name}`, e);
       return false;
     });
     if (!isOpen && retries > 0) {
-      await this.domActions.wait(interval);
+      if (mutationObserver) {
+        try {
+          await Promise.all([this.domActions.wait(interval), mutationObserver]);
+        } catch (e) {
+          logsConfig.lifecycle && console.log(cmp.name, "popup detection timed out waiting for DOM mutation");
+        }
+      } else {
+        await this.domActions.wait(interval);
+      }
       return this.waitForPopup(cmp, retries - 1, interval);
     }
     logsConfig.lifecycle && console.log(cmp.name, `popup is ${isOpen ? "open" : "not open"}`);

package/dist/autoconsent.extra.esm.js

@@ -11225,6 +11225,7 @@ function normalizeConfig(providedConfig) {
     enableGeneratedRules: true,
     enableHeuristicDetection: false,
     enableHeuristicAction: false,
+    enablePopupMutationObserver: false,
     detectRetries: 20,
     isMainWorld: false,
     prehideTimeout: 2e3,
@@ -14895,16 +14896,29 @@ var AutoConsent = class {
     this.updateState({ selfTest: selfTestResult });
     return selfTestResult;
   }
-  // TODO: use MutationObserver like in findCmp()
   async waitForPopup(cmp, retries = 10, interval = 500) {
     const logsConfig = this.config.logs;
     logsConfig.lifecycle && console.log("checking if popup is open...", cmp.name);
+    let mutationObserver = null;
+    if (this.config.enablePopupMutationObserver) {
+      mutationObserver = this.domActions.waitForMutation("html", 1e4);
+      mutationObserver.catch(() => {
+      });
+    }
     const isOpen = await cmp.detectPopup().catch((e) => {
       logsConfig.errors && console.warn(`error detecting popup for ${cmp.name}`, e);
       return false;
     });
     if (!isOpen && retries > 0) {
-      await this.domActions.wait(interval);
+      if (mutationObserver) {
+        try {
+          await Promise.all([this.domActions.wait(interval), mutationObserver]);
+        } catch (e) {
+          logsConfig.lifecycle && console.log(cmp.name, "popup detection timed out waiting for DOM mutation");
+        }
+      } else {
+        await this.domActions.wait(interval);
+      }
       return this.waitForPopup(cmp, retries - 1, interval);
     }
     logsConfig.lifecycle && console.log(cmp.name, `popup is ${isOpen ? "open" : "not open"}`);

package/dist/autoconsent.playwright.js

@@ -700,6 +700,7 @@
       enableGeneratedRules: true,
       enableHeuristicDetection: false,
       enableHeuristicAction: false,
+      enablePopupMutationObserver: false,
       detectRetries: 20,
       isMainWorld: false,
       prehideTimeout: 2e3,
@@ -3703,16 +3704,29 @@
       this.updateState({ selfTest: selfTestResult });
       return selfTestResult;
     }
-    // TODO: use MutationObserver like in findCmp()
     async waitForPopup(cmp, retries = 10, interval = 500) {
       const logsConfig = this.config.logs;
       logsConfig.lifecycle && console.log("checking if popup is open...", cmp.name);
+      let mutationObserver = null;
+      if (this.config.enablePopupMutationObserver) {
+        mutationObserver = this.domActions.waitForMutation("html", 1e4);
+        mutationObserver.catch(() => {
+        });
+      }
       const isOpen = await cmp.detectPopup().catch((e) => {
         logsConfig.errors && console.warn(`error detecting popup for ${cmp.name}`, e);
         return false;
       });
       if (!isOpen && retries > 0) {
-        await this.domActions.wait(interval);
+        if (mutationObserver) {
+          try {
+            await Promise.all([this.domActions.wait(interval), mutationObserver]);
+          } catch (e) {
+            logsConfig.lifecycle && console.log(cmp.name, "popup detection timed out waiting for DOM mutation");
+          }
+        } else {
+          await this.domActions.wait(interval);
+        }
         return this.waitForPopup(cmp, retries - 1, interval);
       }
       logsConfig.lifecycle && console.log(cmp.name, `popup is ${isOpen ? "open" : "not open"}`);

package/dist/types/types.d.ts

@@ -61,6 +61,7 @@ export type Config = {
     enableFilterList: boolean;
     enableHeuristicDetection: boolean;
     enableHeuristicAction: boolean;
+    enablePopupMutationObserver: boolean;
     visualTest: boolean;
     logs: {
         lifecycle: boolean;

package/lib/types.ts

@@ -65,6 +65,7 @@ export type Config = {
     enableFilterList: boolean;
     enableHeuristicDetection: boolean;
     enableHeuristicAction: boolean;
+    enablePopupMutationObserver: boolean;
     visualTest: boolean; // If true, the script will delay before every click action
     logs: {
         lifecycle: boolean;

package/lib/utils.ts

@@ -78,6 +78,7 @@ export function normalizeConfig(providedConfig: any): Config {
         enableGeneratedRules: true,
         enableHeuristicDetection: false,
         enableHeuristicAction: false,
+        enablePopupMutationObserver: false,
         detectRetries: 20,
         isMainWorld: false,
         prehideTimeout: 2000,

package/lib/web.ts

@@ -553,16 +553,30 @@ export default class AutoConsent {
         return selfTestResult;
     }
 
-    // TODO: use MutationObserver like in findCmp()
     async waitForPopup(cmp: AutoCMP, retries = 10, interval = 500): Promise<boolean> {
         const logsConfig = this.config.logs;
         logsConfig.lifecycle && console.log('checking if popup is open...', cmp.name);
+
+        let mutationObserver: Promise<boolean> | null = null;
+        if (this.config.enablePopupMutationObserver) {
+            mutationObserver = this.domActions.waitForMutation('html', 10000);
+            mutationObserver.catch(() => {});
+        }
+
         const isOpen = await cmp.detectPopup().catch((e) => {
             logsConfig.errors && console.warn(`error detecting popup for ${cmp.name}`, e);
             return false;
-        }); // ignore possible errors in one-time popup detection
+        });
         if (!isOpen && retries > 0) {
-            await this.domActions.wait(interval);
+            if (mutationObserver) {
+                try {
+                    await Promise.all([this.domActions.wait(interval), mutationObserver]);
+                } catch (e) {
+                    logsConfig.lifecycle && console.log(cmp.name, 'popup detection timed out waiting for DOM mutation');
+                }
+            } else {
+                await this.domActions.wait(interval);
+            }
             return this.waitForPopup(cmp, retries - 1, interval);
         }
         logsConfig.lifecycle && console.log(cmp.name, `popup is ${isOpen ? 'open' : 'not open'}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duckduckgo/autoconsent",
-  "version": "14.82.0",
+  "version": "14.83.0",
   "description": "",
   "types": "./dist/types/web.d.ts",
   "exports": {

package/tests-wtr/lifecycle/wait-for-popup.html

@@ -0,0 +1,14 @@
+<html>
+    <body>
+        <script type="module">
+            import { runTests } from '@web/test-runner-mocha';
+
+            runTests(async () => {
+                await import('./wait-for-popup');
+            });
+        </script>
+        <div id="page-content">
+            <p>Test page for waitForPopup tests</p>
+        </div>
+    </body>
+</html>

package/tests-wtr/lifecycle/wait-for-popup.ts

@@ -0,0 +1,214 @@
+import { expect } from '@esm-bundle/chai';
+import Autoconsent from '../../lib/web';
+import { AutoCMP } from '../../lib/types';
+
+function createAutoconsent(enablePopupMutationObserver: boolean): Autoconsent {
+    return new Autoconsent(() => Promise.resolve(), {
+        enabled: false,
+        autoAction: null,
+        enablePopupMutationObserver,
+    });
+}
+
+function createMockCmp(detectPopupFn: () => Promise<boolean>): AutoCMP {
+    return {
+        name: 'mock-cmp',
+        hasSelfTest: false,
+        isIntermediate: false,
+        isCosmetic: false,
+        runContext: { main: true, frame: false },
+        checkRunContext: () => true,
+        checkFrameContext: () => true,
+        hasMatchingUrlPattern: () => true,
+        detectCmp: () => Promise.resolve(true),
+        detectPopup: detectPopupFn,
+        optOut: () => Promise.resolve(true),
+        optIn: () => Promise.resolve(true),
+        openCmp: () => Promise.resolve(true),
+        test: () => Promise.resolve(true),
+    };
+}
+
+describe('Autoconsent.waitForPopup', () => {
+    describe('without mutation observer (legacy polling)', () => {
+        let autoconsent: Autoconsent;
+
+        beforeEach(() => {
+            autoconsent = createAutoconsent(false);
+        });
+
+        it('should resolve true if popup is detected on first check', async () => {
+            const cmp = createMockCmp(() => Promise.resolve(true));
+            const result = await autoconsent.waitForPopup(cmp, 5, 50);
+            expect(result).to.be.true;
+        });
+
+        it('should resolve false if popup is never detected', async () => {
+            const cmp = createMockCmp(() => Promise.resolve(false));
+            const result = await autoconsent.waitForPopup(cmp, 2, 50);
+            expect(result).to.be.false;
+        });
+
+        it('should retry and detect popup that appears later', async () => {
+            let callCount = 0;
+            const cmp = createMockCmp(() => {
+                callCount++;
+                return Promise.resolve(callCount >= 3);
+            });
+            const result = await autoconsent.waitForPopup(cmp, 5, 50);
+            expect(result).to.be.true;
+            expect(callCount).to.equal(3);
+        });
+
+        it('should handle errors in detectPopup gracefully', async () => {
+            const cmp = createMockCmp(() => Promise.reject(new Error('detection error')));
+            const result = await autoconsent.waitForPopup(cmp, 2, 50);
+            expect(result).to.be.false;
+        });
+
+        it('should not retry when retries is 0', async () => {
+            let callCount = 0;
+            const cmp = createMockCmp(() => {
+                callCount++;
+                return Promise.resolve(false);
+            });
+            const result = await autoconsent.waitForPopup(cmp, 0, 50);
+            expect(result).to.be.false;
+            expect(callCount).to.equal(1);
+        });
+    });
+
+    describe('with mutation observer', () => {
+        let autoconsent: Autoconsent;
+
+        beforeEach(() => {
+            autoconsent = createAutoconsent(true);
+        });
+
+        it('should resolve true if popup is detected on first check', async () => {
+            const cmp = createMockCmp(() => Promise.resolve(true));
+            const result = await autoconsent.waitForPopup(cmp, 5, 50);
+            expect(result).to.be.true;
+        });
+
+        it('should resolve false when retries are exhausted despite mutations', async () => {
+            const cmp = createMockCmp(() => Promise.resolve(false));
+
+            const mutationInterval = setInterval(() => {
+                const el = document.createElement('div');
+                el.className = 'test-exhaust-mutation';
+                document.body.appendChild(el);
+            }, 30);
+
+            const result = await autoconsent.waitForPopup(cmp, 2, 50);
+
+            clearInterval(mutationInterval);
+            document.querySelectorAll('.test-exhaust-mutation').forEach((el) => el.remove());
+
+            expect(result).to.be.false;
+        });
+
+        it('should retry when a DOM mutation occurs and detect popup', async () => {
+            let callCount = 0;
+            const cmp = createMockCmp(() => {
+                callCount++;
+                return Promise.resolve(callCount >= 2);
+            });
+
+            // schedule a DOM mutation so the observer resolves
+            setTimeout(() => {
+                const el = document.createElement('span');
+                el.id = 'test-mutation-element';
+                document.body.appendChild(el);
+            }, 30);
+
+            const result = await autoconsent.waitForPopup(cmp, 5, 50);
+            expect(result).to.be.true;
+            expect(callCount).to.equal(2);
+
+            document.getElementById('test-mutation-element')?.remove();
+        });
+
+        it('should detect popup that appears after multiple mutations', async () => {
+            let callCount = 0;
+            const cmp = createMockCmp(() => {
+                callCount++;
+                return Promise.resolve(callCount >= 3);
+            });
+
+            // schedule DOM mutations to keep the observer firing
+            const mutationInterval = setInterval(() => {
+                const el = document.createElement('div');
+                el.className = 'test-multi-mutation';
+                document.body.appendChild(el);
+            }, 40);
+
+            const result = await autoconsent.waitForPopup(cmp, 5, 50);
+
+            clearInterval(mutationInterval);
+            document.querySelectorAll('.test-multi-mutation').forEach((el) => el.remove());
+
+            expect(result).to.be.true;
+            expect(callCount).to.equal(3);
+        });
+
+        it('should handle errors in detectPopup gracefully', async () => {
+            let callCount = 0;
+            const cmp = createMockCmp(() => {
+                callCount++;
+                if (callCount <= 2) {
+                    return Promise.reject(new Error('transient error'));
+                }
+                return Promise.resolve(true);
+            });
+
+            // schedule mutations so retries proceed
+            const mutationInterval = setInterval(() => {
+                const el = document.createElement('div');
+                el.className = 'test-error-mutation';
+                document.body.appendChild(el);
+            }, 30);
+
+            const result = await autoconsent.waitForPopup(cmp, 5, 50);
+
+            clearInterval(mutationInterval);
+            document.querySelectorAll('.test-error-mutation').forEach((el) => el.remove());
+
+            expect(result).to.be.true;
+            expect(callCount).to.equal(3);
+        });
+
+        it('should not retry when retries is 0', async () => {
+            let callCount = 0;
+            const cmp = createMockCmp(() => {
+                callCount++;
+                return Promise.resolve(false);
+            });
+            const result = await autoconsent.waitForPopup(cmp, 0, 50);
+            expect(result).to.be.false;
+            expect(callCount).to.equal(1);
+        });
+
+        it('should continue retrying after mutation observer timeout', async () => {
+            // Override waitForMutation to use a very short timeout so it rejects quickly
+            const originalWaitForMutation = autoconsent.domActions.waitForMutation.bind(autoconsent.domActions);
+            autoconsent.domActions.waitForMutation = (selector, _timeout?) => {
+                return originalWaitForMutation(selector, 10);
+            };
+
+            let callCount = 0;
+            const cmp = createMockCmp(() => {
+                callCount++;
+                // popup appears on the 3rd attempt (after 2 mutation timeouts)
+                return Promise.resolve(callCount >= 3);
+            });
+
+            const result = await autoconsent.waitForPopup(cmp, 5, 50);
+
+            autoconsent.domActions.waitForMutation = originalWaitForMutation;
+
+            expect(result).to.be.true;
+            expect(callCount).to.equal(3);
+        });
+    });
+});