Merge branch 'main' into dependabot/npm_and_yarn/main/fast-check-4.2.0

Author: jonathanKingston

.cursorrules

@@ -6,7 +6,7 @@ When asked about Content Scope Scripts topics, refer to these documentation file
 
 - **API Reference**: `injected/docs/api-reference.md`
 - **Feature Development**: `injected/docs/features-guide.md`
-- **Platform Integration**: `injected/docs/platform-integration.md`
+- **Platform Integration and engine support**: `injected/docs/platform-integration.md`
 - **Development Utilities**: `injected/docs/development-utilities.md`
 - **Testing**: `injected/docs/testing-guide.md`
 - **Favicon**: `injected/docs/favicon.md`

injected/README.md

@@ -18,6 +18,15 @@ Content Scope Scripts provides a unified API for browser privacy features across
 
 ## Key Concepts
 
+### Project Structure
+
+Content Scope Scripts contains two main sub-projects:
+
+- **[Special Pages](../special-pages/)** - HTML/CSS/JS applications loaded into browsers (DuckPlayer, Release Notes, New Tab page, etc.)
+- **Injected Features** - Features injected into websites (privacy protections, compatibility fixes)
+
+> **For Special Pages development**, see the [Special Pages README](../special-pages/README.md) for detailed getting started instructions.
+
 ### Features
 Features are JavaScript modules that implement privacy protections. Each feature:
 - Extends the `ConfigFeature` class for remote configuration support
@@ -65,13 +74,9 @@ npm run fake-extension # Runs an example extension used within the integration t
 - `unit-test/` - Unit test suite
 - `integration-test/` - Integration test suite
 
