caretline
caretline— fps

The text editor
as a state machine.

A headless, deterministic text-editing engine you drive like a state machine: the whole editor is one JSON state, every input is a message, and any session can be saved, sent, replayed, or shared live with an agent.

cargo add caretline

try it in one linemacOS · Linux

curl -fsSL https://caretline.app/install.sh | sh -s -- --demo
  • start here
  • timed slides
  • the editor, hands on
  • an agent beside you

or cargo install caretline-cli · Quickstart

caretline demo

Start with one line.

One line installs the binary and opens the welcome: what caretline is, then each demo as a chapter (a timed showcase, the tour, an agent beside you, layers over the text, animated scenes), and back to the page when one ends. In the tour, the status bar names the keys as you go: type and wrap, move by word and row, select, add carets, undo exactly, indent and move lines, fold, open a second view, then dump the whole editor to JSON and watch your own session replay to the identical state. Quickstart

$ caretline demo tour72x16
  #   Welcome to caretline                                              
                                                                        
      A terminal editor where the whole editor is one value you can     
      save, send and replay. Work down this page with ↓: the status bar 
      names the keys for the section the caret is in.                   
                                                                        
  ##  1 · Type                                                          
                                                                        
      The caret is already at the end of this paragraph, so just start  
      typing, and keep going past the edge of the window.               
                                                                        
  ##  2 · Move                                                          
                                                                        
      ⌥← and ⌥→ jump a word at a time. ↑ and ↓ move by the rows you see,
       not by lines, and keep their column: go down through this        
 tour.md  1/11 · type past the edge: lines wrap at words          4:117 
Frames from the real binary, caretline demo tour --snapshot 72x16 --keys …: the same engine, headless.
frames

Every keystroke, replayable. Every frame, too.

To find the engine's ceiling, a script pushed full-screen ASCII animations into a live caretline editor: each frame a whole new state, 122×64 cells, with the brightest cells sent as selections. The engine applied between 835 and 1,674 full states a second. The terminal paints 60. These are the same scenes, ported to your browser and drawn on a frame clock.

Unthrottled state.set requests over the socket, Apple-silicon Mac, release build. All scenes interleaved ran at 1,155 a second. Busier frames, with more selection ranges, are slower. The numbers

one state

The whole editor is one state.

State in, message in, state out. update is the only place state changes and it reads no clock. view turns the state into a grid of cells. Below is the real engine, compiled to WebAssembly and running in this page. Click the frame and type, then drag the scrubber back.

