oxyst

A terminal editor for Typst documents with a live preview that never blocks typing.

Overview

oxyst is a terminal editor for Typst documents. It has syntax highlighting, background compilation and a live preview drawn inside the terminal, so a whole writing session happens in one window.

Problem

Typst compiles quickly, but editing it from the terminal still meant a second window for the preview. Compiling on the same thread as the editor made every keystroke wait for the compiler.

I wanted an editor where typing always stays smooth and the preview catches up on its own.

Requirements

Typing never waits for the compiler
The preview updates on its own after each edit
No separate typst install is needed
Settings live in one optional TOML file

Architecture

The editor is a Rust workspace of small crates. The tui crate handles input and drawing with Ratatui. Edits go to a pipeline worker that compiles in the background with the embedded compiler crate. The render crate turns pages into images and keeps a cache, and the preview shows them in the terminal.

+-----------+   edits    +-----------------+
|  editor   | ---------> | pipeline worker |
|  (tui)    |            |  (background)   |
+-----------+            +-----------------+
      ^                           |
      |  pages                    |  compile
      |                           v
+-----------+   images   +-----------------+
|  preview  | <--------- | render + cache  |
+-----------+            +-----------------+

Technology choices

Rust: Fast startup and safe threads for the background compiler.
Ratatui: A solid base for a terminal interface with many panes.
Typst: Its compiler is a Rust library, so it can live inside the editor.
Criterion: Repeatable benchmarks with confidence intervals for every core operation.

Implementation

Each edit is handed to a worker thread, so the input loop never runs the compiler. The worker keeps the Typst world warm between compiles and reports diagnostics back to the editor.

The renderer caches each page and reuses it when the page did not change.
A sync step maps the cursor to its spot in the preview and back.
Export writes PDF, PNG or SVG.
Key bindings and the theme come from an optional TOML file.

Major challenges

Keeping the compiler warm between edits without holding stale results
Showing images in terminals that support different graphics protocols
Measuring speed reliably enough to trust each change

Testing

Integration tests compile and render checked-in Typst fixtures: simple, multi-page, math, imports and a file with errors. A Criterion benchmark suite covers the document, compiler, sync, rendering and export steps, and keeps the raw samples so runs can be compared.

Results

About 120 µs mean time from an edit to a finished recompile
Page rendering cut from 813 µs to 842 ns with the page cache, about 965 times faster
Installs with one cargo install command, with no typst executable needed

What I'd improve

Measure the time from a key press to the redrawn screen
Add more themes beyond dark and light

Code

GitHub