WEFT_OS/docs/architecture/spidermonkey-bridge-assessment.md

# SpiderMonkey Bridge Assessment

**Status:** Assessment complete — blocker 3 resolved.
**Decision:** Custom SpiderMonkey bindings are not required. WebSocket satisfies the UI endpoint contract.

---

## Context

The weft-appd IPC channel design (see `docs/architecture/wasm-servo-channel.md`) requires a
UI endpoint: a mechanism by which the system UI HTML page running inside Servo can receive
notifications from `weft-appd` (e.g., `APP_READY`) and send requests (e.g., `LAUNCH_APP`).

The original concern ("blocker 3") was that satisfying this requirement might need custom
SpiderMonkey bindings injected into Servo — functionality that is not stable or exposed as a
public Servo API.

---

## What the UI Endpoint Requires

1. The system-ui.html page must be able to **send** structured messages to `weft-appd`
   (LAUNCH_APP, TERMINATE_APP, QUERY_RUNNING, QUERY_APP_STATE).
2. The system-ui.html page must be able to **receive** asynchronous push notifications from
   `weft-appd` (LAUNCH_ACK, APP_READY).
3. Messages must carry a session identifier and structured payload.
4. The transport must work over a local connection (same machine, session-local).

None of these requirements are specific to SpiderMonkey internals. They describe a generic
bidirectional message channel.

---

## Servo's Relevant Capabilities (as of 2025)

| Feature | Status | Notes |
|---------|--------|-------|
| WebSocket API (RFC 6455) | Implemented | `servo/components/script/dom/websocket.rs` |
| fetch() | Implemented | Standard Fetch API |
| JSON.parse / JSON.stringify | Implemented | Core JS, SpiderMonkey |
| `addEventListener` / `dispatchEvent` | Implemented | Full DOM events |
| ES modules | Partially implemented | Not required for this use case |
| Service Workers | Not implemented | Not required |
| Custom native APIs via embedder | Not stable / no public API | This was the original concern |

**Key finding:** WebSocket is implemented in Servo and is the standard API for persistent
bidirectional message channels between a web page and a local service.

---

## Proposed Implementation: WebSocket Endpoint in weft-appd

`weft-appd` already has `tokio` with the `net` feature. Adding a WebSocket server alongside
the existing Unix socket server requires only the `tokio-tungstenite` crate (tokio-native
WebSocket).

### Transport architecture

```
system-ui.html (Servo)
  └─ WebSocket ws://127.0.0.1:<port>/appd
        │
        │  JSON frames (human-readable, same semantics as MessagePack IPC)
        │
weft-appd WebSocket listener
  └─ shared SessionRegistry (same Arc<Mutex<...>>)
```

The Unix socket remains the production IPC path for machine-to-machine communication
(servo-shell native path). The WebSocket listener is the UI endpoint for Servo.

### Message format

The same `Request` / `Response` enum used by the MessagePack Unix socket path is also
serialized as JSON for the WebSocket channel (using `serde_json`). The type tag remains
`SCREAMING_SNAKE_CASE`.

Example:
```json
{"type":"LAUNCH_APP","app_id":"com.example.notes","surface_id":0}
```

### Port selection

`weft-appd` binds on `127.0.0.1` only. The port is resolved in priority order:
1. `WEFT_APPD_WS_PORT` environment variable
2. Default: `7410`

The port is written to `$XDG_RUNTIME_DIR/weft/appd.wsport` at startup so that the
system-ui.html can discover it without hardcoding.

### Push notifications

The WebSocket connection stays open. `weft-appd` pushes `APP_READY` frames to all connected
clients when a session transitions to `Running`. This is implemented with a `tokio::sync::broadcast`
channel that the WebSocket handler subscribes to.

---

## What This Assessment Does Not Cover

- **Servo's Wayland EGL surface stability**: covered in `docs/architecture/winit-wayland-audit.md`.
- **Servo DPI / HiDPI rendering**: not assessed; deferred.
- **Content Security Policy interactions with ws://127.0.0.1**: `system-ui.html` is served
  from the local filesystem (file://) or a bundled origin. CSP headers are controlled by
  WEFT, so `ws://127.0.0.1` can be explicitly allowed.
- **Servo WebSocket reconnect on compositor restart**: not designed; out of scope for initial
  implementation.

---

## Blocker 3 Resolution

The original concern was that the UI endpoint would require injecting custom SpiderMonkey
bindings into Servo, which is not a stable operation.

**This concern is resolved.** The UI endpoint is implemented entirely via the standard
WebSocket API, which Servo ships as a fully functional implementation. No custom SpiderMonkey
bindings are needed. The WEFT codebase does not modify Servo's internals for this feature.

**Implementation required:**
1. Add `tokio-tungstenite` + `serde_json` to `weft-appd`.
2. Add `broadcast::Sender<Response>` to `run()` for push notifications.
3. Start a WebSocket listener task alongside the existing Unix socket listener.
4. Update `system-ui.html` to connect via WebSocket and handle `APP_READY` events.

This work is scoped and ready to implement.