AGENTS.md

1# Injected Features
2 
3JavaScript 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.
4 
5**See also:**
6- `docs/coding-guidelines.md` for code style, patterns, and examples
7- `docs/css-decision-guide.md` for when to use C-S-S vs native code
8- [privacy-configuration experiments guide](https://github.com/duckduckgo/privacy-configuration/blob/main/.cursor/rules/content-scope-experiments.mdc) for A/B testing features
9 
10## Structure
11 
12```
13src/features/<name>.js    # Feature implementation (extends ContentFeature)
14src/features.js           # Feature registry (baseFeatures + otherFeatures arrays)
15entry-points/<platform>.js # Platform-specific bundles
16integration-test/         # Playwright integration tests
17unit-test/                # Jasmine unit tests
18```
19 
20**Adding a new feature:** Add to `baseFeatures` or `otherFeatures` in `src/features.js`, then add to relevant platform arrays in `platformSupport`. Build the project after adding a new feature in `src/features/` to keep types up-to-date (`npm run build`).
21 
22**Strict TypeScript:** All new feature files must be added to the `CORE_FILES` set in `scripts/check-strict-core.js`. This enforces full TypeScript strict mode (`strict: true`, `noUncheckedIndexedAccess`) on the file. Run `npm run tsc-strict-core` from the repo root to verify. Existing files in the set must not regress.
23 
24## TypeScript
25 
26JSDoc types in JavaScript files. Import types via `@typedef`:
27 
28```javascript
29/** @typedef {import('../types/feature.js').SettingType} SettingType */
30```
31 
32## Testing
33 
34Run from `injected/` directory:
35 
36| Command | Purpose |
37|---------|---------|
38| `npm run test-unit` | Jasmine unit tests |
39| `npm run test-int` | Playwright integration tests |
40| `npm run build` | Build all platform bundles |
41 
42Integration tests use test pages in `integration-test/test-pages/`.
43 
44## Linting
45 
46After making code changes, **always run** `npm run lint-fix` (from repo root) and incorporate any auto-fixes before returning results.
47 
48## Key Patterns
49 
50- **Event listeners**: Use `handleEvent` pattern or stored references (avoid `.bind(this)`)
51- **API existence**: Check `typeof API === 'function'` before wrapping
52- **DOM timing**: Check `document.readyState` before accessing DOM
53- **Error types**: Match native error signatures in API shims
54 
55See `docs/coding-guidelines.md` for DDGProxy, captured globals, retry utilities, and other patterns.
56 
57## Platform Considerations
58 
59Features are bundled per-platform in `entry-points/`:
60- `apple.js` - iOS/macOS
61- `android.js` - Android  
62- `windows.js` - Windows
63- `extension-mv3.js` - Browser extension
64 
65Platform-specific features: `navigatorInterface`, `windowsPermissionUsage`, `messageBridge`, `favicon`, `breakageReporting`, `webInterferenceDetection`, `webDetection`, `webEvents` (see `utils.js` `platformSpecificFeatures`).
66 
67## Messaging Constraints
68 
69- **Never include `nativeData` as a field in any message sent to the client.** The `nativeData` field is reserved for native platform use — native implementations inject a `nativeData` field into incoming messages, and `nativeData` is reserved for that layer. When constructing `notify()` or `request()` params, only pass explicitly defined fields (destructure rather than spread).
70 
71## Notes
72 
73- When running Playwright commands, use `--reporter list` to prevent hanging
74- Features can be enabled/disabled per-site via remote config
75- Add debug flags with `this.addDebugFlag()` for breakage reports
76 
77## “internal” / “preview” conditional config
78 
79The injected config system supports `internal` and `preview` keys inside conditional blocks (see `ConfigFeature` in `injected/src/config-feature.js`). These values come from `userPreferences.platform.internal` / `userPreferences.platform.preview` and are not inferred automatically.
80