AGENTS.md

1# Special Pages
2 
3Preact-based HTML/CSS/JS applications embedded in DuckDuckGo browsers. Each page is an isolated app with privileged native API access.
4 
5## Structure
6 
7```
8pages/<name>/
9├── app/              # Preact components (App.jsx, *.module.css)
10├── src/index.js      # Page class with messaging methods  
11├── messages/         # JSON schemas → auto-generates types/
12├── types/<name>.ts   # Generated types (DO NOT EDIT)
13├── public/           # Static assets, index.html, locales/
14└── integration-tests/
15shared/               # Reusable components (Button, Card, Switch, Text) and functions
16```
17 
18## Code Style
19 
20Pages communicate with native via `@duckduckgo/messaging`. Define schemas in `messages/`:
21- `*.request.json` + `*.response.json` → async request/response
22- `*.notify.json` → fire-and-forget notification
23- `*.subscribe.json` → push-based subscription
24 
25Types in `types/` are auto-generated from `messages/` schemas - never edit these manually.
26 
27Use JSDoc types in JavaScript files. Import types via a `@typedef` after imports:
28 
29```javascript
30/** @typedef {import('./types.js').MyType} MyType */
31```
32 
33Use the Page Object pattern (see `integration-tests/<name>.js` for helpers) when writing integration tests.
34 
35Localized strings are compiled from multiple `strings.json` files into a single `public/locales/en/<page>.json` file. This is manually uploaded to Smartling to generate each `public/locales/<locale>/<page>.json` file.
36 
37## Testing
38 
39Run from `special-pages/` directory:
40 
41| Command | Purpose |
42|---------|---------|
43| `npm run test-unit` | Unit tests |
44| `npm run test-int -- --reporter list` | Integration tests (all platforms) |
45| `npm run test-int -- --project ios --repoter list` | Single platform |
46| `npm run test-int -- --grep "test name" --reporter list` | Run integration tests matching a pattern |
47| `npm run test-int -- pages/new-tab/integration-tests/new-tab.spec.js --reporter list` | Run single integration test suite |
48| `npm run test-int-x -- --reporter list` | Exclude screenshot tests |
49| `npm run test.screenshots -- --reporter list` | Screenshot tests only |
50 
51Top-level commands (`npm run build`, `npm run lint`) also work from this directory.
52 
53## Notes
54 
55- Use `.github/pull_request_template.md` when creating a pull request.
56- Use the `Build Branch` PR comment links (docs/static pages/integration pages) in testing steps for pull requests.
57- Playwright MCP server (if available) or `npx playwright` can be used to validate UI changes if desired. Use `npm run watch -- --page <name>` if user hasn't already done so and then navigate to `http://localhost:8000`.
58