Design documents for splitting the notes browser into a browser process (wx GUI) and a separate kernel process (Python executor). Motivated by the current single-thread limitation where long-running cells block the control socket and freeze the UI.
Documents
- Architecture — process overview, transport comparison (pipe vs WebSocket), startup sequences, file locations.
- Protocol — message format, framing, all request methods and events, state machine, error codes, authentication, worked example.
Key Design Points
- Two processes: browser (wx, rendering, control socket) and kernel (Python executor, namespace).
- Same JSON protocol on both transports — pipe for local, WebSocket for remote.
- Framing: newline-delimited JSON. One message per line on pipe; one message per frame on WebSocket.
- Cell execution is fire-and-forget: browser sends execute.cell, kernel responds immediately, then pushes stream/display/done events asynchronously.
- Control socket sheet.cell.run becomes non-blocking; new sheet.cell.await method for callers that need synchronous behaviour.
- Interrupt, reset, and input() reply all work mid-execution via the same message channel.