@duckduckgo/autoconsent 14.77.1 → 14.78.0

package/.agents/skills/publicwww-search/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: publicwww-search
+description: Search PublicWWW to find websites using specific HTML/JS/CSS snippets. Use this skill to check if a cookie popup is from a widespread third-party CMP, to find additional test URLs for a CMP rule, or to discover how many sites use a particular consent banner pattern.
+---
+
+# PublicWWW Source Code Search
+
+Search website source code via the [PublicWWW](https://publicwww.com) API. Requires `PUBLICWWW_KEY` env var.
+
+**Caveat:** PublicWWW indexes server-rendered HTML source only. CMPs injected purely via client-side JavaScript (e.g. tag managers, async script loaders) may not appear in results.
+
+## API
+
+Download search results as CSV:
+
+```
+https://publicwww.com/websites/SEARCH_QUERY/?export=csvsnippetsu&key=$PUBLICWWW_KEY
+```
+
+CSV format: `url;rank;snippet` (one site per line, sorted by popularity rank).
+
+Use `export=csv` instead of `csvsnippetsu` to get `domain;rank` without snippets.
+
+## Query Syntax
+
+- Exact phrase: `"onetrust-banner-sdk"`
+- Combine terms: `"cookie-banner" "reject-all"`
+- Exclude: `"cookie-banner" -wordpress`
+- TLD filter: `"sd-cmp" site:de`
+- File type: `"__cmp" filetype:js` (also `filetype:css`)
+- Page depth: `depth:all "math.min.js"` (0–5, default homepage only)
+- Escape inner quotes: `"data-testid=\"cookie-reject\""`
+
+Full syntax: https://publicwww.com/syntax.html
+
+## Examples
+
+Check if a banner ID is from a shared CMP:
+
+```bash
+curl -s "https://publicwww.com/websites/%22sd-cmp%22/?export=csv&key=$PUBLICWWW_KEY" | head -20
+```
+
+Find German sites using OneTrust:
+
+```bash
+curl -s "https://publicwww.com/websites/%22onetrust-banner-sdk%22+site%3Ade/?export=csv&key=$PUBLICWWW_KEY" | head -10
+```
+
+Search JS files for a CMP API:
+
+```bash
+curl -s "https://publicwww.com/js/%22__cmp%22+filetype%3Ajs/?export=csv&key=$PUBLICWWW_KEY" | head -10
+```

package/.agents/skills/verify-pr/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: verify-pr
+description: Verifies an autoconsent pull request by running local CI checks, reviewing rule quality, and inspecting Jenkins E2E results. Use when reviewing, verifying, or approving a PR, when checking if a PR is ready to merge, or when the user asks to validate PR changes.
+---
+
+# Verify PR
+
+Copy this checklist and track progress:
+
+```
+PR Verification:
+- [ ] Step 1: Local checks pass
+- [ ] Step 2: Rule review complete
+- [ ] Step 3: CI results checked
+- [ ] Step 4: Browser verification done
+```
+
+## Step 1: Local Checks
+
+```bash
+npm run lint
+npm run rule-syntax-check
+npm run test:lib
+npx playwright test tests/<cmp>.spec.ts --project webkit
+```
+
+If any check fails, fix the issue and re-run before proceeding.
+
+## Step 2: Rule Review
+
+### JSON rule PRs
+
+- [ ] Test spec exists in `tests/` with reachable URLs
+- [ ] Selectors are stable (no CSS module hashes, dynamic IDs, or framework-generated IDs)
+- [ ] `optOut` targets a reject/decline button, not a privacy policy link or close button
+- [ ] `prehideSelectors` are narrow (no `body` or full-page selectors)
+- [ ] `minimumRuleStepVersion: 2` if rule uses `removeClass`, `setStyle`, or `addStyle`
+- [ ] Generated rule fixes (`rules/generated/`) are consistent across all region variants
+
+### Code-based rule PRs
+
+- [ ] No hardcoded site-specific values
+- [ ] Fallback paths for regional variants
+- [ ] Uses existing DOM helpers (`this.click()`, `this.waitForElement()`, etc.)
+
+## Step 3: CI Results
+
+**GitHub Actions** (`.github/workflows/checks.yml`): Runs `lint` and `test:lib`. Must pass.
+
+**Jenkins**: Runs Playwright E2E in 9 regions (US, GB, AU, CA, DE, FR, NL, CH, NO) for modified rules only. Posts a PR comment with artifact ZIP and [review tool](https://zok.pw/autoconsent-review-tool/) link for inspecting screenshots.
+
+### Flaky E2E failures
+
+Before concluding a test is broken:
+
+1. Check Jenkins screenshots in the review tool
+2. Verify the site still shows the same popup
+3. Region-only failures → consider adding `skipRegions`
+4. CI retries twice — intermittent failures often self-resolve
+
+## Step 4: Browser Verification
+
+Build and load extension: `npm run prepublish` → load `dist/addon-mv3/` in Chrome.
+
+Confirm on target site(s):
+
+- Popup is detected and handled
+- Page scrolls normally after opt-out
+- Interactive elements remain clickable
+
+For CMP rules: test on multiple sites using the same CMP (find sites in `data/coverage.json`).

package/.claude/skills/publicwww-search/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: publicwww-search
+description: Search PublicWWW to find websites using specific HTML/JS/CSS snippets. Use this skill to check if a cookie popup is from a widespread third-party CMP, to find additional test URLs for a CMP rule, or to discover how many sites use a particular consent banner pattern.
+---
+
+@.agents/skills/publicwww-search/SKILL.md

package/.claude/skills/verify-pr/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: verify-pr
+description: Verifies an autoconsent pull request by running local CI checks, reviewing rule quality, and inspecting Jenkins E2E results. Use when reviewing, verifying, or approving a PR, when checking if a PR is ready to merge, or when the user asks to validate PR changes.
+---
+
+@.agents/skills/verify-pr/SKILL.md

package/AGENTS.md

@@ -10,8 +10,9 @@ lib/cmps/         Code-based CMP rule classes (sourcepoint, onetrust, etc.)
 lib/rules.ts      Type definitions for AutoConsentCMPRule and rule steps
 lib/eval-snippets.ts  Eval snippets for main-world JS execution
 rules/autoconsent/    Hand-maintained JSON rules
-rules/generated/      Auto-generated JSON rules (auto_XX_domain_hash.json)
+rules/generated/      Crawler-generated JSON rules (auto_XX_domain_hash.json)
 rules/build.ts        Merges all rules into rules.json, consentomatic.json, compact-rules.json
+data/                 Coverage data (coverage.json) and site lists
 tests/                Playwright E2E test specs (one per CMP)
 tests-wtr/            Web Test Runner unit tests for DOM actions and rule logic
 playwright/runner.ts  Test harness: generateCMPTests(name, urls, options)
@@ -42,310 +43,103 @@ npm run watch         # auto-rebuild on changes to lib/, addon/, rules/
 | `npm run create-rule` | Scaffold a new JSON rule + test spec |
 
 ## Code Style
-
 - **Preserve existing comments.** Do not remove JSDoc comments, TODO comments, or inline explanations unless the related code is also being removed. Rewriting a comment to reflect updated logic is fine.
 
-## Working with Rules
-
-### JSON Rules
-
-JSON rules live in `rules/autoconsent/` (hand-maintained) and `rules/generated/` (auto-generated). Each file defines one CMP rule following the `AutoConsentCMPRule` type in `lib/rules.ts`.
-
-```json
-{
-  "name": "example-cmp",
-  "prehideSelectors": ["#cookie-banner"],
-  "detectCmp": [{ "exists": "#cookie-banner" }],
-  "detectPopup": [{ "visible": "#cookie-banner" }],
-  "optIn": [{ "waitForThenClick": "#accept-all" }],
-  "optOut": [{ "waitForThenClick": "#reject-all" }],
-  "test": [{ "cookieContains": "consent=rejected" }],
-  "minimumRuleStepVersion": 1
-}
-```
+## Working with autoconsent rules
 
+### Rule syntax
 For the complete rule syntax reference (all step types, element selectors, conditionals, etc.), see [docs/rule-syntax.md](docs/rule-syntax.md).
 
-### prehideSelectors
-
-`prehideSelectors` inject CSS early (before the CMP is even detected) to prevent the cookie popup from flickering on screen. They use `opacity: 0` (not `display: none`) so the popup still occupies layout space and detection via `visible` checks still works. If opt-out doesn't start within 2 seconds, the elements are automatically unhidden to avoid permanently hiding page content.
-
-Keep prehideSelectors **narrow** — they are applied across all matching rules simultaneously, so an overly broad selector (e.g. `body`) could hide the entire page during the 2-second window.
-
-### minimumRuleStepVersion
-
-New step types are added to the autoconsent engine over time. `minimumRuleStepVersion` declares which version of the step format a rule requires. Clients that don't support the required version silently skip the rule, preventing failures on older app versions.
-
-**Version history:**
-- `1` (default) — all original step types (`exists`, `visible`, `waitFor`, `click`, `waitForThenClick`, `wait`, `hide`, `if`/`then`/`else`, `any`, `eval`, `cookieContains`, etc.)
-- `2` — added `removeClass`, `setStyle`, `addStyle`
-
-**When to set it:** Omit the field (or set to `1`) if the rule only uses original step types. Set to `2` if the rule uses `removeClass`, `setStyle`, or `addStyle`. When future versions add new step types, set accordingly.
-
-### Code-Based Rules
-
-For CMPs requiring complex  non-linear logic, CMP API interaction, or complex multi-path flows, use a TypeScript class extending `AutoConsentCMPBase` in `lib/cmps/`. Examples: `sourcepoint-frame.ts`, `onetrust.ts`, `cookiebot.ts`, `consentmanager.ts`.
-
-Code-based rules implement the `AutoCMP` interface: `detectCmp()`, `detectPopup()`, `optOut()`, `optIn()`, and optionally `test()`. They have access to DOM helpers like `this.click()`, `this.waitForElement()`, `this.waitForVisible()`, and `this.elementExists()`.
-
-### When to Use Code vs JSON
-
-- **JSON:** Linear consent flows, DOM-based detection, single-path opt-out. JSON rules are preferable because they can be shipped in DuckDuckGo apps without a full app release.
-- **Code:** Multi-path branching, CMP JavaScript API calls, `Promise.race()` for competing UI states, complex state machines (e.g., Sourcepoint serving GDPR/CCPA/US National variants on different URL paths).
-
-### Selector Strategy
-
-Prefer selectors in this order (most stable first):
-
-1. **Stable data attributes:** `[data-testid="cookie-reject"]`, `[data-action="sp-cc"]`, `[data-qa="allow-all-cookies"]`
-2. **Stable IDs:** `#sp-cc-accept`, `#cookie-banner` — but avoid dynamic IDs from React Aria (`#react-aria*`), Radix (`#radix-\:*\:`), or CSS Modules (`.sd-cmp-3cRQ2`), which change between builds/sessions.
-3. **Semantic class substrings:** `[class*="cookie-banner"]`, `[class*="reject"]` — avoid full body class lists (`body.home.wp-singular.page-template...`) which break across pages.
-4. **Structural CSS:** `#banner button.secondary` — avoid deep `nth-child` chains from generated rules.
-5. **XPath text matching (fallback):** `xpath///button[contains(., 'Reject')]` — use as a last resort since button text is language-specific and breaks across locales. Same caution applies to `aria-label` attributes, which are often localized.
-6. **Array selectors** for shadow DOM / iframe piercing: `["host-element", "button"]` finds `button` inside the shadow root of `host-element`. Each string in the array narrows the search scope — if an intermediate element has an open `shadowRoot`, the next selector runs inside it; if it's a same-origin iframe, the next selector runs inside its `contentDocument`. Use when a CMP renders inside shadow DOM or a same-origin iframe.
-
-When writing or reviewing selectors, also watch out for:
-- **Hardcoded attribute values** that are site-specific — use generic selectors in code-based rules.
-- **Over-qualified selectors** from generated rules — e.g. `div[id][name][role][aria-modal][tabindex][lang]` requiring every attribute to exist, or redundant `:nth-child(2)#some-id` where the ID alone suffices.
-
-## Debugging and Fixing Rules
-
-### Identifying Broken Rules
-
-1. **Use a real browser** to investigate. A real browser in a computer-use subagent is **highly preferred** over Playwright or Puppeteer-based scripts — cookie popups often behave differently in headless/automated browsers.
-2. **Playwright test failures** are a secondary signal. Run the specific test:
-   ```bash
-   npx playwright test tests/sirdata.spec.ts --project webkit
-   ```
-3. **Check test output** for which stage failed: `cmpDetected`, `popupFound`, `autoconsentDone`, `optOutResult`, `selfTestResult`.
-4. **Use the test extension** (`dist/addon-mv3/`) for manual debugging. Load it in Chrome, visit the site, and check the devtools panel for step-by-step logs.
-
-### Common Failure Modes
-
-**Race conditions:** Consent popups load asynchronously. Use `waitFor` / `waitForThenClick` / `waitForVisible` instead of bare `exists` / `click`. Add `{ "wait": 500 }` before critical actions when the CMP has known async initialization. In code-based rules, use `Promise.race()` for multiple possible UI states. **Never** use `{ "wait": N }` in `detectCmp` or `detectPopup` — the engine handles retries internally.
-
-**Incorrect consent action selectors:** Generated rules sometimes target a privacy policy link instead of the reject button. Ensure `optOut` steps target an actual reject/decline button.
-
-**Region-dependent behavior:** Many CMPs show different dialogs by region (GDPR in EU, CCPA in US). See [Regional Differences](#regional-differences) below.
-
-### Fixing JSON Rules
-
-1. Read the existing rule to understand its current selectors and flow.
-2. Identify the broken step from test output or by inspecting the site.
-3. Edit the JSON file — apply the fix to every occurrence of the selector within the file (`detectCmp`, `detectPopup`, `optOut`, and `test` often use similar selectors).
-4. For site-specific rules, double-check if the popup is still site-specific. If not, consider if a generic rule is more appropriate.
-5. **Always update the corresponding test spec** in `tests/`. If no spec exists, create one.
-6. **Cross-check other rules** — search for the same selectors or CMP provider name across `rules/autoconsent/` and `rules/generated/` to find other rules that may need the same change.
-7. For generated rules, the same CMP may appear across multiple region files (`auto_CH_*.json`, `auto_DE_*.json`, etc.). Apply the fix to all affected files.
-8. Run `npm run lint` to validate.
-
-### Fixing Code-Based Rules
-
-1. Read the CMP class in `lib/cmps/` and trace the failing code path.
-2. Avoid hardcoded attribute values that are site-specific.
-3. Add path/state detection for new CMP variants. Check `location.pathname`, button presence, or URL parameters.
-4. Add fallback paths when variants may not have the expected buttons.
-
-### Adding Fallback Paths
-
-Use `if`/`then`/`else` for region-dependent or variant-dependent flows:
-
-```json
-{
-  "if": { "exists": "#reject-button" },
-  "then": [{ "waitForThenClick": "#reject-button" }],
-  "else": [{
-    "if": { "exists": "#manage-cookies" },
-    "then": [
-      { "waitForThenClick": "#manage-cookies" },
-      { "waitForThenClick": "#reject-all" }
-    ],
-    "else": [
-      { "waitForThenClick": "[role='button'][title='Close']" }
-    ]
-  }]
-}
-```
-
-## Adding New Rules
-
-1. Run `npm run create-rule` to scaffold the JSON + test spec.
-2. **Check if the popup is from a third-party CMP provider** (e.g. OneTrust, Cookiebot, Sourcepoint). If so, prefer extending or fixing the existing generic rule rather than creating a site-specific one.
-3. Fill in `detectCmp`, `detectPopup`, `optOut`, `optIn` with stable selectors. Do **not** use `{ "wait": N }` steps in `detectCmp` or `detectPopup` — detection must be fast and non-blocking (the engine retries automatically).
-4. Add a `test` array — prefer `cookieContains` when the CMP stores consent in cookies.
-   - JSON rules can also use `{ "eval": "SNIPPET_NAME" }` steps to execute predefined JavaScript snippets from `lib/eval-snippets.ts`. Useful for calling CMP APIs (e.g., `window.Cookiebot`, `__cmp('getCMPData')`) in detection, opt-out, or test phases. Each snippet is a named function that returns a boolean. New snippets must be added to `lib/eval-snippets.ts` and referenced by name in the rule JSON.
-5. **Always create or update the corresponding test spec** in `tests/`.
-6. **Cross-check other rules** — search for the same selectors or CMP provider name across `rules/autoconsent/` and `rules/generated/` to see if other rules need the same change or already cover this CMP.
-7. Use `data/coverage.json` to find example sites for testing. It contains per-CMP, per-region URLs: `{ "CmpName": { "REGION": { "exampleSites": [...] } } }`.
-8. Run `npm run lint` and `npm run test:lib`.
-9. Test with Playwright: `npx playwright test tests/my-cmp.spec.ts --project webkit`.
-
-### When Generated Rules Need Fixes
+### Regional Differences
 
-Generated rules (`rules/generated/auto_XX_domain_hash.json`) are created by a crawler and often have:
-- Deep `nth-child` chains that break on layout changes
-- Dynamic IDs from UI frameworks
-- Long body class lists
-- Over-qualified selectors requiring many attributes simultaneously
+CMPs behave differently by region:
 
-Fixes typically need to be applied across all region variants of the same domain (e.g., `auto_CH_kitbag.com_*.json`, `auto_DE_kitbag.com_*.json`). Search for the domain to find all related files.
+- **EU/EEA (GDPR):** Full consent dialog with explicit reject/accept options.
+- **US (CCPA/state laws):** Often a simpler notice with "Close" or "Do Not Sell". Some CMPs show nothing.
+- **Other regions:** Varies.
 
-## Cosmetic Rules
+Use `if`/`then`/`else` to handle regional variants within a single rule.
 
-Cosmetic rules hide the cookie popup via CSS rather than clicking a reject button. They are marked with `"cosmetic": true` and use `hide` steps in their `optOut` array. Use cosmetic rules when a popup has no reject/decline button — only an "Accept" or "Close" option.
+**All rule changes MUST be tested across geographic regions** to catch regional popup variations. Test from real geographic locations using available regional-testing tooling (e.g. proxy-based remote browsers).
 
-### When to Use Cosmetic vs Click-Based Rules
+### Generic vs Site-Specific Rules
 
-A popup should use a **click-based rule** (the default) if it has a reject/decline button. This includes buttons with text like "Reject all", "Only necessary cookies", "Decline", and equivalents in other languages. If the popup only has "Accept" / "OK" / "Close" / "Got it" and no way to reject, use a **cosmetic rule** to hide it.
+**Always prefer writing a generic CMP rule over a site-specific rule.** One CMP rule can cover multiple sites. See "Identifying a Consent Management Platform" below for common techniques. If the popup is genuinely custom-built, a site-specific rule is the right call.
 
-### Common Breakage Patterns
+### JSON Rules vs Code-based rules
 
-Hiding a popup can break the page if the CMP also locks scrolling or adds overlays. Watch for:
-
-**Scroll lock via CSS class:** `body` or `html` gets a class like `no-scroll`, `modal-open`, `overflow-hidden`. Fix with:
-```json
-{ "removeClass": "no-scroll", "selector": "body" }
-```
-
-**Scroll lock via inline style:** `body.style.overflow = "hidden"`. Fix with:
-```json
-{ "addStyle": "overflow: auto !important", "selector": "body" }
-```
-
-**Overlay preventing clicks:** A `position: fixed` div with high z-index covers the page. Fix by hiding it:
-```json
-{ "hide": "#overlay-selector" }
-```
-
-**Body position lock:** `body.style.position = "fixed"` with `top: -XXpx`. Fix with:
-```json
-{ "setStyle": "", "selector": "body" }
-```
-
-### Cosmetic Rule Structure
+JSON rules live in `rules/autoconsent/` (hand-maintained) and `rules/generated/` (auto-generated). Each file defines one CMP rule following the `AutoConsentCMPRule` type in `lib/rules.ts`.
 
 ```json
 {
-  "name": "example-cosmetic",
-  "cosmetic": true,
+  "name": "example-cmp",
   "prehideSelectors": ["#cookie-banner"],
   "detectCmp": [{ "exists": "#cookie-banner" }],
   "detectPopup": [{ "visible": "#cookie-banner" }],
-  "optOut": [
-    { "hide": "#cookie-banner" },
-    { "removeClass": "no-scroll", "selector": "body", "optional": true }
-  ],
-  "optIn": [{ "waitForThenClick": "#accept-button" }]
+  "optIn": [{ "waitForThenClick": "#accept-all" }],
+  "optOut": [{ "waitForThenClick": "#reject-all" }],
+  "test": [{ "cookieContains": "consent=rejected" }]
 }
 ```
 
-Add breakage fix steps AFTER the `hide` step in `optOut`. Mark breakage fixes as `"optional": true` since they may not always apply.
-
-## Triaging Broken Sites
-
-When investigating a site where cookie popup handling is broken or missing:
-
-### Step 1: Check Current State
-
-Load the bundled extension in Chrome (`dist/addon-mv3/` after `npm run prepublish`), visit the site, and check the devtools panel for autoconsent logs. Determine whether:
-- An existing rule matched but failed (which stage? `detectCmp`, `detectPopup`, `optOut`?)
-- No rule matched at all
-
-### Step 2: Diagnose
-
-If an **existing rule matched but failed**: identify the broken step from the logs, inspect the site to understand what changed (new selectors, different layout, region variant), and fix the rule.
-
-If **no rule matched**: determine the CMP type. Check if the popup is from a known CMP (OneTrust, Sourcepoint, Cookiebot, etc.) by inspecting the banner's HTML, class names, and script sources. If it's a known CMP, the existing rule may need updated detection selectors. If it's unknown, create a new rule.
-
-**Always check if the popup is from a third-party CMP provider.** If so, prefer creating or extending a generic rule rather than a site-specific one. Use `data/coverage.json` to find additional example sites for the same CMP to verify the rule works broadly.
-
-### Step 3: Determine Rule Type
+Code-based rules live in `lib/cmps/`. Each file defines one CMP rule following the `AutoConsentCMPBase` type in `lib/rules.ts`.
 
-- If the popup has a **reject/decline button** → create or fix a click-based rule
-- If the popup has **no reject option** (only accept/close) → create a cosmetic rule
-- If the CMP requires **complex logic** (API calls, multiple UI states, iframe communication) → use a code-based CMP class
+**JSON rules are always preferred over code-based rules.** Code-based rules are rarely needed, and should only be used for complex cases, when JSON format is not expressive enough.
 
-### Step 4: Implement and Test
+### Selectors
 
-1. Create or edit the rule file
-2. Add or update the test spec in `tests/`
-3. Run `npm run lint` to validate
-4. Test locally: `npx playwright test tests/<cmp>.spec.ts --project webkit`
-5. Test in multiple regions if the CMP is region-dependent (requires both `REGION` and `PROXY_SERVER` — see [Testing Across Regions](#testing-across-regions))
-6. For cosmetic rules, verify no breakage (scrolling works, page is interactable)
+Prefer selectors stable across builds and locales: data attributes (`[data-testid="..."]`) > stable IDs > class substrings (`[class*="..."]`) > structural CSS > XPath (last resort). **Do NOT use CSS module hashes** (4+ random chars like `.css-1a2b3c`) or framework-generated IDs.
 
-## Regional Differences
+Array selectors pierce shadow DOM and same-origin iframes. Each selector in the array
+scopes into the previous match's `.shadowRoot` or `.contentDocument`:
 
-CMPs behave differently depending on the user's region due to different privacy regulations:
-
-- **EU/EEA (GDPR):** Full consent dialog with explicit reject/accept options. Most rules target this variant.
-- **US (CCPA/state laws):** Often a simpler notice with just a "Close" button, or a "Do Not Sell" link. Some CMPs show nothing at all in the US.
-- **Other regions:** May show GDPR-like dialogs, simplified notices, or nothing.
-
-### Handling Regional Variants in Rules
-
-Use `if`/`then`/`else` conditionals to handle different UIs within a single rule. For code-based rules, add path detection (e.g., Sourcepoint's `/privacy-manager/index.html` vs `/us_pm/index.html`).
-
-### Testing Across Regions
-
-Two things are needed to test from a specific region:
-
-1. **`REGION` env var** — filters which test URLs to run (from `data/coverage.json`). This only controls test selection, it does **not** change where requests come from.
-2. **`PROXY_SERVER` env var** — routes browser traffic through a geographic proxy so sites see the correct region. Without a proxy, the site sees your real location regardless of `REGION`.
-
-```bash
-# Local: only filters tests, requests come from your real location
-REGION=DE npx playwright test tests/sirdata.spec.ts --project webkit
-
-# With proxy: tests are filtered AND requests are routed through the proxy
-REGION=DE PROXY_SERVER=socks5://proxy.example:1080 npx playwright test tests/sirdata.spec.ts --project webkit
-```
-
-In CI, Jenkins loads region-specific `.env` files that set both `REGION` and `PROXY_SERVER` together.
-
-Test specs support `skipRegions` and `onlyRegions` to control when tests run:
-
-```typescript
-generateCMPTests('Sirdata', ['https://gizmodo.com/'], {
-    skipRegions: ['US'],   // skip test in these regions
-    onlyRegions: [],       // only run in these regions
-});
+```json
+["#shadow-host", "button.reject"]
+["#cmp-container iframe", ".opt-out-btn"]
 ```
 
-## PR Review Checklist
-
-### CI Pipeline
-
-Two CI systems run on PRs:
-
-1. **GitHub Actions** (`.github/workflows/checks.yml`): runs `npm run lint` and `npm run test:lib` on every push/PR. These must pass.
-2. **Jenkins**: runs Playwright E2E tests in 9 regions (US, GB, AU, CA, DE, FR, NL, CH, NO). Only tests for modified rule files and their corresponding test specs are run. Jenkins posts a PR comment with an artifact ZIP link and a link to the [review tool](https://zok.pw/autoconsent-review-tool/) for inspecting screenshots.
-
-### Reviewing New Rule PRs
-
-- [ ] `npm run lint` passes (ESLint + Prettier + schema validation)
-- [ ] JSON rule validates against schema (`npm run rule-syntax-check`)
-- [ ] A corresponding test spec exists in `tests/`
-- [ ] Test URLs are reachable and relevant
-- [ ] Selectors are stable (no dynamic IDs, no full body class lists, no CSS module hashes)
-- [ ] `optOut` targets an actual reject/decline button, not a privacy policy link
-- [ ] For generated rule fixes: all region variants are updated consistently
-
-### Reviewing Code-Based Rule PRs
-
-- [ ] Lint and unit tests pass
-- [ ] No hardcoded site-specific attribute values
-- [ ] Fallback paths exist for regional variants
-- [ ] Uses existing DOM helpers (`this.click()`, `this.waitForElement()`, etc.)
-
-### Handling Flaky E2E Tests
-
-E2E tests hit live sites and are inherently flaky due to site changes, regional differences, and network conditions. Before concluding a test is broken:
-
-- Check Jenkins screenshots in the review tool
-- If a test fails only in certain regions, consider adding `skipRegions`
-- Playwright is configured with retries (2 retries in CI)
-- Verify the site still has the same cookie consent popup by visiting it manually
+Single-string selectors cannot pierce — use arrays whenever the target is inside a
+shadow root or same-origin iframe.
+
+### General Guidelines and Gotchas
+- **Regional testing is mandatory** for any rule change — CMPs behave differently under GDPR (EU), CCPA (US), and other jurisdictions. Run the rule against different regions using available regional-testing tooling before considering the change done.
+- When verifying a rule, **look at the screenshots** on top of the API results — sometimes a rule reports success, but the popup is not actually handled - a screenshot will detect this.
+- **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.
+- **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.
+- **`prehideSelectors` do not affect autoconsent visibility checks.** Prehide selectors are injected early to prevent flicker, and are intentionally implemented using opacity, which hides elements from the user, but not from built-in steps such as `waitForVisible` and `visible`. That said, _prehide selectors should be narrow_: overly broad selectors (e.g. `body`) could hide the entire page.
+- Prefer DOM-based steps when possible — `eval` steps are a last resort.
+- Set `minimumRuleStepVersion: 2` if using `removeClass`, `setStyle`, or `addStyle`.
+- Prefer `cookieContains` in `test` when the CMP stores consent in cookies.
+- Use `npm run create-rule` to scaffold a new rule and a spec file.
+
+### Fixing breakage in cosmetic rules
+When using `hide`, the CMP may lock scrolling or add overlays. Add fixes AFTER the `hide` step, marked `"optional": true`:
+
+| Problem | Fix |
+|---------|-----|
+| Scroll lock via CSS class | `{ "removeClass": "no-scroll", "selector": "body", "optional": true }` |
+| Scroll lock via inline style | `{ "addStyle": "overflow: auto !important", "selector": "body", "optional": true }` |
+| Overlay blocking clicks | `{ "hide": "#overlay", "optional": true }` |
+| Body position lock | `{ "setStyle": "", "selector": "body", "optional": true }` |
+
+Using `removeClass`, `setStyle`, or `addStyle` requires `"minimumRuleStepVersion": 2`.
+
+## Identifying a Consent Management Platform
+The following techniques can help identify a generic CMP:
+
+1. **DOM inspection:** Check class names on popup elements for vendor prefixes
+   (`onetrust-`, `didomi-`, `sp_choice_type_`, `cmp-`, `fc-`, `klaro-`, `pd-`, etc.).
+2. **JS source analysis:** Inspect the popup buttons' click handlers or find the cookie
+   that stores consent and search for that cookie name in the page's scripts. Look for:
+   - Vendor names in variable/function names or `window` globals.
+   - Scripts in `node_modules/`, `vendor/`, or `wp-content/plugins/` paths.
+   - License comments with vendor URLs at the top of the script.
+3. **Cross-site prevalence:** Use the `publicwww-search` skill to search for distinctive
+   selectors, script URLs, or copy strings. If the same popup markup appears on many
+   sites, it's a CMP.
 
 ## CMP Discovery with PublicWWW
 
@@ -355,9 +149,10 @@ Requires `PUBLICWWW_KEY` environment variable.
 
 ## Verification
 
-| Step | Command |
-|------|---------|
-| Schema + formatting | `npm run lint` |
-| Unit tests | `npm run test:lib` |
-| Single CMP E2E test | `npx playwright test tests/<cmp>.spec.ts --project webkit` |
-| Full E2E suite | `npm run test` |
+After creating or modifying a rule:
+
+1. `npm run build-rules` — rebuild rules.json (required for tests)
+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.

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# v14.78.0 (Fri May 08 2026)
+
+#### 🚀 Enhancement
+
+- Improve agent context: restructure skills, slim AGENTS.md [#1319](https://github.com/duckduckgo/autoconsent/pull/1319) ([@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.77.1 (Thu May 07 2026)
 
 #### 🐛 Bug Fix

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/dist/addon-firefox/manifest.json

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

package/dist/addon-mv3/manifest.json

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

package/eslint.config.mjs

@@ -8,7 +8,7 @@ const c = tseslint.config(
     ...ddgConfig,
 
     {
-        ignores: ['lib/consentomatic/**/*', 'dist/**/*'],
+        ignores: ['lib/consentomatic/**/*', 'dist/**/*', '.agents/**/*'],
     },
 
     {

package/package.json

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