Introduction

bemtvi is a modal, vim-style editor written in Rust. It is a headless, asynchronous editor server with thin UI clients (a terminal client, a native GPU GUI, and a client-side WebAssembly build) talking over msgpack-RPC. The editor logic lives in one place; every front end shares identical editing behavior.

It speaks vim at the keyboard — keystrokes, modes, ex-commands, and options track vim/neovim’s observable editing behavior — but every API is bemtvi’s own. Configuration and plugins target the btv.* Lua namespace, where the server owns every UI surface and plugins provide data and behavior. There are a few vim.* aliases over the native btv.* API for convenience.

How to read this book

• Getting started — install or build bemtvi and run it.
• Configuration — point bemtvi at your init.lua and set options through btv.*.
• Plugin Development — the anatomy of an bemtvi plugin and a worked example.
• btv.* API Reference — the public Lua API, generated directly from the prelude source so it always matches the running editor.
• Architecture — the crate layout, client-server model, RPC and View protocols, the rope text model, and the Lua bridge.

This book is itself generated from the repository: the narrative chapters and the long-form architecture and plugin-authoring docs come from docs/, and the API reference is extracted from crates/bemtvi-lua/src/prelude/.

Getting started

Install a pre-built binary

Grab a binary from the latest release (or the rolling edge build from main). Binaries are published for Linux (x86_64/aarch64, glibc), macOS (x86_64/aarch64, signed & notarized .pkg/.dmg), and Windows (x86_64). Each release ships both the terminal editor (bemtvi) and the native GUI (bemtvi-gui); on Linux the GUI is published as a single-file, desktop-integrated .AppImage (alongside a plain .tar.gz).

Then run it on a file (the argument is optional):

bemtvi file.txt        # terminal editor
bemtvi-gui file.txt    # native GUI (mitsuami + wgpu)

Downloads ship with checksums and SLSA build provenance — see Verifying downloads.

Truecolor terminal recommended. bemtvi emits 24-bit color escapes; use a modern terminal with truecolor support.

The terminal editor is the whole thing in one binary: it embeds the server on its own thread and runs the client on the main thread, joined over the same msgpack-RPC the UI clients speak.

Build it yourself

You need a Rust toolchain. Then:

# Build and run (the file argument is optional)
cargo build --release
./target/release/bemtvi file.txt

# …or straight from cargo
cargo run -p bemtvi -- file.txt

# the native GUI
cargo run -p bemtvi-gui -- file.txt

Try it in the browser

A fully client-side WebAssembly build runs the entire editor core in the browser with no server. Try the live demo at https://bemtvi-demo.netlify.app: use :eo to open a local file, and :setf <lang> / :TSInstall to activate treesitter highlighting for a language.

Configuration

