Splat – the native macOS Markdown editor for vibecoders, written in Rust

Sven Müller — Thu, 29 Oct 2026 20:22:52 +0000

I spend a good part of every day in Markdown files: CLAUDE.md and AGENTS.md, specs, plans, READMEs. Most of the time I read them rendered, and that is exactly where I spot the typo or the sentence I want to change. Switching to the source, finding the same spot among the asterisks and brackets, fixing it and switching back gets old quickly.

Editors that let you type into the rendered view exist, but many of them work the same way under the hood: parse the file into a tree, apply your edit to the tree, and print the tree back out as Markdown. That last step is where things go wrong. The printer has its own opinions. *emphasis* turns into _emphasis_, list numbers get renumbered, tables get realigned, line breaks move. You fix one word and your Git diff shows forty changed lines.

Splat is a native macOS Markdown editor I wrote in Rust, with the source and a live preview side by side. Both panes are editable, and the rule for the preview is strict: an edit in the preview may only change the bytes it has to. Every line you did not touch stays byte-for-byte identical. This post is about how that works.

Never print the tree

The trick is to never serialize anything. The Markdown text is the only truth. The preview is a projection of it, and every edit in the preview is translated into one plain text edit on the source:

pub struct Edit {
    pub range: Range<usize>,      // bytes of the source to replace
    pub replacement: String,      // what goes there
    pub selection: Range<usize>,  // where the caret ends up
}

Typing, deleting, pasting, pressing Return, ticking a checkbox: all of them end up as one Edit. The source is patched, the affected part is parsed again, and the preview is updated from the new source. Undo works on the source too, so there is one undo history for both panes, and every preview edit is a single undo step.

For that to work, the preview has to know, for every character it shows, where that character came from.

Every rendered character knows its source byte

Splat parses with comrak and lays the document out into paragraphs of styled runs. Each run carries a map back into the source:

pub enum RunMap {
    /// Source byte offset of every char of the run text, plus the end of the last char.
    Text { chars: CharMap, end: usize },
    /// Something that renders as a unit: a list marker, a formula, a diagram, an image...
    Atom { atom: Atom, src: Range<usize> },
}

Take Some **bold** text. The preview shows Some bold text in three runs. The run bold maps its four characters to bytes 7 to 10 of the source; the asterisks are not in the preview at all, so they are simply not referenced by any character.

Storing an offset for every character would be expensive for a 10 MB file, and it is almost never needed: most text is copied verbatim from the source, so its offsets are consecutive. CharMap therefore has two shapes:

pub enum CharMap {
    /// The run is a verbatim copy of the source starting here.
    Verbatim(usize),
    /// Offsets relative to the first char's: a run never spans gigabytes.
    Offsets(usize, Box<[u32]>),
}

Only runs where the rendered text differs from the source pay for a table: escaped characters, typographic quotes and dashes, HTML entities, soft line breaks. Even then it is four bytes per character, relative to the run's first one.

Things that do not render as text, such as list bullets, task checkboxes, formulas, Mermaid diagrams or footnote references, become atoms. An atom knows the source range it stands for, but you cannot place the caret inside it. You can delete it as a whole, and a click on a formula or a diagram opens its editor.

Typing: where does the character go?

When you type at a position in the preview, the question is which source byte the new text goes in front of. Splat answers it the way macOS answers "which font do I type in": the character left of the caret decides. Type right after bold and you extend the bold text; type after a link and you continue the link text.

In code, insert_point walks the runs of the paragraph, finds the one that ends at or contains the caret, and asks its CharMap for the source offset. After that, the typed text has to stay literal. If you type an asterisk into the preview, you mean an asterisk, not the start of emphasis, so it is escaped before it goes into the source:

match c {
    '\\' | '`' | '*' | '[' | ']' | '<' | '$' | '~' | '^' => {
        out.push('\\');
        out.push(c);
    }
    // more rules: `_` next to non-letters, doubled `=`, `%` and `|`,
    // and `#`, `>`, `-` or `1.` at the start of a paragraph
    _ => out.push(c),
}

Inside code spans and code blocks nothing is escaped, because there everything is literal anyway.

Deleting: only the characters you can see

Deleting a selection in the preview deletes the source bytes behind the selected characters, and nothing else. The markup between them stays. Select ld te across **bold** text and Splat removes ld and te from the source, but keeps the closing ** between them, so the result is **bo**xt. That is exactly what the preview showed you would get.

