Two files, one repository
duckduckgo/content-scope-scripts ships 2 formats across 18 indexed files. The question worth asking is whether the second one says anything the first does not.
CompareAGENTS.md ↔ Cursor rules
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 13 | 6 | 0% |
| Commands | 0 | 12 | 1 | 0% |
| Section tags | 2 | 7 | 2 | 18% |
What each file covers
Sections
0 shared · 13 only in A · 6 only in B- − Content Scope Scripts (C-S-S)
- − Workspaces
- − `injected/` - Browser Privacy Features
- − `special-pages/` - Embedded Browser Pages
- − `messaging/` - Web-Native Communication
- − `types-generator/` - Schema to TypeScript
- − Commands
- − Coding Standards
- − Strict TypeScript
- − Debugging
- − Notes
- − Local dev quick wins (common pain points)
- − Cursor Cloud specific instructions
- + Types Generator
- + Structure
- + Usage
- + Rules
- + Testing
- + Run from types-generator/ directory
Commands
0 shared · 12 only in A · 1 only in B- − npm run build
- − npm run test-unit
- − npm run test-int
- − npm run lint
- − npm run lint-fix
- − npm run serve
- − npm run serve-special-pages
- − npm run tsc-strict-core
- − npm run watch -- --page=<page>
- − npm link
- − npm ci
- − npm run test-int-x
- + npm test
Section tags
2 shared · 7 only in A · 2 only in B- − build
- − lint-format
- − code-style
- − git-pr
- − database
- − deployment
- − agent-behaviour
- + architecture
- + do-not
- test
- types
Line diff
duckduckgo/content-scope-scripts · AGENTS.md
@@ −1 @@
1# Content Scope Scripts (C-S-S)
2
3Shared JavaScript projects powering privacy features and special pages in DuckDuckGo's native apps (macOS, Windows, iOS, Android).
4
5## Workspaces
6
7This is an npm workspace monorepo with four sub-projects:
8
9### `injected/` - Browser Privacy Features
10
11JavaScript features injected into web pages for privacy protections. Features extend `ConfigFeature` and integrate with remote configuration for per-site enable/disable.
12
13**Features** (in `injected/src/features/`):
14- `api-manipulation` - API behavior modifications
15- `autofill-import` - Credential import support
16- `breakage-reporting` - Site breakage reports
17- `broker-protection` - Data broker removal automation
18- `click-to-load` - Social embed blocking
19- `cookie` - Cookie management
20- `duck-player` / `duck-player-native` - YouTube privacy player
21- `element-hiding` - Hide page elements
22- `exception-handler` - Error handling
23- `favicon` - Favicon privacy
24- `fingerprinting-*` - Audio, battery, canvas, hardware, screen, storage fingerprint protection
25- `google-rejected` - Google rejection handling
26- `gpc` - Global Privacy Control
27- `harmful-apis` - Dangerous API restrictions
28- `message-bridge` - Page↔content script messaging
29- `navigator-interface` - Navigator API modifications
30- `performance-metrics` - Performance tracking
31- `referrer` - Referrer protection
32- `web-compat` - Site compatibility fixes
33- `web-interference-detection` / `web-telemetry` - Monitoring
34
35**Docs:** `injected/docs/README.md` (index to all docs)
36
37### `special-pages/` - Embedded Browser Pages
38
39Preact-based HTML/CSS/JS applications embedded in browsers. Each page lives in `special-pages/pages/<name>/`.
40
41**Pages:**
42- `duckplayer` - YouTube privacy player UI
43- `errorpage` - Browser error pages
44- `example` - Template for new pages
45- `history` - Browsing history viewer
46- `new-tab` - New Tab Page
47- `onboarding` - First-run experience
48- `release-notes` - Browser release notes
49- `special-error` - SSL/certificate error pages
50
51**Docs:** `special-pages/README.md`, plus `readme.md` in each page directory
52
53### `messaging/` - Web-Native Communication
54
55Abstraction layer for web↔native messaging: `notify` (fire-and-forget), `request` (async response), `subscribe` (push updates).
56
57**Docs:** `messaging/docs/messaging.md`
58
59### `types-generator/` - Schema to TypeScript
60
61Generates TypeScript types from JSON Schema files. Used by other workspaces.
62
63## Commands
64
65Run from root. Use `nvm use` to set the correct Node version.
66
67| Command | Purpose |
68|---------|---------|
69| `npm run build` | Build all workspaces |
70| `npm run test-unit` | Unit tests (all workspaces) |
71| `npm run test-int` | Integration tests (Playwright) |
72| `npm run lint` | ESLint + TypeScript + Prettier |
73| `npm run lint-fix` | Auto-fix lint issues |
74| `npm run serve` | Serve injected test pages (port 3220) |
75| `npm run serve-special-pages` | Serve special pages (port 3221) |
76
77## Coding Standards
78
79Follow the error handling guidelines in [`guides/error-handling.md`](guides/error-handling.md). Key rules:
80- Errors are for **exceptional conditions** (invariant violations, unreachable code), not control flow
81- Never leave promises unhandled — use `.catch()` or `try/catch` with `await`
82- Return `null`/sentinel values for expected missing data instead of throwing
83
84### Strict TypeScript
85
86All **new** source files under `injected/src/` must be added to the `CORE_FILES` set in `scripts/check-strict-core.js`. This enforces TypeScript strict mode (`strict: true`, `noUncheckedIndexedAccess`). Run `npm run tsc-strict-core` to verify. Do not remove existing entries from the set.
87
88## Debugging
89
90See [`guides/debugging.md`](guides/debugging.md) for debugging resources including script integrity validation, feature triage checklist, and platform-specific troubleshooting.
91
92## Notes
93
94- When running Playwright commands, use `--reporter list` to prevent the Shell tool from hanging
95- Use `.github/pull_request_template.md` when creating a pull request.
96
97## Local dev quick wins (common pain points)
98
99- **Special Pages CSS local dev**: use `npm run serve-special-pages` (repo root) + `npm run watch -- --page=<page>` (inside `special-pages/`) for hot CSS reload (usually `http://localhost:8000/`). The `build/` output does **not** auto-update in watch mode.
100- **Release workflow**: releases are created from GitHub Actions (see `CONTRIBUTING.md` → “Release Process”). For most iteration, prefer Netlify preview URLs or `npm link` into native apps; only cut a release when you need native consumption via the `releases` branch artifacts.
101
102## Cursor Cloud specific instructions
103
104- Node 22 and npm are pre-installed. Playwright browsers + system deps are pre-installed. Just run `npm ci` to refresh dependencies.
105- `npm run serve-special-pages` actually serves on **port 3210** (not 3221 as the Commands table above states). The injected test pages serve on port 3220 as documented.
106- Integration tests for injected workspace may show 2 flaky iOS mobile drawer timeouts (`duckplayer-mobile-drawer.spec.js`); these are pre-existing timing issues, not environment problems.
107- No Docker, databases, or external services are needed. All tests are self-contained with local HTTP servers and mocked native messaging.
108- On headless Linux, `xvfb` is pre-installed. The injected workspace provides `npm run test-int-x` which wraps Playwright with `xvfb-run`, but standard `npm run test-int` also works in this environment.
109
duckduckgo/content-scope-scripts · types-generator/AGENTS.md
@@ +1 @@
1# Types Generator
2
3Generates TypeScript types from JSON Schema files. Used by `injected/` and `special-pages/` workspaces.
4
5## Structure
6
7```
8build-types.mjs # Main entry — buildTypes(config)
9json-schema.mjs # Schema → TypeScript conversion logic
10json-schema-fs.mjs # File system utilities for schema resolution
11unit-test/ # Unit tests
12```
13
14## Usage
15
16```javascript
17import { buildTypes } from "../types-generator/build-types.mjs";
18
19const config = {
20 "featureName": {
21 "schema": "path/to/schema.json",
22 "types": "path/to/output/types.d.ts",
23 "kind": "settings" // or "messages"
24 }
25};
26
27buildTypes(config); // writes directly to disk
28```
29
30Two mapping kinds:
31- **`SettingsKind`** — schemas representing feature settings → TypeScript types
32- **`MessagesKind`** — messaging schemas → TypeScript types integrated with `@duckduckgo/messaging`
33
34## Rules
35
36- **Never manually edit generated `.ts` files** — they are overwritten on each run
37- The script **fails fast** — errors are not caught, to ensure visibility during type generation
38- Platform-specific exclusions can be specified per mapping entry
39
40## Testing
41
42```shell
43# Run from types-generator/ directory
44npm test
45```
46
@@ −1 +1 @@
1−# Content Scope Scripts (C-S-S)
1+# Types Generator
22
3−Shared JavaScript projects powering privacy features and special pages in DuckDuckGo's native apps (macOS, Windows, iOS, Android).
3+Generates TypeScript types from JSON Schema files. Used by `injected/` and `special-pages/` workspaces.
44
5−## Workspaces
5+## Structure
66
7−This is an npm workspace monorepo with four sub-projects:
7+```
8+build-types.mjs # Main entry — buildTypes(config)
9+json-schema.mjs # Schema → TypeScript conversion logic
10+json-schema-fs.mjs # File system utilities for schema resolution
11+unit-test/ # Unit tests
12+```
813
9−### `injected/` - Browser Privacy Features
14+## Usage
1015
11−JavaScript features injected into web pages for privacy protections. Features extend `ConfigFeature` and integrate with remote configuration for per-site enable/disable.
16+```javascript
17+import { buildTypes } from "../types-generator/build-types.mjs";
1218
13−**Features** (in `injected/src/features/`):
14−- `api-manipulation` - API behavior modifications
15−- `autofill-import` - Credential import support
16−- `breakage-reporting` - Site breakage reports
17−- `broker-protection` - Data broker removal automation
18−- `click-to-load` - Social embed blocking
19−- `cookie` - Cookie management
20−- `duck-player` / `duck-player-native` - YouTube privacy player
21−- `element-hiding` - Hide page elements
22−- `exception-handler` - Error handling
23−- `favicon` - Favicon privacy
24−- `fingerprinting-*` - Audio, battery, canvas, hardware, screen, storage fingerprint protection
25−- `google-rejected` - Google rejection handling
26−- `gpc` - Global Privacy Control
27−- `harmful-apis` - Dangerous API restrictions
28−- `message-bridge` - Page↔content script messaging
29−- `navigator-interface` - Navigator API modifications
30−- `performance-metrics` - Performance tracking
31−- `referrer` - Referrer protection
32−- `web-compat` - Site compatibility fixes
33−- `web-interference-detection` / `web-telemetry` - Monitoring
19+const config = {
20+ "featureName": {
21+ "schema": "path/to/schema.json",
22+ "types": "path/to/output/types.d.ts",
23+ "kind": "settings" // or "messages"
24+ }
25+};
3426
35−**Docs:** `injected/docs/README.md` (index to all docs)
27+buildTypes(config); // writes directly to disk
28+```
3629
37−### `special-pages/` - Embedded Browser Pages
30+Two mapping kinds:
31+- **`SettingsKind`** — schemas representing feature settings → TypeScript types
32+- **`MessagesKind`** — messaging schemas → TypeScript types integrated with `@duckduckgo/messaging`
3833
39−Preact-based HTML/CSS/JS applications embedded in browsers. Each page lives in `special-pages/pages/<name>/`.
34+## Rules
4035
41−**Pages:**
42−- `duckplayer` - YouTube privacy player UI
43−- `errorpage` - Browser error pages
44−- `example` - Template for new pages
45−- `history` - Browsing history viewer
46−- `new-tab` - New Tab Page
47−- `onboarding` - First-run experience
48−- `release-notes` - Browser release notes
49−- `special-error` - SSL/certificate error pages
36+- **Never manually edit generated `.ts` files** — they are overwritten on each run
37+- The script **fails fast** — errors are not caught, to ensure visibility during type generation
38+- Platform-specific exclusions can be specified per mapping entry
5039
51−**Docs:** `special-pages/README.md`, plus `readme.md` in each page directory
40+## Testing
5241
53−### `messaging/` - Web-Native Communication
54−
55−Abstraction layer for web↔native messaging: `notify` (fire-and-forget), `request` (async response), `subscribe` (push updates).
56−
57−**Docs:** `messaging/docs/messaging.md`
58−
59−### `types-generator/` - Schema to TypeScript
60−
61−Generates TypeScript types from JSON Schema files. Used by other workspaces.
62−
63−## Commands
64−
65−Run from root. Use `nvm use` to set the correct Node version.
66−
67−| Command | Purpose |
68−|---------|---------|
69−| `npm run build` | Build all workspaces |
70−| `npm run test-unit` | Unit tests (all workspaces) |
71−| `npm run test-int` | Integration tests (Playwright) |
72−| `npm run lint` | ESLint + TypeScript + Prettier |
73−| `npm run lint-fix` | Auto-fix lint issues |
74−| `npm run serve` | Serve injected test pages (port 3220) |
75−| `npm run serve-special-pages` | Serve special pages (port 3221) |
76−
77−## Coding Standards
78−
79−Follow the error handling guidelines in [`guides/error-handling.md`](guides/error-handling.md). Key rules:
80−- Errors are for **exceptional conditions** (invariant violations, unreachable code), not control flow
81−- Never leave promises unhandled — use `.catch()` or `try/catch` with `await`
82−- Return `null`/sentinel values for expected missing data instead of throwing
83−
84−### Strict TypeScript
85−
86−All **new** source files under `injected/src/` must be added to the `CORE_FILES` set in `scripts/check-strict-core.js`. This enforces TypeScript strict mode (`strict: true`, `noUncheckedIndexedAccess`). Run `npm run tsc-strict-core` to verify. Do not remove existing entries from the set.
87−
88−## Debugging
89−
90−See [`guides/debugging.md`](guides/debugging.md) for debugging resources including script integrity validation, feature triage checklist, and platform-specific troubleshooting.
91−
92−## Notes
93−
94−- When running Playwright commands, use `--reporter list` to prevent the Shell tool from hanging
95−- Use `.github/pull_request_template.md` when creating a pull request.
96−
97−## Local dev quick wins (common pain points)
98−
99−- **Special Pages CSS local dev**: use `npm run serve-special-pages` (repo root) + `npm run watch -- --page=<page>` (inside `special-pages/`) for hot CSS reload (usually `http://localhost:8000/`). The `build/` output does **not** auto-update in watch mode.
100−- **Release workflow**: releases are created from GitHub Actions (see `CONTRIBUTING.md` → “Release Process”). For most iteration, prefer Netlify preview URLs or `npm link` into native apps; only cut a release when you need native consumption via the `releases` branch artifacts.
101−
102−## Cursor Cloud specific instructions
103−
104−- Node 22 and npm are pre-installed. Playwright browsers + system deps are pre-installed. Just run `npm ci` to refresh dependencies.
105−- `npm run serve-special-pages` actually serves on **port 3210** (not 3221 as the Commands table above states). The injected test pages serve on port 3220 as documented.
106−- Integration tests for injected workspace may show 2 flaky iOS mobile drawer timeouts (`duckplayer-mobile-drawer.spec.js`); these are pre-existing timing issues, not environment problems.
107−- No Docker, databases, or external services are needed. All tests are self-contained with local HTTP servers and mocked native messaging.
108−- On headless Linux, `xvfb` is pre-installed. The injected workspace provides `npm run test-int-x` which wraps Playwright with `xvfb-run`, but standard `npm run test-int` also works in this environment.
42+```shell
43+# Run from types-generator/ directory
44+npm test
45+```
10946