bemtvi reads a Lua config. On startup it resolves a config directory — the first of $BEMTVI_CONFIG, $XDG_CONFIG_HOME/bemtvi, or the platform default — and sources <config>/init.lua before the first frame. The runtimepath is that dir plus every pack/*/start/* entry under it:

~/.config/bemtvi/
├── init.lua                      # sourced at startup
└── pack/
    └── plugins/
        └── start/
            └── myplugin/       # a plugin; its lua/ and colors/ are found here

-- ~/.config/bemtvi/init.lua
require("myplugin").setup()

Where the directories are

The layout follows neovim’s, so the XDG_* variables win everywhere and the platform default is only what they fall back to. btv.stdpath("config") (and "data" / "state" / "cache") always reports the resolved path.

On Windows the managed directories take a -data suffix so they do not land on top of the config tree you hand-edit — the split neovim spells nvim / nvim-data.

btv.* vs vim.*

The editor’s own config API is the btv.* namespace — see the API reference. The only vim.* is a closed whitelist of muscle-memory aliases (vim.g, vim.o/vim.opt, vim.cmd, vim.keymap.set, autocmds, vim.notify, and friends), each a 1:1 alias over its btv.* equivalent, so config can be written in familiar spellings:

vim.g.mapleader = " "
vim.o.number = true
btv.keymap.set("n", "<leader>w", ":w<CR>", { desc = "Save" })

The full whitelist lives in ADR 0002. A neovim colorscheme reaches for a handful of those aliases (notably the nvim_set_hl highlight helper) and nothing more.

Built-in clipboard chords — Ctrl+C / Ctrl+V

bemtvi ships the desktop copy/paste keys bound to the system clipboard (the "+ register), so they work without any config:

Paste is P, not p: the text lands at the cursor (charwise) or above the line (linewise), where a modeless editor puts it. Nothing vim-ish is displaced — bemtvi has no blockwise visual mode for <C-v> to open and no i_CTRL-V literal insert, and <Esc> is how you leave visual mode. The shifted twins exist because a GUI, a browser tab, or a terminal speaking the kitty keyboard protocol reports Ctrl+Shift+C as its own chord; a plain terminal folds it onto <C-c>, which is mapped anyway.

They are overridable defaults, so your own map wins, and mapping one to an empty function turns it off:

btv.keymap.set("n", "<C-v>", function() end)  -- disable the normal-mode paste
btv.keymap.set("v", "<C-x>", '"+d')           -- add a cut to match the copy

Copying needs a clipboard to copy to: the host clipboard (Windows’, or a tool: wl-copy / pbcopy / xclip), a terminal that speaks OSC 52 (the ssh case), or the browser’s navigator.clipboard. With none of them a copy says so rather than quietly going nowhere.

The intro screen

Started with no file, bemtvi shows an intro screen the way vim and neovim do: the app icon, the name and version, and the commands to quit and to manage plugins. The icon is drawn with text, two pixels per cell in half block characters (▀ / ▄), so it needs a truecolor terminal; elsewhere only the text is shown. It sits beside the empty [No Name] buffer without touching it, and goes for good on the first edit, on :e file, or when a split shows the buffer twice.

To start without it:

btv.g.intro = false

:intro (or btv.intro.show()) draws it on demand in any empty, unnamed buffer; :enew gives you one. Its colours come from BtvIntroTitle, BtvIntroText and BtvIntroKey, which link to Title, Comment and Special unless your config or colorscheme defines them. examples/intro walks through it.

Option scopes — which buffers a setting reaches

A buffer-local option (tabstop, expandtab, foldmethod, …) has two values: the local one on each buffer, and the global one every newly created buffer is born from. Which you write is what decides whether a config line applies to the files you open later — the same model as vim:

vim.opt.tabstop = 3        -- :set       — this buffer AND the global value
vim.opt_local.tabstop = 8  -- :setlocal  — this buffer only
vim.opt_global.tabstop = 2 -- :setglobal — the global value only

vim.o and vim.opt are the ones a config almost always wants: a vim.opt.tabstop = 3 in init.lua sets the buffer you happen to be in and the value every file opened afterwards starts from. vim.bo / vim.wo (and vim.opt_local) are the per-instance surfaces — what a filetype rule uses, so one buffer’s indent does not become everyone’s default:

btv.on("FileType", { pattern = "go", callback = function()
  vim.opt_local.expandtab = false   -- Go files only
end })

Reads follow the same split: vim.o.tabstop / vim.bo.tabstop report the current buffer’s value, vim.go.tabstop the global one. The ex commands :set / :setlocal / :setglobal are the exact equivalents, and :setglobal x? reads the global value where :set x? reads the buffer’s. The by-name API spells the same three: nvim_set_option_value(name, value, {}) is a :set (both tiers), and a scope or a buf / win target narrows it to one of them.

vim.api.nvim_set_option_value("tabstop", 3, {})                    -- :set
vim.api.nvim_set_option_value("tabstop", 8, { scope = "local" })   -- :setlocal
vim.api.nvim_set_option_value("tabstop", 2, { scope = "global" })  -- :setglobal

Three buffer options — commentstring, foldexpr and foldmarker — resolve their global value as a fallback when the buffer has none of its own, rather than copying it at creation. So a :setglobal commentstring=… reaches buffers that are already open, where a :setglobal tabstop=3 only reaches ones created afterwards. A buffer that sets its own with :setlocal still wins either way. (This is a deliberate departure from vim, where every buffer always holds a local value.)

A few buffer options have no global value, because the read decides them — fileencoding, bomb, fileformat, endofline — as does modifiable, a per-buffer marker, and the two nouns derived per buffer, filetype and ts_highlight. :setglobal on one of those tells you so instead of storing a value nothing would read.

Window options (number, scrolloff, signcolumn, …) carry the same two tiers, with one extra rule from vim: a split copies the window it came from, so your init.lua settings follow you into new splits whichever tier you wrote. The global value is what :setglobal / vim.go read, and what a window created with no source window to copy — a dock, the quickfix tab — is born from.

Plugins — the built-in :Plugins manager

Dropping a checkout under pack/*/start/* works, but the ergonomic path is the built-in package manager: there is no third-party manager layer because the manager ships with bemtvi. You declare a set of plugins in init.lua with btv.plugins{}; it clones/updates them over the async runtime (via btv.git_local — first-party gix, no git binary) and loads each one — adds its directory to the runtimepath so require and its colors/ / queries/ / lsp/ resolve without a restart, sources its plugin/ scripts, and runs its config. Nothing blocks: every step is a promise, so the UI paints before plugins finish loading.

-- ~/.config/bemtvi/init.lua
btv.plugins({
  -- "owner/repo" shorthand expands to a GitHub clone.
  { "bemtvi/bemtvi-keys-helper",
    config = function() require("bemtvi-keys-helper").setup({}) end },

  -- Lazy-load on a trigger: any of cmd / event / ft / keys makes it lazy.
  { "someone/markdown-tools", ft = "markdown" },

  -- Pin a ref, rename, add dependencies.
  { "owner/repo", tag = "v1.2.0", name = "repo",
    dependencies = { "owner/dep" } },
})

Each spec is the repo ("owner/repo" shorthand, or src / url, or a local dir) plus optional fields: name, branch, tag (alias version), commit, dependencies (alias deps), enabled, init (run before load) and config (run after). Lazy triggers — cmd, event, ft, keys — defer loading until first use; set lazy = false to force eager load even with a trigger. Clones land under the data dir (not your config repo), which the manager owns.

Run :Plugins to open the dashboard — a lazy.nvim-style floating UI listing every declared plugin grouped by load state, with live per-plugin progress (a spinner while a clone/pull runs, ✓/✗ on finish) and verb keymaps in two scopes. Upper-case acts on everything: I install · U update · S sync · R restore · X clean (plus <C-r> refresh, <CR> details, q quit). Lower-case acts on the plugin under the cursor: i install · u update · s sync · r restore · x remove (delete just that clone — x then i is the “give me a fresh copy” move). The same operations are available as ex-commands:

Every verb command above (all but :PluginList / :PluginsWelcome) takes an optional plugin list — :PluginUpdate bemtvi-tree, :PluginSync bemtvi-dap bemtvi-line — and <Tab> completes the declared names. Scoped that way it acts on those plugins (and their dependencies, which a plugin needs to load at all) and leaves every other plugin’s checkout and its lockfile entry exactly as they were: you get the one fix you were waiting for, not eleven other people’s changes. The same scope is a plugins option on the Lua verbs — btv.plugins.update({ plugins = "bemtvi-tree" }). :PluginClean is the one verb whose scope does not pull in dependencies (deleting a checkout nobody named is destruction by inference), and it refuses outright to delete a local dir plugin’s checkout — that is your own working tree, not a managed clone.

bemtvi ships minimal; on a fresh setup it offers a recommended first-party set as one decision, with c opening a checklist to pick individually — see Recommended plugins for what’s in it. See Writing plugins for authoring your own.

The lockfile

Every install / update / sync records the commit each managed plugin resolved to in <config>/bemtvi-lock.json, and installing reproduces those commits. Commit it alongside your init.lua: config + lockfile is the pair that pins the exact plugin tree, so a second machine gets the same code instead of whatever each remote’s HEAD happens to be that day.

{
  "catppuccin": { "branch": "main", "commit": "0b0a9a1…" },
  "bemtvi-line": { "commit": "ada94b5…", "tag": "v2.1.0" }
}

It is generated, so treat it as output: a flat map keyed by plugin name, encoded with sorted keys and 2-space indentation so a diff is one line per plugin that moved. An entry records the commit and the declaration it resolved — the branch the plugin tracks, the tag it was pinned to — which is what lets a changed spec invalidate it (below). A dev dir plugin never contributes a commit (a working checkout is not a reproducible artifact), and neither does one that isn’t installed yet — but neither loses an entry another machine wrote for it, since the file you commit must not be strip-mined by whichever machine happens to sync. Only a plugin your config no longer declares is dropped. btv.plugins.lock() writes it on demand (:PluginLock) and btv.plugins.locked() returns the current contents; a malformed lockfile — including an entry with no commit — is a hard error naming the file rather than being treated as “nothing pinned”. Relocate it with btv.plugins.setup_manager{ lockfile = … }.

Which revision wins. Highest first:

1. commit = "…" in the spec — a hand-written pin is an instruction, and always beats the lockfile, which is only a record.
2. the lockfile entry — it outranks the floating refs below, because pinning a floating ref is exactly what it is for.
3. tag / version, then branch.
4. the remote’s default branch.

…but only while the entry still records what your spec asks for. Bump tag = "v1" to "v2", or point branch somewhere else, and the entry describes a resolution of a question you are no longer asking: it is discarded and the new ref re-resolved, the way Cargo.lock gives way to a changed Cargo.toml. Otherwise a record would outrank the config that produced it, and your edit would be silently ignored forever.

A plugin with no lock entry and no pin still gets a fast depth = 1 clone; reaching a locked commit is the only reason to pay for a full one. If the lockfile names a commit the remote no longer has (force-pushed away), the install fails loud and names the file to fix — quietly installing something other than what the lockfile says would defeat the point of having one.

Reproduce vs advance — the two verbs mean different things, like cargo build and cargo update:

• :PluginSync reproduces the lockfile. Missing plugins are installed at their locked commits, and a plugin whose checkout has drifted from what the file records is moved back onto it — so pulling a colleague’s newer bemtvi-lock.json and syncing gets you the tree it names. Realizing your declared state never moves a plugin past the recorded revision. (:PluginInstall only clones what is missing; it never moves an existing checkout, and records only the clones it made.)
• :PluginUpdate advances past it: each unpinned plugin is fast-forwarded to its branch tip and the lockfile is re-recorded. A plugin sitting on a locked (detached) commit is re-attached to the branch it tracks first, so a lock is never a permanent freeze.

Neither verb moves a plugin past an explicit commit / tag pin — that is what pinning means — but both realize one: change the pin and the next sync checks the plugin out at it. And if a plugin is detached with no branch recorded anywhere (a hand-written lock entry with only a commit), :PluginUpdate fails loud rather than guessing a branch: add branch = "…" to its spec.

Going back. :PluginRestore (or R in the dashboard) checks every plugin out at the commit the lockfile records — the “that update broke my editor” verb, and the reason recording commits is worth anything. Check out an older bemtvi-lock.json from your config repo and restore to get exactly that plugin tree back.

Restore reaches commits a shallow clone does not contain: it deepens the clone (fetch --unshallow) and retries, so an unpinned depth = 1 install is no obstacle. A plugin already at its locked commit is left alone rather than re-checked-out. A commit that is genuinely gone from the remote is reported loud and by name, and that plugin’s checkout is left untouched — a rollback that silently skipped a plugin while reporting success is the one failure you must not miss.

:PluginList and the dashboard mark a plugin drifted when its checkout is at a different commit than the lockfile records — the signal that the tree no longer matches what your config promises.

Runnable examples

The examples/ directory has ~85 self-contained, end-to-end-verified configs — one per feature (treesitter, LSP, floats, registers, tabs, mouse, statusline, completion, picker, snippets, decor, docks, quickfix, image previews, …). Each is a config dir you point bemtvi at:

BEMTVI_CONFIG=examples/treesitter cargo run -p bemtvi -- examples/treesitter/sample.rs

The recommended plugins

bemtvi ships minimal by design — the editor core has no bundled plugins. Everything below is optional, installed only if you say so, and removable with one line in your config.

On a brand-new setup bemtvi offers this set once, at startup:

╭──  Welcome to bemtvi  ────────────────────────────────────────╮
│  bemtvi ships minimal by design — no bundled plugins.         │
│                                                              │
│  Install the recommended set? 11 plugins from github.com/…   │
│                                                              │
│    <CR>    Install all of them                               │
│    c       Customize — see every plugin and pick individually │
│    ?       What's in the set — opens this page in a browser  │
│    <Esc>   Skip — :PluginsWelcome reopens this any time      │
╰──────────────────────────────────────────────────────────────╯

• <CR> installs the whole set.
• c opens the checklist: every plugin with its exact source, pre-ticked, untickable with <Space> (a toggles all). Only what stays ticked gets installed.
• ? opens this page.
• <Esc> skips. bemtvi asks at most once ever — a marker under the data dir records that it asked — but :PluginsWelcome reopens the offer whenever you want it, and :Plugins opens the manager dashboard.

Whatever you accept is written to a managed lua/plugins.lua next to your init.lua, as ordinary btv.plugins specs. From then on it is your config: edit, extend, or delete any of it by hand.

Each bemtvi plugin in the set is pinned to a release (tag = "v1.0.0"), so a fresh setup gets the version this editor was tested against, not whatever the plugin’s default branch holds that day. :PluginUpdate leaves a pinned plugin where it is. To move to a newer release, change its tag. To follow the default branch instead, delete the tag line.

The set

Every one of these is a first-party plugin built on the public btv.* API — no compatibility layer, no privileged access (The btv.* model). Each links to its own repository, where the full documentation lives; once bemtvi-help is installed, the same docs are in the editor as :help <plugin-name>.

“Loaded” is when the plugin’s code actually runs: the lazy ones cost nothing until you press the key or run the command that triggers them.

Appearance

The colours need no plugin. bemtvi’s own colorscheme, bemtvi, is built in and loads by default in the GUI, the browser and any truecolor terminal; :colorscheme neutral switches to the bundled One Dark. Every scheme neovim ships is built in too, ported to bemtvi: habamax, retrobox, sorbet, catppuccin, lunaperche, morning and the rest, plus neovim’s own theme as neovim and vim’s as vim (:colorscheme <Tab> lists them). :colorscheme default is the same as :colorscheme bemtvi. Their authors are credited in runtime/colors/README.md. Any scheme a plugin installs is a :colorscheme away as well.

bemtvi-line — configure it the way you’d configure lualine.nvim: sections a–z, a component library (mode, branch, diff, diagnostics, filename, filetype, progress, location, LSP, …), themes that recolour by mode, powerline separators. It compiles that config down onto bemtvi’s native btv.statusline registry, so the hot path stays in Rust.

Getting around

bemtvi-tree — a lazy, watched file tree in a dock: <leader>e toggles it. Full file operations, git status per entry, glob filters, mouse support, Nerd-Font icons with an ASCII fallback.

bemtvi-keys-helper — press a prefix (<leader>, g, z, <C-w>) and pause: a popup lists every key that can follow, with descriptions. It subscribes to bemtvi’s pending-key oracle rather than intercepting input, so it never disturbs the sequence you’re typing.

bemtvi-help — :help {topic} in a read-only split, with a fuzzy topic picker on <leader>fh. Its tag index is merged across the runtimepath, which is what makes every other plugin’s documentation readable in the editor: install this one and :help bemtvi-tree works.

Writing code

bemtvi-lspconfig — curated btv.lsp configs for 407 language servers, driven onto bemtvi’s own LSP control surface. It configures servers; it does not install them — you still install gopls, rust-analyzer, pyright, and friends yourself.

bemtvi-efmls-configs — presets for ~150 linters and formatters (eslint, stylua, black, luacheck, …) run through efm-langserver, which speaks their output back over LSP. Installed with languages = "*defaults", so the bundled default tool per filetype is wired lazily on first open. Needs the efm-langserver binary, plus whichever tools you want it to run.

bemtvi-snippets — the LSP snippet grammar (tabstops, placeholders, choices, mirrors, transforms) with VSCode-format collection loading. It installs friendly-snippets as a dependency, so there are snippets for most languages from the start: type a trigger, accept the completion row with <C-y>, jump between tabstops with <C-j> / <C-k>.

bemtvi-editorconfig — reads the .editorconfig files above each file you open and applies indentation, line-ending and charset settings to that buffer. No configuration; switch it off per buffer or globally with vim.g.editorconfig = false.

Reviewing and debugging

bemtvi-diff — :DiffGit diffs the current file against git HEAD; :DiffConflict opens conflict markers as a 3-way diff. Panes scroll in lockstep, changed lines are tinted, and the Lua API renders any 2- or 3-pane spec you build.

bemtvi-markdown-preview — :MarkdownPreview serves your open markdown buffers over the editor’s own HTTP mount and opens them in your browser, re-rendering as you type (no :w needed), with highlighted code fences and mermaid diagrams. Because it’s a mount rather than a bound port, it works the same in the browser build.

bemtvi-dap — a Debug Adapter Protocol client: breakpoints (conditional / hit / log), stepping, a scopes-stack-watches sidebar with inline value editing, a REPL, and multiple concurrent sessions. <F5> or :DapToggleBreakpoint loads it. You supply the adapter (debugpy, codelldb, …) and a configuration per filetype — its README shows both.

What you still need to install yourself

Plugins configure tools; they don’t ship them. Depending on what you accepted:

• Language servers for bemtvi-lspconfig (gopls, rust-analyzer, lua-language-server, …).
• efm-langserver plus the linters/formatters you want, for bemtvi-efmls-configs.
• Debug adapters for bemtvi-dap.
• A Nerd Font for the tree’s file icons (it falls back to ASCII without one).

Everything else — the picker, completion, tree-sitter highlighting, LSP itself, quickfix, terminals, docks — is already in bemtvi. See What bemtvi adds.

Changing your mind

The set is not special after installation: it is ordinary spec data in your own lua/plugins.lua.

To drop one, delete its entry from lua/plugins.lua and run :PluginClean (which removes the checkouts nothing declares any more). To add anything else, declare it the same way and run :PluginSync:

btv.plugins({
  { "owner/repo", config = function() require("repo").setup() end },
})

• :Plugins — the dashboard: what’s declared, installed, loaded, or drifted, with install / update / sync / restore / clean.
• :PluginsWelcome — reopen the offer and re-pick from the recommended set. Note it overwrites the managed lua/plugins.lua with your new choice.

To start from nothing, skip the offer (<Esc>) — or, if you’re writing a config for others, register your own set with btv.plugins.recommend{...}, which replaces bemtvi’s default one; btv.plugins.recommend({}) suppresses the offer entirely.

Beyond the set

Not offered on first run, but first-party and worth knowing about:

• bemtvi-workspaces — per-project editor configuration as a committable .bemtvi/config.json (language servers, save actions, options) instead of hand-written rc Lua. See Workspaces.
• bemtvi-remotes — teaches :connect the ssh:// and container:// schemes, so the filesystem, processes and language servers live on a remote while the editing stays local.
• bemtvi-lspconfig-base — the same LSP configs trimmed to the most widely-used servers; a smaller alternative to bemtvi-lspconfig, not a companion to it.

See also

• First-party plugins — the same plugins read as reference implementations: which btv.* surfaces each one is worth studying for.
• Writing plugins — the manager’s full spec vocabulary (lazy triggers, dependencies, pinning, the lockfile) and the authoring guide.

Beyond vim — what bemtvi adds

bemtvi speaks vim at the keyboard: keystrokes, modes, ex-commands, and options track vim/neovim’s observable editing behavior. On top of that baseline it grows a handful of features vim and neovim don’t have natively — modern editing and UI surfaces that fit the modal grammar rather than fighting it.

This page is the index. Each feature below has a full guide linked from its name; the one-liner is the elevator pitch.

Editing

UI surfaces

Platform

Helix mode — selection-first editing

An opt-in selection-first editing model, alongside — not replacing — bemtvi’s vim grammar. Where vim is verb→noun on a point cursor (d waits for a motion), Helix is noun→verb on a persistent anchor..head range: a motion re-selects on every keystroke, and a verb acts on the current selection immediately, with no operator-pending wait. Every cursor is a selection; a bare cursor is a width-1 selection, and multi-selection is the always-on default.

This is the Helix editing model ported natively — not its keybindings bolted on. The hard part isn’t rebinding keys; it’s that a motion means something different: w moves and re-selects the next word on every selection, so wd deletes a word with no motion-wait in between. That semantic change is why the model is native Rust (a genuine core-grammar change), while the key layout ships as the bundled btv.helix plugin.

Vim behavior is untouched. Helix is per-session and off by default.

Turning it on

-- ~/.config/bemtvi/init.lua
btv.helix.enable()          -- enter Helix normal mode at startup

Or interactively: :helix toggles it (and btv.helix.disable() turns it off). Both are idempotent. The status line reads HELIX (normal) or HELIX-SEL (select); the mode codes are hn / hs, distinct from vim’s n/v so plugins and ModeChanged can tell them apart.

Search defaults to smart-case in Helix without touching the global ignorecase/smartcase; opt out with btv.helix.enable{ smart_case = false }.

The two modes

v toggles between them (keeping the selection and its shape). <Esc> in select drops to normal; in normal it collapses to a point and drops secondary selections.

Motions

Motions return a range, so the selection follows the cursor as you move.

Word motions are Helix-semantic (a line’s leading indentation is its own word; blank lines are skipped; a selection never spans a newline). W/B/E collapse the word/punct classes so a run of any non-blank chars is one WORD.

Verbs act now — no operator-pending

A verb operates on the current selection immediately, across every selection, as one undo group:

So wd = select a word, delete it. wcXyz<Esc> = change a word to “Xyz”. No motion-wait ever.

Selection verbs

Transforms on the selection set itself — these have no direct vim analog:

Multiple selections

Multi-selection is the default, so most verbs already fan out. To grow a selection set:

• C / Alt-C — copy the primary selection onto the next / previous line(s), each copy becoming the new primary (walk it down/up with repeats).
• The regex spawners below (s / S).

Insert entry fans out too: i a I A collapse each selection to its insert point and open a multi-cursor Insert at all of them; o / O open a fresh line at every selection.

Match mode (m) — brackets, text objects, surround

m opens a sub-grammar:

The text-object alphabet is the full shared set — vim objects (w W p s, pairs ( { [ <, quotes " ' `) and the tree-sitter captures f function / a argument / c comment / t class — so mif selects the enclosing function body, maf the whole function, mia the argument. (Requires a grammar with textobjects.scm; btv.textobject.map keys work here too.)

Regex selection (s / S / K / Alt-K)

Each opens a /-style prompt that transforms the selection set; the would-be result previews live as you type:

s over % (whole file) then a verb is the “change every occurrence” workflow — e.g. %sfoo<CR>c….

Registers, view, and more

• Register select "{reg} — target register {reg} for the next y/d/c/p/P/R (one-shot), reusing vim’s registers.
• View menu z — zt / zz / zb reposition the viewport around the cursor line, leaving the selection put.
• Search / ? n N — a match becomes the selection in normal mode; in select mode each search / n adds the match as a new selection (growing a multi-selection).
• Undo / redo — u / U.

Menus (the plugin layer)

The bundled btv.helix plugin binds the keys a bare grammar key can’t reach:

• Insert entry — i a I A o O (all per-selection).
• Goto menu g — gg file start, ge last line, gh / gl line start/end, gs first non-blank, plus LSP gd/gy/gr/gi (definition / type / references / implementation).
• Space menu <Space> — the picker + LSP leader: find files, global search, buffers, document/workspace symbols, diagnostics, hover, rename, code action, jumplist, marks.

which-key

The native which-key (btv.on_key_pending, see UI primitives) lights up for Helix too — both the plugin menus (g, <Space>) and the native sub-grammars: m match mode, mi/ma (the object alphabet, tree-sitter captures included), z view, f/t find, r replace, and " register.

Rebinding

Both Helix modes share one keymap bucket, helix, which falls through to the native grammar on no match (so Helix stays fully usable with no config — the plugin only adds keys). Every verb is exposed by name through btv.helix.actions.<name>, so any key is rebindable:

-- alias X to "extend line" (x); user maps win over defaults
btv.keymap.set("helix", "X", btv.helix.actions.extend_line_below)

-- add a goto entry: gm -> last line (a count typed before it still applies)
btv.keymap.set("helix", "gm", btv.helix.actions.goto_last_line, { desc = "Last line" })

The action names mirror Helix’s own command names (extend_line_below, select_regex, flip_selections, rotate_selection_contents_forward, …), so a Helix user’s muscle memory carries over. An unknown name fails loud.

Try it

The examples/helix config is a runnable, annotated walkthrough:

BEMTVI_CONFIG=examples/helix cargo run -p bemtvi -- examples/helix/sample.txt

How it works (in brief)

Helix reuses vim’s machinery rather than forking it. A Range { anchor, head } / Selections vocabulary projects over the existing stores — the primary lives in the vim cursor + visual anchor, secondaries in the same CURSOR_NS / ANCHOR_NS extmarks the multi-cursor mode uses — so selections ride the buffer’s edit choke point and undo for free. Mode::HelixNormal / HelixSelect have their own parse step (handle_helix) but share the operator / multi-cursor engine; the one predicate Mode::shows_selection() (visual or Helix) lets Helix reuse the visual selection’s rendering and multi-cursor sweep wholesale.

For the full design — the projection seam, the grammar, the named-action registry, and every verb — see the Helix editing model design record.

Multi-cursor mode

A Helix/kakoune/Sublime-style multi-cursor, built on top of bemtvi’s vim grammar rather than replacing it. You drop several cursors, then every motion, operator, visual selection, and insert acts at all of them at once — cw, x, typing, o, p, even per-cursor visual mode.

It is single-buffer multi-editing: cursors are per-buffer and shown only in the focused window.

The two phases

Multi-cursor is split into two phases with a mode boundary between them, so you never have to think about “placement” and “editing” at the same time.

Normal ──<A-c>──▶ MultiCursor ──<Esc>──▶ Normal (cursors live) ──<Esc>──▶ Normal
                  │  motions move primary           │  motions/edits → all cursors
                  │  c / {n}c{motion} drop cursors  │
                  └─ /search keeps cursors          └─ /search or n clears them

1. Placement — enter with <A-c> (Alt+c). The status line reads MULTICURSOR and the active cursor is recolored amber. Motions move only that active cursor — you navigate around (including /-search) and drop secondary cursors at the spots you want.
2. Editing — press <Esc> to leave placement. The dropped cursors stay, and the status line returns to NORMAL. Now motions and operators apply at every cursor at once. A second <Esc> collapses back to a single cursor.

On leaving placement the primary cursor snaps onto the nearest placed cursor, so the final set is exactly the cursors you dropped — never an extra one where you happened to stop navigating.

Placement grammar

While in MULTICURSOR mode:

The spawn key is Alt+c, not Helix’s bare C — that’s already vim’s change-to-end-of-line. On macOS the terminal must send Option as Meta for <A-c> to arrive: in Terminal.app enable Use Option as Meta key; in iTerm2 set Left Option = Esc+.

Editing with the cursor set

Back in Normal mode with cursors live, the whole normal grammar replays at every cursor. A motion is re-resolved per cursor, so w lands at the right word for each one independently. What’s wired:

• Motions and the operators over them — dw yw cw =w, dd yy cc, text objects like diw / ci".
• The standalone edits — x X D C s J ~ r.
• Insert — typing, Enter, and Backspace apply at every cursor; so do the insert-entry keys a A i I (each cursor moves to its own target column — line-end for A, first-non-blank for I) and o / O.
• Paste — p / P with per-cursor registers: a multi-cursor yank (yy, yiw, …) captures each cursor’s own text, and a later paste gives each cursor back its own slice. When the captured count doesn’t match the live cursor count (a single-source yank, or the set changed), every cursor pastes the active register instead — plain vim p, broadcast.

Cursors that converge onto the same cell after a motion (e.g. everyone hits 0 or gg) automatically merge, so you never get a silent pile of cursors editing one spot.

Per-cursor visual mode

Each cursor carries its own selection. Press v or V over a placed set and every cursor gets a one-wide selection; visual motions extend each independently. Operators (d, y, c, …) bracket each cursor’s own selection. Visual o swaps to the other end of the selection at every cursor (there’s no visual-block mode yet, so O aliases o). <Esc> collapses the selections but keeps the cursor heads; a second <Esc> collapses those too.

Search clears the set (in Normal)

A committed search — / ? n N * # — in Normal mode is treated as navigating away: it abandons the multi-cursor session and collapses to a single cursor. In placement mode the same search instead jumps to a match so you can drop a cursor there, keeping the set. (Incsearch preview never clears anything — only the committed search does.)

Undo

Undo restores cursors to where they were before the undone edit, not where the edit shifted them. Each multi-cursor edit undoes as a single step.

Custom keymaps while placing

Placement mode has its own keymap bucket — mode code 'm' — so a binding can fire only while placing:

vim.keymap.set('m', '<Tab>', 'wc')  -- in MULTICURSOR: jump a word, drop a cursor

This is isolated the way vim isolates modes: a plain 'n' (normal) map does not fire while placing, and an 'm' map does not fire in normal mode. The all-mode '' map (:map) still covers placement. Any key the 'm' trie doesn’t bind passes straight through to the built-in placement grammar, so h/j/c/{count}c{motion}/<Esc> keep working.

How it works (in brief)

The load-bearing trick is that secondary cursors are stored as extmarks in a reserved namespace, so the buffer’s single edit choke point shifts them all for free — an edit at one cursor keeps every other cursor’s position correct with no bespoke fix-up, and cursors ride the undo snapshot. The editing phase then just replays an ordinary single-cursor command at each cursor in turn. The primary cursor stays the existing self.cursor; secondary cursors are a purely additive layer.

For the full design — the extmark model, the replay primitives (for_each_cursor / edit_each_cursor), per-cursor visual anchors, undo cursor baking, and rendering — see the multi-cursor design spec.

Keyboard macros

Record a sequence of keys once, then replay it as often as you like. The behaviour is vim’s; the bindings are bemtvi’s.

<F2>{reg}     start recording into register {reg}   (uppercase appends)
<F2>          stop recording
<F3>{reg}     play register {reg} back
{count}<F3>{reg}   play it {count} times
<F3><F3>      play the last register again
<F3>:         re-run the last ex command

While a recording is open the message line reads recording @a, exactly as vim announces it, and the macro statusline segment shows the same.

Why not q and @?

q is the close key on half of bemtvi’s read-only surfaces (a btv.view pane, a dock, the plugin dashboard), and vim’s q shadows a genuinely useful key for every user who never records a macro. So the trigger moved somewhere nothing else wants. If your fingers disagree, one line brings vim’s spelling back:

btv.keymap.set("n", "q", "<F2>")
btv.keymap.set("n", "@", "<F3>")

That works — rather than merely typing the F-key’s name — because of how recording is built: see below.

A macro is a register, and a register is text

A recording is stored as ordinary key notation in an ordinary register:

<F2>a  0ciwbeta<Esc>j  <F2>        →  register a = "0ciwbeta<Esc>j"

Which means everything you already know about registers applies. "ap pastes the macro into the buffer as editable text. :registers lists it. It persists across sessions through shada, and syncs over a daemon or browser session like any other register. And you can write one by hand, no recording needed:

btv.reg.set("a", "0ciwbeta<Esc>j")

The one thing to know: because the register is parsed as keys, playing a register that happens to hold ordinary yanked text will read any <...> in that text as a key name rather than as literal characters.

Recording captures what you typed, mappings included

bemtvi records the keys you pressed — not what they resolved to — and replays them through the keymap matcher, so the mappings fire again. This matters here more than it does in vim, because so much of bemtvi is Lua keymaps: the LSP gd, the completion triggers, every plugin’s bindings. A recording that captured only what reached the editor would silently drop them and the replay would do nothing.

So a macro over <leader>f records <leader>f and re-fires it on playback. It is also why remapping q to <F2> above works at all.

Keys that were not typed stay out: a mapping’s own RHS, nvim_feedkeys typeahead, and the keys of a macro that is playing back. Recording <F3>b stores those two keys, not everything b expands to.

A failed keystroke ends the playback

The classic idiom is to record one line’s worth of edit and then replay it far more times than there are lines:

<F2>a  I- <Esc>j  <F2>       record: prefix this line, go down
99<F3>a                       …and do that until it stops

j on the last line fails, and a failure ends the whole run — every remaining repeat and every suspended macro. Without that, the extra repeats would keep prefixing the last line. Anything vim would beep at counts: a motion already at the buffer edge, an unmatched f{char}, a search that finds nothing, any E### error.

Macros can call macros

<F3>b inside macro a suspends a, runs b to completion, and resumes. A macro that calls itself is legal — vim relies on the first failing command to end the recursion, and so does bemtvi — with a depth cap and a key budget behind it that report loudly rather than hanging.

From Lua

btv.macro.recording()   -- register being recorded into, or nil
btv.macro.executing()   -- register playing back right now, or nil (innermost)
btv.macro.play("a", 2)  -- play register a twice

vim.fn.reg_recording() / vim.fn.reg_executing() are the vim-shaped aliases (they return "" rather than nil). btv.macro.executing() is the cheap way for a plugin to skip work no human is watching — an expensive redraw during a long 100<F3>a, say.

The macro statusline segment is built in:

btv.statusline.setup({ left = { "mode", "macro", "filename" }, right = { "location" } })

Fonts

'guifont' is a list of fonts. For every character, the GUI and the browser use the first font in the list that has it, the way wezterm’s font_with_fallback does. So a coding font can come first, a Nerd Font symbols font next for icons, then a CJK font and an emoji font, and each character comes from the right one. The order is yours for every script: a CJK font you list beats the one the system would pick.

btv.ui.font({
  { "JetBrains Mono", features = { "+zero", "-calt" } },
  { "Symbols Nerd Font Mono", scale = 0.9 },
  "Noto Sans CJK JP",
  "Noto Color Emoji",
}, { size = 14 })

That writes the option, which you can also set directly:

:set guifont=JetBrains\ Mono[features=+zero\ -calt],Symbols\ Nerd\ Font\ Mono[scale=0.9]:h14

The --font flag and BEMTVI_GUI_FONT take the same syntax, for a GUI started without a config. 'guifont' wins over them once a config sets it.

Each font’s options

Options go in brackets after a font’s name, separated by ;:

After the list, :h<size> sets the size. Other : flags (:b, :i, :w…, :#e-…) are accepted and ignored, as in Neovide.

A font draws only the weights it has, so text never leaves it for lack of one. A font with no bold face draws bold text at its nearest weight, not in another font and not with a synthesized bold. The same goes for a weight it has no face for.

When something is wrong

A malformed value is refused, whichever way you set it (:set, btv.o, btv.ui.font), and the font you had stays:

E474: Invalid argument: guifont: unknown option wieght on JetBrains Mono

A font that isn’t installed is skipped and named on the message line: guifont: not installed: Fira Kode. If it was the first in the list, the system monospace takes its place, so plain text never comes from an icon or emoji font further down.

In the browser

The browser takes the list, the size and each font’s weight and scale. It can’t set OpenType features per font, so the first font’s features apply to all the text, which is where they’re almost always wanted. Features on a later font are reported on the message line as not applied in the browser.

With no font set

The GUI uses the platform’s monospace, the first of these that’s installed: Menlo then Monaco on macOS; Cascadia Mono, Consolas then Courier New on Windows; Noto Sans Mono, DejaVu Sans Mono then Liberation Mono elsewhere. If none is, it takes any installed monospaced font with an upright face.

Symbols Nerd Font Mono comes after it, if installed, so icons work without a config. The same happens when the first font in your list isn’t installed, with your other fonts ahead of it. A list whose first font is installed is used exactly as written.

Limits

• The terminal client draws with the terminal’s own fonts and ignores the option.
• No fonts are bundled: the list uses what’s installed.

Modeless editing

:set modeless makes bemtvi edit the way VS Code, Sublime or a text field in a browser do. You type and the text goes in. Shift with an arrow selects, and typing over a selection replaces it. Ctrl-C, Ctrl-X and Ctrl-V use the system clipboard, and Ctrl-Z undoes about a word at a time (Undo steps). There is no Normal mode to fall into, and <Esc> never takes you out of typing.

It is a setting for the GUI and the web client. The terminal client refuses it.

In the GUI and the browser the cursor is a blinking bar while you type or select, at the moving end of a selection, and the mouse pointer is an I-beam over text, read-only text included. It stays the arrow over the line numbers, status lines and popups, and over a terminal.

-- init.lua
btv.o.modeless = true

How it works

Every buffer rests in Insert. Whatever leaves it in Normal (closing the command line, finishing an ex command, switching windows) lands back in Insert before the next key. There is no Normal mode anywhere in the session.

A read-only buffer (a file tree, the quickfix list, help, a panel) rests in Insert too, with the same caret, arrows, Shift-selection, mouse selection and keys. What it refuses is the edit: typing, <CR>, <BS>, paste, cut and undo there say E21: Cannot make changes, 'modifiable' is off and change nothing. Copy, Select All and find work as anywhere else. The keys a read-only buffer answers to (the quickfix list’s <CR>, a panel’s q) are its own maps in the modeless layer; see Plugins.

A terminal rests in the running program: its keys go to the process, and <C-\><C-n> lands straight back there. Once the program exits, the buffer is ordinary text and rests in Insert.

<Esc> closes what is open over the text (the completion popup, signature help, a snippet session) and drops a selection, and that is all.

A selection is Select mode, the mode vim’s snippets use: typing replaces it, and replacing it writes no register, so typing over text never clobbers the clipboard. A mouse drag, a double click (word) and a triple click (line) select the same way.

Undo and redo bring the selection back. Undoing a type-over, a cut or an indent leaves the text it changed selected again, facing the way you selected it, and redo returns to whatever was selected when you undid.

Keys

On macOS the layout uses Command (<D-…>) where this table says Ctrl.

The language keys are VS Code’s. They run the btv.lsp verbs, so they need a language server attached to the buffer, and they stand in for vim’s gd, gr, K and ]d, which are Normal-mode letters a modeless session can’t reach:

On macOS the Ctrl ones use Command, as above; the F-keys and <S-A-f> (Shift+Option+F) are the same. <C-k> starts the hover chord, so an Insert-mode <C-k> (the signature help bemtvi binds when a language server attaches, or one of your own) now waits 'timeoutlen' for a second key; signature help has <C-S-Space> here.

The arrows move the caret the way a GUI editor does: <Right> at the end of a line goes to the next one, <C-Left> and <C-Right> move by word, <Home> goes to the first non-blank and then to column 0, <C-Home> / <C-End> go to the buffer’s ends, and <PageUp> / <PageDown> slide the view a page with the caret keeping its row on screen.

On macOS, Command with an arrow goes to the line’s edges or the buffer’s ends, and Option with Left or Right moves by word. Shift with any of them selects.

The mouse wheel scrolls the view and nothing else. The caret and any selection stay where they are, even off screen, and the first key that types or moves the caret brings the view back to it, as does an input method starting to compose. A page key pages from the caret’s place. Each window keeps its own scroll while focus is elsewhere, including one you scrolled without focusing it. Shift with the wheel scrolls sideways (down goes right), as does a tilting wheel or a touchpad; a long line only scrolls sideways with 'wrap' off. Sideways scrolls slide like vertical ones.

Dragging a selection to the top or bottom of a window scrolls it while the pointer stays there, and with 'wrap' off so does dragging it to the window’s left or right edge, so a selection can grow past what is on screen in any direction.

Each window shows where its view is: a slim thumb along the right edge for the lines in view, and with 'wrap' off one along the bottom of the text for the columns, measured against the widest line on screen (as far as you can scroll). A thumb shows only when there is something to scroll to. It marks the place and does not take clicks or drags yet. Floating windows have none.

The command palette lists every picker (Live Grep, Buffers, Find Files, and any a plugin registers with a title) and every ex command. A picker row opens that picker. A command that needs an argument opens the : line with its name typed, ready for the rest.

Every key is a default you can replace. The layout lives in its own keymap layer, modeless, which is consulted ahead of the Insert maps while a modeless session is typing or selecting, so your Insert maps (completion, snippets, your own) still work. The verbs are named, so you can bind them anywhere:

btv.keymap.set("modeless", "<C-d>", btv.modeless.actions.duplicate_line)
btv.keymap.set("modeless", "<C-s>", function() end) -- free the key

The named actions are copy, cut, paste, undo, redo, select_all, delete_word_back, delete_word_forward, indent, outdent, duplicate_line, move_line_up, move_line_down, search_next, search_prev, save, find, replace, command_line, palette, files, close, next_buffer, prev_buffer, reveal_caret (bring a scrolled-away view back to the caret), the language verbs definition, implementation, references, hover, signature_help, rename, code_action, format, document_symbol and workspace_symbol, and next_diagnostic / prev_diagnostic. In a read-only buffer the verbs that don’t edit (copy, select_all, search_next, search_prev, reveal_caret and the commands) run as anywhere else, and the editing ones refuse with E21.

The context menu

A right-click opens a menu at the pointer. A click inside the selection keeps it, so the menu acts on it; anywhere else the caret moves to the click first. The menu offers Undo and Redo, Cut, Copy, Paste and Select All, the LSP verbs when a language server is attached, and the command palette, and each row shows the key that does the same thing. A read-only window (help, the quickfix list) gets Copy and Select All.

The same menu works in a vim session, and it is built from groups you can reorder, edit and add to: see the context menu. For a key hint in a row of your own, btv.modeless.key_hint(action) gives the chord that runs a named action.

In the browser

On Windows and Linux, Chrome keeps <C-w>, <C-t>, <C-n> and <C-Tab> for itself. The web client sends <C-w> when you press Alt-W instead; <C-Tab> has no stand-in, so use the command palette for :bnext. On a Mac the client forwards the layout’s Command chords to the editor, except Command-V (the browser’s own paste does the same job) and Command-W (the browser keeps it).

Of the language keys, the browser keeps a bare F12 (its developer tools), so go to definition is in the right-click menu and the command palette there; <C-F12> and <S-F12> reach the editor. <C-t> (symbols in the workspace) is Alt-T on Windows and Linux, like <C-w>, and has no key on a Mac, where the browser keeps Command-T.

Plugins

A plugin with a read-only buffer (a tree, a sidebar, a results list, a dialog) binds its keys for both models. A modeless session never reaches Normal mode, so an "n" map never fires there, and nothing guesses one into the modeless layer for you. Bind the same keys in both:

local view = btv.view.create({ name = "[Tree]" })
-- …
btv.keymap.set({ "n", "modeless" }, "<CR>", open_entry, { buffer = view })
btv.keymap.set({ "n", "modeless" }, "q", close_tree, { buffer = view })

buffer = view binds to the view’s buffer, which is created after the chunk that creates the view, as soon as it exists. Until then view:bufnr() reads false, and a buffer option given false is an error rather than a global map.

A printable key such as q is safe in the modeless layer on a read-only buffer: typing is refused there anyway, so the map takes nothing away. A buffer-local map in the layer beats the layout’s own key on the same chord, so a view can bind <C-v> to “open in a split” without losing it to paste. btv.view installs its <CR>, and with an on_select its double-click, this way, and so do the quickfix list, the panels, the explorer and the :Plugins screens. On an editable buffer, keep to keys that don’t type (chords, function keys), since the layer comes ahead of typing.

The rest of a plugin written for the vim model mostly works unchanged. Three things differ in a session that never leaves Insert:

• TextChanged and InsertLeave don’t fire while you type; TextChangedI does. A [+] indicator should listen to BufModifiedSet, which fires the same way in either model.
• btv.diagnostic.config({ update_in_insert = false }) (“hold until InsertLeave”) holds updates until typing goes quiet for 3 seconds instead.
• btv.cmd("normal! …") and keys fed with btv._feedkeys still run as Normal-mode keys: an <Esc> in them leaves Insert, and the session comes back once they end.

btv.ui.caps() reports client ("gui", "web", "tui") and platform ("macos", "linux", "windows"), which is how the layout picks Command.

Limits

• The terminal client: :set modeless fails there, and a terminal attaching to a session that has it on turns it off.
• Helix mode and modeless editing can’t both be on.
• Several cursors at once (<A-c> placement) keep their own motions; the GUI gestures for them (Ctrl-D, Alt-click) aren’t bound yet.

The context menu

A right-click opens a menu at the pointer, in every session: vim or modeless, the GUI, the browser or the terminal. Before the menu opens, the click moves the cursor to where you clicked. A click inside the selection keeps the selection instead, so the menu acts on it.

In an editable buffer the menu offers Undo and Redo; Cut, Copy, Paste and Select All; the LSP verbs while a language server is attached; and the command palette. A read-only buffer (help, the quickfix list) offers Select All, plus Copy: always in a modeless session, and when text is selected in a vim one.

One click chooses a row, and the row under the pointer is highlighted. A click or right-click anywhere else dismisses the menu, and a right-click opens a new one where it landed. The keys work too: <Down> / <Up> move, <CR> chooses and <Esc> dismisses.

A runnable tour of everything below, with its own spec, is examples/context-menu/:

BEMTVI_CONFIG=examples/context-menu cargo run -p bemtvi -- examples/context-menu/sample.txt

Groups

The menu is built from groups. Each buffer has its own ordered list of group names, and each name refers to a registered group that gives rows. Groups that give no rows are dropped, and a separator goes between the rest.

btv.contextmenu.list(0)   --> { "undo", "clipboard", "lsp", "commands" }

• Helix’s modes are a vim session here, with Helix’s % for Select All and x then y for Copy with nothing selected, which leaves out the line’s end.
• undo, and Cut and Paste, show only in a buffer that is 'modifiable'.
• Copy with nothing selected copies the line, in any modeless buffer and in an editable vim one. A read-only buffer in a vim session needs a selection to copy. In a vim session Cut needs a selection too; a modeless Cut takes the line.
• lsp shows while a server is attached, and greys out a verb no attached server answers.
• In a modeless session each row shows the key that does the same thing, read from the live layout, so a rebound key shows its new chord. A vim session shows no keys: vim’s keys are verbs plus motions, not one chord.

Changing the menu

A buffer’s list is live: edit it and that buffer’s menu changes, and no other’s.

local list = btv.contextmenu.list(0)
table.insert(list, 1, "commands")       -- the palette first
btv.contextmenu.set(0, { "clipboard" }) -- or replace the list
btv.contextmenu.set(0, {})              -- no menu in this buffer

A buffer gets its list the first time it’s asked for: a copy of btv.contextmenu.default for a 'modifiable' buffer, or of btv.contextmenu.default_readonly otherwise. Edit the defaults in your config to change what every buffer starts with:

table.remove(btv.contextmenu.default, 1) -- no Undo / Redo in new buffers

A group is a table you can change. Add a row, remove one, or hide the whole group:

table.insert(btv.contextmenu.groups.commands.items, {
  label = "Save",
  action = function() btv.cmd("write") end,
})
btv.contextmenu.groups.undo.when = false

Adding a group

A group has items, the rows, and an optional when. items is a list, or a function that returns one, or returns a promise of one:

btv.contextmenu.groups.file = {
  when = function(ctx) return btv.buf.name(ctx.buf) ~= "" end,
  items = function(ctx)
    local path = btv.buf.name(ctx.buf)
    return btv.fs.stat(path):next(function(st)  -- answers later
      return {
        { label = "Copy Path", detail = st.size .. " bytes",
          action = function() return btv.clipboard.write(path) end },
      }
    end)
  end,
}
table.insert(btv.contextmenu.default, "file")

A row has:

A group’s when hides the whole group the same way. A field a group or a row doesn’t know about is an error that names the group, so a typo doesn’t silently drop a row. So is a name in a list with no registered group. Lists hold names, so a group registered after a buffer’s list was made shows as soon as it exists.

The menu opens once every group has answered. Rows keep list order, whichever group answers first.

ctx is built once per right-click and passed to every items, when, enabled, detail and action:

{
  buf = 3, win = 1000,        -- the clicked buffer and window
  mouse = btv.getmousepos(),  -- the click
  mode = "n",                 -- the mode once the click has moved the cursor
  selection = false,          -- Visual or Select is active
  modifiable = true,          -- the buffer can be edited
  modeless = false,           -- a modeless session
}

For a modeless verb’s key hint in your own row, use btv.modeless.key_hint:

{ label = "Save", action = btv.modeless.actions.save,
  detail = function(ctx) return ctx.modeless and btv.modeless.key_hint("save") or nil end }

Opening it yourself

btv.contextmenu.open() opens the current buffer’s menu at the pointer, which is what a right-click does. From a key with no click behind it, the menu opens at the text cursor. It returns a promise that settles once the chosen row’s action has run, or once the menu closed. btv.contextmenu.entries(buf) returns a promise of the rows a buffer’s menu would show right now, without showing it.

A menu of your own

Groups are the one way to put rows in the right-click menu. For a buffer that should show only your rows, set its list: btv.contextmenu.set(buf, { "mine" }). To take the right-click over entirely, bind a buffer-local <RightMouse>: a map replaces a key’s default, so no menu opens.

Underneath, a right-click fires the MenuPopup event (see autocmd events), as vim does just before its popup menu shows, and this menu is what opens. Don’t open a second menu from a MenuPopup handler: only one menu shows at a time, so it would replace this one or be replaced by it.

Undo steps

bemtvi keeps vim’s undo tree but not vim’s undo steps. In vim, everything you type between entering Insert and pressing <Esc> is one step, so u after a paragraph takes the whole paragraph. bemtvi breaks typing into the steps a GUI editor uses, roughly a word at a time. This is the same in every mode, Helix included. There is no option to get vim’s grouping back.

ifoo bar baz<Esc>   then  u  →  foo bar
                          u  →  foo
                          u  →  (empty)

Where a step ends

You start a new step when you:

A run of separators stays together, so foo bar undoes bar in one step. Punctuation counts as a separator: foo.bar(x) is four steps.

Moving the cursor counts however it happens: an arrow, <Home>/<End>, a mouse click, a jump, or a plugin calling btv.win.set_cursor. An i_CTRL-O command is a step of its own, even one that doesn’t move the cursor.

What stays one step

• A Normal-mode command, including the text a c command types. cwnew<Esc>u restores the old word in one u. With more than one word typed, the last ones come off first.
• A paste, a register insert (<C-r>{reg}, <C-r><C-w>), and an <C-r>= result. The typing after one of these is a new step.
• A mapping’s output. One key pressed is one step, however much text its right-hand side types, for a string RHS, an <expr> RHS, or a Lua function that feeds keys. A mapping that changes nothing leaves the word you were typing in one piece.
• A snippet expansion. Typing over a placeholder, or into an empty tabstop, is a separate step, so u puts the placeholder back before it removes the snippet.
• An edit made with several cursors. Each step spans every cursor.
• A replay: ., a macro (<F3>{reg}), :normal, :g. u after . undoes the whole repeat.

The tree is unchanged

Each step is a node in the same undo tree, so g-/g+, :earlier/:later, :undo {N}, :undolist and btv.undotree all work on word-sized states. 'undolevels' still counts nodes, and with smaller steps the default of 1000 covers less editing than it did.

Tests and fed keys

Keys a plugin feeds with btv._feedkeys are one step per run, like a mapping. Keys fed as typed are the keyboard: the btv.test runner’s t:feed uses them, so a spec that types ifoo bar<Esc>u sees foo, the same as you would.

Expressions

There are places where a fixed rule is not enough and a whole plugin is too much: how a substitution builds each replacement, what a collapsed fold says, which filetype a .h file really is. For those, bemtvi takes a small Lua expression and evaluates it where the answer is needed.

-- double every number on every line
:%s/\d+/\=tonumber(m[0]) * 2/g

-- a collapsed fold shows its first line and how much it hides
btv.fold.text([[ first:gsub("%s+$", "") .. "  (" .. lines .. " lines)" ]])

-- a .h file with templates in it is C++, not C
btv.filetype.detect([[ ext == "h" and head:find("template", 1, true) and "cpp" or nil ]])

Each one is an expression, not a function body: it evaluates to a value, and that value is the answer. There is no return, no statements, no end. (Two are blocks — the frame-time paint and the quickfix parser — because a per-line paint loops over the line’s matches and a parser builds a record, so each ends in its own return.)

The eleven surfaces

Everything an expression needs is handed to it. That is the whole design, and the reason for most of what follows.

Substitutions

A replacement that starts with \= is an expression, evaluated once per match. m holds the submatches — m[0] is the whole match, m[1], m[2], … the capture groups — and lnum is the line the match sits on.

:%s/(\w+)_(\w+)/\=m[2] .. "_" .. m[1]/     -- one_two      -> two_one
:%s/\w+/\=m[0]:upper()/g                   -- alpha beta   -> ALPHA BETA
:%s/^/\=lnum .. ": "/                      -- number every line

A group that did not participate in the match is nil, not "", so type(m[2]) distinguishes “matched nothing” from “did not match”.

The expression is compiled once per command and called per match, and it works the same in bulk :s, in the live inccommand preview, and in the :s///c confirm walk. The delimiter still ends the replacement, so an expression containing / needs it escaped — or a different delimiter:

:%s#(\w+)/(\w+)#\=m[2] .. "/" .. m[1]#

A number is accepted and rendered as Lua prints it, so \=tonumber(m[0]) * 2 gives 14, not 14.0.

Fold levels

'foldexpr' decides a line’s fold level under foldmethod=expr. It sees the line’s own text as line and its 1-based number as lnum.

Set it through btv.bo rather than :set, since an expression contains spaces:

btv.bo.foldmethod = "expr"
btv.bo.foldexpr = "line:find('{%s*$') and '>1' or line:find('^%s*}') and '<1' or '='"

The value is vim’s fold-level grammar, and it is worth knowing because it is how you express nesting without the expression having to remember anything:

The engine carries the running level from line to line, so >1 / <1 bracket a block however deeply it is nested, and your expression only ever looks at one line.

Two ready-made values need no expression at all: btv.treesitter.foldexpr folds by the syntax tree and btv.lsp.foldexpr by the language server’s foldingRange. Both are native — they never enter the sandbox.

btv.bo.foldexpr = "v:lua.btv.treesitter.foldexpr()"

Fold text

btv.fold.text replaces the +-- 12 lines: … placeholder a closed fold shows.

btv.fold.text([[ first:gsub("%s+$", "") .. "  (" .. lines .. " lines)" ]])
btv.fold.text(nil)   -- back to the built-in

first is the fold’s first line verbatim, lines how many it covers, lnum where it starts. The result is memoized on the first line, so a screen that is not changing costs nothing.

Indentation

bemtvi indents from tree-sitter’s indents.scm wherever a grammar has one. btv.indent.expr is the escape hatch for a filetype that has no grammar, or whose indent query gets a construct wrong.

btv.indent.expr([[
  line:match("^%s*end") and previndent - sw
    or prev:match("then%s*$") and previndent + sw
    or nil
]])

Return the target indent in columns, or nil to decline. Declining matters: it hands the line to smartindent/autoindent exactly as if no expression were installed, so you only have to describe the cases you care about.

The precedence is tree-sitter → your expression → smartindent → autoindent. Structure beats a hand-written rule, so an expression never overrides a grammar that has an opinion.

Filetype from content

bemtvi resolves a filetype from a file’s name, a path pattern, or its extension. Extensions that can only be settled by looking inside the file — .h for C-vs-C++, and .r, .v, .m, .pl — are deliberately left alone rather than guessed. btv.filetype.detect is where you answer them.

btv.filetype.detect([[
  ext == "h" and (head:find("template", 1, true) or head:find("::", 1, true))
    and "cpp" or nil
]])

name is the basename, ext the extension without its dot, and head the first few lines (bounded, about 2 KB). Return a filetype to decide it, or nil to decline and leave the built-in tables to answer — a returned filetype wins over them, which is what makes the .h case work.

It runs once per buffer, and its verdict becomes that buffer’s filetype exactly as :setf would set it.

Picker and completion ranking

btv.picker.scorer reorders a picker’s results. It is handed the native fuzzy score alongside the row’s label and the active query, so the natural shape is to nudge the existing order rather than reinvent matching:

-- push test files down; leave everything else where the matcher put it
btv.picker.scorer([[ score - (label:find("/test") and 50 or 0) ]])

It re-ranks only rows that already matched, and only the top 1000 of them. Matching stays native, which is what keeps a picker responsive while 100 000 candidates stream in.

btv.complete.scorer is the same thing for the completion popup, with the row’s kind also in scope ("Snippet", an LSP kind name, or "" for a buffer word):

-- keep snippets available, but below real code completions
btv.complete.scorer([[ score - (kind == "Snippet" and 20 or 0) ]])

Its score is the blended native key — the fuzzy score plus the source’s own bias (lsp 8 > snippets 5 > buffer 0) — so nudging it composes with source order rather than replacing it. Both re-rankers run at most once per repaint, never once per streamed batch, and the completion caret follows the row it was standing on: a popup that reordered under the caret would accept a candidate nobody chose.

The expression register

"= is the register whose contents are computed. It is reachable from three places, and each prompts with = for one expression:

i<C-r>=6*7<CR>          in Insert — inserts `42` at the cursor
"=lnum*10<CR>p          in Normal — the following `p` pastes the result
:e log-<C-r>=lnum<CR>   in the command line — splices the result into the line

In scope are line (the cursor’s line text), lnum and col (1-based) — vim’s expression register can reach the whole Vimscript environment, so the pure equivalent is handed what a computed insert actually wants.

A result ending in a newline pastes linewise, anything else charwise — so "="a\nb\n"<CR>p opens two new lines below.

Two consequences of it being an ordinary register once evaluated:

• It is evaluated when you submit the prompt, not each time it is read. The text is then stored, so getreg("=") shows it and p pastes it — but "=lnum<CR>p followed by j. pastes the first line number again. (vim re-evaluates on read; bemtvi cannot, because the paste path resolves registers through a read-only borrow while the sandbox needs a mutable one.)
• A computed insert or paste is not .-repeatable, for the same reason :s and d/foo are not: it transits the command line. . replays the last repeatable change instead.

<Esc> at the prompt computes nothing. From a nested prompt it abandons only the expression — the command line you were typing comes back untouched, as it does when the expression fails.

Painting a line

btv.decor.expr runs over every visible line during the frame and returns the spans to highlight on it:

btv.decor.expr([[
  local out, i = {}, 1
  while true do
    local s, e = line:find("TODO", i, true)
    if not s then break end
    out[#out + 1] = { s, e, "Todo" }
    i = e + 1
  end
  return out
]])

Each span is { first, last, group } with 1-based inclusive columns — what string.find hands back, so a match drops straight in. An empty list declines the line. This is the surface that takes a block rather than an expression, for the loop above.

A span can draw more than a colour. Beside the three positional slots it takes named keys, each the scalar form of the extmark key it lowers into:

virt_text          text drawn beside the line
virt_hl            its highlight group
virt_pos           where it draws: "eol" (the default), "inline", "overlay", "right_align"
hl_mode            how it merges with the cell under it: "replace" (default), "combine", "blend"
virt_lines         a whole extra screen row, or a list of them
virt_lines_hl      their highlight group
virt_lines_above   draw them above the line instead of below
sign_text          a 1-2 cell glyph in the gutter
sign_hl            its highlight group
line_hl            a highlight group backing the whole line
line_fill          a glyph repeated from the end of the line to the right edge
line_fill_hl       its highlight group
priority           where the span sits in the paint stack (default 4096)

btv.decor.expr([[
  local s, e = line:find("FIXME", 1, true)
  if not s then return {} end
  return { { s, e, "Todo", virt_text = "  <- fix me", sign_text = ">>" } }
]])

-- a heading above every `## ` line, and a rule out to the right edge
btv.decor.expr([[
  if not line:find("^## ") then return {} end
  return { { virt_lines = line:gsub("^## ", ""), virt_lines_hl = "Title",
             virt_lines_above = true, line_fill = "-", line_fill_hl = "NonText" } }
]])

The columns and the group are each optional when the span carries a decoration — a sign anchors on the line, not on a stretch of it, so { sign_text = ">>" } is a whole span. A span that draws nothing at all, or a qualifier with nothing to qualify (virt_hl without virt_text, sign_hl without sign_text), is refused rather than ignored.

priority is the span’s own, so a highlight takes one too: draw an indent guide below the treesitter layer (priority = 90) and it colours only what the syntax left plain.

It is the pure sibling of btv.decor.provider, and the choice between them is what each can see:

Reach for the block when the paint is a pure function of the text — indent guides, colour swatches, trailing whitespace, a keyword badge — and for the provider when it needs git, an LSP reply, or anything the line alone cannot tell it.

The paint is evaluated over each window’s visible rows and memoized on the viewport, so a steady screen costs nothing and only scrolling, resizing or editing re-evaluates.

Quickfix rows

btv.qf.text renders the rows of the quickfix window — vim’s 'quickfixtextfunc'. It is the one surface handed a record: item is the entry, keyed exactly as btv.qf.getqflist() returns it, and idx is its 1-based position.

-- the message first, the location trailing
btv.qf.text([[ item.text .. "  (" .. item.filename .. ":" .. item.lnum .. ")" ]])

btv.qf.text(nil)   -- back to vim's `file|lnum col N| message`

item carries filename, bufnr, module, lnum, end_lnum, col, end_col, vcol, nr, pattern, text, type and valid.

One row per entry is a hard rule — the row index is the entry index for <CR>, :cc and the severity colouring — so a newline inside a rendered row is flattened to a space, exactly as the default flattens a multi-line message.

It applies to the quickfix list, every named list and every window’s location list, and installing or clearing it re-renders the ones that are open.

Parsing build output

btv.qf.parse turns one line of build output into a quickfix entry — the job 'errorformat' does, in Lua rather than in a mini-language inherited from a 1990s C compiler:

btv.qf.parse([[
  local file, ln, col, msg = line:match("^(%S+)%((%d+),(%d+)%): (.*)$")
  if not file then return nil end
  return { filename = file, lnum = tonumber(ln), col = tonumber(col),
           text = msg, type = msg:find("^error") and "E" or "W" }
]])

The entry may set filename, bufnr, module, lnum, end_lnum, col, end_col, vcol, nr, pattern, text, type and valid. Any other key is an error rather than an ignored one — a parser that writes line where it meant lnum would otherwise quietly produce entries that cannot be jumped to.

Returning nil declines the line, which is not the same as dropping it: like 'errorformat', a line no pattern matched is kept as an invalid entry carrying its raw text, which is what makes :copen show a build’s prose alongside its errors.

It applies wherever 'errorformat' does — :cbuffer, :cfile, :cexpr, setqflist{ lines = … }, :make, :grep — and replaces that pass while it is installed, because two parsers disagreeing about one line has no sensible answer.

What it cannot do. The block sees one line and carries nothing between calls, because the sandbox is stateless. That rules out errorformat’s multi-line entries (%A/%C/%Z) and its directory stack (%D/%X) — exactly the features that need an accumulator. 'errorformat' stays for those, and stays the default.

What an expression can do

The expression runs in a second, deliberately tiny Lua VM. It has the value-level standard library — string, table, math, utf8, plus tostring, tonumber, type, pairs, ipairs, next, select, assert, error — and nothing else.

There is no io, os, package, require, load, dofile or debug, no coroutines, and no btv.*. An expression cannot read the buffer, touch the filesystem, or reach the editor at all. Everything it is allowed to know is in its arguments.

Why source text, not a function

You pass a string of Lua rather than a function:

btv.fold.text([[ first .. " (" .. lines .. ")" ]])   -- yes
btv.fold.text(function(first, lines) end)            -- fails loudly

The expression runs in a different Lua VM from your config, and a closure cannot cross between VMs — it would carry references to everything it captured. The source crosses instead, and is compiled on the other side.

Expressions are stateless

Nothing carries from one call to the next, and assigning a global raises an error. That is deliberate, and the reason is that none of these surfaces calls your expression once per item in order:

A counter over :%s/x/…/g on a three-x line would read 16 17 18, not 1 2 3, because the preview got there first. Statelessness turns that class of bug into an error you see immediately.

Fold nesting, the one case that genuinely wants carried state, is served by the relative fold values above — the engine does the accumulating.

When an expression fails

Every failure is reported, and none of them silently produces an empty value.

A compile error is caught when you configure the expression, before it can touch anything. A runtime error, a wrong return type (a table where a string was wanted), or an expression that runs longer than its 50 ms budget aborts that use.

Surfaces that run continuously — fold text, indentation, filetype, picker ranking — report the failure once and then uninstall the expression, falling back to the built-in behaviour. An expression evaluated on every repaint cannot be allowed to print the same error on every frame.

:s and the expression register are the exceptions, because they are one-shot. A failing "= echoes, computes nothing, and leaves whatever was stored alone. A failing :s expression aborts the substitution and says so: a compile error leaves the buffer untouched; a failure partway through leaves the substitutions already made, which one u undoes, since the whole run is a single undo step.

An expression that loops forever is stopped at its deadline rather than hanging the editor, and the VM has a hard memory ceiling, so string.rep("x", 1e12) fails the call instead of the process.

Smooth scrolling

Viewport scrolls slide instead of teleporting — neoscroll.nvim’s behavior, built into the core. It is on by default and needs no plugin.

When the viewport moves more than a step — <C-d>/<C-u>, <C-f>/<C-b>, the mouse wheel, or an off-screen jump like G/gg/a search — the editor emits a scroll descriptor (the from/to lines and a duration) and the client interpolates the slide locally over its own wall clock with an ease-out curve. Because the animation runs client-side, it stays smooth even over a slow remote daemon link, and any new keystroke interrupts the in-flight slide and snaps straight to the destination.

Sideways scrolls slide too. With 'wrap' off, a pan of more than a column — the horizontal wheel (or Shift with the wheel in a modeless session), $ or 0 on a long line, a jump that lands off the side of the screen — pans smoothly, and a jump that moves the view both ways slides diagonally. The GUI pans sub-pixel; the terminal and the browser step a column at a time.

Single-line motions at the window edge, a one-column pan, typing in insert/command mode, and edits that reflow the buffer are kept crisp — only genuine viewport jumps animate.

Options

btv.o.scrollanim = true
btv.o.scrollanimduration = 160   -- ms ceiling; raise for a slower, more visible slide

'scrollanim' is also a window-local option (btv.wo.scrollanim): nil inherits the global value, false forces this window’s scrolls to snap, and true forces the slide even when the global is off. A synced side-by-side diff sets it false on its panes so a mirrored scroll doesn’t desync.

See examples/smooth-scroll/ for a runnable demo.

Indent detection

A file’s own indentation decides how you indent it. Open a tab-indented file in a spaces-by-default config and >> inserts a tab; open a 2-space file and <Tab> inserts two spaces. This is what the vim-sleuth plugin does for vim — in bemtvi it is built into the core, on by default, with nothing to install.

Every time bemtvi reads a file it looks at the leading whitespace of that file’s own lines and sets the buffer’s 'expandtab' and 'shiftwidth' from what it finds:

• Indented with tabs → 'noexpandtab', and shiftwidth=0 (bemtvi’s “follow 'tabstop'” sentinel), because one indent level in such a file is one tab. 'tabstop' itself is left alone: how wide a tab draws is a preference the bytes cannot reveal.
• Indented with spaces → 'expandtab', and 'tabstop' set to the step the file’s own lines show (2, 4, …), with 'shiftwidth' left at its 0 sentinel.
• No usable evidence — an empty or unindented file, a single indented line, or tabs and spaces exactly as common as each other → nothing changes, and the style your config chose stands.

The width lands on 'tabstop', not on 'shiftwidth', and that is load-bearing. 'tabstop' is the single knob that sets bemtvi’s whole indent width — 'shiftwidth' follows it through the 0 sentinel and 'softtabstop' follows 'shiftwidth' through -1 — so a FileType autocmd doing the documented btv.bo[buf].tabstop = 2 still changes how the buffer indents. Writing the detected width straight into 'shiftwidth' would sever that chain silently: the later write would land on a knob nothing reads any more, and the file’s width would win forever.

The verdict is per buffer, not a mode: a tab-indented file and a 2-space file open side by side each keep their own.

Precedence

The file beats your config; anything set after the read beats the file.

built-in defaults  <  your config  <  the file's own indentation  <  :set / an autocmd / .editorconfig

Detection runs when the bytes become the buffer’s text — before BufReadPost — so an autocmd, an .editorconfig plugin, or you typing :setlocal noexpandtab all have the last word. Re-reading the file (:e!, an autoread reload) runs the detection again, so a file reindented on disk is picked up.

It works identically on a local file, a file fetched over a daemon link, and a file read from OPFS in the browser: the detection hangs off the point where a read’s bytes become the buffer’s text, which is core-side on every one of those legs.

Options

btv.o.indentdetect = false   -- or :set noindentdetect

With it off, every buffer simply uses the 'expandtab' / 'shiftwidth' your config set, as it did before.

How the width is decided

The step, not the raw indent width, is what is counted: a 2-space file’s indent widths are 2, 4, 6, 8 — which alone look as much like a 4-space file with skipped levels — while every step between one line and the next is 2. The most common step wins, ties going to the narrower one.

Three deliberate abstentions keep a stray line from setting the style for a whole file:

• A one-column step is never adopted as a width. It is far more often a wrapped line or prose than a convention, and a silent shiftwidth=1 is a much worse outcome than leaving the configured width alone.
• A file must show at least two indented lines before its width is taken — one indented line is as likely a misindent as a convention. (The tabs-versus-spaces direction is still read from a single line: that much a lone indented line does say.)
• Block-comment bodies (* continuation lines) are skipped, so the space that aligns a star under its /* neither votes for a 1-column indent nor makes a tab-indented C file look space-indented.

The scan is bounded — it stops after enough indented lines to be sure, and never reads more than the first 8192 lines — so opening a huge file costs nothing measurable.

See examples/indent-detect/ for a runnable demo.

Image previews

Open an image file and bemtvi renders the picture inline instead of its raw bytes — image.nvim’s behavior, built in, with no terminal-specific plugin to wire up. Each client draws it the native way: ratatui-image in the terminal (Kitty/Sixel/iTerm2 graphics, with a block-cell fallback), a textured quad in the GPU GUI, and an out-of-band <img> in the browser build.

The feature is opt-in through one option.

Enabling it

'imagepreview' (bemtvi-native, off by default) turns it on:

btv.o.imagepreview = true        -- or :set imagepreview

With it on, opening a file with an image extension — png, jpg/jpeg, gif, bmp, webp, tiff/tif, ico, tga, qoi, ppm/pgm/pbm/pnm (case-insensitive) — loads it as an inert preview buffer: the bytes are never decoded as text, the rope stays empty, and the window projects an image the client paints. The path is retained, so the buffer still has a name. With the option off, an image file opens as ordinary binary text, exactly as before.

There are no special commands or keymaps — opening is the usual :e <path> or a file argument on the command line.

UI primitives

bemtvi gives plugins a small, layered set of primitives for building rich interfaces — a reactive component model, plugin-owned content surfaces, ready-made async widgets, and the floating windows underneath them. They share two properties that make plugin UIs short to write and consistent to use:

• The server owns every surface. You never write a render loop, an input grab, or frame-timing code — you hand the server data and a description of what to show, and react to results. (PUC Lua can’t do frame-time work anyway; ADR 0002.)
• One geometry vocabulary. Floats, views, pickers, and the bottom panel all place themselves with the same size / align / margin words (see Placing things).

A file tree, a dashboard, a modal dialog, a which-key popup, a fuzzy finder — each is a few lines on top of these. Reach for the highest-level one that fits:

Components — reactive UIs

btv.component is a Vue-shaped component model: you write reactive state and a pure render, and the framework re-runs the render automatically whenever the state changes (coalesced to one redraw per tick). It owns the whole lifecycle — waiting for the surface to be ready, batching state writes, tearing down on close — so there’s no tick-dance, no manual re-render, no buffer-number juggling.

A component is a { setup, render } table:

• setup(ctx, props) runs once on mount and owns every side effect — reactive state, derived state, event subscriptions, key binds, data fetches — and returns the state value handed to render. It runs only after the surface is ready, so everything on ctx is valid immediately.
• render(state) is pure: it maps state to what’s on screen and returns it. The framework re-runs it on every state change.

Both may be async — call btv.await(...) straight inside them (each runs in its own btv.async coroutine), so a setup that loads from disk, or a render that fetches to display, reads top-to-bottom.

local Counter = btv.view.component({
  setup = function(ctx)
    local s = ctx.reactive({ n = 0 })            -- writing s.n re-renders
    ctx.keymap_set("n", "+", function() s.n = s.n + 1 end)
    ctx.keymap_set("n", "q", ctx.close)
    return s
  end,
  render = function(s)
    return { lines = { "count: " .. s.n, "", "+ to increment · q to quit" } }
  end,
})

Counter.mount({ float = { width = 30, height = 4, grab = true } })

ctx carries the reactivity and lifecycle:

Two surfaces, one reactive core

Where a component renders is a pluggable backend, so the same reactive core drives two very different surfaces:

• "view" (the default, and what btv.view.component selects) — a focus-taking, navigable btv.view buffer, mounted in a dock, split, or grabbing float. render returns { lines, decor }. This is the file-tree / list / modal-dialog case; ctx gains keymap_set / line / set_cursor / bufnr / winid / bo / wo.
• "float" — a non-focus popup-content float (the which-key surface). It never steals focus and binds no keys; render returns { lines, title?, relative?, border? } (rows may be styled chunks), and an empty render hides the float — so a component shows and hides purely by what it returns. Reach it with btv.component{ surface = "float", … }.

-- A self-dismissing toast on the non-focus float surface.
local Toast = btv.component({
  surface = "float",
  setup = function(ctx)
    local s = ctx.reactive({ text = ctx.props.text })
    btv.timer(function() s.text = nil end, 1500)   -- clear -> empty render -> hides
    return s
  end,
  render = function(s)
    if not s.text then return { lines = {} } end  -- an empty render hides the float
    return { lines = { { { s.text, "Comment" } } }, relative = "bottom" }
  end,
})
Toast.mount({ props = { text = "saved ✓" } })

mount(opts) instantiates the component (returning the instance, with :close()); opts.props is passed to setup, and the rest configures the surface. Render and setup errors are caught and surfaced through btv.notify rather than crashing the editor.

Views — the content surface

btv.view is the surface components are built on, and is useful on its own. A view is a plugin-owned, read-only buffer: its lines a plugin sets wholesale, the editing grammar treats it as inert (navigation works, text-mutating keys don’t), and <CR> dispatches to an on_select callback. It’s the generalization of the bottom panel — the surface a file tree, a symbol list, or any line-oriented widget mounts in a dock or a split.

local v = btv.view.create({ name = "files", filetype = "btvfiles" })
v:set_lines({ "  init.lua", "  README.md" })
v:set_userdata({ { path = "init.lua" }, { path = "README.md" } })  -- parallel to lines
v:on_select(function(line, data) btv.open(data.path, { where = "main" }) end)
v:mount({ dock = "left", size = 30 })
-- later: v:unmount()  (keeps it alive)  /  v:close()  (drops it)

Persisting a view across sessions

A view opts into the workspace session by passing persist — a stable, plugin-chosen string id (instance-unique within your plugin) — to create. The editor records only the (namespace, id) pair and the view’s slot in the layout, never its content: the plugin owns what’s worth saving and stores it in its own btv.shada.plugin() store, keyed by the same id.

On restart the editor reopens the layout with each persisted view’s slot held by an empty placeholder window, then — once your plugin has loaded — calls the restorer you registered with btv.view.on_restore so you can rebuild the view and drop it into the reserved slot:

-- Save side: create with a persist id, and stash whatever you need to rebuild it.
local function open_tree(state)
  local v = btv.view.create({ name = "Files", filetype = "btvfiles", persist = "main" })
  v:set_lines(render(state))
  v:on_select(...)
  -- The plugin owns the content; persist just enough to rebuild it.
  btv.shada.plugin():set("view:main", state)
  -- Clean up the stored state if the user closes the view for good.
  v:on_close(function() btv.shada.plugin():delete("view:main") end)
  v:mount({ dock = "left", size = 30 })
  return v
end

-- Restore side: register once at load. `id` is the persist string; `place(view)` drops a
-- freshly-built view into the reserved slot instead of opening a new window.
btv.view.on_restore(function(id, place)
  local state = btv.shada.plugin():get("view:" .. id)
  local v = btv.view.create({ name = "Files", filetype = "btvfiles", persist = id })
  v:set_lines(render(state))
  v:on_select(...)
  place(v)
end)

The owning namespace is derived from your plugin’s location, exactly like btv.shada.plugin() — so two plugins can both use persist = "main" without colliding, and a persisted view whose plugin is no longer installed has its slot quietly collapsed on restore. A lazy plugin does not have to be awake for this. A reserved slot names its owner, so a restore that finds one belonging to a cmd/keys/event/ft-lazy plugin loads that plugin — the slot is itself a trigger, on equal footing with the ones you declared. You do not arm anything for it: keep bemtvi-tree behind cmd = "BtvTree" and the sidebar you quit with still comes back, its config running (and its on_restore registering) before the slot is given up on. A plugin that is enabled = false stays unloaded and its slot collapses, exactly as if it had been removed. From a context that attributes to no plugin (a bare :lua, an RPC, a test), pass an explicit namespace = "…" to both create and on_restore, the same escape hatch btv.shada.plugin(namespace) takes. GC: the editor never deletes your stored state — delete it yourself when the view is closed for good (the on_close line above). A view created without persist is ephemeral: it does not ride the session. Session persistence is a native-build feature (the web build does not restore layouts yet).

The high-level way: a persistent component. The create + on_restore + fresh-mount dance above is what btv.view.component (see Components above) automates. Pass persist = "<id>" to mount and the framework resolves the namespace once, threads it through the backing view + a per-component ctx.store, and on restart adopts the reserved slot or mounts fresh for you — no on_restore handler, no VimEnter fallback:

local Files = btv.view.component({
  setup = function(ctx)
    local s = ctx.reactive({ tree = ctx.store:get("tree") or load_tree() })
    ctx.on_close(function() ctx.store:delete("tree") end)  -- GC is still yours
    return s
  end,
  render = function(s) return { lines = render_tree(s.tree) } end,
})
Files.mount({ name = "Files", filetype = "btvfiles", persist = "main", dock = "left", size = 30 })

ctx.store is this component’s btv.shada.plugin() slice; mutate it on every change and the sidebar comes back intact. A full runnable example is examples/view-persist/. Reach for the raw create / on_restore pair only when you need a surface the component doesn’t model.

Widgets — ready-made prompts

The btv.ui widgets are the common interactions, prebuilt. The three input ones are non-blocking and promise-only (ADR 0002): the call returns at once and you react with :next(fn), or await it inside btv.async. (The vim.ui.* muscle-memory aliases keep neovim’s callback shape.)

-- input: a one-line prompt. Resolves to the text, or nil on <Esc>.
btv.ui.input({ prompt = "Rename to: ", default = vim.fn.expand("%:t") })
  :next(function(name) if name and name ~= "" then btv.notify(name) end end)

-- select: a floating chooser. Resolves to the chosen item, or nil on cancel.
btv.ui.select({ "apple", "banana", "cherry" }, { prompt = "Pick:" })
  :next(function(item) if item then btv.notify("picked " .. item) end end)

-- confirm: a yes/no dialog. Resolves to a boolean.
btv.ui.confirm("Quit without saving?", { default = false })
  :next(function(ok) if ok then btv.cmd("qa!") end end)

• btv.ui.input(opts) — prompt label + default prefill, over the command line. "" on an empty <CR>, nil on <Esc>.

• btv.ui.select(items, opts) — a floating list. format_item maps an item to its label (default tostring); the original item round-trips back, so an arbitrary table survives even though only strings cross the bridge. Its keys are rebindable select-mode maps (j/k/<C-n>/<C-p>/arrows nav, gg/G first/last, <CR> confirm, <Esc>/q cancel):

  btv.keymap.set("select", "<C-j>", btv.ui.select_actions.next)   -- actions: next,
  btv.keymap.set("select", "q", function() end)                  -- prev, first, last,
  ```                                                            -- confirm, cancel
  
  

• btv.ui.menu(entries, opts) — a context menu on the same list. Each entry is { label, detail?, enabled?, separator? }. detail (a shortcut, say) sits in an aligned column on the right, a row with enabled = false greys out, and { separator = true } draws a rule. Keys and clicks skip the rows that can’t be chosen. The promise resolves to the chosen entry itself, so extra fields (an action) come back with it. anchor = "mouse" opens it at the pointer (at the text cursor when a key came after the last click), where it acts like a GUI menu: one click chooses, hovering highlights, a click or right-click off it dismisses it. The right-click menu itself is built on it: to add rows there, register a group with btv.contextmenu rather than opening a second menu.

  btv.ui.menu({
    { label = "Format", detail = "Shift+Alt+F", action = btv.lsp.format },
    { separator = true },
    { label = "Close", action = function() btv.cmd("bdelete") end },
  }, { anchor = "mouse" }):next(function(e) if e then e.action() end end)
  

• btv.ui.confirm(message, opts) — yes/no. default = true (the default) makes <CR> Yes and shows [Y/n]; false makes it decline and shows [y/N]. For a multi-choice menu use select.

• btv.ui.open(uri) — hand a path/URL to the OS opener (open / explorer / xdg-open), off-tick; resolves to the run result { code, stdout, stderr } (like btv.run, it resolves rather than rejects — a missing opener is code = -1).

Popup content

btv.ui.float(contents, opts) is the popup-content surface — a box of read-only content (a rounded border by default; border = "none" for borderless) with no list, no selection, no input grab. By default it is transient: the next key dismisses it.

btv.ui.float("A hint.\nPress any key to dismiss.", { title = " info ", relative = "cursor" })

contents is a string (split on newlines), a list of line strings, or — for a styled popup — a list where a row is a chunk list { {text, hl_group?}, … } (neovim’s virt_text shape), so a row can colour its key one group and its description another. With persist = true it survives keystrokes and returns a handle (:update(contents, opts) / :close() / :is_open()) — the surface a key-observer plugin like which-key refreshes as keys arrive. Options: border ("none"/"single"/"rounded"/"double"/"solid", default "rounded"), title, relative ("cursor" / "editor" / "bottom").

The float surfaces

When something floats, it’s one of four distinct surfaces — worth knowing which, because they behave differently. The two axes: is it a real window? (a real window holds a buffer, so it can scroll and be focused) and does it carry a selectable list?

The naming is a two-axis system: “popup” marks the transient, read-only family (popup content, popup window); “window” marks a real backing window (floating window, popup window). The popup window sits in the intersection — it auto-dismisses like popup content, but because it’s a real window it scrolls (a long hover scrolls past its box) and gets syntax highlighting for free. That’s why LSP hover and signature help use it, not popup content; it has no direct Lua constructor — btv.lsp.hover / signature_help open it internally.

Placing things

Every windowed surface — floating windows, btv.view, components, pickers, the bottom panel — shares one placement vocabulary, so you learn it once:

For low-level parity there’s also anchor ("NW"/"NE"/"SW"/"SE") + row/col offsets, the explicit form align + margin sugar over.

Floating windows directly

When you need a real, editable window over the layout — not a view or a widget — the float form of nvim_open_win is the low-level primitive. It lives on the RPC surface (the nvim_* methods a client, test, or remote tool drives), not in config Lua: bemtvi’s Lua API deliberately omits the mutating vim.api.nvim_* entity surface (ADR 0002), so a plugin opens its float through btv.view:mount{ float = … } or a component instead — the same window with the lifecycle managed for you (pass grab = false for a non-modal panel focus can leave).

-- over RPC (a client or test):
-- win = nvim_open_win(buf, true, { relative = "editor", width = 40, height = 3,
--                                  align = "center", border = "rounded", title = " scratch " })
-- nvim_win_set_config(win, { height = 6 })   -- move / resize live
-- nvim_win_close(win, true)                  -- dismiss

From Lua the float reads are first-class: nvim_win_get_config(win) (alias of btv.win.config) reads a window’s float config back ({ relative = "" } for a tiled window), and btv.win.gettype(win) returns "popup" for a float. A float is a real window — it holds an editable buffer, splits are disallowed, and :q / focus / :only treat it as an overlay rather than part of the tiled tree.

Try it

Runnable playgrounds ship under examples/:

BEMTVI_CONFIG=examples/btvchecklist cargo run -p bemtvi

How it works (in brief)

A floating window is a real window carried by the same WindowOp queue and View projection as tiled windows — redraw() projects each with its rect, floating flag, border, and zindex, and every client paints the tiled windows first, then the floats in z-order. The two placement modes map onto existing FloatRelative::{Cursor, Editor} variants with no new positioning code.

The widgets sit on one server-side float-list component — completion, the picker, and btv.ui.select are thin engines over the same widget, differing only in whether they carry a prompt and a preview; for each, only a display label and an integer key cross the Lua↔Rust bridge. The component model is pure Lua: a Vue-3 reactivity core (dependency-tracked reactive / computed) over the btv.view (and popup-content) surfaces, with the render coalesced to one redraw per tick and async renders generation-gated so a slow one can’t clobber a newer one.

For the full design, see the floating-windows plan, the float-list widget spec, and the native plugin API spec.

Permanent docks

A dock is a permanent, editable window region pinned to a screen edge — like VSCode’s side bars and bottom panel. It holds normal buffer windows (you can split inside it), but unlike an ordinary split it is global — it shows on every tab — and the main editing area can never disturb it: splits, window switches, and tab changes in the main area leave it untouched.

There are four docks, one per edge: left, right, top, bottom. The top dock sits above the tabline, owning the very top rows of the screen.

Layers: main ↔ docks

The screen is split into two layers: the main editing area and the docks. <C-w> window commands act within the focused layer; the doubled <C-w><C-w> prefix is a layer switch that crosses between them.

So once focus is inside a dock, every plain <C-w>{cmd} operates inside that dock; <C-w><C-w> returns you to the main area. Each dock starts on an empty scratch buffer — cross into one and start typing.

Opening and closing

Drive docks from Lua or the ex-command wrappers:

-- side is "left" / "right" / "top" / "bottom"; size is columns (left/right) or
-- rows (top/bottom); buf is an optional existing buffer (default: a scratch).
btv.dock.open({ side = "left", size = 28 })
btv.dock.open({ side = "bottom", size = 6 })

btv.dock.focus("left")   -- move focus to a dock
btv.dock.close("left")   -- drop the dock and its content

The ops are queued and applied after the current Lua chunk runs (the editor’s “Lua queues, core mutates” flow), so docks opened in init.lua appear on the first frame.

Toggle vs. close

These are different on purpose:

• :DockClose (and btv.dock.close) drops the dock and its content.
• :DockToggle / :DockHide / :DockShow (and btv.dock.toggle/hide/show) collapse a dock from view while keeping everything — its splits, tabs, cursor, and text all come back exactly as they were when you show it again.

A collapsed dock isn’t gone: it leaves a ▸LABEL chip on the command-line row (bottom-left, when idle). Click the chip to bring that dock back.

Toggling from a keymap uses the same path as the ex-command:

vim.keymap.set("n", "<leader>e", function()
  btv.dock.toggle("left")
end, { desc = "toggle the left explorer dock" })

Per-dock options

Docks have their own option scope, alongside btv.bo / btv.wo / btv.o. Set options inline in btv.dock.open{...} or after the fact through btv.dock.opt(side); reads return the cached value (or its default).

btv.dock.opt("left").title = "EXPLORER"   -- a fixed strip label
btv.dock.opt("left").showtabline = 2      -- always show the dock's own tabline
btv.dock.opt("bottom").autohide = true    -- collapse when focus leaves
btv.dock.opt("left").size = 40            -- resize live

Setting an unknown option warns loudly rather than silently ignoring it.

autohide is great for a panel you want out of the way until you need it — a terminal tray, say. It collapses as soon as focus leaves and re-appears when you cross back in (<C-w><C-w>j) or run :DockShow {side}.

Per-dock tabs and tablines

Each dock — and the main area — has its own independent tab stack and tabline. Focus a dock and :tabnew opens a tab inside that dock; its strip lights up on its own, driven by that dock’s showtabline. Clicking a dock’s tabline switches tabs within that dock. (Design: the per-region tablines spec.)

Try it

A runnable playground ships in examples/dock:

BEMTVI_CONFIG=examples/dock cargo run -p bemtvi -- examples/dock/sample.txt

It opens a titled left side bar and an autohide bottom tray, maps <leader>e to toggle the explorer, and walks through the layer-switch keys interactively.

How it works (in brief)

A dock is a parked WindowTree swapped onto the live self.windows whenever it gains focus — the same trick tab pages use to keep one tree active. Because every split / close / focus / edit / redraw reads from self.windows, they “just work” inside the focused dock with no retargeting. Geometry reserves the edge bands before laying out the main area, and each client maps a window’s region (Main / DockLeft / …) to its absolute screen origin. One region is not a band: an editor-relative float is laid out against the whole windows area and tagged Screen, so a centered dialog centers on the screen and paints over the dock bands rather than being boxed into whichever region opened it.

For the full design — the layer-swap model, geometry, <C-w><C-w> parsing, and the cross-client rendering — see the permanent docks plan and its per-region tablines follow-up.

Fuzzy picker

btv.picker is bemtvi’s native fuzzy finder — a centered float with a prompt that grabs every key, a Rust fuzzy matcher that re-ranks as you type, and an optional preview pane. The server owns the widget: the prompt, the matcher, navigation, and a generation token that drops a stale response for a query you’ve already typed past. No input loop runs in Lua — a source is just a thin driver that streams candidates in and handles confirm.

It ships with a set of built-in sources — files, files_git, live_grep, live_grep_git, buffers, curbuf, diagnostics, keymaps, marks, jumplist, pickers — and registering your own is a few lines.

File finding and grepping come in pairs:

• files_git / live_grep_git respect .gitignore (and .ignore / .rgignore) — rg --hidden, so a dotfile like .github/workflows/ci.yml is still found and only ignored paths drop out. Without rg they fall back to git ls-files / git grep inside a work tree, to plain find / grep outside every repository (no .git at or above the directory, so, as for rg, no .gitignore applies), and otherwise (git missing or refusing the repository, or the pure web client) to a btv.fs walk that reads the ignore files itself (btv.fs.walk{ gitignore = true }) — so the ignore rules hold everywhere. The git grep leg needs git 2.19 or later (--column); with an older git, live_grep_git says so instead of searching. A basic grep (busybox, stock Alpine: no --null, -I or --exclude-dir) still works, but a file name holding :<digits>: is cut short there. These are the everyday <leader>ff / <leader>fg.
• files / live_grep search unrestricted — the equivalent of rg -uu (--no-ignore --hidden), so a .gitignored build artifact is still findable. The one exclusion is .git itself. These are <leader>fF / <leader>fG.

Either way, narrowing a search is the filter boxes’ job (<C-g>) — per-search, so hiding target/ this time never makes a file unfindable the next.

Using a picker

The built-in sources are bound out of the box, plus a resume map:

These are overridable defaults — your own map for the same key wins, and you can disable one by binding it to an empty function. To open any registered source from your own keymap, call btv.picker.open:

btv.keymap.set("n", "<leader>o", function() btv.picker.open("files") end)

Resume — <leader>fr

<leader>fr (telescope’s resume) reopens the most-recently-closed picker restored to exactly where you left off — the same displayed rows, prompt text, highlighted row, and multi-select marks. The server replays a frozen snapshot it captured at close, so a live_grep picker comes back with its actual previous results rather than a fresh, differently-ordered search; editing the query from there re-runs the source as usual. It’s a no-op (with a gentle notice) before any picker has closed. Call it from your own map with btv.picker.resume().

Transient internal pickers (the command-line completion overlay, for instance) opt out by setting resumable = false on their source, so resume always points at the last real picker.

In the open picker (all of these are rebindable — see Keys):

Sending results to a list

<C-q> sends the picker’s current results to a named list keyed <picker>:<query> — bemtvi’s take on telescope’s send-to-loclist, and a fast way to turn a search into a working set you step through with <CR> in the list. Each distinct search is its own persistent dock tab (re-running the same search updates it in place); a named list never collides with the quickfix and survives closing the window you sent it from. See named lists.

• Filtered, not everything. It sends the rows matching your live query — what you see — not every candidate the source streamed.
• Multi-select. Mark individual rows with <Tab> (it marks and advances; <S-Tab> too). Marks are kept by item, so they survive further typing / re-ranking. When any rows are marked, <C-q> sends only the marked ones (in mark order); with none marked it sends the whole filtered list.

Where the list opens is governed by the 'qfdock' option (on by default, the bemtvi way): each send opens as a tab in the bottom dock, so several searches sit side by side, and <CR> on an entry jumps into the main editing area. Set :set noqfdock for a bottom split instead. See Quickfix & named dock lists for the full model and the btv.qf.list / show API the action builds on.

Writing a source

btv.picker.source{...} registers a source. The driver, items(ctx), streams candidates by calling ctx.push(item) per result and signals completion by returning. An item is a table with a text display field plus whatever data confirm (or the preview) needs — e.g. path / row / col.

A static source pushes a fixed set, fuzzy-matched in Rust as you type:

btv.picker.source({
  name = "colours",
  items = function(ctx)
    for _, c in ipairs({ "red", "green", "blue", "amber" }) do
      ctx.push({ text = c })
    end
  end,
  confirm = function(item) btv.notify("picked " .. item.text) end,
})

A source can be asynchronous — wrap items in btv.async and stream from a subprocess. bemtvi is promise-only, so an async source returns its promise and the engine awaits it; there is no done callback. Reap any spawned job on close via ctx.on_cancel. This is essentially how the built-in files source works (the shipped one adds a fallback chain — find, then an btv.fs walk — for when rg is missing):

btv.picker.source({
  name = "files",
  preview = "file",
  items = btv.async(function(ctx)
    local stream = btv.run_stream({ cmd = "rg", args = { "--files" }, cwd = ctx.cwd })
    ctx.on_cancel(function() stream:kill() end)
    for batch in btv.await_each(stream) do
      for _, l in ipairs(batch) do
        if l ~= "" then ctx.push({ text = l, path = l }) end
      end
    end
  end),
  confirm = function(item) btv.picker.edit(item) end,
})

Row shape: heads, tags and colors

A row can be more than one string. A source that knows its row has structure — a location, a classification, a matched fragment — declares it, and the widget fits the parts separately instead of truncating one long label:

ctx.push({
  tag = "E",                       -- pinned classification, never elided
  head = "src/main.rs:12:5 ",      -- the location column, aligned down the list
  text = "unused variable `x`",    -- the body
  match = { 17, 17 },              -- 1-based INCLUSIVE char range of a hit in `text`
  hl = "DiagnosticError",          -- the group the row is painted with
})

• head makes the row two-column. The head keeps at least 40% of the row (a long body can never squeeze the file name off), and the body is windowed around match so a hit 200 columns into a line still shows. A head that doesn’t fit elides tail-first, keeping file:line — the part you scan for.
• tag is a short classification prepended to the head and pinned: the elision happens after it, so E survives however narrow the column gets. Use it whenever the head’s leading characters say what the row is.
• hl is an ordinary highlight group, resolved against the live colorscheme each frame (an undefined group simply doesn’t paint). It colors the head of a two-column row — leaving the body’s match highlight readable — and the whole label of a plain one.

The shipped diagnostics source is exactly this shape: E src/main.rs:12:5 in the severity’s color, then source: message folded onto one line.

Declaring filter = true gives the source the include/exclude boxes. Every candidate carrying a path is then tested against them at the single point they all cross, so a source gets the filter for free however it enumerates. A source that shells out to a ripgrep-compatible tool should also splice ctx.rg_globs (ready-made -g argument pairs) into its argv, so the tool prunes the tree instead of streaming paths that are about to be dropped — on a node_modules-sized directory that is the difference between the results arriving and the cap filling with noise. The patterns themselves reach the source as ctx.include / ctx.exclude.

items = btv.async(function(ctx)
  local args = { "--files", "--color=never" }
  for _, a in ipairs(ctx.rg_globs) do args[#args + 1] = a end
  local stream = btv.run_stream({ cmd = "rg", args = args, cwd = ctx.cwd })
  …
end),

btv.picker.edit(item, mode) is the common confirm action: it opens item.path and, if the item carries a 1-based row (and optional col), jumps the cursor there. The mode is the confirm gesture (the picker passes it to confirm(item, mode)): "current" opens in the focused window honoring 'switchbuf'; "tab" / "split" / "vsplit" (the defaults <C-t> / <C-x> / <C-v>) open in a new tab / horizontal split / vertical split. Forward it from a custom source’s confirm to support those keys: confirm = function(item, mode) btv.picker.edit(item, mode) end.

Switching to an open tab

Where a confirmed pick (and every jump — LSP go-to, quickfix, marks) lands is governed by 'switchbuf'. bemtvi defaults it to usetab: opening a buffer already shown in another tab focuses that tab instead of re-opening it in the current window. Set it like vim — btv.o.switchbuf = "useopen" (reuse a window in the current tab only) or btv.o.switchbuf = "" (classic: always open in the current window). <C-t> always makes a new tab regardless (an explicit tab gesture).

The widget windows its rendering and matches incrementally, so a source can stream 100k+ candidates and stay fast; max_results (default 100000) is only a runaway-source safety bound.

Dynamic (live) sources

Set dynamic = true and the source re-runs on every prompt edit with the local fuzzy matcher bypassed — the source itself does the filtering. It reads the live prompt from ctx.query and the working directory from ctx.cwd. This is essentially how live grep works (re-spawning rg per query; the shipped source falls back to grep, then an btv.fs match, when rg is missing):

btv.picker.source({
  name = "live_grep",
  dynamic = true,
  preview = "location",
  items = btv.async(function(ctx)
    if ctx.query == "" then return end
    local stream = btv.run_stream({
      cmd = "rg", args = { "--vimgrep", "--", ctx.query }, cwd = ctx.cwd,
    })
    ctx.on_cancel(function() stream:kill() end)
    for batch in btv.await_each(stream) do
      for _, l in ipairs(batch) do
        local file, lnum, col = l:match("^(.-):(%d+):(%d+):")
        if file then
          ctx.push({ text = l, path = file, row = tonumber(lnum), col = tonumber(col) })
        end
      end
    end
  end),
  confirm = function(item) btv.picker.edit(item) end,
})

A dynamic source is debounced: a query edit cancels the in-flight job and schedules the search debounce ms later, so a fast typist spawns one process per pause, not one per keystroke. While the new search runs the previous results stay on screen — the list never flashes empty; they swap out only when the first new result arrives (or clear if nothing matched). The prompt row’s spinner is what tells the two states apart. The delay defaults to btv.picker.debounce (250 ms), overridable per source (debounce = N) or per open; 0 disables it.

Preview pane

Add preview to show a side pane for the highlighted item:

• "file" — shows the head of item.path.
• "location" — shows item.path scrolled to item.row / item.col (1-based) with the match range highlighted.

Omitted means no preview pane. Preview content is tree-sitter-highlighted by the server, and works across the terminal, GUI, and web clients. Scroll it with the <C-d> / <C-u> / <C-f> / <C-b> keys above.

Open-time options

btv.picker.open(name, opts) — each opts field overrides the matching field on the source, which in turn overrides the picker default:

-- a snappier live grep, just for this map:
btv.keymap.set("n", "<leader>fG", function()
  btv.picker.open("live_grep", { debounce = 100 })
end)

Keys

Every picker key is an ordinary picker-mode keymap, not a hardcoded grab: while a picker owns input the server selects the picker bucket, so navigation, confirm, cancel, preview-scroll, and query-editing are all rebindable like any other mode:

btv.keymap.set("picker", "<C-j>", btv.picker.actions.next)
btv.keymap.set("picker", "<C-k>", btv.picker.actions.prev)
btv.keymap.set("picker", "<Tab>", btv.picker.actions.confirm)
-- disable a default binding by mapping it to an empty function:
btv.keymap.set("picker", "<C-n>", function() end)

The actions are next, prev, confirm, confirm_tab, confirm_split, confirm_vsplit, cancel, send_to_list, toggle_select, clear_select, preview_half_down, preview_half_up, preview_page_down, preview_page_up, backspace, delete, left, right, to_start, to_end, next_field, toggle_filters. The one key that is not a map is an arbitrary printable char — there is no way to enumerate every char, so an unmapped printable just inserts into whichever line has focus.

Progress — the count and the spinner

The right end of the prompt row is the picker’s own status line:

┌─ Live Grep ──────────────────────┐      ┌─ Live Grep ──────────────────────┐
│ > handler                  ⠹ 128 │      │ > handler                    247 │
├──────────────────────────────────┤ ───► ├──────────────────────────────────┤
│ src/net/handler.rs:12:5: …       │      │ src/net/handler.rs:12:5: …       │
└──────────────────────────────────┘      └──────────────────────────────────┘
    still searching (128 hits so far)          done — 247 hits

• A spinner turns while the source is still working. It covers the whole in-flight window — the debounce, the process spawn, the scan — so a search over a big tree never looks like a picker that has stopped responding. It matters most for a dynamic source, where the rows on screen belong to the previous query until the new run’s first result lands (see Dynamic sources): with no spinner, “searching” and “broken” look identical.
• The count is the number of rows the list is showing. Once the local matcher has narrowed the candidates it reads matched/total (12/3480 — twelve rows answer what you typed, out of 3480 the source found), and a bare number when everything found is on show — which is always the case for a dynamic source, since it does its own filtering. A finished search that found nothing says 0.

Results also appear as they stream: a partial batch crosses to the widget at the end of the tick it was pushed on, so a query with three hits shows them the moment rg prints them rather than when the scan of the whole tree finishes.

The readout is composed server-side, so the terminal, GUI and web clients all show the same thing, and a remote (daemon) or browser session animates exactly like a local one.

Include / exclude filters

files, files_git, live_grep and live_grep_git carry two glob boxes, the way VSCode’s search panel does — files to include and files to exclude. <C-g> reveals them and steps through the three editable lines (query → include → exclude); typing goes to whichever has focus.

┌─ Find Files ─────────────────────┐      ┌─ Find Files ─────────────────────┐
│ > handler        12/3480 [+1 -2] │      │ > handler                12/3480 │
├──────────────────────────────────┤ <C-g>│ include  src/**                  │
│ src/net/handler.rs               │ ───► │ exclude  target/, *.lock         │ ← focus
│ src/ui/handler.rs                │      ├──────────────────────────────────┤
└──────────────────────────────────┘      │ src/net/handler.rs               │
        collapsed, filters active         └──────────────────────────────────┘

Each box holds a comma-separated list of globs. A comma inside {…} belongs to the pattern, so **/{node_modules,target}/** is one glob, not two. Collapsing the boxes does not turn the filter off — the badge ([+1 -2]: one include, two exclude patterns) keeps an active filter visible, so a search that is quietly hiding files never looks like one that isn’t.

Defaults

btv.picker.setup sets the line every filterable picker opens with — the “stop showing me build output” knob:

btv.picker.setup({
  exclude = { "target/", "node_modules/", "*.min.js" },
  history = 20,  -- past lines kept per box for <C-Up>/<C-Down>; 0 disables
})

History — <C-Up> / <C-Down>

Each box remembers the lines you have used, most recent first, and persists them across restarts (via btv.shada.plugin, on the ordinary shada cadence). With a box focused, <C-Up> walks back into older lines and <C-Down> forward again, returning to the line you were composing — cmdline history. The two boxes keep separate lists, so an include pattern never surfaces in the exclude box where it would mean the opposite.

A filterable picker opens pre-filled with the most recent line for each box, so the filter you worked out yesterday is already applied rather than retyped.

btv.picker.history("exclude")   -- the stored lines, most recent first
btv.picker.forget_history()     -- drop them all

Precedence, lowest to highest: the source’s own default → btv.picker.setup → the most recent line used → an explicit btv.picker.open{ include = … }. History outranks the configured default because a line you actually typed is a stronger statement than one configured months ago; an explicit open option outranks everything, so a picker asked for a scope gets exactly that scope.

Two conveniences make a typed pattern mean what you meant:

A picker can also open already scoped, which is what a dedicated map usually wants:

-- "find in sources"
btv.keymap.set("n", "<leader>fs", function()
  btv.picker.open("files", { include = { "src/**", "crates/**" } })
end)

-- grep everything except the vendored trees, with the boxes already showing
btv.picker.open("live_grep", { exclude = "vendor/, **/*.min.js", filters = "open" })

