Content Scope Scripts handles injecting DOM modifications in a browser context; it's a cross-platform solution that requires some minimal platform hooks.

Content Scope Scripts provides a unified API for features running in web page DOM environments across multiple platforms (Firefox, Chrome, Safari, Android, iOS). Features are loaded dynamically based on remote configuration and can be enabled/disabled per site.

📚 Detailed documentation is available in the docs directory:

• API Reference - Complete reference for the Content Scope Features API
• Features Guide - How to develop features and understand the feature lifecycle
• Platform Integration - Platform-specific implementation details
• Development Utilities - Scope injection utilities and development tools
• Testing Guide - Local testing and development workflow

Content Scope Scripts contains two main sub-projects:

• 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, DOM manipulations)

For Special Pages development, see the Special Pages README for detailed getting started instructions.

Features are JavaScript modules running in web page DOM environments. Each feature:

• Extends the ConfigFeature class for remote configuration support
• Implements the feature lifecycle (load, init, update)
• Can be enabled/disabled per site via remote configuration

• Firefox: Standard extension content scripts
• Apple/Android: UserScripts with string replacements
• Other browsers: Base64-encoded script injection

The global contentScopeFeatures object provides:

• load() - Initialize features that may cause loading delays
• init(args) - Main feature initialization with platform/site configuration
• urlChanged() - Handle Single Page App navigation
• update() - Receive browser updates

High-level overview of how Content Scope Scripts are built and integrated into platforms (example: macOS).

npm test

npm run test-unit      # Unit tests (Jasmine)
npm run test-int       # Integration tests (Playwright)  
npm run build          # Build platform-specific artifacts
npm run fake-extension # Runs an example extension used within the integration tests

• src/features/ - Feature implementations
• entry-points/ - Platform-specific entry points
• unit-test/ - Unit test suite
• integration-test/ - Integration test suite

For detailed development setup instructions, debugging tips, and test build workflows, see the Development Utilities and Testing Guide.

Running specific tests:

To run a specific test or test suite, you can use the --grep flag to filter tests by name:

# Run tests containing "Test infra" in their name
npx playwright test pages.spec.js --grep "Test infra"

# Run tests containing "Conditional frame matching" in their name
npx playwright test pages.spec.js --grep "Conditional frame matching"

# Run tests in headed mode (shows browser window)
npx playwright test pages.spec.js --grep "Test infra" --headed

Debugging tests:

For debugging, you can run tests in headed mode and add debugging output:

# Run with browser visible and debugging enabled
npx playwright test pages.spec.js --grep "Test infra" --headed --debug

To produce all artefacts that are used by platforms, just run the npm run build command. This will create platform specific code within the build folder (that is not checked in)

npm run build

For detailed information about any specific topic, please refer to the documentation.