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 byte offsets for each newline. The index is rebuilt on each edit. This provides O(1) line-to-offset and offset-to-line translation.

Undo/redo

Undo is unlimited and linear (no branching history). 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:

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)

The "+ register uses OSC 52 terminal escapes for clipboard writes. 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)
        -- and the new line state for multiline tracking.
        highlight_line = function(self, text, prev_state)
            -- ...
            return spans, new_state
        end,

        -- Reset state (e.g., on file reload).
        reset = function(self) end,
    }
end

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). The secondary (CALM) ghost uses completion_secondary (accent-color italic by default).

Triggering

CALM is manual-only: CTRL+space in insert mode runs inference and installs the secondary ghost. There is no keystroke-by-keystroke auto-trigger -- prose writing has natural pauses, and running the model on every keypress would stall the editor.

Any subsequent edit or cursor move dismisses the secondary ghost (its anchor becomes stale); the user can re-trigger at the new position.

Filetype gating

CALM activates only for filetypes in cfg.calm_filetypes. The default is {markdown, text, ""} (markdown, plain text, and buffers with no detected filetype). Override programmatically before startup:

local lem_cfg = require("lem.config").new({
    calm_filetypes = { markdown = true, text = true },
})

Model resolution

The source resolves its model in this order:

1. LILUSH_LEM_MODEL environment variable (absolute path override)

2. calm.registry lookup for mode_map["lem"]

3. Registry default (same fallback the shell uses)

To use a dedicated prose model, add an entry to ~/.config/lilush/calm/registry.json:

{ "default": "shell",
  "mode_map": { "lem": "prose" } }

:calm model <name> installs a runtime override; :calm model auto clears it and returns to the mode-map mapping.

Context construction

The source builds a prose-domain sequence directly, without frame tokens:

<BOS> <ATN> [lookback text as byte tokens...]

Lookback is the text from the start of the buffer up to the cursor, capped at the model's l_max budget (minus BOS, ATN, and generation headroom). The trim walks backward to the nearest paragraph boundary (double newline), then sentence boundary (.!? + space/newline), then word boundary -- never splits mid-word.

Sampler parameters come from the CWGT metadata (sampler_defaults) if present, with fallbacks: temperature=0.8, top_k=8, max_tokens=40, num_candidates=1.

Accepting

When the secondary ghost has only one candidate, CTRL+n/CTRL+p fall through to scrolling the primary ghost as usual.

Accepting a CALM ghost also dismisses any active primary session so the next keystroke refreshes cleanly.

Hot-reload

The source tracks the model file's mtime. Overwriting the .cwgt on disk causes the next trigger to reload the weights without restarting LEM -- useful during training-and-test cycles.

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