Any source whose items carry a path can have the boxes by declaring filter = true — see Writing a source. On a source without it, <C-g> says so rather than presenting boxes that would filter nothing.

Vendored paths last — deprioritize

A search over a real project hits node_modules/, build output, lockfiles and source maps by the thousand, and the hits you wanted — the project’s own sources — end up under them. So every filterable picker lists those paths after the rest. Nothing is hidden (that is the exclude box’s job): a yarn.lock hit is still there, below src/. Each group keeps its own order — the order found with no query, match order under one — so a better-matching vendored file never jumps a project file.

┌─ Live Grep ──────────────────────────────────┐
│ > useAuth                               412  │
├──────────────────────────────────────────────┤
│ src/composables/auth.ts:3:17: export func…   │  ← the project's own hits first
│ src/pages/login.vue:12:9: const { user } …   │
│ node_modules/@nuxt/auth/dist/index.mjs:88…   │  ← then the vendored ones
│ .output/server/chunks/auth.mjs.map:1:4410…   │
└──────────────────────────────────────────────┘

The shipped list is btv.picker.defaults.deprioritize: the JS/TS, Python and build-output trees (node_modules/, .nuxt/, .output/, dist/, build/, target/, .venv/, __pycache__/, vendor/, …), editor and toolchain directories, every common lockfile, and *.min.js / *.min.css / *.map. Test files are not on it — plenty of people grep their tests on purpose. btv.picker.setup replaces the list, in the same glob syntax as the exclude box; extend the shipped one rather than retyping it:

