LEM: Lilush Editor, Modal

Mode transitions

              ESC / operation complete
          +------------------------------+
          |                              |
          v          i/a/o/O/I/A         |
     +---------+ ------------------> +---------+
     | NORMAL  |                     | INSERT  |
     |         | <------------------ |         |
     +----+----+        ESC          +---------+
          |
          |  v/V
          |
          v
     +---------+
     | VISUAL  |
     | (char/  | ---- ESC ----> NORMAL
     |  line)  |
     +---------+

     : (from NORMAL)
          |
          v
     +---------+
     | COMMAND | ---- ESC/ENTER ----> NORMAL
     +---------+

Normal mode

The default mode. Keystrokes are interpreted as motions, operators, or commands. Supports the [count]operator[count]motion/text-object grammar. In operator-pending form, counts multiply, so 2d3w acts like d6w, and line-target motions follow the same rule (2d3G targets line 6).

Insert mode

Keystrokes are inserted as text. Special keys:

All typing within an insert session (from entering insert mode to pressing ESC) is grouped as a single undo entry.

Visual mode

Entered from normal mode with v (character-wise) or V (line-wise). Motions extend the selection from the anchor (entry point) to the cursor.

Command mode

Entered by pressing :, /, or ? in normal mode. A command line appears at the bottom of the screen.

Line index

The piece table maintains a line index -- an array of line-start byte offsets plus an end-of-buffer sentinel. The index is rebuilt on each edit (a full scan of the piece list). This provides O(1) line-to-offset and O(log n) offset-to-line translation.

Undo/redo

Undo is linear (no branching history) and capped at 1000 entries; the oldest entries are dropped past the cap. Each edit pushes a snapshot to the undo stack. Redo is populated when undo is invoked; any new edit after undo clears the redo stack.

Edit grouping: Consecutive inserts in insert mode are grouped into a single undo entry. The group is sealed when the user leaves insert mode. This matches vi behavior: u undoes the entire insert session.

Lua API

local pt = require("lem.piece_table")

local p = pt.new(content_string)  -- or pt.new() for empty buffer
p:insert(offset, text)            -- 0-based byte offset
p:delete(offset, length)
local text = p:get_text(offset, length)
local total = p:length()

-- Line index (1-based line numbers)
local count = p:line_count()
local off = p:line_offset(line)
local len = p:line_length(line)
local line = p:offset_to_line(offset)

-- Undo/redo
p:undo()   -- returns true/false
p:redo()
p:group_open()
p:group_close()

-- Full content for saving
local content = p:snapshot()

-- GC releases resources, or explicit:
p:close()

Buffer fields

Modification state is exposed through buf:is_modified(), which returns true whenever the buffer is not at the last-saved position in its undo history.

Filetype detection

Filetype is detected from the file extension, with a fallback to shebang inspection. Extensions with a bundled highlighter:

.txt files are detected as text (no highlighter).

Filenames Makefile / GNUmakefile and Dockerfile (case-insensitive) are recognized as make and dockerfile respectively. Shebang lines (#!/usr/bin/env lua, #!/bin/sh, #!/usr/bin/env python, etc.) provide detection when the extension is absent; recognized interpreters include lua, luajit, python/python3, ruby, sh/bash/dash/ zsh, node, and perl.

Additional extensions (.go, .rs, .js, .ts, .yaml/.yml, .toml, .rb, .html, .css, .xml, .conf, .ini) are detected and assigned a filetype label, but there is no bundled highlighter for them. Register one via highlight.register(filetype, module_name) to enable highlighting.

Multiple buffers

The buffer list manages open buffers with :e, :bn, :bp, :bd, :b, and :ls. CTRL+n cycles to the next buffer from normal mode. When the last buffer is closed, the editor exits.

Closing a modified buffer requires :bd! or saving first.

Clipboard (OSC 52)

Every write to the "+ register (yank, delete, or change) is mirrored to the system clipboard via OSC 52 terminal escapes. This works over SSH sessions and in terminals that support OSC 52 (kitty, foot, alacritty, ghostty, etc.). Paste from the system clipboard is delivered via bracketed paste mode.

Design principles

1. Selective, not exhaustive. Most code stays in base text color. Highlighting is reserved for things that benefit from visual separation.

2. Minimal palette. The default theme targets five semantic colors.

3. Highlight the rare, leave the common. Constants and definitions get color. Variable usage and function calls stay in base text.

4. Language keywords are scaffolding. if, for, local render in base text. The names and values beside them matter more.

5. Comments deserve attention. Explanatory comments get a visible, distinct color -- not greyed out.

6. Punctuation steps back. Brackets and delimiters are dimmed below base text.

7. Red is for errors. No ordinary token type uses red.

Token types

Untagged text renders in the base text color. This is the default for variable references, function calls, and language keywords.

Multiline constructs

Constructs that span multiple lines (block comments, multiline strings, heredocs) are tracked via line state -- a value passed from each line to the next indicating whether a multiline construct is open.

Bundled highlighters

Highlighter interface

A highlighter module exports new() and returns a table with:

local new = function()
    return {
        -- Returns {from, to, token_type} spans (1-based byte positions
        -- within `text`) and the new line state for multiline tracking.
        highlight_line = function(self, text, prev_state)
            -- ...
            return spans, new_state
        end,
    }
end

Note: the editor passes the tab-expanded line text, so spans are positions in the expanded text and line state must not depend on tab widths. Common token scanners (scan_quoted, scan_ident_end, scan_number_end) live in lem.highlight.style.

Register custom highlighters via highlight.register(filetype, module_name) before the editor starts.

Supported filetypes

Only the first error is reported (single-error model).

Validation runs only when the buffer content changes (tracked via an internal version counter), not on cursor-only movements.

Triggering

A session auto-triggers on every insert-mode edit whenever the cursor is at end-of-line and the prefix immediately before the cursor is at least two characters long. Typing more characters narrows the active session; deleting characters or moving the cursor refreshes it. Leaving insert mode, moving the cursor away from end-of-line, or reducing the prefix below the threshold dismisses the session.

When the prefix and cursor position are unchanged between refreshes, the currently chosen candidate is preserved so scrolling doesn't reset as you keep typing the same word.

Sources by filetype

For .lua buffers the session merges three sources in this order:

1. Lua keywords (and, break, do, ...)

2. Lua symbols from an enriched global table: every name visible in _G plus the modules configured in cfg.lua_preloads (by default std, crypto, dns, term, lev, mneme, http, json, wg; the json binding loads cjson.safe and wg loads wireguard). Dotted access like std.fs.r walks the table path and lists matching members. Add extra modules by overriding lua_preloads in your LEM config.

3. Unique identifiers harvested from all open buffers (active buffer first).

For every other filetype only the buffer-word source runs.

The buffer-word source scans each buffer's piece table once per __version change and caches the token set, so repeated completions on an unchanged buffer do not rescan.

Keys

TAB falls through to its normal indent behavior when no session is active. Any other key ends the session implicitly by changing the prefix or cursor position; the ghost disappears on the next refresh.

TSS

Ghost text uses the single completion TSS path from the lem theme section (gray italic by default).

Screen layout

+-----+----------------------------------------+
| gut | text area                              | row 1
| ter |                                        |
|     |                                        |
|     |                                        |
+-----+----------------------------------------+
| status line                                  | row H-1
+----------------------------------------------+
| command line / message area                  | row H
+----------------------------------------------+

TSS paths

Defaults

Scalar settings can be changed at runtime with :set. Table-valued settings like lua_preloads are set programmatically by overriding config.new(overrides) before starting the editor.

Files

Dependencies