AGENTS.md

1# Messaging
2 
3Abstraction layer for web↔native messaging across DuckDuckGo platforms (macOS, iOS, Android, Windows, Extensions).
4 
5## Structure
6 
7```
8index.js              # Main entry — Messaging class, MessagingContext, platform configs
9schema.js             # Message schemas (NotificationMessage, RequestMessage, etc.)
10native.js             # Native transport for embedded special pages
11lib/
12  webkit.js           # WebkitMessagingTransport (Apple platforms)
13  windows.js          # WindowsMessagingTransport
14  android.js          # AndroidMessagingTransport
15  android-adsjs.js    # Android ads-specific transport
16  typed-messages.js   # createTypedMessages() utility
17  test-utils.mjs      # TestTransportConfig for testing
18docs/
19  messaging.md        # Protocol specification
20  implementation-guide.md  # Native-side implementation algorithm
21  examples.md         # JSON payload examples
22```
23 
24## Core API
25 
26Three communication patterns — all require a `MessagingContext` and platform-specific config:
27 
28```javascript
29// Fire-and-forget notification
30messaging.notify("methodName", { some: "data" })
31 
32// Async request → response
33const response = await messaging.request("methodName", { some: "data" })
34 
35// Push-based subscription
36const unsubscribe = messaging.subscribe("methodName", (data) => console.log(data))
37```
38 
39## Platform Configs
40 
41Each platform has its own config class:
42- `WebkitMessagingConfig` — Apple (webkit message handlers)
43- `WindowsMessagingConfig` — Windows (chrome.webview.postMessage)
44- `AndroidMessagingConfig` — Android (@JavascriptInterface)
45- `TestTransportConfig` — Testing (in `lib/test-utils.mjs`)
46 
47## Testing
48 
49Tests are in the parent project. Use `TestTransportConfig` from `lib/test-utils.mjs` to mock messaging in tests.
50 
51## Notes
52 
53- Message format follows [JSON-RPC](https://www.jsonrpc.org/specification)-inspired structure with `context`, `featureName`, `method`, and optional `params`/`id`
54- See `docs/messaging.md` for the full protocol specification
55- See `docs/implementation-guide.md` for the native-side implementation algorithm
56