btv.picker.setup({
  deprioritize = btv.list.extend(
    btv.tbl.deepcopy(btv.picker.defaults.deprioritize),
    { "*test*", "*_spec.lua" }
  ),
})

btv.picker.setup({ deprioritize = {} })   -- turn it off: pure stream / match order

Ordering alone would not stop a node_modules-heavy tree from filling the result cap before the project’s hits were even found, so the shipped files / live_grep pickers search in two passes: rg first with the deprioritized globs excluded — it never enters node_modules/ — then a second run over just those paths. The btv.fs walk fallback (the web client) pushes its list the same way, normal paths first. Only the fallbacks on a machine without rg — find / grep, and git ls-files / git grep for the _git pickers inside a work tree — search in one pass; their rows are still ordered.

A source can use the same machinery. A row pushed with low = true lists after the rest; a source with filter = true gets its paths tested against the deprioritize list automatically, and can search in the same two passes through ctx.passes:

items = btv.async(function(ctx)
  for _, pass in ipairs(ctx.passes) do   -- normal paths first, then the low ones
    ctx.begin_pass(pass)                 -- the sink keeps only this pass's tier
    run_my_tool(pass.rg_globs)           -- the box globs plus this pass's own
  end
end),

A tool that honours .gitignore takes pass.rg_excludes instead of rg_globs: rg lets a positive -g override the ignore files, so the low pass’s includes would re-include an ignored node_modules/. The negations alone are safe, and the sink applies the include box and the tier; pass.keeps(path) says whether a path belongs to the pass, for a source that lists first and searches only its own.

