diff --git a/.cursorrules b/.cursorrules index 473c997ac6..672eff1778 100644 --- a/.cursorrules +++ b/.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` diff --git a/injected/README.md b/injected/README.md index b6f15cdf4e..801e94cb11 100644 --- a/injected/README.md +++ b/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/). diff --git a/injected/docs/development-utilities.md b/injected/docs/development-utilities.md index 583d71fc1a..6d5586954d 100644 --- a/injected/docs/development-utilities.md +++ b/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 "/submodules/content-scope-scripts:/content-scope-scripts" node:latest /bin/bash + +root@:/# cd /content-scope-scripts +root@:/content-scope-scripts# npm install +root@:/content-scope-scripts# npm run build +``` + ## ContentFeature Utilities ### `ContentFeature.defineProperty(object, propertyName, descriptor)` diff --git a/injected/docs/platform-integration.md b/injected/docs/platform-integration.md index 46e8e1d3cf..be3a1c6bef 100644 --- a/injected/docs/platform-integration.md +++ b/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 diff --git a/injected/docs/testing-guide.md b/injected/docs/testing-guide.md index 78ef8f34e6..688df48c2c 100644 --- a/injected/docs/testing-guide.md +++ b/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. diff --git a/special-pages/README.md b/special-pages/README.md index 298b38f0db..5b806fc0de 100644 --- a/special-pages/README.md +++ b/special-pages/README.md @@ -1,3 +1,68 @@ +# Special Pages + +## Overview + +Special Pages gives us a single place to implement isolated HTML/CSS/Javascript projects that can be loaded into a web context that has privileged access to API. + +## Getting Started with Special Pages Development + +### Prerequisites + +Before starting Special Pages development, ensure you have completed the initial setup: + +> **Repository access and initial setup**: See [Development Utilities - Development Setup](../injected/docs/development-utilities.md#development-setup) for repository access, cloning, and initial build setup. + +### Step 1: Make a Change to the 'Example' Special Page + +Edit the file `App.jsx` within `special-pages/pages/example/app/components` + +### Step 2: Rebuild + +Since Content Scope Scripts contains additional projects, you can just rebuild the special-pages parts: + +```shell +cd special-pages +npm run build +``` + +### Step 3: Review Your Change + +Still within `special-pages`, you can now serve the built pages: + +```shell +npm run serve +``` + +Then access the Example page you edited via: `http://127.0.0.1:3210/example/` + +> **Note**: The output of the build command is just plain HTML/CSS/JS, so you can serve the build directory in any way that suits you. + +### Step 4: Watch Mode + +The build command builds every special page, but to run just 1 in isolation: + +```shell +npm run watch -- --page= +``` + +Check the terminal for the dev URL, but it's normally `localhost:8000`. + +> **Note**: Any changes you make here will not be automatically reflected in the build folder output. + +### Step 5: Create a PR + Preview the Change + +Content Scope Scripts uses Netlify preview deployments, so opening a PR will create a preview URL. + +During the deployment: +- Docs are generated +- All special pages are built + +When you access the Netlify URL, you'll land on the docs homepage. Append `/build/pages/example` to the URL to see the changes you made to the Example application. + +**Example URLs:** +- Preview: `https://content-scope-scripts.netlify.app/build/pages/example/` +- Production: `https://content-scope-scripts.netlify.app` + ## Architecture Special Pages gives us a single place to implement isolated HTML/CSS/Javascript projects that can be loaded into a web context that has privileged access to API.