From d32c75c66a1de316b6919ff68cc49ce3aa5629a4 Mon Sep 17 00:00:00 2001 From: Robert Anderson Date: Thu, 4 Dec 2025 14:15:07 +1100 Subject: [PATCH] Add top level and special-pages .cursorrules --- .cursorrules | 95 +++++++++++++++++++++++++++++++------- special-pages/.cursorrules | 57 +++++++++++++++++++++++ 2 files changed, 136 insertions(+), 16 deletions(-) create mode 100644 special-pages/.cursorrules diff --git a/.cursorrules b/.cursorrules index 672eff1778..408b631c27 100644 --- a/.cursorrules +++ b/.cursorrules @@ -1,16 +1,79 @@ -# Content Scope Scripts - Cursor Rules - -## Documentation References - -When asked about Content Scope Scripts topics, refer to these documentation files: - -- **API Reference**: `injected/docs/api-reference.md` -- **Feature Development**: `injected/docs/features-guide.md` -- **Platform Integration and engine support**: `injected/docs/platform-integration.md` -- **Development Utilities**: `injected/docs/development-utilities.md` -- **Testing**: `injected/docs/testing-guide.md` -- **Favicon**: `injected/docs/favicon.md` -- **Message Bridge**: `injected/docs/message-bridge.md` -- **Test Pages**: `injected/docs/test-pages-guide.md` -- **Documentation Index**: `injected/docs/README.md` -- **High-level Overview**: `injected/README.md` \ No newline at end of file +# Content Scope Scripts (C-S-S) + +Shared JavaScript projects powering privacy features and special pages in DuckDuckGo's native apps (macOS, Windows, iOS, Android). + +## Workspaces + +This is an npm workspace monorepo with four sub-projects: + +### `injected/` - Browser Privacy Features + +JavaScript features injected into web pages for privacy protections. Features extend `ConfigFeature` and integrate with remote configuration for per-site enable/disable. + +**Features** (in `injected/src/features/`): +- `api-manipulation` - API behavior modifications +- `autofill-import` - Credential import support +- `breakage-reporting` - Site breakage reports +- `broker-protection` - Data broker removal automation +- `click-to-load` - Social embed blocking +- `cookie` - Cookie management +- `duck-player` / `duck-player-native` - YouTube privacy player +- `element-hiding` - Hide page elements +- `exception-handler` - Error handling +- `favicon` - Favicon privacy +- `fingerprinting-*` - Audio, battery, canvas, hardware, screen, storage fingerprint protection +- `google-rejected` - Google rejection handling +- `gpc` - Global Privacy Control +- `harmful-apis` - Dangerous API restrictions +- `message-bridge` - Page↔content script messaging +- `navigator-interface` - Navigator API modifications +- `performance-metrics` - Performance tracking +- `referrer` - Referrer protection +- `web-compat` - Site compatibility fixes +- `web-interference-detection` / `web-telemetry` - Monitoring + +**Docs:** `injected/docs/README.md` (index to all docs) + +### `special-pages/` - Embedded Browser Pages + +Preact-based HTML/CSS/JS applications embedded in browsers. Each page lives in `special-pages/pages//`. + +**Pages:** +- `duckplayer` - YouTube privacy player UI +- `errorpage` - Browser error pages +- `example` - Template for new pages +- `history` - Browsing history viewer +- `new-tab` - New Tab Page +- `onboarding` - First-run experience +- `release-notes` - Browser release notes +- `special-error` - SSL/certificate error pages + +**Docs:** `special-pages/README.md`, plus `readme.md` in each page directory + +### `messaging/` - Web-Native Communication + +Abstraction layer for web↔native messaging: `notify` (fire-and-forget), `request` (async response), `subscribe` (push updates). + +**Docs:** `messaging/docs/messaging.md` + +### `types-generator/` - Schema to TypeScript + +Generates TypeScript types from JSON Schema files. Used by other workspaces. + +## Commands + +Run from root. Use `nvm use` to set the correct Node version. + +| Command | Purpose | +|---------|---------| +| `npm run build` | Build all workspaces | +| `npm run test-unit` | Unit tests (all workspaces) | +| `npm run test-int` | Integration tests (Playwright) | +| `npm run lint` | ESLint + TypeScript + Prettier | +| `npm run lint-fix` | Auto-fix lint issues | +| `npm run serve` | Serve injected test pages (port 3220) | +| `npm run serve-special-pages` | Serve special pages (port 3221) | + +## Notes + +- When running Playwright commands, use `--reporter list` to prevent the Shell tool from hanging diff --git a/special-pages/.cursorrules b/special-pages/.cursorrules new file mode 100644 index 0000000000..8597f6543e --- /dev/null +++ b/special-pages/.cursorrules @@ -0,0 +1,57 @@ +# Special Pages + +Preact-based HTML/CSS/JS applications embedded in DuckDuckGo browsers. Each page is an isolated app with privileged native API access. + +## Structure + +``` +pages// +├── app/ # Preact components (App.jsx, *.module.css) +├── src/index.js # Page class with messaging methods +├── messages/ # JSON schemas → auto-generates types/ +├── types/.ts # Generated types (DO NOT EDIT) +├── public/ # Static assets, index.html, locales/ +└── integration-tests/ +``` + +**Shared code:** `shared/` contains reusable components (`Button`, `Card`, `Switch`, `Text`), `Environment` class, `TranslationProvider`, and `createSpecialPageMessaging()`. + +## Messaging Pattern + +Pages communicate with native via `@duckduckgo/messaging`. Define schemas in `messages/`: +- `*.request.json` + `*.response.json` → async request/response +- `*.notify.json` → fire-and-forget notification +- `*.subscribe.json` → push-based subscription + +## TypeScript + +JSDoc types in JavaScript files. Import types via `@typedef` after imports: + +```javascript +/** @typedef {import('./types.js').MyType} MyType */ +``` + +## Styling + +- Use CSS Modules (`*.module.css`) +- Global styles: `shared/styles/` + +## Testing + +Run from `special-pages/` directory: + +| Command | Purpose | +|---------|---------| +| `npm run test-unit` | Unit tests | +| `npm run test-int` | Integration tests (all platforms) | +| `npm run test-int -- --project ios` | Single platform | +| `npm run test.screenshots` | Screenshot tests only | + +Integration tests use Page Object pattern—see `integration-tests/.js` for helpers. + +Top-level commands (`npm run build`, `npm run lint`) also work from this directory. + +## Notes + +- When running Playwright commands, use `--reporter list` to prevent the Shell tool from hanging +- Types in `types/` are auto-generated from `messages/` schemas—never edit manually