btv.picker.scorer re-ranks within each group and never lifts a deprioritized row above the rest.

Try it

A runnable playground ships in examples/ui-picker:

BEMTVI_CONFIG=examples/ui-picker cargo run -p bemtvi -- examples/ui-picker/sample.txt

It maps the three built-in sources, registers a custom static source, and shows the box-size, preview, and debounce overrides.

For the filter boxes there is a second playground, examples/picker-filters:

BEMTVI_CONFIG=examples/picker-filters \
  cargo run -p bemtvi -- examples/picker-filters/sample.txt

It ships the mess a real project has — a target/ artifact, a vendor/ lock file, a dotfile — and walks through defaults, editing a box, what each pattern shape means, the <C-Up> history, pre-scoped pickers, and a custom filterable source.

Deprioritizing and the .gitignore pickers have a third, examples/picker-priority:

BEMTVI_CONFIG=examples/picker-priority \
  cargo run -p bemtvi -- examples/picker-priority/sample.txt

It shows the default ordering, extending the list with test files, and <leader>fg versus <leader>fG on an ignored file.

How it works (in brief)

The full item tables stay Lua-side; only a display label and an integer key cross the bridge per result (exactly like btv.ui.select), so an item’s arbitrary fields never need to serialize. Candidates are batched rather than crossing one at a time, which is what makes streaming 100k results fast: a batch crosses every ~1000 items, or at the end of the tick it was pushed on — whichever comes first, so a handful of hits is never held back waiting for a threshold it will not reach. A generation token stamps every run, so a push from a query you’ve typed past — or from a picker that has since closed — is dropped.

For the full design — the unified float-list widget, the Rust matcher, dynamic forwarding, and the preview cache — see the fuzzy-finder plan, the preview-pane plan, and the float-list widget spec.

Quickfix & named-list dock tabs

bemtvi shows the quickfix list and named lists as tabs in the bottom dock by default, not as a split window — so you can keep several searches open side by side and flip between them, while activating an entry opens the file in the main editing area. The classic vim behavior (a bottom split, one list, replaced in place) is one option away. Location lists are the exception: they always keep vim’s behavior — a bottom split owned by their window — and never dock.

This is the surface the fuzzy picker’s <C-q> builds on, but it is a general list facility — :copen, :make, :vimgrep, diagnostics, and the btv.qf.* API all flow through it.

The 'qfdock' option

'qfdock' governs only the dock-oriented lists — the global quickfix list and named lists. It does not touch location lists.

btv.o.qfdock = false      -- prefer the classic split behavior
-- or, transiently:  :set noqfdock  /  :set qfdock

The option governs :copen, named lists, and the quickfix btv.qf.*_qflist actions. Location lists (:lopen, btv.qf.{send,add}_to_loclist) always open as a bottom split owned by their window, regardless of this option.

Closing a list

:cclose closes the quickfix list — its dock tab (and the bottom dock itself when it was the last tab) under 'qfdock', or its split otherwise. :lclose closes the location list’s split. Same commands as vim, either way.

Dock tabs are ordinary dock tabs: cycle between saved searches with gt / gT while the dock is focused, cross in and out of the dock with <C-w><C-w>. (See Permanent docks.)

Sending results to a list

The btv.qf.* family populates a list and shows it. Each takes an array of entry dicts ({ filename =, lnum =, col =, text = }, the setloclist shape) and an optional { title = }:

To save several searches as side-by-side dock tabs, use a named list (btv.qf.list / show, below) — that, not the loclist, is the dock-tab surface.

(Bare btv.send_to_loclist etc. aliases exist too.) Example — send the current buffer’s TODO lines to a saved location list:

