emjupy speaks to a Jupyter server the way the browser does: HTTP for files and kernels, WebSockets for a kernel's messages and the language server's. Everything goes over the server's one port, so a remote server needs one SSH tunnel and nothing started on the far side.

 Emacs, on this machine                         Jupyter server, here or remote
┌─────────────────────────────────────┐        ┌───────────────────────────────────────┐
│ notebook buffer       (emjupy-mode) │  HTTP  │ Contents API ──── .ipynb files        │
│   cells ⇄ structs ⇄ .ipynb JSON ────┼───────▶│ Sessions and Kernels APIs             │
│     │ outputs, widget controls      │        │                                       │
│     ▼                               │   WS   │                          ZMQ          │
│   kernel connection ────────────────┼───────▶│ /api/kernels/…/channels ──▶ kernel    │
│                                     │   WS   │                                       │
│ shadow buffer (.py) ◀── Eglot ──────┼───────▶│ /lsp/ws/… ── jupyter-lsp ──▶ pylsp    │
│                                     │        │                                       │
│ figure window ◀── page ◀── bridge   │        └───────────────────────────────────────┘
└─────────────────────────────────────┘
   the bridge relays a widget page's messages over the
   kernel connection above

• The notebook buffer is the notebook: cells drawn as text, kept in step with the cell structs, which are what is saved as .ipynb.
• The kernel connection carries execution and its output; widgets' messages too.
• The shadow buffer is every code cell as one Python file, for Eglot, whose language server runs beside the kernel through jupyter-lsp.
• The figure window shows what a text buffer cannot – plotly figures, widgets that draw themselves – and a widget's page talks back through the bridge, a WebSocket server in Emacs, not to the Jupyter server.

A notebook is not valid Python, but a JSON document holding cells. There are n Python fragments with prose between them, and a name defined in, say, cell 3 is used in cell 7. A language server handed one cell at a time would see seven unrelated files. So instead, emjupy keeps a shadow buffer: one ordinary Python file holding every code cell concatenated, each preceded by a marker comment naming its cell. eglot attaches to that file and sees exactly what it expects – one module, in order, with all the definitions in it.

The shadow buffer is hidden: it exists so that a language server has a well-formed document to read. C-c ' shows it, for editing several cells at once; C-c C-c there writes the changes back into the cells.

Everything that needs the server is delegated there at the matching position:

• completion and eldoc, through completion-at-point-functions and eldoc-documentation-functions;
• M-. and friends, through an xref backend that forwards to eglot's own and maps the answers back onto cells;
• eglot-rename and the other eglot commands, advised to run in the shadow buffer and pull their edits back.

Because the shadow buffer holds every cell at once, this is not merely a workaround: a rename fixes references in all cells, and M-. on a call in one cell lands on the definition in another.

The language server that answers must run where the kernel runs: only there can it see your own modules and the Python the code runs against. emjupy talks to it the way JupyterLab does, through jupyter-lsp on the Jupyter server, over a WebSocket on the same connection the notebook uses – so it works through the same SSH tunnel, with nothing started on the remote by hand.

The shadow file itself stays on this machine – beside the notebook when the notebook is on this machine too, in a temporary directory when it is not – and nothing on the far side reads it. Its contents go over the socket as the LSP document, and every path in the traffic is rewritten in flight – the shadow's local directory to the kernel's working directory on the way out, and back on the way in – so the server resolves import mylib beside the notebook, where the module is. The server is also told that directory explicitly, as the place to look for modules.

When that server cannot be reached, emjupy falls back to one on this machine; what that costs is in Language server support.

Point in a cell maps to a position in the shadow buffer by finding that cell's marker and adding the offset within the cell; results coming back map the other way. Everything the server returns is in shadow-file coordinates, so xref results inside the shadow are rewritten into positions in the notebook.

A location anywhere else is a file on the kernel's machine, when the server beside the kernel answered, and is named there over TRAMP: the host comes from emjupy-remote-root or from the SSH tunnel the server is reached through. When the answer came from the local fallback, its paths already name this machine's files and are left alone.

Output arrives as messages on the kernel's WebSocket, each naming the request it belongs to. A request is finished when two things have come: the reply, on the shell channel, and the status message that follows the request's last output, on the iopub channel. The protocol does not order one channel against the other, so an output can arrive after its reply; waiting for both is what keeps it.

Stream text continues the output it belongs to rather than starting a new one. Consecutive text on one stream is one output, and text on a stream whose line is still open – no newline yet – continues that line even if the other stream wrote in between. That is a terminal's rule, and the one a progress bar relies on: each update begins with a carriage return, and carriage returns are applied as a terminal would.

How wide output is drawn, and when the kernel is told the width, is in Using a notebook.

Output is redrawn at most a few times a second, however many messages arrive, and only in the cell it belongs to.