Skip to content

Docs: Work with content-scope-scripts repo on Windows #1794

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jul 7, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .cursorrules
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
17 changes: 11 additions & 6 deletions injected/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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/).
71 changes: 71 additions & 0 deletions injected/docs/development-utilities.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)`
Expand Down
35 changes: 35 additions & 0 deletions injected/docs/platform-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 18 additions & 0 deletions injected/docs/testing-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
65 changes: 65 additions & 0 deletions special-pages/README.md
Original file line number Diff line number Diff line change
@@ -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=<page-directory-name>
```

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.
Expand Down
Loading