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

jonathanKingston · web-flow · commit 9b055be6f556 · 2025-07-07T23:15:45.000+01:00
* Add working with C-S-S for Windows content

* Add windows caveat

* Add Getting started docs

* Add platform support docs

* Lint fix

* Change certainty of WSL advice
diff --git 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
@@ -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
@@ -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)`
diff --git 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
@@ -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
@@ -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.
