Initial code comments from PR reviews

CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# Contributing
+
+## Workspace-specific guides
+
+- [Injected coding guidelines](./injected/docs/coding-guidelines.md)
+- [Injected testing guide](./injected/docs/testing-guide.md)
+- [Special Pages README](./special-pages/README.md)
+- [Messaging docs](./messaging/docs/messaging.md)
+
+## Development
+
+Consider using [nvm](https://github.com/nvm-sh/nvm) to manage node versions, after installing in the project directory run:
+
+```
+nvm use
+```
+
+From the top-level root folder of this npm workspace, you can run the following npm commands:
+
+**Install dependencies**:
+
+Will install all the dependencies we need to build and run the project:
+```
+npm install
+```
+
+**Build all workspaces**:
+
+Use this to produce the same output as a release. The `build` directory will be populated with
+various artifacts.
+
+```sh
+npm run build
+```
+
+> [!TIP]
+> You can run the `build` command from within any sub-project too, the artifacts will always be
+> lifted out to the root-level `build` folder.
+
+**Run unit tests for all workspaces**:
+
+```sh
+npm run test-unit
+```
+
+**Run integration tests for all workspaces**:
+```sh
+npm run test-int
+```
+
+**Run extended integration tests for all workspaces**:
+```sh
+npm run test-int-x
+```
+
+**Clean tree and check for changes**:
+```sh
+npm run test-clean-tree
+```
+
+**Generate documentation using TypeDoc**:
+```sh
+npm run docs
+```
+
+**Generate and watch documentation using TypeDoc**:
+```sh
+npm run docs-watch
+```
+
+**Compile TypeScript files**:
+```sh
+npm run tsc
+```
+
+**Watch and compile TypeScript files**:
+```sh
+npm run tsc-watch
+```
+
+**Lint the codebase using ESLint**:
+```sh
+npm run lint
+```
+
+**Lint and automatically fix issues**:
+```sh
+npm run lint-fix
+```
+
+**Serve integration test pages on port 3220**:
+```sh
+npm run serve
+```
+
+**Serve special pages on port 3221**:
+```sh
+npm run serve-special-pages
+```
+
+## Release Process
+
+Releases are created via GitHub Actions: [Release workflow](https://github.com/duckduckgo/content-scope-scripts/actions/workflows/build.yml)
+
+### Creating a release
+
+1. Go to [Actions → Release](https://github.com/duckduckgo/content-scope-scripts/actions/workflows/build.yml)
+2. Click "Run workflow"
+3. Select version bump type
+4. Click "Run workflow"
+
+The workflow creates a tag and GitHub release automatically. Build artifacts on the `releases` branch are consumed by native app repos.

README.md

@@ -30,93 +30,6 @@ Utilities to automatically generate TypeScript types from JSON Schema files.
 
 ---
 
-## NPM commands
+## Contributing
 
-Consider using [nvm](https://github.com/nvm-sh/nvm) to manage node versions, after installing in the project directory run:
-
-```
-nvm use
-```
-
-From the top-level root folder of this npm workspace, you can run the following npm commands:
-
-**Install dependencies**:
-
-Will install all the dependencies we need to build and run the project:
-```
-npm install
-```
-
-**Build all workspaces**:
-
-Use this to produce the same output as a release. The `build` directory will be populated with
-various artifacts.
-
-```sh
-npm run build
-```
-
-> [!TIP]
-> You can run the `build` command from within any sub-project too, the artifacts will always be
-> lifted out to the root-level `build` folder.
-
-**Run unit tests for all workspaces**:
-
-```sh
-npm run test-unit
-```
-
-**Run integration tests for all workspaces**:
-```sh
-npm run test-int
-```
-
-**Run extended integration tests for all workspaces**:
-```sh
-npm run test-int-x
-```
-
-**Clean tree and check for changes**:
-```sh
-npm run test-clean-tree
-```
-
-**Generate documentation using TypeDoc**:
-```sh
-npm run docs
-```
-
-**Generate and watch documentation using TypeDoc**:
-```sh
-npm run docs-watch
-```
-
-**Compile TypeScript files**:
-```sh
-npm run tsc
-```
-
-**Watch and compile TypeScript files**:
-```sh
-npm run tsc-watch
-```
-
-**Lint the codebase using ESLint**:
-```sh
-npm run lint
-```
-
-**Lint and automatically fix issues**:
-```sh
-npm run lint-fix
-```
-
-**Serve integration test pages on port 3220**:
-```sh
-npm run serve
-```
-
-**Serve special pages on port 3221**:
-```sh
-npm run serve-special-pages
-```
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, npm commands, and release process.

injected/.cursor/rules/injected.mdc

@@ -0,0 +1,70 @@
+---
+description: Guidelines for features running in web page DOM environments
+globs: injected/**
+---
+
+# Injected Features
+
+JavaScript features injected into web pages or running in DOM environments of DuckDuckGo browsers. Features extend `ContentFeature` and `ConfigFeature` and integrate with remote configuration for per-site enable/disable.
+
+**See also:**
+- `docs/coding-guidelines.md` for code style, patterns, and examples
+- `docs/css-decision-guide.md` for when to use C-S-S vs native code
+- [privacy-configuration experiments guide](https://github.com/duckduckgo/privacy-configuration/blob/main/.cursor/rules/content-scope-experiments.mdc) for A/B testing features
+
+## Structure
+
+```
+src/features/<name>.js    # Feature implementation (extends ContentFeature)
+src/features.js           # Feature registry (baseFeatures + otherFeatures arrays)
+entry-points/<platform>.js # Platform-specific bundles
+integration-test/         # Playwright integration tests
+unit-test/                # Jasmine unit tests
+```
+
+**Adding a new feature:** Add to `baseFeatures` or `otherFeatures` in `src/features.js`, then add to relevant platform arrays in `platformSupport`.
+
+## TypeScript
+
+JSDoc types in JavaScript files. Import types via `@typedef`:
+
+```javascript
+/** @typedef {import('../types/feature.js').SettingType} SettingType */
+```
+
+## Testing
+
+Run from `injected/` directory:
+
+| Command | Purpose |
+|---------|---------|
+| `npm run test-unit` | Jasmine unit tests |
+| `npm run test-int` | Playwright integration tests |
+| `npm run build` | Build all platform bundles |
+
+Integration tests use test pages in `integration-test/test-pages/`.
+
+## Key Patterns
+
+- **Event listeners**: Use `handleEvent` pattern or stored references (avoid `.bind(this)`)
+- **API existence**: Check `typeof API === 'function'` before wrapping
+- **DOM timing**: Check `document.readyState` before accessing DOM
+- **Error types**: Match native error signatures in API shims
+
+See `docs/coding-guidelines.md` for DDGProxy, captured globals, retry utilities, and other patterns.
+
+## Platform Considerations
+
+Features are bundled per-platform in `entry-points/`:
+- `apple.js` - iOS/macOS
+- `android.js` - Android  
+- `windows.js` - Windows
+- `extension-mv3.js` - Browser extension
+
+Platform-specific features: `navigatorInterface`, `windowsPermissionUsage`, `messageBridge`, `favicon` (see `utils.js` `platformSpecificFeatures`).
+
+## Notes
+
+- When running Playwright commands, use `--reporter list` to prevent hanging
+- Features can be enabled/disabled per-site via remote config
+- Add debug flags with `this.addDebugFlag()` for breakage reports

injected/README.md

@@ -4,7 +4,7 @@ Content Scope Scripts handles injecting DOM modifications in a browser context;
 
 ## Quick Start
 
-Content Scope Scripts provides a unified API for browser privacy features across multiple platforms (Firefox, Chrome, Safari, Android, iOS). Features are loaded dynamically based on remote configuration and can be enabled/disabled per site.
+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.
 
 ## Documentation
 
@@ -23,12 +23,12 @@ Content Scope Scripts provides a unified API for browser privacy features across
 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)
+- **Injected Features** - Features injected into websites (privacy protections, compatibility fixes, DOM manipulations)
 
 > **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:
+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

injected/docs/README.md

@@ -15,6 +15,7 @@ This directory contains detailed documentation for the Content Scope Scripts pro
 
 - **[Development Utilities](./development-utilities.md)** - Scope injection utilities and development tools
 - **[Testing Guide](./testing-guide.md)** - Local testing and development workflow
+- **[Coding Guidelines](./coding-guidelines.md)** - Code style, architecture, security, and performance guidelines
 
 ### Existing Documentation
 
@@ -25,7 +26,8 @@ This directory contains detailed documentation for the Content Scope Scripts pro
 
 If you're new to Content Scope Scripts, start with the main [README](../README.md) for a high-level overview, then dive into the specific documentation based on your needs:
 
-- **Building features?** → [Features Guide](./features-guide.md)
+- **Building features?** → [Features Guide](./features-guide.md) (feature files contain inline guidelines)
+- **Writing code?** → [Coding Guidelines](./coding-guidelines.md)
 - **Integrating with a platform?** → [Platform Integration](./platform-integration.md) and [Platform-Specific Build & Troubleshooting Tips](./build-and-troubleshooting.md)
 - **Using the API?** → [API Reference](./api-reference.md)
 - **Developing utilities?** → [Development Utilities](./development-utilities.md)