JJ LSP Follow-Up: Virtual Documents Bring Magit-Style UX to jj

The recent announcement about LSP 3.18's virtual document support has significant implications for the jj project's vision of implementing Magit-style UX. This development addresses a key architectural challenge that was previously making the implementation feel "massively hacky."

The Challenge of Magit-Style UX in jj

Magit, the popular Git porcelain for Emacs, revolutionized how developers interact with version control by providing a rich, contextual interface directly within the editor. The core idea for jj was to bring this same experience to the jj ecosystem by leveraging the Language Server Protocol (LSP).

However, there was a fundamental problem: LSP operates on text documents, but Git diffs and version control operations don't naturally map to physical files on disk. How do you provide semantic highlighting, code actions, and navigation features for content that exists only in memory or as a diff?

Virtual Documents: The Missing Piece

The upcoming LSP 3.18 release introduces a feature that elegantly solves this problem: Text Document Content Request can now provide virtual documents that aren't actually materialized on disk. This means you can create a "virtual file" that represents:

• A Git diff view
• A commit message interface
• A staging area preview
• Any other version control context that doesn't correspond to a physical file

How It Works

With virtual documents, the workflow becomes much cleaner:

1. Semantic Highlighting: Instead of trying to hack syntax highlighting onto a diff view, you can now provide proper semantic tokens for the virtual document
2. Code Actions: "Check out this commit" becomes a legitimate code action rather than a custom command
3. Navigation: "Goto definition" can jump from the diff in the virtual file to a real file in the working tree
4. Integration: All of this works through standard LSP mechanisms without special-casing

The virtual document acts as a bridge between the Git world (where things are organized by commits, branches, and diffs) and the LSP world (where things are organized by physical files).

Why This Matters

This architectural improvement is significant because it:

• Reduces Complexity: Eliminates the need for hacky workarounds and custom integrations
• Improves Performance: Virtual documents don't require disk I/O or file watching
• Enhances Reliability: Standard LSP mechanisms are well-tested and stable
• Enables Better UX: Provides a more seamless experience that feels native to both Git and LSP

The Road Ahead

The introduction of virtual documents in LSP 3.18 represents a maturation of the protocol and opens up new possibilities for editor integrations that work with non-traditional content. For jj, this means the Magit-style vision can be implemented in a way that's both powerful and maintainable.

As LSP 3.18 rolls out across language servers and editors, we can expect to see more innovative uses of virtual documents beyond just version control—any scenario where you want to provide rich editing features for content that doesn't live on disk becomes viable.

This is a great example of how protocol improvements can unlock new user experiences that were previously difficult or impossible to implement cleanly.