AGENTS.md

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