The graph webview protocol

In short: the host and the webview each wrap postMessage in a small RPC layer adapted from VS Code's own. Each side gets a proxy for the other side's interface, so calling webviewApi.$setState(state) on the host becomes a JSON message, a call to the webview's implementation, and a response matched back by ID. Before any call goes out, both sides repeat a handshake until each knows the other is listening. The webview announces itself with $webviewReady, and the host answers with a WebviewState. At this pin that state is a single hard-coded commit.

1. The two interfaces

ExtensionShape: implemented by the host, called by the webview

Order carries the layout's results back to the host: childrenOrder (a ChildrenOrder {parentHash, childrenHashes} per commit, in the order drawn), topToBottomOrder (all hashes as displayed), and wcCommitIndex (the working copy's position in that list, or -1). That lets keyboard navigation or "next/previous commit" commands in the host follow what the user sees.

WebviewShape: implemented by the webview, called by the host

Every method name starts with $. That's how the RPC proxy recognises remote methods: a property starting with anything else reads as undefined.

2. The transport

The RPC layer lives in third_party/vscode/rpc_protocol/, adapted from VS Code (MIT licensed). Both sides speak to it through a two-method Channel: postMessage(message) and onMessage(callback) → Disposable.

Messages with any other rpcProtocolId are ignored, because "We may not be the only ones using the channel" (source). Both directions use the same code: the host calls getWebviewApi and the webview calls getExtensionApi. Both are thin wrappers over getApi, which:

1. creates a sender: a Proxy whose $ methods post a request with an incrementing numeric id and return a promise stored in a pending map (source);
2. calls the caller's callback with that proxy to get the local implementation;
3. creates a receiver that answers each request by calling impl[name](...args), awaiting it, and posting a response with the same id (source);
4. starts the handshake, and returns the proxy immediately. Every proxy call first awaits a "blocker" promise that only resolves once the handshake finishes (source).

Pairing. Each side numbers its own requests independently, and a response is matched only against the sender's own pending map, so the two directions never collide. Calls can overlap, and responses may arrive in any order.

Errors. If the implementation throws, the receiver copies message, name and stack into a plain object, because methods don't survive the boundary, and sends it as err. Non-Error throws become {name: 'UNKNOWN_ERROR'} with a stringified message. An unknown method name produces No such function: <name>. On the calling side the code builds a fresh Error from err but then rejects with the original plain object (source), so callers receive an object that has message and name but isn't an Error instance.

Disposal. Disposing the returned disposable removes the listeners and rejects every pending call with RPC channel disposed.

3. The handshake

Webviews take time to load, and a message posted before the other side is listening is lost. shakeHands solves this symmetrically. Each side posts {received: weHaveReceived} every 100 ms. The first handshake message it gets sets weHaveReceived. Once a message arrives saying the other side has received ours (received: true), it resolves, posts one final message so the other side can finish too, and stops. Then the blocker opens and queued calls go out.

Timeout. After 300 tries, which is 30 seconds, it rejects with Handshake timed out after 30s. Nothing catches that rejection, since getApi only attaches a .then, and the blocker never opens, so every later call on that side hangs forever. The webview logs JJ Dojo commit graph started on boot, "temporarily to debug handshake time out errors" (source).

Request IDs are per direction: the webview's $webviewReady and the host's $setState are both id: 1 without colliding, because each side only matches responses against its own pending map.

4. The host side

JjUi registers CommitGraphViewProvider for the view type jj-dojo.commit-graph with retainContextWhenHidden: true, so the webview, and its RPC session, survive the view being hidden (source). When VS Code shows the view, resolveWebviewView:

1. sets enableScripts: true and limits localResourceRoots to the extension's own directory;
2. writes the HTML (getHtmlForWebview): the codicon stylesheet, _jj_graph_base_styles.css, the bundled webview_module.bundle.js, and a body containing <jj-context-menu-provider> and <jj-app id="jj-app">;
3. builds a Channel from webview.postMessage and webview.onDidReceiveMessage;
4. calls getWebviewApi with a callback that returns a new ExtensionShapeImpl wrapping the webview proxy;
5. disposes the RPC session when the view is disposed (source).

ExtensionShapeImpl is the only host implementation. A TODO in its header says its contents "should be replaced by the Google internal code". Only $webviewReady does anything: it sends createFakeWebviewState(), marked // TODO - Replace with a real implementation. That state is one graph named jj-dojo with a single empty working-copy commit, change IDs shown, one-line rendering, and search disabled. Every other method is an empty async function.

Multi-selection, not wired yet

MultiSelectManager sits next to the provider and holds the set of selected commits in a HashSet. Upstream says it came from Google's internal code with minimal changes. Nothing outside its test constructs it at this pin, so the host still ignores $onClick.

• setOrder(ids) stores the graph's top-to-bottom row order.
• onClick(id, metaKey, shiftKey): a plain click selects just that commit; a meta-click toggles it. Both remember it as the last clicked. A shift-click adds every commit between the last clicked and this one, inclusive and in either direction, and keeps the anchor; when there is no order or either commit isn't in it, the shift key is ignored (source).
• evictMissing(ids) drops selected commits that are no longer in the repository, and forgets the anchor if it went too (source).
• getOnlySelected() returns the selection when it is exactly one commit.

Its eight tests cover each of those paths, including matching distinct ID objects by their string (source).

5. The webview side

webview_module.ts is the webview's entry point. It imports the JjApp component, gets VS Code's webview API with acquireVsCodeApi(), and wraps vscode.postMessage and the window's message events in a Channel. Its getExtensionApi callback hands the host proxy to <jj-app>, fires $webviewReady, and returns the WebviewShape implementation, which forwards $setState and $openSearchBox to the app. The returned disposable is deliberately not kept: the comment says resources are released when the webview itself is disposed.

From there the components call the host through extensionApi, mostly with $executeCommand. See the graph webview UI.

6. The state types

Everything the host sends lives in api/types.ts. All of it must survive structured cloning through postMessage, so it is plain data: strings, numbers, booleans, arrays and objects, with commands named by ID rather than passed as functions. The tables start at the root, WebviewState.

WebviewState

types.ts, lines 247–251

WebviewOptions

types.ts, lines 253–256

CommitGraphState

types.ts, lines 261–291

Commit

types.ts, lines 20–71

CommitGraphOptions

types.ts, lines 123–174

RenderMode

types.ts, lines 180–188

CommitMetadataTextStyle

types.ts, lines 115–118

Callout

types.ts, lines 203–215

CalloutType

types.ts, lines 193–198

TopBarButton

types.ts, lines 220–242

Chip

types.ts, lines 296–316

SplitChip

types.ts, lines 321–345

ChipColors

types.ts, lines 94–98

IconButton

types.ts, lines 76–89

VSCodeCommand

types.ts, lines 103–110

File

types.ts, lines 350–352

Types that never cross the wire

The same file also defines the layout's own types. The webview builds them from the Commits it receives, and the host never sees them. They're covered on commit graph layout.