Architecture
Browser Bridge
Debugging entry points for the WebSocket bridge between the browser extension and the desktop app.
The browser extension connects to ws://127.0.0.1:14370 by default. The desktop implementation lives in app/services/browser_service.py, and the extension implementation lives in browser_extension/app/src/background/desktop-bridge.ts.
Handshake Flow
- The extension reads the service URL and pairing token.
- It sends
hellowithprotocolVersionandtoken. - The desktop app validates the protocol version and token.
- If validation succeeds, the desktop app returns
hello_ackwith capability information. - The extension sends
subscribe_tasksto receive task snapshots.
Message Types
| Type | Purpose |
|---|---|
create_task | Create a desktop task from a captured web resource. |
task_snapshot | Push a task list snapshot from the desktop app to the extension. |
task_action | Pause, delete, redownload, open a file, or open a folder. |
error | Report protocol errors, auth failures, or request failures. |
Protocol Boundary
This bridge protocol exists for the browser extension. It is not a public remote-control API. Use the desktop and extension source code as the source of truth while debugging.
Debugging Entry Points
| Location | Purpose |
|---|---|
app/services/browser_service.py | Desktop WebSocket service, token validation, task creation, and task actions. |
browser_extension/app/src/background/desktop-bridge.ts | Extension-side connection, reconnect logic, request queue, and task snapshot subscription. |
browser_extension/app/src/shared/constants.ts | Default service URL, extension version, and help content. |