-## Third-Party Libraries
-- [Adguard Scriptlets](https://github.com/AdguardTeam/Scriptlets)
-
----
+> **For detailed development setup instructions, debugging tips, and test build workflows, see the [Development Utilities](./docs/development-utilities.md) and [Testing Guide](./docs/testing-guide.md).**
 
 ## Third-Party Libraries
-We make use of the following submodules:
-- [Adguard Scriptlets](https://github.com/AdguardTeam/Scriptlets) 
+- [Adguard Scriptlets](https://github.com/AdguardTeam/Scriptlets)
 
 For detailed information about any specific topic, please refer to the [documentation](./docs/).

injected/docs/development-utilities.md

@@ -4,6 +4,77 @@
 
 To handle the difference in scope injection we expose multiple utilities which behave differently per browser in `src/utils.js` and `ContentFeature` base class. For Firefox the code exposed handles [xrays correctly](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts) without needing the features to be authored differently.
 
+## Development Setup
+
+### Repository Access
+
+1. **Clone the repository**: `https://github.com/duckduckgo/content-scope-scripts`
+2. **Request write-access** (for contributors): Submit a request via [Internal Support README](https://app.asana.com/1/137249556945/project/908478224964033/task/1209367367171662?focus=true) asking for `https://github.com/orgs/duckduckgo/teams/core` group access
+
+### Local Development Setup
+
+**Important**: Before cloning the repo on Windows, to avoid major headaches, make sure you clone it with unix-style line endings:
+
+```shell
+git clone --config core.autocrlf=false https://github.com/duckduckgo/content-scope-scripts
+```
+
+The Content Scope Scripts repo includes the build artifacts, which need to be generated as part of your commit.
+
+### Initial Setup
+
+Inside the repo, run:
+
+```shell
+npm ci  # Preferred over 'npm install' for accurate lockfile updates
+```
+
+Ensure you have a version of node that matches what's in the `.nvmrc` file.
+
+Now, to ensure everything's setup, try a full build:
+
+```shell
+npm run build
+```
+
+This will place built files into the top-level `build` folder. If this command ran successfully, you can continue with development.
+
+### Windows Development
+
+The tools should work on Windows, but if you have problems you _may_ wish to try using WSL.
+
+**Optional:**: Use Windows Subsystem for Linux - [WSL Installation Guide](https://learn.microsoft.com/en-us/windows/wsl/install)
+
+Once you have WSL running, make sure you have node and make installed:
+
+```shell
+sudo apt update
+sudo apt install make
+```
+
+For Node.js installation: [How to Install Node.js on Ubuntu/Debian](https://computingforgeeks.com/how-to-install-node-js-on-ubuntu-debian/)
+
+Once node is installed, navigate to the repo path (e.g., `/mnt/c/dev/git/content-scope-scripts`) and:
+
+```shell
+npm install    # Install packages
+npm run build  # Build JS artifacts
+```
+
+After this, you can commit the generated files from your Windows environment through the usual git tools.
+
+### Docker Alternative
+
+If you don't want to install npm on your machine, you can use Docker instead:
+
+```shell
+docker run -it --rm -v "<repo root>/submodules/content-scope-scripts:/content-scope-scripts" node:latest /bin/bash
+
+root@<id>:/# cd /content-scope-scripts
+root@<id>:/content-scope-scripts# npm install
+root@<id>:/content-scope-scripts# npm run build
+```
+
 ## ContentFeature Utilities
 
 ### `ContentFeature.defineProperty(object, propertyName, descriptor)`

injected/docs/platform-integration.md

@@ -4,6 +4,41 @@
 
 The [injected/entry-points/](https://github.com/duckduckgo/content-scope-scripts/tree/main/injected/entry-points) directory handles platform specific differences and is glue code into calling the contentScopeFeatures API.
 
+## Browser Compatibility
+
+The following is a guideline for when using native JavaScript syntax or built-in global DOM objects. Testing is always advised, but code authors might be unable to replicate the code on the correct application environments (due to hardware or an updated local environment).
+
+### Minimum Supported Engines
+
+#### iOS
+
+- **Safari 14** (minimum)
+- **Minimum support**: iOS 14 - [Review supported device and iOS versions](https://support.apple.com/en-us/102662)
+- **Engine**: WKWebView should behave like Safari 14 as this is the native engine
+
+#### macOS
+
+- **Safari 14** (minimum)
+- **Minimum support**: Catalina (potentially Safari 14 is native engine in non-updated device)
+- **Engine**: WKWebView should behave like Safari 14
+
+#### Android
+
+- **Android 23** (minimum) - [Product feedback request: Android - min supported version](https://app.asana.com/1/137249556945/project/908478224964033/task/1209367367171662?focus=true)
+- **Chrome 80+** (minimum)
+- **Reference**: See [pixel dashboard](https://app.asana.com/1/137249556945/project/908478224964033/task/1209367367171662?focus=true)
+
+#### Windows
+
+- **Edge-based** behavior expected
+- **Minimum**: Chrome 83 (if client has disabled all updates)
+- **Reference**: [Windows Browser: Minimum specs](https://app.asana.com/1/137249556945/project/908478224964033/task/1209367367171662?focus=true)
+
+#### Extensions
+
+- **Chrome**: Version 96+ - [Chrome manifest reference](https://github.com/duckduckgo/duckduckgo-privacy-extension/blob/249d8d6ebe38b9b8265ba311909c8971c422122c/browsers/chrome/manifest.json#L6)
+- **Firefox**: Version 91+ - [Firefox manifest reference](https://github.com/duckduckgo/duckduckgo-privacy-extension/blob/249d8d6ebe38b9b8265ba311909c8971c422122c/browsers/firefox/manifest.json#L6)
+
 ## Platform-Specific Implementation Details
 
 ### Firefox

injected/docs/testing-guide.md

@@ -50,3 +50,21 @@ To produce all artefacts that are used by platforms, just run the `npm run build
 ```shell
 npm run build
 ```
+
+## Test Builds for Ship Review
+
+Test builds are created with a GitHub workflow. The assets for Content Scope Scripts will be created on demand if they are absent (which they will be, if you're pointing to a branch of CSS).
+
+1. Commit any changes to CSS and push a branch to the remote
+2. Make sure you commit the submodule reference update in the Windows PR
+3. Continue with "Build an installer for ship review / test"
+
+## Debugging
+
+### Adding Breakpoints
+
+If you drop a `debugger;` line in the scripts and open DevTools window, the DevTools will breakpoint and navigate to that exact line in code when the debug point has been hit.
+
+### Verifying CSS is Loaded
+
+Open DevTools, go to the Console tab and enter `navigator.duckduckgo`. If it's defined, then Content Scope Scripts is running.

injected/integration-test/broker-protection-tests/broker-protection.spec.js

@@ -664,4 +664,47 @@ test.describe('Broker Protection communications', () => {
             dbp.isErrorMessage(response);
         });
     });
+
+    test.describe('condition', () => {
+        test('a successful condition returns success with steps in the response', async ({ page }, workerInfo) => {
+            const dbp = BrokerProtectionPage.create(page, workerInfo.project.use);
+            await dbp.enabled();
+            await dbp.navigatesTo('form.html');
+            await dbp.receivesAction('condition-success.json');
+            const response = await dbp.collector.waitForMessage('actionCompleted');
+            dbp.isSuccessMessage(response);
+
+            // Check that the response contains an actions array
+            const successResponse = await dbp.getSuccessResponse();
+
+            expect(successResponse).toHaveProperty('actions');
+            expect(Array.isArray(successResponse.actions)).toBe(true);
+            expect(successResponse.actions.length).toBeGreaterThan(0);
+        });
+
+        test('a condition with failSilently returns success with empty actions array', async ({ page }, workerInfo) => {
+            const dbp = BrokerProtectionPage.create(page, workerInfo.project.use);
+            await dbp.enabled();
+            await dbp.navigatesTo('form.html');
+            await dbp.receivesAction('condition-fail-silently.json');
+            const response = await dbp.collector.waitForMessage('actionCompleted');
+            dbp.isSuccessMessage(response);
+
+            // Check that the response does not contain an actions array
+            const successResponse = await dbp.getSuccessResponse();
+
+            expect(successResponse).toHaveProperty('actions');
+            expect(Array.isArray(successResponse.actions)).toBe(true);
+            expect(successResponse.actions.length).toBe(0);
+        });
+
+        test('a failing condition returns error', async ({ page }, workerInfo) => {
+            const dbp = BrokerProtectionPage.create(page, workerInfo.project.use);
+            await dbp.enabled();
+            await dbp.navigatesTo('form.html');
+            await dbp.receivesAction('condition-fail.json');
+            const response = await dbp.collector.waitForMessage('actionCompleted');
+            dbp.isErrorMessage(response);
+        });
+    });
 });

injected/integration-test/test-pages/broker-protection/actions/condition-fail-silently.json

@@ -0,0 +1,30 @@
+{
+    "state": {
+      "action": {
+        "actionType": "condition",
+        "retry": {
+            "environment": "web",
+            "interval": { "ms": 1000 },
+            "maxAttempts": 1
+        },
+        "expectations": [
+          {
+            "type": "element",
+            "selector": "form.fakeForm",
+            "failSilently": true
+          }
+        ],
+        "actions": [
+          {
+            "actionType": "click",
+            "elements": [
+              {
+                "type": "button",
+                "selector": ".btn-sbmt"
+              }
+            ]
+          }
+        ]
+      }
+    }
+  }

injected/integration-test/test-pages/broker-protection/actions/condition-fail.json

@@ -0,0 +1,29 @@
+{
+    "state": {
+      "action": {
+        "actionType": "condition",
+        "retry": {
+            "environment": "web",
+            "interval": { "ms": 1000 },
+            "maxAttempts": 1
+        },
+        "expectations": [
+          {
+            "type": "element",
+            "selector": "form.fakeForm"
+          }
+        ],
+        "actions": [
+          {
+            "actionType": "click",
+            "elements": [
+              {
+                "type": "button",
+                "selector": ".btn-sbmt"
+              }
+            ]
+          }
+        ]
+      }
+    }
+  }

injected/integration-test/test-pages/broker-protection/actions/condition-success.json

@@ -0,0 +1,24 @@
+{
+    "state": {
+      "action": {
+        "actionType": "condition",
+        "expectations": [
+          {
+            "type": "element",
+            "selector": "form.ahm"
+          }
+        ],
+        "actions": [
+          {
+            "actionType": "click",
+            "elements": [
+              {
+                "type": "button",
+                "selector": ".btn-sbmt"
+              }
+            ]
+          }
+        ]
+      }
+    }
+  }

injected/src/features/broker-protection.js

@@ -100,9 +100,9 @@ export default class BrokerProtection extends ContentFeature {
             };
         }
         /**
-         * Special case for when expectation contains a check for an element, retry it
+         * Special case for when expectation or condition contains a check for an element, retry it
          */
-        if (!retryConfig && action.actionType === 'expectation') {
+        if (!retryConfig && (action.actionType === 'expectation' || action.actionType === 'condition')) {
             if (action.expectations.some((x) => x.type === 'element')) {
                 return {
                     interval: { ms: 1000 },