view(state) → frameloading
rev 0··
msg streamupdate(state, msg)
    state.jsonone value
    1. State

      Everything that decides the screen: text, selections, scroll, viewport, the undo tree, the clock. Plain data that round-trips through JSON.

    2. Msg

      Every input: an edit, a motion, a click, a resize, a clock tick, the result of a save. Each one has a JSON form.

    3. update(&mut State, Msg) → Vec<Effect>

      The only place state changes. Pure: no I/O, no clock, no randomness. Work for the outside world comes back as effects; update_with_changes also hands back the text changes, to move positions you keep.

    4. view(&State) → Frame

      A grid of cells and the caret’s cell. Pure, so the same state always draws the same frame.

    // The pieces, end to end (docs/architecture.md)
    use caretline::{keymap, update, view, Key, KeyCode, State, Viewport};
    
    let mut state = State::new("hi", None, Viewport { width: 20, height: 3 });
    let msg = keymap(&Key::plain(KeyCode::End)).unwrap();   // Move { forward, line_end }
    let effects = update(&mut state, msg);                   // no effects for a motion
    assert!(effects.is_empty());
    assert_eq!(view(&state).cursor, Some((2, 0)));          // the caret is after "hi"
    uses

    Edit together: you, your scripts, your agents.

    One engine, driven the same way by a keyboard, a test, a script or a model. What that makes easy:

    Agents editing beside people

    Attach to the editor a person is using and drive it over JSON lines. Every result carries a rev; pass if_rev and a write only lands if nothing changed since you read. Events say whether a change came from the terminal or a client.

    $ caretline draft.md --listen          # a person edits here
    $ caretline send keys '<d-down>from another shell'
    $ caretline send '{"op":"msgs","msgs":[{"msg":"undo"}],"if_rev":0}'
    {"error":{"kind":"stale","message":"rev is 12, the request expected 0"}}

    Replay and time travel

    A trace is a state line followed by every message, clock ticks included. Replaying it gives the identical state and the identical frame, so a bug report can be the session itself.

    $ caretline send trace.get all --raw > live.jsonl
    $ caretline --replay live.jsonl --snapshot 80x24

    Snapshot testing

    Because update and view are pure, a test is data: a state, some keys, the expected result. No terminal, no timing, no mocks. Goldens write the selection inline.

    #[test]
    fn e01_left_collapses_to_start() {
        golden("Hello ⟦wor▮⟧ld", "<left>", "Hello ▮world");
    }

    Embedding in a TUI

    caretline owns the editing rules; you own the loop, the terminal, files and the clipboard. Turn input into a Msg, call update, perform the effects, copy view’s cells to the screen. No terminal crate inside.

    let msg = keymap(&key).unwrap();          // a key → a Msg
    let effects = update(&mut state, msg);     // pure
    for fx in effects { run(fx) }              // files, clipboard, quit
    draw(view(&state));                        // a grid of cells

    Blocks with an identity

    Block documents read the text as blocks: paragraphs, bullets, numbered items, headings. Each block keeps an id through every edit, undo and redo, and cut and paste, and its mark can carry your own data, so your app can hang anything on it.

    text                          marks         block
    ───────────────────────────   ───────────   ─────────────────────
    - Pay the deposit             1 @ line 2    1  bullet, depth 0
      - ask Ana about her desk    2 @ line 3    2  bullet, depth 1

    Your meaning, on top

    caretline edits text and never decides what it means. Your app adds that: named commands that run as one undo step and replay, input rules, a JSON payload on each block and on each view, decorations drawn in a block’s hang, passes that draw over the frame, and protocol ops of its own. All pure, so state, traces and the protocol keep working.

    let host = Host::new()
        .command("cycle", cycle)          // Msg::Command { name: "cycle", .. }
        .input_rule("shorthand", rule)    // takes a typed key first
        .decorator(|_, b| badge_for(b));  // text + a role name in the hang
    state.doc.set_host(host);
    scope

    A text-editing engine. Nothing else.

    caretline edits text and knows its shape. What your text means belongs in your app, added through host commands, input rules, block and view payloads, decorations and frame passes. Extending the engine

    caretline iscaretline isn't
    Text, navigation, carets and selectionsA notes app or a task manager
    Undo and redo, changes from elsewhereA sync engine or a store
    Blocks, marks with payloads, foldsStatuses, due dates or checkboxes
    Views, rendering, hit-testingColours or glyphs for your concepts
    State, messages, replay, the protocolFile I/O: it returns effects
    compare

    How it compares.

    caretline puts Helix's editing model (a rope, multi-range selections, transactions, an undo tree, grapheme-correct motion and soft wrap) inside a strict Elm architecture. Against the usual ways to get an editor into a program:

    caretlineA textarea widgetA browser editor coreAn editor run as a server
    The whole editor serializes to one value yes no partly no
    Undo history, viewport and clock included yes no partly no
    Every input is a recorded message yes no partly partly
    Exact replay of a session, built in yes no no no
    Drive a live session from another process yes no no yes
    Runs in a terminal yes yes no yes

    Not there yet: syntax highlighting, search, multiple buffers, keys that add cursors, IME and bidirectional text. Multi-range selections work in the engine and every caret is drawn; no key creates them yet. The protocol's socket transport is Unix-only. What it covers

    performance

    The engine is never the bottleneck.

    Document size barely matters: a million-line document edits and scrolls as fast as a hundred-line one. The real ceilings are how fast the terminal paints and how fast a client can produce input.

    one edit, in process
    1.6 µs
    one edit over the socket
    13.4 µs
    load 1,000,000 lines (82 MB)
    202 ms
    a keystroke with 10,000 carets
    1.4 ms
    characters a second, live redraw
    72,000
    render an 80×24 frame
    0.13 ms

    Release builds on an Apple-silicon Mac. caretline bench reproduces the engine and protocol numbers. Every figure, and where the limits are

    Start with one state.

    Add the crate, build a State, send it messages. Or run caretline serve and talk to it from any language.