btv.keymap.set("n", "<leader>lt", function()
  local items = {}
  for i, line in ipairs(vim.api.nvim_buf_get_lines(0, 0, -1, false)) do
    if line:match("TODO") then
      items[#items + 1] = { filename = btv.buf.name(), lnum = i, text = line }
    end
  end
  btv.qf.send_to_loclist(items, { title = "TODOs" })
end)

From the picker

In any picker, <Tab> marks rows (multi-select) and <C-q> sends the results to a named list keyed <picker>:<query> — the marked rows if any are marked, else the whole filtered set. Each distinct search is its own persistent dock tab (re-running the same search updates it in place), independent of the quickfix and of any window.

Named lists (window-independent, addressed by name)

A named list is like the global quickfix list — structured entries, its own bottom-dock tab, <CR> jumps to the entry in the main editing layer — but there can be many, each addressed by a stable name. Storage lives on the editor (not a window), so a named list survives closing any window and never collides with the single quickfix list (or with :grep / :make). That makes it the right home for a persistent plugin panel (e.g. a debugger’s “All Breakpoints”).

You push items with btv.qf.list(name, items) whenever your data changes — no datasource/refresh indirection — then btv.qf.show(name) opens or focuses the tab.

local function todo_items()           -- re-scan the live buffer on demand
  local items = {}
  for i, line in ipairs(vim.api.nvim_buf_get_lines(0, 0, -1, false)) do
    if line:find("TODO") then
      items[#items + 1] = { filename = btv.buf.name(), lnum = i, col = 1, text = line }
    end
  end
  return items
end

btv.keymap.set("n", "<leader>tl", function()
  btv.qf.list("todos", todo_items(), { title = "TODO / FIXME" })
  btv.qf.show("todos")                 -- repaints the tab if already open
end)

opts.title sets the dock-tab label (defaults to name); opts.action is "r" (default — replace in place), " " (push a new list onto the stack), or "a" (append). btv.qf.list only writes the list — it never opens or focuses the tab, so call btv.qf.show to surface it. Showing a name with no items yet opens an empty tab.

Each name is an independent list shown as its own dock tab, so several sit side by side and a :grep later clobbers none of them. Closing the tab — or any window — never destroys a named list: re-show it by name and it re-renders.

Try it

A runnable playground ships in examples/picker-to-named-list:

BEMTVI_CONFIG=examples/picker-to-named-list \
  cargo run -p bemtvi -- examples/picker-to-named-list/sample.txt

Named lists have their own playground in examples/named-lists (\tl collects a TODO/FIXME list, \ll a long-lines list beside it, \td drops the first):

BEMTVI_CONFIG=examples/named-lists \
  cargo run -p bemtvi -- examples/named-lists/sample.txt

How it works (in brief)

Three list flavors share one rendering / navigation engine, differing only in where they’re stored and shown:

• The quickfix list is global. Under 'qfdock' (default) it shows as the single bottom-dock tab; otherwise a bottom split.
• A location list is owned by a window (vim’s model). :lopen / send_to_loclist open it in a bottom split of that window; closing the owner closes the list. It never docks — 'qfdock' does not apply to it.
• A named list is the dock-tab “save searches” surface. Its list lives in an editor-side registry keyed by name (not on a window), so it is addressed and re-shown by name, sits beside other named lists as its own dock tab, and outlives any window close.

All three jump the same way: a jump excludes the display window as its target, so it falls back to the main layer (always enumerated first), landing the file in the editing area rather than inside the dock. The picker’s <C-q> captures the matched item keys and the live query server-side, then (in Lua) builds a named list keyed <picker>:<query> via btv.qf.list + btv.qf.show.

Gutter text

A plugin can give each line a column of its own text, between the line numbers and the text: a diff’s old and new line numbers, a blame hash and author, a side-by-side view’s own numbering. It is the gutter_text extmark key, so it uses extmarks’ namespaces, gravity and view:set_decor, and it moves with its line as the text is edited.

local ns = btv.ns.create("my-diff")
btv.buf.set_extmark(0, ns, 4, 0, {
  gutter_text = { { "  12 ", "DiffDelete" }, { "     " } },
  line_hl_group = "DiffDelete",
})

A window reads, left to right: fold column, signs, line numbers, gutter text, text.

What it does

• The column is not part of the line. The text keeps its own columns, so a sideways scroll under 'nowrap' leaves the column where it is, a click lands on the character under the pointer, $ scrolls by the text area that is left, and 'wrap' wraps into it. (Inline virtual text at column 0, the usual way to fake this, gets all four wrong.)
• One width for the whole buffer. The column is as wide as the widest gutter_text in the buffer, measured in screen cells, so a wide character in a blame column still lines up. A shorter one is padded on the right. The width comes from the whole buffer rather than the visible rows, so the text doesn’t shift as you scroll past a long entry. A plugin that wants numbers right-aligned pads them itself. The column is never wider than what the window has left beside its fold, sign and number columns: text past that is cut off.
• First row only. Like a line number, it shows on a wrapped line’s first display row; continuation rows, virtual lines and ~ filler rows leave the column blank. A closed fold shows its first line’s.
• One mark per line wins. Several marks on one line don’t concatenate, so the column can’t fall out of line: the highest priority wins, then the higher mark id. Within one namespace that is the mark placed later, unless you reuse an explicit id; across namespaces, give the marks different priorities.
• Colours. Each chunk’s group is honoured as given, through the window’s 'winhighlight'. A chunk without one paints like the line numbers: LineNr, or CursorLineNr on the cursor line. A line_hl_group tint runs under the column too, so a diff’s tint reaches its numbers.

The rules

• gutter_text is a non-empty list of { text, group? } chunks. Anything else raises, naming the key and the chunk: an empty list, a hole in the list, a named key beside it, or a third slot in a chunk. So does a newline, a tab or any other control character in the text.
• It works from btv.buf.set_extmark, view:set_decor and a btv.decor provider’s publish alike, since the three share one option vocabulary.
• A btv.decor.expr block can’t paint it: that frame-time surface has its own key list, and gutter_text isn’t on it.
• One column per window. Two plugins wanting a column each (blame beside a diff) is not supported yet.
• The column is not clickable on its own: a click there behaves like a click on a line number, and the pointer stays the arrow.

Testing it

In a btv.test spec, t:decor(row).gutter is the row’s text as sent (the chunks joined, before padding) and t:gutter().gutter_text_width is the column’s width. t:screen() doesn’t show it, since it isn’t buffer text.

Example

examples/gutter-text/ paints old and new numbers over a unified diff and a blame column with a CJK author:

BEMTVI_CONFIG=examples/gutter-text cargo run -p bemtvi -- examples/gutter-text/sample.txt
bemtvi --test-plugin examples/gutter-text

Cost

Reading the column’s width costs nothing per frame: the extmark store keeps a count of marks per width as marks are set, deleted and cleared. A buffer with no gutter_text skips the column’s projection entirely. With some, the visible marks come from the extmark store’s position index, as every other layer’s do, so marks off screen cost a frame nothing.

Workspaces

A workspace is the VSCode “open a folder” model brought to a modal editor: open a directory as a workspace — bemtvi --workspace <dir> in the terminal, or the :workspace [dir] command in the GUI — and it becomes a persistent project session. The window/split/dock layout, the open files (with cursor and scroll), and any modified scratch buffers are saved on exit and restored on the next launch — and the directory becomes the working directory, so relative paths, :find, and project plugins resolve against the project root.

It is opt-in: an ordinary bemtvi <dir> does not start a workspace — you ask for one with the flag or command. vim/neovim have :mksession for something adjacent, but it is manual on both ends (you save and load the session yourself) and global. Once a workspace is open, the save-on-exit / restore-on-launch is automatic, per-directory, and carries its own option overrides.

Opening a workspace

--workspace takes the directory as its value (a bare --workspace uses the current directory). The positional TARGET is a separate optional file to open:

bemtvi --workspace ~/code/myproject          # open a directory as a workspace
bemtvi --workspace ~/code/myproject README.md  # …and open a file in it
bemtvi --workspace                           # the current directory

--workspace does three things:

• Derives a per-directory shada namespace from the directory, so each project keeps its own session and history, isolated from every other workspace and from the global store. (An explicit --shada-namespace overrides the derived one.)
• Enables session capture and restore with no plugin opt-in — the layout is saved on exit and replayed on the next launch.
• Changes the working directory to the workspace root (by default; pass --workspace-no-cwd to keep the launch directory). A relative TARGET file then resolves against the workspace root.

The native GUI also exposes a :workspace [dir] command: a bare :workspace reopens the current directory as a workspace, and :workspace <dir> switches the running window to that directory’s session (a relative dir is taken against the editor’s working directory). The GUI registers the command when it starts a session; running it hands the GUI the directory, which builds the new session, as with :connect. An embedding app gets it only with session_switching(true).

What gets restored

A workspace session round-trips, across restarts:

• Tabs — count and order.
• The split layout — the full nesting and proportional sizes of every window.
• One file per window leaf — its path, cursor line/column, and scroll position; the focused window is re-selected.
• Docks — left/right/top/bottom docks, their size and shown/hidden state, and any file-backed content.
• Modified unnamed buffers — a [No Name] buffer with unsaved edits is saved with its contents (under 'workspacepersistunnamed', on by default).

The quickfix and location lists are deliberately not part of the session (they are transient search results, not layout); marks and registers ride the ordinary shada store within the workspace’s namespace.

Keeping the launch directory — --workspace-no-cwd

By default a --workspace launch makes the workspace directory the process working directory: the editor cds into the root at boot, before it opens any file or restores the session, so relative paths and the session’s (relative, portable) buffer paths resolve against the root. Pass --workspace-no-cwd to keep the directory you launched from instead:

bemtvi --workspace ~/code/myproject --workspace-no-cwd

The cd is a launch-time decision (a CLI flag), not a config option — there is no init.lua knob, so the working directory is settled from the first instruction. --workspace-no-cwd has no effect without --workspace.

Per-workspace option overrides — btv.wso

btv.wso is a per-workspace overlay over the global option tier: a value set here takes precedence over the global value for this workspace only, and is persisted with the session. It is the place to pin project-specific settings — a tab width, a colorscheme toggle, search case sensitivity — without touching your global config.

btv.wso.tabstop = 2             -- this project indents with 2
btv.wso.ignorecase = true       -- case-insensitive search here
btv.wso.tabstop = nil           -- clear the override; revert to the global value

Only global options can be workspace-overridden (not window- or buffer-local ones), and the name and value type are validated on write. The resolution order is simply: the btv.wso overlay when present, otherwise the global value (btv.o / :set).

Workspaces and the remote daemon

A workspace pairs with the edit-host split: launch --workspace together with --connect-daemon and the workspace root is resolved from the daemon’s working directory after connect, so you edit a remote project as a first-class workspace with the layout restored locally. (--workspace is a client-side concept and does not combine with running as a daemon.)

Browser editor

bemtvi runs the real editor — entirely in a browser tab, with no server. Not a cut-down demo or a syntax-highlighted textarea: bemtvi-core plus the PUC Lua 5.4 VM plus the production server tick (autocmds, mirrors, the redraw projection — the same keystroke path the native server drives) compile to WebAssembly and run client-side. Your init.lua sources, your keymaps and autocmds fire, files open and save — all in the tab.

Because the editing engine is local, typing has zero round-trips: motions, operators, undo, and Lua all run in the page. Only the filesystem — and processes, in daemon mode — ever crosses a wire, and even the filesystem can be the browser’s own storage. It’s the edit-host split taken to its limit: the local half is a browser tab; the fs/process half is the browser’s storage or a remote daemon.

What runs

• The whole editor — core + the full Lua VM + the server tick, in a Web Worker.
• Your config — init.lua is read from the browser’s storage at boot and sourced through the real path, so options, keymaps, autocmds, user commands, and highlights all apply.
• Files persist — :e / :w open and save real files (see Files), surviving a reload.
• Syntax highlighting — done JS-side via web-tree-sitter. A small set of grammars is bundled for offline use (rust, lua, json, javascript, typescript, python, markdown); :TSInstall <lang> fetches any other prebuilt grammar on demand and caches it. Embedded content highlights too, through each grammar’s injections.scm: markdown’s prose is parsed by the markdown_inline grammar the block grammar injects, and the code inside a ```lang fence by that language’s own.

What’s different from native

Anything unavailable fails loud with a named error rather than faking a result — the same no-silent-stubs rule the rest of bemtvi follows.

Files

The browser is the filesystem, three ways — all riding the same off-tick fs seam the native edit-host split uses, so only the transport differs:

• OPFS (default, serverless). :e / :w persist to the browser’s Origin Private File System, and :e <dir> lists it. Your init.lua and shada live there too, so edits and config survive a reload.
• Real local files. The File System Access API backs :eo / :wo (and a bare :w on a bound path) — pick a real file or directory on disk through the browser’s permission picker.
• A real daemon. Open the page with ?daemon=bemtvi://HOST:PORT/TOKEN?cert=HASH (the string bemtvi --daemon --listen prints), or dial it at runtime with :connect bemtvi://…, and :e / :w operate on the daemon’s filesystem over WebTransport (HTTP/3 / QUIC). Editing still happens entirely in the tab — only fs crosses the wire. Having no local disk, the browser is always remote-config: it runs the daemon’s config + plugins (fetched over the wire), where a native client would default to local. Because a link can name any daemon, a ?daemon= from the page URL connects only after you approve it in a prompt that shows HOST:PORT and the cert hash; the page remembers the approval for that address and cert, and declining keeps the tab local. A daemon session’s shada (registers, history, marks, plugin state) is its own OPFS blob, one per daemon address, so a daemon’s config never sees the local session’s state or another daemon’s. Daemon mode also brings async processes (btv.run / btv.process), :terminal, and LSP over the wire — the daemon’s real language servers, driven from the tab. A dropped WebTransport link auto-reconnects (the tab’s editor is local, so your buffers survive): the Worker re-dials underneath the seams and re-syncs them — re-opening LSP, re-arming watches, and re-statting open files (a change made while disconnected is caught) — exactly like the native clients. btv.daemon.status() reports the link state.

Run it locally

cd crates/bemtvi-edithost
./build.sh                  # cargo → em++ link → dist/eh.{mjs,wasm} + tree-sitter assets
cd web && npm install       # once: Playwright + chromium
node serve.mjs              # a cross-origin-isolated (COOP/COEP) dev server
# open http://localhost:8088/web/

node harness.mjs is a headless Node smoke test (feeds ihello<Esc>, asserts the lines and a real redraw); the verify-*.mjs scripts drive the real wasm editor in a headless browser (renderer, OPFS, the local-file picker, daemon mode, …).

How it works (in brief)

• A Web Worker owns the editor. web/worker.mjs is the single !Send thread holding core + Lua; it loads the wasm module (dist/eh.mjs) and runs the production tick. The UI thread (web/index.html) paints the server redraw frame as HTML/CSS — a per-cell-span DOM renderer (windows, gutter, status/tabline, pmenu, cursor shapes, smooth scroll) — and translates KeyboardEvents to vim key-notation. The two talk over postMessage and a shared ring.
• One wait drives input and timers. When cross-origin isolated, the Worker parks on Atomics.wait over a SharedArrayBuffer input ring, waking on a keystroke or the next timer deadline — so btv.timer / vim.defer_fn fire without Asyncify, one mechanism. (Without isolation it falls back to a postMessage loop where timers don’t fire.)
• Interop is emscripten ccall/cwrap, not wasm-bindgen — it links the C lua54 backend + vim-regex, so the final link is emcc. src/lib.rs exports eh_input / eh_exec_lua / eh_redraw_json / the fs legs / … and the redraw returns as JSON.
• It’s agent-drivable. The page exposes a window.__bemtvi hook (feed / mouse / execLua / lines / frame) so a headless browser (Playwright) can feed keys and assert on state — the same black-box style as the native test harness.
• Built outside the workspace. It targets wasm32-unknown-emscripten and links C via emcc, so it sits in the root Cargo.toml’s [workspace] exclude (a host cargo build --workspace never touches it) and pins its own deps. Deployed as static files (netlify.toml); the one hard requirement is cross-origin isolation.

See also

• The edit-host split — the same split reached natively, with the editor local and an bemtvi --daemon serving fs / processes over ssh or QUIC.
• Architecture → the web build — the crate layout and the full redraw/interop projection.
• The edit-host & browser-Lua plan — the design and its phased implementation.

The edit-host split

Editing on another machine the usual way — running the whole editor over there and a thin client here — means every keystroke round-trips the network before the cursor moves. That lag is structural, not tunable: the editing state machine lives on the far side of the wire.

The edit-host split moves the network boundary below the editor instead. The editor and Lua run locally; only an bemtvi --daemon serving the filesystem, processes, and file-watching runs on the remote. So typing, motions, operators, and undo are all local — zero round-trips — and only fs / process / watch / LSP traffic crosses the wire, the work that was always going to feel like a spinner anyway. It’s the direction VS Code Remote takes: the text model is local, the heavy I/O is remote.

The same bemtvi --daemon serves the Browser editor too — one remote, reached natively here or from a browser tab over WebTransport.

The two halves

editor + Lua  (LOCAL, your machine)  ──network──▶  bemtvi --daemon = fs + processes + watch  (REMOTE)

• The local half is the same embedded editor as a normal bemtvi, with its host seams — HostFs, HostProc, the async HostFsAsync, the LSP transport, and the Lua-facing LuaFs — pointed at the daemon instead of the local disk.
• The remote half is bemtvi --daemon: it reads and writes the remote machine’s files, spawns its processes, and watches its files. Nothing about editing lives there.

Running it

Two transports reach a daemon — ssh (simple) and QUIC (multiplexed, and the same transport the browser uses).

Over ssh (stdio)

Point a local editor at a daemon spawned over ssh:

BEMTVI_DAEMON_CMD="ssh user@host bemtvi --daemon" bemtvi --connect-daemon path/to/file

BEMTVI_DAEMON_CMD is run through sh -c, so any command line ending in bemtvi --daemon over stdio works. Left unset, --connect-daemon spawns this same binary locally (bemtvi --daemon) — a two-process local split, handy for testing.

In the GUI, do it at runtime with :connect [user@]host[:port][/file] — it spawns ssh … bemtvi --daemon and routes any password / passphrase prompt to a native dialog via SSH_ASKPASS, so it works from a windowed launch with no tty.

Over QUIC / WebTransport

Run a standalone listener on the remote — the same wtransport-on-quinn stack the browser dials:

bemtvi --daemon --listen                 # binds 127.0.0.1:8765, prints a connect URI
bemtvi --daemon --listen 0.0.0.0:9000    # accept off-host connections

It prints a connect URI — bemtvi://HOST:PORT/TOKEN?cert=HASH. Dial it from a local editor (the bemtvi://… scheme selects the QUIC path; --connect-daemon is optional):

bemtvi bemtvi://HOST:PORT/TOKEN?cert=HASH path/to/file

In the GUI, :connect bemtvi://… does the same at runtime.

What crosses the wire (and what doesn’t)

Only the things that were always going to feel like a spinner cross the wire.

Local or remote config (and shada)

By default a daemon session runs your local config and keeps shada (marks / registers / history) local — only I/O crosses the wire. Pass --remote-config to run the daemon’s config + plugins instead: the daemon’s config is fetched over the wire (one config_bundle request, materialized into a per-process cache and run locally, since Lua’s synchronous require can’t await the network), and shada follows the same choice — a remote-config session keeps its shada on the daemon, so a remote workspace’s editor state travels with it. The browser client has no local disk, so it is always remote-config. See examples/remote-config.

The split-brain filesystem (for Lua)

One subtlety the split forces: which filesystem does Lua see? bemtvi splits it on purpose. Project-facing fs APIs route to the daemon — the async btv.fs surface (btv.fs.read / btv.fs.readdir / btv.fs.stat / btv.fs.watch / …), root detection, a picker’s previewer, a VCS-status provider — so they see the project on the remote. Config and shada stay local by default, or move to the daemon with --remote-config (see above). (This is the LuaFs seam.)

Plugin management is always local. The btv.plugins manager clones, discovers, and sources plugins on the local disk in every session — even a daemon / --remote-config one — because a plugin loads into the local Lua VM (its dir is added to the local runtimepath and required). So :PluginSync downloads into the local stdpath('data')/plugins, and a dir= plugin is read locally; a git clone runs the local git, never the daemon’s. (A loaded plugin’s own runtime btv.fs / btv.run still route to the daemon — it edits the remote’s files.) This is separate from the pack/*/start plugins a --remote-config session fetches in the config_bundle: those come from the daemon and are materialized into the local cache alongside the config. Either way, plugin code ends up on the local disk where the VM can load it.

Staying connected (auto-reconnect)

Because the editor runs local and only the seams cross the wire, a dropped connection — a laptop sleeping past the QUIC idle timeout, an ssh hop dropping, a network blip — does not tear the session down. The link re-dials underneath the seam handles the editor already holds: your buffers, undo, cursor, windows and Lua state are untouched, and the transport beneath them reconnects. While the link is down, remote ops (save, read, LSP, watch, terminal) fail loud rather than hanging.

• Automatic. A drop is retried a few times with backoff (≈0.5 → 8 s). On success the seams rebind and editing resumes with no action from you. If the budget is spent the link parks disconnected and tells you to run :reconnect.
• :reconnect re-dials now (and resets the retry budget); :disconnect drops the link on demand. Both are server-side ex-commands, so they work on the TUI too.
• Status is a first-class API: btv.daemon.status() returns "connected" / "reconnecting" / "disconnected" (or nil for a local session), and a User DaemonStatusChanged autocmd fires on every change — so a statusline component can render it (green / yellow / red). See examples/daemon-status.
• On reconnect the editor re-syncs what a fresh daemon doesn’t know about: it re-opens LSP servers, re-arms file watches, and re-stats open files — a file changed while the link was down is detected (an unmodified buffer autoreloads; an edited one is flagged as a conflict). Remote terminals/jobs do not survive a drop (the PTYs die with the link) and are surfaced as exited; reopen them with :terminal.

All three transports reconnect — ssh/stdio, QUIC, and the browser’s WebTransport. (Daemon- side session survival — keeping terminals/jobs alive across a drop — is out of scope.)

Auth & identity (QUIC)

A daemon executes arbitrary processes, so an open listener is remote code execution by design — the TLS cert buys encryption, not authorization. Two mechanisms, both minted at --daemon --listen launch and presented by the local half on connect:

• Bearer token — 32 random bytes, carried on the connect URI’s path. The daemon compares it constant-time and drops the session without accepting on a mismatch, so a bad token is a failed connect, never a half-open session.
• Server identity — a self-signed cert whose SHA-256 hash the daemon prints; the client pins that hash on first use (the known-hosts / TOFU model, no CA). The browser passes the same hash to its WebTransport constructor.

The default loopback bind (127.0.0.1) is defense-in-depth — the token is the real gate. Bind 0.0.0.0 only when the token (and, ideally, a trusted network) is doing its job.

How it works (in brief)

• One code path. The local half is the same embedded editor as the default role; the boundary is the same RPC every client speaks. Only its host seams (HostFs / HostProc / HostFsAsync / the LSP transport / LuaFs) are repointed at the daemon — the editing logic is untouched.
• ssh vs. QUIC. ssh stdio carries every leg over one ordered stream — simple, but a process flood (a fuzzy-finder’s rg, an npm install) can head-of-line-block a file save queued behind it. QUIC gives each traffic class its own stream, removing that coupling at the protocol level: the legs ride four independently flow-controlled bidi streams by latency class — Control (fs / config / btv.fs), Proc, Lsp, Term — each prefixed with a one-byte group tag the daemon dispatches on. Because it’s the same wtransport/quinn stack the browser’s WebTransport uses, native and browser unify on one daemon (the browser opens the same four streams). See the multi-stream plan.
• :connect swaps the backend, not the window. In the GUI, :connect builds a fresh local server whose seams point at the daemon and re-attaches the same window. The editor transport is always the in-process duplex, so the window never notices.

See also

• Browser editor — the same daemon reached from a browser tab.
• Architecture → Embedded vs. remote — where this sits in the client–server model.
• The edit-host & browser-Lua plan — the design and its phased implementation.

Embedding bemtvi in an app

A mitsuami app can put a bemtvi editor anywhere in its own layout: a pane beside a sidebar, a tab, a dialog. It’s the whole editor, with its config, its plugins and LSP. The app drives it through a handle, and hears from it through events. bemtvi-gui is itself one of these editors, filling a window.

cargo run -p bemtvi-mitsuami --example embed

runs a small notes app built this way (crates/bemtvi-mitsuami/examples/embed.rs), with examples/embed/init.lua as its editor’s config.

Depending on it

The crates aren’t on crates.io yet: an app takes bemtvi-mitsuami from git, and the mitsuami from crates.io at a version compatible with bemtvi’s (the editor’s view is a mitsuami view, so both must resolve to one mitsuami):

[dependencies]
bemtvi-mitsuami = { git = "https://github.com/bemtvi/bemtvi" }
mitsuami = "2.0.0"

bemtvi-mitsuami is a thin layer: the editor’s client itself, with no toolkit, is bemtvi-gpu (renderer, sessions, the Client a host drives through effects and deadlines), so a host on another toolkit builds on that instead.

The editor in a layout

#![allow(unused)]
fn main() {
use bemtvi_mitsuami::{Config, Editor, EditorEvent, EditorHandle, SessionOptions, Shada};

let editor = EditorHandle::new();
let session = SessionOptions::new()
    .file("notes.md")
    .config(Config::Dir(app_config_dir))      // or Config::User, Config::None
    .shada(Shada::Namespace("myapp".into()))  // or Shada::Global, Shada::Off
    .host("myapp")
    .spawn()?;

Row::new().children((
    sidebar(),
    Editor::new(session, move || tabs.close_current())   // on_exit
        .handle(editor.clone())
        .on_event(move |event| match event {
            EditorEvent::Host { name, payload } => status.set(format!("{name}: {payload}")),
        }),
))
}

• The session comes first. SessionOptions::spawn starts the editor’s server on a thread of its own and fails then, before anything is mounted: a daemon that refused the connection (.connect(target), the edit-host split), or a shada namespace that isn’t a safe name.
• on_exit is required. It’s what the app does when the editor quits (:q of the last window, or its server went away), so a quit editor never sits there showing its last frame.
• It takes the space left over. The editor’s surface has no size of its own: it grows into what its row or column has left, stretched across the other way.

Its config and shada

Config::User runs the user’s own config, as bemtvi does: right for a tool whose users already run bemtvi. Config::Dir runs the app’s own directory (its init.lua, and plugins under its pack/*/start/). Config::None runs no config at all. The directory and no-config cases leave out the user’s system-plugin tier too.

Shada::Global shares marks, registers and history with the user’s other bemtvi instances. Shada::Namespace keeps a store of its own under the shada directory. Shada::Off persists nothing.

By default the editor stays on the session the app gave it: :workspace isn’t a command, and :connect or a plugin’s btv.session.reconnect is refused with a message saying why. SessionOptions::session_switching(true) allows them, as bemtvi-gui does.

Taking things away

An app can take from the editor what makes no sense for how it’s used.

• Commands. SessionOptions::disable_commands(["lua", "terminal"]) disables commands by any spelling (e is :edit). A disabled command fails with E5800: :lua is disabled in this editor wherever it’s run from: typed, from a mapping, from a plugin’s btv.cmd, an autocmd, under :silent or :tab. As an error it also stops the rest of a | chain. Completion leaves it out, and Lua can ask btv.command_disabled(name). A user command can be disabled by its name too.
• User commands from elsewhere. user_commands_from_startup_only(true) takes user commands only from the editor’s config and the plugins loaded with it. Once startup ends (PluginsLoaded), a command defined by any other code fails with E5802, naming where that code is: a plugin loaded later, typed :lua, a file :sourced from elsewhere. What counts is the file the defining code is in, not when it runs, so a startup plugin that defines a command later, from an autocmd say, still may. So may the app’s own exec_lua. :command defines none after startup: it runs deferred, and the code that asked for it is gone. This is a policy, not a sandbox: Lua can name its code what it likes, and plugins are trusted code.
• Other files. lock_to_file(true) locks the editor to its file. Opening, switching to or writing any other file fails with E5801: this editor only edits <file>, and so does a new file buffer. That holds whatever asks: :e, :sp, :tabedit, :enew, :b, <C-^>, btv.open, the picker, an LSP or quickfix jump, :w other, :bd of the file itself. Views, panels, floats, quickfix lists and terminals work as ever, and so do :e!, :w and :sp of the file itself.
• The plugin manager. disable_plugin_manager() makes every btv.plugins call fail with E5805, so the config declares, loads, installs and updates nothing through it, and its :Plugin* commands are disabled. Plugins under the config’s pack/*/start/ still load. A config can ask btv.plugins.disabled().
• LSP. disable_lsp() means no language server starts. btv.lsp.enable, start and restart fail with E5804, and the :Lsp* commands are disabled. A config meant to run both ways checks btv.lsp.disabled() first.
• Pickers. disable_pickers(["files", "live_grep"]) takes pickers away by source name. btv.picker.open fails with E5803 for one, and the commands and pickers lists leave it out. A config can ask btv.picker.disabled(name).

An editor for one file

SessionOptions::single_file(path) is all of it, for an app that embeds the editor to edit one given file:

• it locks to the file and takes user commands only from startup;
• it turns the plugin manager and LSP off;
• it takes away the pickers in SINGLE_FILE_DISABLED_PICKERS (buffers, diagnostics, files, live_grep);
• it disables SINGLE_FILE_DISABLED_COMMANDS. That is what runs code or processes (:lua, :=, :source, :command, the autocmd family :autocmd / :augroup / :doautocmd, :terminal, :make, :grep, :TSInstall), changes directory or session (:cd, :connect, :workspace, :rshada), or reads other files into a list (:vimgrep, :cfile).

.enable_commands([...]) gives commands back.

SessionOptions::views_only() is all of that with no file, for an app whose editor only shows what its plugins put in views, a diff say. Opening or writing any file fails with E5801: this editor edits no files. A plugin mounts its view with view:mount({ here = true }), so it’s the editor’s one window and :q quits.

cargo run -p bemtvi-mitsuami --example single_file [file]

runs one, with examples/single-file/init.lua as its config.

Talking to the app

The app names itself with SessionOptions::host. Inside the editor that’s btv.host (its page is under the API reference):

if btv.host.name() then                 -- nil when no app embeds the editor
  btv.host.forward({ "changed", "wrote" })
  btv.keymap.set("n", "<leader>p", function()
    btv.host.send("preview", { file = btv.buf.name(0) })
  end)
end

btv.host.send(name, payload) reaches the app as EditorEvent::Host { name, payload }. btv.host.forward sends changed (a buffer’s name and modified state, once typing pauses) and wrote messages. Neither sends the buffer’s text: the app asks for what it needs. The app’s on_event handler runs on the UI thread with the editor free, so it can drive the editor straight back.

The other way, EditorHandle has command (an ex command, whatever the mode), exec_lua (a future of what the chunk returns), exec_lua_with (the same, with arguments as the chunk’s ..., so the app’s values needn’t be quoted into its source), open(path), focus(), request_quit() (:qa, which refuses while a buffer is unsaved, as a window’s close button wants) and quit_now() (:qall!).

An app can build the Editor anywhere on the UI thread, not only in a view: a C ABI’s call has no current mitsuami Ui, and it uses the one it’s built in.

Its lifetime

The editor’s threads start as it’s mounted and are told to stop as it’s unmounted: a Show switching it out, a closed tab. Mounting it again starts a new one. The handle goes on whichever is mounted, one at a time.

EditorHandle::close() waits for the threads to end and says whether a server panicked. An app calls it before its process ends, so the editor’s exit sequence (its shada, plugins’ VimLeave) lands.

Every editor in the process shares one GPU device, which is never dropped (wgpu’s EGL teardown crashes on Wayland with Mesa otherwise); each editor’s own surface and glyph caches go with it.

Keys and focus

The window’s shortcuts get a key first: a menu item’s shortcut is the app’s, and the editor never sees that chord. A mapping on it in the editor never fires. Everything else goes to the editor while it has focus, Tab included. Control+Tab moves focus on, so a <C-Tab> mapping never fires in any mitsuami app, bemtvi-gui included.

A modeless caret shows and blinks only while the editor has the focus, as a text field’s does, so an app with several editors shows one caret. Vim’s and Helix’s block cursors are an outline without it, with the glyph in its own colour; Insert’s bar and Replace’s underline stay as they are. It’s the same while the editor’s window isn’t the active one, though the editor keeps its focus.

The editor’s surface is a native child surface on GTK, Kirigami and Windows, drawn above the window’s own content. Nothing the app draws inside the window can overlap it, so popovers and menus over it have to be the platform’s own popup windows, as GTK’s popovers and Kirigami’s windowed lists are.

Versions

mitsuami’s types are part of the API (Editor is a mitsuami View), so the app has to build against the same mitsuami bemtvi does. For now that’s a GitHub revision, pinned in bemtvi’s root Cargo.toml.

Plugin Development

A plugin is pure Lua over the btv.* API — a lua/<name>/init.lua module that exposes setup(opts) and wires keymaps, commands, autocmds, and UI through btv.*. The server owns the UI surfaces; the plugin supplies data and behavior.

Install one by declaring it with the built-in manager and running :PluginSync:

btv.plugins({
  { "bemtvi/bemtvi-keys-helper",
    config = function() require("bemtvi-keys-helper").setup({}) end },
})

Where to go next

• Writing plugins — the full authoring guide: anatomy, loading, the btv.* surfaces you’ll use, a worked example, and testing.
• btv.* API Reference — every public function in the btv.* namespace, generated from the prelude source.
• bemtvi-plugin-skills — agent skills that teach a coding agent the btv.* model, one skill per surface. The model is not in any agent’s training data, so without them an agent writes neovim plugins that do not run here.

First-party plugins

The surest way to learn the btv.* API is to read code that already ships on it. bemtvi is its own plugin API’s first and most demanding consumer: its first-party plugins use the same public btv.* surface a third party would, with no privileged access. That makes them honest reference implementations — if a behavior can be built in one of these, it can be built in yours.

They live in their own repositories under github.com/bemtvi and are each installable with the built-in manager:

btv.plugins({
  { "bemtvi/bemtvi-lspconfig",
    config = function() require("bemtvi-lspconfig").setup({}) end },
})

The catalogue

Each is paired below with the neovim plugin it echoes and the btv.* surfaces worth studying it for.

Every one ships its own integration-test suite (most run a real server over the black-box harness, exactly as Testing plugins describes) — those tests double as worked, runnable usage examples for the surfaces above.

Bundled in the editor

A plugin that ships inside bemtvi and loads by default — also pure btv.*, and browsable in this repository under crates/bemtvi-lua/src/prelude/:

• plugins.lua + plugins_ui.lua — the btv.plugins package manager and its dashboard: declarative specs, async git over btv.process, lazy-loading on command/event/filetype/keys, and a full floating UI.

See also

• Recommended plugins — the same plugins from the user’s side: what bemtvi offers on first run, what each gives you, and how to pick a subset.
• Writing plugins — the authoring guide these implement.
• Testing plugins — how their test suites are structured.
• The btv.* model — the five rules they all obey; the btv.* API Reference chapter lists every surface named above.

The btv.* model

bemtvi has its own, purpose-built plugin system. Every editor API lives in the btv.* namespace (config and plugins alike), with a small set of familiar vim.* names aliased to btv.* for convenience. This page explains the model that shapes the whole API; Writing plugins is the hands-on how-to, and the btv.* API Reference chapter lists every function.

The model in one sentence:

The server owns every UI surface and the frame; plugins are async, declarative providers of data and behavior.

Where neovim hands you buffer primitives and redraw hooks and says “draw your own completion menu,” bemtvi hands you a completion engine and says “give it items.”

Compared to neovim’s plugin model

neovim’s plugin model fits neovim’s architecture. A plugin there is an imperative program written against the editor’s runtime — synchronous, re-entrant editor access; blocking reads (getcharstr, vim.wait pumping the loop); libuv as a public API (vim.uv timers / processes); frame-time render hooks (decoration providers running Lua inside redraw); and the open-ended vim.fn inventory. The plugins that define that ecosystem’s UX — completion menus, fuzzy pickers, statuslines, popups, tree sidebars — own frame time and input loops, and neovim’s single-process, synchronous core is built to let them.

bemtvi’s architecture is different (see Architecture), so its plugin model is too. bemtvi-core is pure and synchronous, Lua influences the editor only through snapshot reads + queued effects drained at a settle point, and a client-server boundary puts the server in charge of the frame and every UI surface. Those properties — a pure core, a frame no script can stall, identical behavior across every front end including the serverless WebAssembly build — are the point of the design, and they call for plugins that are async, declarative providers rather than imperative programs. Same goal (rich, scriptable UX); a model shaped by a different runtime.

The five rules

The model is five rules — each one a property the architecture already enforces internally; the API just makes it the documented contract:

1. Reads are snapshots. btv.buf.lines(b) and friends read the state pushed at Lua entry. Documented, not disguised as live access.
2. Writes are queued effects. Applied at the settle point, not instantly. The buffer mutations (btv.buf.set_lines / btv.buf.set_text) validate loud up front, queue the edit, and return a promise that fulfils once it has landed.
3. Nothing blocks, ever. No wait-pumps, no blocking reads, no uv handles. Anything that waits returns a promise you btv.await inside btv.async, or — for streaming — an async-iterator (btv.run_stream + btv.await_each). See Async & promises.
4. No frame-time Lua. Plugins publish decorations / segments / items whenever they like; the server folds them into the next frame. A plugin cannot make redraw slow.
5. Registrations are data. A provider registers with a name + schema and is called with a context carrying a generation token; it emits through the context’s sink (ctx.push) and signals completion by returning. Stale async responses are dropped by the engine.

Because Lua influences the editor through the same queues RPC clients use, every btv.* registration has an RPC twin in principle — out-of-process providers, in any language, are the same surface (later). The in-process Lua host is v1.

Providers, not programs

The inversion rule 5 implies: the server owns the engine, and a plugin is a thin source / segment / provider plugged into it. This is what keeps plugins small and the frame safe — the hot path (rendering, navigation, matching, input grab) lives in Rust, written once, and the plugin only supplies data.

The same applies to the UI itself. In neovim, plugin UIs are bespoke — a file tree, a popup, a dashboard is each hand-built from buffer and window primitives, so every plugin reinvents rendering, navigation, and input handling. bemtvi ships those as first-class APIs: btv.view (dockable content surfaces), floating windows, the btv.ui widgets, and the reactive btv.component — so a plugin describes a UI instead of drawing one.

vim.* aliases

The editor API is btv.*. For convenience, a small set of familiar vim.* names are provided as thin aliases over their btv.* equivalents, so common config reads in muscle-memory spellings — vim.g.mapleader, vim.o.number = true, a vim.keymap.set block, an nvim_create_autocmd block, vim.cmd.colorscheme — without learning a new vocabulary first. They’re aliases, not a second API: the same objects, with btv semantics (snapshot reads, queued effects, settle-point callbacks).

The aliased names (ADR 0002 has the canonical list):

• Variables / options / env — vim.g / vim.b / vim.w, vim.o / vim.opt / vim.opt_local / vim.bo / vim.wo, vim.env.
• Dispatch & keymaps — vim.cmd, vim.keymap.set / del.
• Pure helpers — vim.tbl_*, vim.split, vim.trim, vim.startswith / endswith, vim.list_extend, vim.deepcopy, vim.inspect, vim.json.
• Declarative registrations — a partial vim.api of nvim_create_autocmd / augroup / del / clear (→ btv.on), nvim_create_user_command (→ btv.command), and nvim_set_hl (→ btv.hl.define).
• Callback-shaped async — vim.notify, vim.schedule, vim.defer_fn, and vim.ui.input / select (process spawning is btv.run / btv.run_stream — there is no vim.system).
• Treesitter foldexpr — vim.treesitter.foldexpr, neovim’s spelling of the native 'foldexpr' marker (btv.treesitter.foldexpr). Highlighting itself is declarative buffer state — the btv.bo.filetype / btv.bo.ts_highlight nouns — not a function call.

The list is intentionally small — these convenience spellings, and nothing more; everything else (LSP, treesitter, processes, the filesystem, …) is btv.*.

Colorschemes are data, not plugins

A colorscheme is pure data — a table of highlight-group definitions, registered through the btv highlight API (the nvim_set_hl alias above). It never touches the runtime model, so it crosses the snapshot/effect boundary intact: sourcing one is just running Lua that fills the highlight registry. It uses the same vim.* aliases as any other config — there’s no plugin host and no special case.

Dogfooding the btv.* API

The split: the core provides primitives — the engines and UI surfaces, in Rust: completion, the picker (a float-list widget), statusline, snippets, btv.view / btv.dock / floats, btv.decor, plus the tree-sitter / LSP / regex engines — and the more complex UI behavior is implemented as plugins in Lua, composing those primitives. A file explorer, a which-key popup, statusline extras, a completion or picker source: each is a plugin, not bespoke Rust.

bemtvi is the plugin API’s first and most demanding consumer — its first-party plugins use the same public btv.* API a third party would, with no privileged access. That keeps the API honest: a feature that can’t be expressed against btv.* is a gap to close in it.

See also

• Writing plugins — the hands-on authoring guide.
• Async & promises — rule 3 in practice (btv.promise / async/await).
• ADR 0002 — native plugin system — the decision record and the canonical list of vim.* aliases.
• The native plugin API design sketch — the full surface, the five rules, and six worked examples.

Writing bemtvi plugins

A plugin is pure Lua over the btv.* API — no Rust, no Vimscript. The server owns every UI surface (windows, floats, the completion menu, the statusline); a plugin supplies data and behavior and reaches the screen through btv.*. Our prime directive is every feature that can be a plugin is one, so we exercise our own APIs.

If you’ve written a neovim plugin, the shape is familiar — a lua/<name>/init.lua module exposing setup(opts) — but the API you call is btv.*, not vim.*. (A closed whitelist of vim.* muscle-memory aliases exists for config ergonomics; new plugin code should target btv.* directly.)

Writing plugins with a coding agent

The btv.* model is not in any agent’s training data — left to itself, an agent writes neovim plugins that fail on bemtvi (vim.uv, blocking vim.wait, a nvim_buf_set_lines that does not exist). bemtvi-plugin-skills is a set of agent skills that teach it the real model, the surfaces below, and the traps; it also bundles a generated snapshot of the btv.* API reference and every public btv.*/vim.* name in a live editor.

npx skills add https://github.com/bemtvi/bemtvi-plugin-skills   # any agent

Claude Code can install it as a plugin instead:

/plugin marketplace add bemtvi/bemtvi-plugin-skills
/plugin install bemtvi-plugin-skills

One skill per surface — scaffolding, async, keymaps/commands/events, buffers/windows, UI and components, views and docks, decorations, picker, completion, statusline, LSP and diagnostics, fs/process/net, testing, vimdoc, and porting from neovim — with the bemtvi skill routing to the right one.

Anatomy of a plugin

A plugin is a directory laid out the way neovim plugins are, so it resolves on the runtimepath:

my-plugin/
├── lua/
│   └── my-plugin/
│       └── init.lua        # the module: returns { setup = … }
├── plugin/                 # optional: *.lua here is auto-sourced at load
│   └── my-plugin.lua
├── after/plugin/           # optional: sourced after plugin/
├── colors/                 # optional: colors/<name>.lua for a colorscheme
└── test/                   # optional: *_spec.lua (see Testing)
    └── my-plugin_spec.lua

The conventional entry point is a module that exposes setup:

-- lua/my-plugin/init.lua
local M = {}

function M.setup(opts)
  opts = opts or {}
  btv.keymap.set("n", "<leader>x", function()
    btv.notify("hello from my-plugin", "info")
  end, { desc = "my-plugin: do the thing" })
end

return M

setup should be idempotent (a user may call it more than once) and side-effect light at module load — do the wiring in setup, not at require time, so load order and lazy-loading stay predictable.

Installing & loading

Two paths, both runtimepath-based:

The built-in manager (btv.plugins). Declare plugins in init.lua; the manager clones, runtimepaths, and loads them (with optional lazy triggers):

btv.plugins({
  -- eager:
  { "bemtvi/bemtvi-keys-helper",
    config = function() require("bemtvi-keys-helper").setup({}) end },

  -- lazy by key / command / event / filetype:
  { "owner/repo", keys = { "<leader>ff" }, cmd = "Find",
    config = function() require("repo").setup({}) end },

  -- pinned, or a local checkout for development:
  { "owner/repo", tag = "v1.0.0" },
  { name = "my-plugin", dir = "/path/to/my-plugin",
    config = function() require("my-plugin").setup({}) end },
})

Then :PluginSync (realize the declared + locked state), :PluginInstall, :PluginUpdate (fast-forward, advancing past the lockfile), :PluginRestore (check out the locked commits), :PluginLock, :PluginClean, :PluginList, or the :Plugins dashboard. Cloned plugins live under stdpath("data")/plugins/<name>.

Each of those verbs takes an optional plugin list — :PluginUpdate my-plugin, <Tab>-completed — and then touches only those plugins (and their dependencies), leaving every other checkout and lockfile entry alone; in the dashboard the lower-case keys (i u s r x) do the same for the row under the cursor. When you are developing one plugin, that is the verb you want: re-cloning or updating the whole set to test one change is how a working editor turns into a bisect.

Every install/update records each plugin’s resolved commit in <config>/bemtvi-lock.json, and installing reproduces those commits — so a config plus its lockfile pins the exact plugin tree. :PluginSync therefore does not move a plugin the lockfile pins; advancing past it is :PluginUpdate’s job, and :PluginRestore goes back. See Configuration → the lockfile for the full rules. A spec with cmd/event/ft/keys (or lazy = true) loads on first use; config runs after the plugin is on the runtimepath, init runs at startup regardless. Restoring a workspace session counts as first use too: a persisted btv.view slot names its owner, so a lazy plugin whose sidebar was open when you quit is loaded by the restore itself — no trigger to press, nothing extra to declare.

Git submodules are initialised by default — the manager clones with --recurse-submodules and runs git submodule update --init --recursive on update, so a plugin that vendors its dependencies as submodules lands complete. Set submodules = false on a spec to opt a plugin out (skips the extra git work for one you know has none).

By hand. Drop the plugin under <config>/pack/*/start/* and require it from init.lua — the runtimepath picks it up with no manager involved.

The btv.* surfaces you’ll use

A plugin composes these (each has runnable examples under examples/ and a deeper treatment in the API design):

• Keymaps — btv.keymap.set(mode, lhs, rhs, opts) / btv.keymap.del; introspect with btv.keymap.get. Always pass a desc — it surfaces in completion and which-key.
• User commands — btv.command(name, fn, { desc = …, usage = …, complete = … }); fn receives { args, fargs, bang, … }. usage is the argument signature in vim help notation (usage = "[file]", "{name}") — it heads the command’s :-completion docs pane as :Name <usage>, exactly like a built-in. complete ("file" / "dir" / a fn(args)) drives <Tab> completion of the argument.
• Autocmds / events — btv.on(event, { pattern = … }, fn) for editor lifecycle events (BufReadPost, FileType, …), or btv.on(event, fn) with no options.
• Options & vars — read/write btv.o (global), btv.bo (buffer), btv.wo (window), and btv.g (globals). Edge docks have their own scope too: btv.dock.opt(side) (e.g. btv.dock.opt("left").size = 32), alongside btv.bo/btv.wo — per-dock showtabline, laststatus, size, title, winhighlight, and autohide.
• Highlights — btv.hl.define(ns, name, spec), btv.hl.get, btv.hl.exists. Define your groups as fallbacks (btv.hl.exists guard) so a colorscheme that already styles them wins.
• Messages — btv.notify(msg, level).
• Async — the editor is single-threaded and tick-based, so anything that waits is promise-based: btv.async/btv.await, btv.promise, btv.run/btv.run_stream (subprocesses), btv.fs (filesystem), btv.timer, btv.utils.debounce, and the scheduling primitives btv.schedule (end of the current tick) / btv.on_next_tick / btv.wait_for(pred, opts) (across ticks). Reach for on_next_tick/wait_for — never a btv.schedule re-arm — when waiting on state that only refreshes between ticks (e.g. a freshly-mounted window id). Full guide: Async & promises.
• UI — the floating-widget layer btv.ui.input/select/confirm/float (promise-based, never steals focus for float), and btv.component (reactive state + a pure render + lifecycle) for live popups. Bigger server-owned surfaces: btv.picker (fuzzy finder), btv.complete (completion sources), btv.snippet, btv.statusline (composable segments), btv.decor (viewport decorations / extmarks), btv.dock (edge docks), and btv.view (a read-only mountable content surface — what a plugin ui is built on).

When something genuinely useful is missing, the convention is to add it to btv.* for everyone, so let us know if you find anything missing.

A worked example

bemtvi-keys-helper — the first-party which-key — is a compact, real-world plugin: it subscribes to the pending-key oracle (btv.on_key_pending), debounces with btv.utils.debounce, and renders the continuations on a non-focus btv.component{ surface = "float" }. It is packaged exactly as above (lua/bemtvi-keys-helper/init.lua with setup/add) and carries its own test suite.

The examples/ directory has ~85 self-contained configs — one per feature — that double as plugin-authoring references.

Testing

Plugins are pure Lua, so their tests are too. bemtvi ships a native test framework (btv.test) and a headless runner — write test/*_spec.lua, then:

bemtvi --test-plugin .

The suite drives a real editor (feed keys, assert on buffer / cursor / UI) and exits 0/1 for CI. See the full guide: Testing plugins.

See also

• bemtvi-plugin-skills — agent skills for authoring plugins, one per btv.* surface.
• Native plugin API design — the model and six worked API examples.
• ADR 0002 — native plugin system — why btv.*, and the exact vim.* alias whitelist.
• Testing bemtvi plugins — btv.test + bemtvi --test-plugin.
• Architecture — the crate layout, tick model, and Lua bridge.

Async & promises

The editor is single-threaded and tick-based: all Lua runs on the editor’s own loop, and nothing may block it — a blocking read would freeze every keystroke, every repaint, every client. So bemtvi has no blocking I/O at all. Instead it gives plugins a browser-shaped async runtime: Promises/A+ (btv.promise) plus async/await sugar (btv.async / btv.await), layered over the editor’s event loop. If you’ve written fetch(...).then(...) or await fetch(...) in JavaScript, you already know this API.

One rule shapes the whole surface (ADR 0002):

btv async is promise-only. Every “do a thing, get a result later” API returns a promise — never takes a callback. Streaming is an async-iterator over promises. (The vim.* muscle-memory aliases keep neovim’s callback shapes; new btv code uses promises.)

So btv.run, btv.fs.read, btv.ui.input, btv.lsp.hover — anything that waits — hands you a promise you :next() / await.

Promises

A promise is a value that arrives later. btv.promise.new(executor) is the browser constructor — executor(resolve, reject) runs now, and you call resolve (or reject) when the result is ready:

local function after(ms)
  return btv.promise.new(function(resolve)
    btv.timer(function() resolve("done") end, ms)   -- settle later, off the tick
  end)
end

after(500)
  :next(function(v) btv.notify(v) end)     -- "done", ~500ms later
  :catch(function(e) btv.notify("failed: " .. tostring(e), "warn") end)

The three chaining methods are the browser’s, with one spelling change:

Ready-made promises: btv.promise.resolve(v) (already fulfilled), btv.promise.reject(e) (already rejected), and btv.promise.try(fn, ...) — run fn inside a promise so a synchronous throw becomes a rejection and a returned promise is adopted, folding “might fail either way” into one chain.

Two semantics worth knowing:

• Reactions are always asynchronous. A :next callback runs as a microtask (deferred to the end of the current tick via btv.schedule), never inline — even on an already-settled promise. Same as the browser running .then off the stack.
• Unhandled rejections are reported, not swallowed. A promise that rejects with nothing subscribed surfaces a loud bemtvi: unhandled promise rejection: … (CLAUDE.md: no silent failures). Attach a :catch — or handle it via await.

async / await

Chains are fine for one step, but nest badly. btv.async + btv.await flatten them into straight-line code — the same trade the JS async/await keywords make.

btv.async(fn) returns a function that, when called, runs fn as a coroutine and returns a promise for its result. Inside, btv.await(p) suspends until p settles and evaluates to its value (or re-raises its rejection as a Lua error):

local load_config = btv.async(function(path)
  local exists = btv.await(btv.fs.exists(path))
  if not exists then return {} end
  local text = btv.await(btv.fs.read_text(path))
  return parse(text)                       -- becomes the promise's fulfilment
end)

load_config("init.lua")
  :next(use_config)
  :catch(function(e) btv.notify("config load failed: " .. tostring(e), "warn") end)

Error handling works either way: a rejected await raises inside the coroutine, so you can pcall it to handle locally (PUC 5.4 yields across a pcall), or let it propagate to the coroutine edge — the returned promise rejects, caught by :catch on the result.

btv.await must be called inside an btv.async function (there’s nothing to suspend otherwise — it errors loudly). It’s also what setup / render run inside on an btv.component, so you can btv.await(...) straight inside those too.

The async APIs you get

Everything that waits is one of these promise-shaped surfaces — all awaitable, all non-blocking:

btv.run resolves rather than rejects on a non-zero exit — the exit code is part of the value, so you decide what counts as failure:

btv.async(function()
  local r = btv.await(btv.run({ cmd = "git", args = { "rev-parse", "HEAD" } }))
  if r.code == 0 then btv.notify("HEAD is " .. r.stdout:gsub("%s+$", "")) end
end)()                                       -- note the trailing () — call it to run

Streaming

For output you want as it arrives (not after the process exits), btv.run_stream returns a Stream you iterate with btv.await_each. Each step awaits the next batch of lines; the loop ends when the stream is exhausted. :kill() reaps the child early. This is how the picker’s files / live_grep sources stream rg:

btv.async(function()
  local stream = btv.run_stream({ cmd = "rg", args = { "--files" } })
  for batch in btv.await_each(stream) do
    for _, line in ipairs(batch) do
      -- … push each result as it streams in …
    end
  end
end)()

The contract is sequential: at most one outstanding :next() at a time — which is exactly what the for loop does. Batches arriving between steps buffer internally.

Combinators

The browser’s, on btv.promise — for fanning out concurrent work:

btv.async(function()
  -- read three files concurrently, wait for all
  local texts = btv.await(btv.promise.all({
    btv.fs.read_text("a.lua"),
    btv.fs.read_text("b.lua"),
    btv.fs.read_text("c.lua"),
  }))
  btv.notify(("read %d files"):format(#texts))
end)()

Scheduling: schedule, on_next_tick, timer

These run a function later but aren’t one-shot results, so they stay callback-shaped (a promise models one eventual value — the wrong shape for a microtask or a repeating timer). Reach for the right one:

The cross-tick gotcha. btv.schedule runs within the same convergence, so it cannot observe anything that only refreshes between server ticks — a freshly-mounted window’s id, a server-repopulated mirror. Re-arming btv.schedule(self) to “wait” for such a value spins forever. For anything cross-tick use btv.on_next_tick or btv.wait_for — the latter is the await-able form:

btv.async(function()
  local v = btv.view.create({}); v:mount({ float = { width = 40, height = 8 } })
  local win = btv.await(btv.wait_for(function() return v:winid() end))  -- settles when the winid exists
  vim.wo[win].number = false
end)()

btv.wait_for(pred, { tries = 200, interval = nil, message = … }) checks once immediately, then once per tick, and rejects (so an await fails loud) if the condition never holds within tries.

Helpers

• btv.utils.debounce(fn, ms) — coalesce a burst of calls into one trailing invocation ms after the last (which-key’s show-delay, on-change/resize/scroll reactions). Callback-shaped, not a promise — a different job — but they compose: pass an btv.async function as fn to kick await-able work after the quiet period.
• btv.promise.wrap(fn) — lift a single-callback async function into a promise-returning one (it appends a resolver as the last argument). The bridge for a vim.*-style callback API into the promise world.
• btv.schedule_wrap(fn) — a function that, when called, defers fn to the end of the tick — the btv.schedule analogue of a wrapped callback.

Try it

BEMTVI_CONFIG=examples/async-runtime cargo run -p bemtvi -- examples/async-runtime/sample.txt

How it works (in brief)

btv.promise is pure Lua layered on the editor’s existing async runtime: a promise’s reactions run as microtasks via btv.schedule, exactly the way the browser runs .then callbacks off the current stack, so :next is always asynchronous and the ordering matches Promises/A+. btv.async drives a coroutine one resume at a time — each btv.await yields the awaited promise, and the runner re-enters the coroutine with the value (or re-raises the reason) once it settles.

Under the hood a background actor owns timers and process I/O and wakes the editor loop when something completes, so deferred work and subprocesses run off the input tick without ever stalling the editor. The transports stay native (btv._system_async / btv._spawn_stream for process, the btv._fs_* bridge for files, the daemon on wasm); only the shape is promises.

See also

• Writing bemtvi plugins — where this fits in a plugin.
• UI primitives — btv.component’s setup/render are btv.async contexts; widgets return promises.
• ADR 0002 — native plugin system — why promise-only, and the vim.* alias whitelist.

Testing plugins

bemtvi plugins are pure Lua over the btv.* API (ADR 0002), so their tests are too. A plugin repo carries a test/*_spec.lua suite that drives a real editor — feeds vim keys, then asserts on the resulting buffer, cursor, or UI — run headlessly by bemtvi --test-plugin. No mocks, no stubs: the same end-to-end philosophy as bemtvi’s own Rust black-box harness (crates/bemtvi-test-harness), reachable from your plugin’s own repo and CI.

The framework is btv.test — describe / it / expect with a small async context — shaped like a familiar BDD test runner (busted / Jest), so a spec reads the way you’d expect.

Quick start

Put specs under test/ in your plugin repo (each file must end _spec.lua):

-- test/my_plugin_spec.lua
btv.test.describe("my-plugin", function()
  btv.test.before_each(function()
    require("my-plugin").setup({})
  end)

  btv.test.it("inserts text", function(t)
    t:feed("itext<Esc>")                          -- type in insert mode, then escape
    btv.test.expect(t:lines()).to_equal({ "text" })
    btv.test.expect(t:mode()).to_be("n")
  end)
end)

Run it — defaults to the current directory:

bemtvi --test-plugin                 # runs ./test/**/*_spec.lua
bemtvi --test-plugin path/to/plugin  # or an explicit plugin dir

The runner boots an embedded editor with your plugin on the runtimepath (so require("<your-plugin>") resolves), runs every spec, prints a report, and exits 0 (all pass) / 1 (any fail) — drop it straight into CI.

The hermetic slate

Each plugin runs in isolation: no user init.lua, an in-memory clipboard, no persistence (shada), and your plugin as the sole runtimepath entry. A test exercises your plugin against a clean editor and nothing else.

Isolation also holds between tests. One editor serves the whole run, so the runner takes a baseline snapshot of the world once — after every spec file has been sourced — and restores it before each test. That timing is the contract:

• A file’s load-time setup is the baseline. A require("my-plugin").setup{} or a dofile at the top of a spec file runs before the snapshot, so it is the state every test in the run starts from, and no test can undo it.
• What a test changes is put back. Restored: global and window-local options, btv.g, the named registers, every sandbox expression surface (btv.fold.text, btv.indent.expr, btv.filetype.detect, btv.picker.scorer, btv.complete.scorer, btv.decor.expr, btv.qf.text, btv.qf.parse), the quickfix list, and any keymap, user command or btv.decor provider a test added. The buffer goes back to a fresh empty one in normal mode.

Some things are not restored, because a snapshot has no way to rebuild them: a keymap, user command or decor provider a test deleted, autocmds, the window layout, and buffers beyond the one the reset replaces. For those, clear down yourself — a before_each that puts the state you depend on into a known shape is more reliable than an after_each that tidies up, because a test that fails part-way never reaches its after_each:

btv.test.describe("my plugin", function()
  btv.test.before_each(function()
    btv.cmd("silent! only")        -- one window, whatever the last test opened
    btv.augroup.create("MyPluginTest", { clear = true })  -- and no stale autocmds
  end)
end)

The one thing restore cannot reach: your module’s own state

Restore puts the editor back. It cannot see the locals inside your plugin, and that asymmetry has a sharp edge — a module that memoizes “I already registered my command” will go stale:

-- WRONG. Test 1 registers the command and flips the memo. Restore then removes
-- the command (a test added it), but `state.commands` is still true, so every
-- later `setup` early-returns and `:MyPlugin` no longer exists.
local function register_commands()
  if state.commands then return end
  state.commands = true
  btv.command("MyPlugin", run, opts)
end

btv.user_command.create and btv.keymap.set key their registries by name, so re-registering is already idempotent — the memo buys nothing and only encodes an assumption about global state your module does not own. Drop it and register unconditionally. The same applies to any “did I do this once” flag guarding something the editor holds; keep such flags for state your module genuinely owns (a spawned process, a cache).

The tick model — why the context is async

The editor is tick-based: fed keys settle at the end of a tick, and the Lua state mirrors refresh before each Lua entry. So a single synchronous chunk that feeds then reads would see stale state (the Rust harness uses a fresh RPC round-trip per assertion for exactly this reason).

btv.test handles it for you: every it body runs inside an btv.async coroutine, and the context’s driving methods await internally. t:feed(...) queues the keys and awaits one tick, so by the next line the keys have drained and the reads are current. You write straight-line code; the awaits are under the hood.

Deterministic (synchronous) input settles in one tick. Asynchronous effects — a debounced popup, a timer, a file watch — won’t be ready on the next line; await them with t:wait_for(predicate):

btv.test.it("shows a debounced popup", function(t)
  t:feed("<Space>")
  local float = t:wait_for(function() return t:float() end)
  btv.test.expect(float.text).to_contain("write")
end)

API

Structure

Assertions — btv.test.expect(value)

Matchers are called with a dot; prefix any with .never to invert (btv.test.expect(x).never.to_equal(y)):

The context t

Driving methods are async — they settle before returning:

Read methods are plain (correct after an await):

t:highlights() and t:decor() are the views that can see a decoration — a btv.decor provider’s mark, a btv.decor.expr paint, a treesitter capture, an LSP inlay hint — which changes neither the buffer text nor the glyphs drawn. The split between them is what each layer is: t:highlights() colours the buffer’s own cells and names the group it painted; t:decor() reads the glyphs that are not in the buffer at all ({ virt_text, virt_pos, virt_col, virt_lines, sign }). Groups are absent from t:decor() on purpose — the wire carries a per-frame palette id for those layers rather than a name.

t:screen() is the sibling of t:lines(), and the difference decides which one a test should assert on. t:lines() is buffer text; t:screen() is what the client would actually draw. Anything the editor renders instead of a buffer line shows up only in the latter — a closed fold’s 'foldtext' placeholder, a ~ filler past the end of the buffer. Assert on t:screen() for those and on t:lines() for an edit. A virtual line is the exception in the other direction: it takes a screen row but its text rides its own layer, so the row reads blank in t:screen() and t:decor(row).virt_lines is what sees it.

Hermetic seams

For plugins that touch the clipboard or the filesystem:

• btv.test.clipboard.seed(text[, linewise]) — put text on "+ / "* as if an external app set it. btv.test.clipboard.peek() → text, linewise (what a plugin wrote). btv.test.clipboard.clear().
• btv.test.tempdir() — a fresh, already-created unique directory; pair with btv.fs to exercise a plugin’s file I/O without collisions.

A real example

bemtvi-keys-helper (the first-party which-key) ships a real suite, test/popup_spec.lua: it feeds a leader prefix, t:wait_fors the debounced popup, and asserts on t:float().text — group names, leaf descriptions, the built-in z grammar, and close-on-abort. It is a compact model of a UI plugin tested entirely through its observable surface.

Gating

The whole surface is off in a normal editor session: btv.test is nil and the UI mirror it reads (btv._ui) is unpopulated. It is turned on only by the --test-plugin runner (via the btv_enable_test_mode RPC), so a config or plugin can’t accidentally depend on the test API, and a normal session pays none of the per-redraw mirror cost.

Note. There is no virtual clock yet — tests use real wall-clock time plus t:wait_for / t:sleep, which covers debounce and timeout behavior. Faking the timer wheel is tracked as a follow-up.

See also

• Writing bemtvi plugins — the anatomy a spec tests.
• Async & promises — the btv.async / t:wait_for machinery the context is built on.
• Native plugin API design — why plugins are pure Lua, hence testable as pure Lua.

Autocommand events

These are the events the bemtvi editor currently emits. Register a handler for one with btv.autocmd.create (or vim.api.nvim_create_autocmd). The event name is matched exactly, and a handler’s callback receives the event table { id, event, match, buf, file, data }.

The list is the emitted set, not all of vim’s events. bemtvi fires events as features come to need them. A handler registered for an event that isn’t emitted yet (e.g. OptionSet) is accepted but simply never fires — it does not error. If you need one that’s missing, it’s a feature gap, not a config mistake.

Patterns support shell globs: a pattern such as "*.rs" (no /) matches a file event by the path tail, one containing a / matches the whole path, and "*" (or an omitted pattern) matches everything. A pattern with no glob metacharacter is an exact compare — so a FileType rust autocmd never glob-matches a path.

Hot-path events are synchronous

Events fall into two classes, and it decides whether your handler may be async.

Hot-path events fire while the editor converges a single input tick — that is, on nearly every keypress:

CursorMoved   CursorMovedI   TextChanged   TextChangedI   ModeChanged
InsertEnter   InsertLeave    BufEnter      BufLeave
WinEnter      WinLeave       WinScrolled   WinResized

Their handlers must be synchronous. Returning a promise from one raises, naming the event and the file:line you registered it at. The editor will never wait for it, so returning one means expecting an ordering that cannot happen.

This is not a ban on async work — only on handing back the promise. Start it and return nothing:

-- WRONG: raises. Nothing awaits this.
btv.autocmd.create("CursorMoved", { callback = function()
  return btv.lsp.buf.hover()
end })

-- Right: fire-and-forget, or defer with btv.schedule / btv.on_next_tick.
btv.autocmd.create("CursorMoved", { callback = function()
  btv.lsp.buf.hover()
end })

Every other event is async-capable: a callback may return a promise (btv.promise, or the result of an btv.* async call). A returned promise is never dropped — a rejection surfaces like any unhandled btv.promise rejection, named for the event that raised it.

The split exists so the machinery below never touches the per-keypress path.

What happens when a handler is async

Two guarantees, both reproducing for async what vim gets for free by being synchronous.

Late subscribers still get the event. If a handler registers another handler for the same event while the first is still running, the newcomer receives that event too. This is what makes a lazily-loaded plugin work: FileType wakes the plugin, the plugin’s config runs (possibly btv.await-ing), it registers its own FileType handler — and that handler still fires for the buffer that woke it. Nothing fires twice: delivery is filtered by registration order, not replayed wholesale.

Plugins loading late still get the startup file’s events. This is the same guarantee widened to the plugin-load boundary — see Plugins and the startup file.

The read sequence is ordered. BufReadPost → FileType → BufEnter → BufWinEnter advances one stage at a time, each waiting for the previous stage’s async handlers to finish. So a BufReadPost handler that detects the filetype asynchronously is reflected in the FileType that follows — you get one correct FileType, not a wrong one followed by a correction. This is vim’s order, and an async handler does not reorder it: BufEnter and BufWinEnter stay behind the read, however long it takes. BufWritePre (the write waits — see Writing) and QuitPre / ExitPre / VimLeavePre (the exit waits — see Quitting & exit) are awaited the same way.

Handlers have a time budget: 500 ms by default. It bounds how long the editor waits, never whether anything gets delivered — when it expires, the sequence advances and late subscribers are still served, so one slow handler cannot wedge a buffer half-initialised. Blowing it warns, naming the handler’s file:line; finishing late warns again with the elapsed time. Raise it for a handler you know is slow:

btv.autocmd.create("FileType", { timeout = 5000, callback = function() … end })

A handler that never settles at all never reports completion, so it stays listed in btv.autocmd.pending() — inspect with :lua print(vim.inspect(btv.autocmd.pending())). Warnings go to :messages.

Buffer lifecycle

Ordering on opening a file is BufAdd → BufReadPost (or BufNewFile for a new path) → FileType → BufEnter → BufWinEnter, with BufLeave for the buffer being left ahead of the whole sequence; an async handler does not reorder it — see What happens when a handler is async. Re-reading the current buffer (:e!) fires the same sequence minus the BufLeave and the BufAdd (the bufnr is neither left nor new).

Plugins and the startup file

Plugins load asynchronously. btv.plugins awaits a spec’s directory before sourcing it, and a spec’s config may btv.await on its own — so a plugin’s config, and every autocmd that config registers, lands several ticks into startup. The file you named on the command line has already been read by then. Painting before the plugins are up is deliberate: it is what makes bemtvi file.txt open instantly.

You do not have to work around it. Every first-announce event fired before the plugins were ready is replayed to the handlers that registered while they were loading, when PluginsLoaded fires:

BufReadPost   -> the handlers that exist now (your init.lua's, the built-in
FileType         treesitter / LSP attach) — so the file colours immediately
BufEnter
VimEnter
  <plugin configs run, registering their own BufReadPost / FileType handlers>
PluginsLoaded -> BufReadPost / FileType replayed to exactly those handlers

So a plugin registers a plain BufReadPost handler and sees the startup file, with the buffer and the match it was read with. There is no separate event to hook and no sweep of btv.buf.list() to write. Restored session windows are covered the same way.

Three things worth knowing:

• Nothing fires twice. Delivery is filtered by registration order, the same watermark the async replay above uses. A handler registered before the read — one from your init.lua — receives it on the read and is never replayed to.
• Only BufReadPost, BufNewFile and FileType are replayed. They fire once per read and carry no pairing semantics, so re-delivering one is unambiguous. BufEnter and BufWinEnter are not: they mean “became current” / “a window displayed it”, which may no longer be true by the time the plugins land, and a BufEnter replayed without its BufLeave twin would misreport editor state.
• The window is a startup one. It closes at PluginsLoaded and never reopens, so a handler registered later — by a lazy plugin, or by you at the : prompt — gets the reads that follow it and nothing from before.

Writing

Window & tab

Mode

Editing & cursor

These fire at high frequency, so they are gated on a registered handler — when no autocmd listens for them they cost nothing.

Mouse

LSP

Treesitter

Files & environment

Startup

Quitting & exit

Fired when the editor is really leaving — a committed :qa / last-window :q / :wq / :x / :wqa (! skips only the modified-buffer E37 guard, not these events). The three *Pre events are awaited: a handler may return a promise and the exit waits for every handler to settle before advancing, so an async flush/cleanup runs before the process leaves. They fire in order.

A handler cannot cancel the quit (these events are advisory, as in neovim), and a handler whose promise rejects does not block the exit — a failing cleanup still lets the editor leave.

Plugins

Fired by the built-in plugin manager (btv.plugins). See Writing bemtvi plugins.

To hook one named plugin, prefer btv.plugins.on_loaded(name, fn) over subscribing to PluginLoaded yourself. The event only reports a load that happens later, so the raw subscription silently never runs if that plugin turns out to be eager and already loaded; on_loaded runs fn immediately in that case and waits otherwise, so it fires exactly once either way:

btv.plugins.on_loaded("bemtvi-lspconfig", function()
  require("bemtvi-lspconfig").setup()
end)

User

User is the freeform event namespace: any plugin (or bemtvi itself) fires one with btv.autocmd.exec("User", { pattern = "MyEvent", data = … }), and a handler subscribes by pattern. bemtvi fires User DaemonStatusChanged whenever a daemon session’s connection phase changes (read the phase with btv.daemon.status()).

Event aliases

A handful of neovim event names are aliases for another event. bemtvi honors these by canonicalizing the alias to its real event at registration — so a config that does btv.autocmd.create("BufRead", …) (muscle memory from neovim) behaves exactly as if it had used "BufReadPost", and the callback’s event field reports the canonical name. Aliases are accepted anywhere an event name is (create, exec, get, clear).

Every alias’s target event is one bemtvi actually emits — registering on an alias whose target never fired would be a silent no-op, so we don’t add one until the target exists.

btv.* API Reference

The public btv.* Lua API, extracted directly from the prelude (crates/bemtvi-lua/src/prelude/*.lua) by book/gen/generate.py. Every entry is a public declaration — a function, a handle method (view:mount(opts)), or a value (btv.json.null) — plus its doc-comment; private btv._* internals are excluded. This is the canonical surface per ADR 0002.