Two cases need more than that.

Emptied containers. Select all of bold and delete it, and the naive result is ****, which renders as a horizontal rule or as literal asterisks depending on context. So after computing the deletions, Splat checks every inline container (emphasis, links, strikethrough, inline code) whose content would now be completely gone, and adds the container itself to the deletion. This repeats until nothing changes, because removing a link can empty the bold around it.

Joining paragraphs. Deleting across the boundary between two paragraphs means the paragraphs should become one. In that case Splat also deletes the source between the end of the first paragraph's content and the start of the second's: the blank line and, if the second one is a heading, its # marks.

All deletions and the insertion are then folded into one Edit by a small compose function, so a paste over a multi-paragraph selection is still one change and one undo step.

Return, checkboxes and other structure

Pressing Return in the preview is structural, so it is handled separately, again as one small text edit:

In a paragraph it inserts a blank line and keeps any quote prefix. If the caret sits inside bold or italic text, the markup is closed before the break and opened again after it, so both halves stay valid.
In a list item it starts the next item with the same indentation and marker. In an ordered list the number goes up by one, and in a task list the new item gets an empty [ ].
In an empty list item it removes the marker, which ends the list.
In a table cell it moves to the cell below.

Some edits touch a single byte. Ticking a task checkbox in the preview replaces the space in [ ] with x. Folding an Obsidian callout flips its - to +. That is the whole change in the file.

Keeping it fast: parse only what changed

After every edit the source has to be parsed again, and parsing 10 MB on every keystroke is too slow. Markdown helps here, because it is mostly local: a blank line between two top-level blocks ends everything that came before. So Splat finds the changed byte range, takes the top-level blocks around it plus one unchanged block on each side, parses only that window and splices the result into the existing tree, shifting the offsets of everything behind it.

There are a few things that are not local, and they are checked for explicitly:

footnotes, because comrak numbers references across the whole document,
link reference definitions, because [ref]: url anywhere can turn brackets anywhere into a link,
front matter, because an opening --- at the top is closed by the next --- anywhere,
%% comments, which can span blank lines.

When one of those is involved, or when the window grows past half of a large document, Splat simply parses everything. The preview then replaces only the blocks that actually changed. A keystroke in a 10 MB document takes about 25 ms.

Testing it with random documents

Code like this is full of edge cases, so most of the guarantees are checked with randomised tests rather than hand-written examples. Two of them carry most of the weight.

The first types a random character at a random position in the preview of a random document, applies the resulting edit to the source, lays the new source out again, and checks that the preview shows exactly the old preview plus that character:

let edit = bridge.replace(p..p, typed).expect("typing in a paragraph");
let new_text = check(&text, &edit, "typing");
let mut expected = shown.clone();
expected.splice(p..p, typed.encode_utf16());
assert_eq!(preview(&new_text), expected);

The documents include bold, italic, code, links, strikethrough and HTML, and the typed characters include *, # and _, the ones most likely to change the meaning of the source.

The second makes random edits to random multi-block documents and checks that the partial re-parse produces exactly the tree a full parse produces, byte offsets and syntax colours included. If the "Markdown is mostly local" assumption ever breaks for some construct, this test is where it shows up. Both tests take a seed and a round count from environment variables, so a longer search before a release is one command.

Native, not a web view

One more design decision makes all of this simpler. Both panes are real AppKit text views, written in Rust via objc2, not HTML in a web view. The preview text lives in the same text system as the source, with native selection, spell checking, dictation and VoiceOver. WebKit is only used, without network access, to turn formulas and diagrams into graphics, which then appear in the preview as atoms, and for the visual formula editor.

Try it

Splat is free and open source (MIT or Apache-2.0), signed and notarized, for macOS 14 and later on Apple Silicon:

brew install --cask sventmueller/tap/splat

The code is on GitHub: github.com/sventmueller/splat. The mapping lives in src/preview/map.rs and src/preview/bridge.rs, the partial re-parse in src/markdown/incremental.rs, and the randomised tests in tests/robustness.rs.

If you find a document where an edit in the preview changes more than it should, I would love to see it. Please open an issue with the Markdown.

Drafted with AI assistance from the Splat source code; every code excerpt and claim was checked against the repository.

DEV Community: Sven Müller