microhx/README.md

MicroHX

A modern modal text editor written in Rust with Lua plugins, LSP support, and tree-sitter syntax highlighting.

Features

• Modal Editing - Kakoune/Helix-style object-verb keybindings (select then act)
• Lua Configuration - Full Lua 5.4 scripting for config and plugins
• Three UI Modes - CLI (terminal), TUI (ratatui), and GUI (egui)
• Built-in LSP - Native language server protocol client
• Tree-sitter - Fast, incremental syntax highlighting
• Static Builds - Compile once, run anywhere (musl, old glibc)
• User-Definable Modes - Create custom editing modes

Quick Start

Build and Run

# Build CLI mode (default)
cargo build --release

# Run
./target/release/microhx [file]

# Build with TUI support
cargo build --release --features tui

# Build with GUI support  
cargo build --release --features gui

Static Build (Linux)

# Install musl target
rustup target add x86_64-unknown-linux-musl

# Build static binary
cargo build --release --target x86_64-unknown-linux-musl --features cli

# Or use zig for better compatibility
cargo install cargo-zigbuild
cargo zigbuild --release --target x86_64-unknown-linux-gnu.2.17 --features cli

Configuration

Create ~/.config/microhx/init.lua:

return {
  settings = {
    theme = "dracula",
    line_numbers = true,
    relative_numbers = false,
    tab_width = 4,
    insert_spaces = true,
  },
  
  keys = {
    normal = {
      ["<leader>w"] = ":write",
      ["<leader>q"] = ":quit",
      ["<C-s>"] = ":write",
    },
    insert = {
      ["jk"] = "<Esc>",
    },
  },
  
  plugins = { "lsp", "treesitter" },
}

Keybindings (Helix Style)

Motions

Key	Action
h/j/k/l	Left/Down/Up/Right
w/b	Word forward/backward
0/$	Line start/end
gg/G	Document start/end

Actions

Key	Action
d	Delete selection
y	Yank (copy)
c	Change (delete + insert)
p/P	Paste after/before

Object Selectors

Key	Action
iw	Select inner word
aw	Select a word
i(	Select inside ()
a"	Select around ""

Goto (LSP)

Key	Action
gd	Go to definition
gr	Go to references
gh	Show hover docs

Project Structure

microhx/
├── Cargo.toml          # Dependencies and build config
├── SPECIFICATION.md    # Full specification document
├── src/
│   ├── lib.rs          # Library root
│   ├── main.rs         # CLI entry point
│   ├── main_tui.rs     # TUI entry point
│   ├── main_gui.rs     # GUI entry point
│   ├── buffer.rs       # Text buffer (ropey)
│   ├── cursor.rs       # Cursor and Position types
│   ├── editor.rs       # Main editor state
│   ├── mode.rs         # Modal system
│   ├── keymap.rs       # Keybinding system
│   ├── config.rs       # Lua configuration
│   └── cli.rs          # CLI rendering (crossterm)
└── tests/              # Integration tests

Development

Running Tests

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific module tests
cargo test buffer
cargo test cursor
cargo test mode

Building Documentation

# Generate docs
cargo doc --open

# Include private items
cargo doc --open --document-private-items

Code Style

# Format code
cargo fmt

# Lint
cargo clippy -- -D warnings

Roadmap

Phase 1: Core Foundation (Current)

• Basic buffer management (ropey)
• Modal system (Normal, Insert, Visual)
• Object-verb keybindings (Helix-style)
• Lua config loading (mlua)
• CLI mode with crossterm
• File open/save
• Static build setup (musl)

Phase 2: Essential Features

• Complete keybinding system
• Undo/redo (tree-based)
• Search/replace
• Command system
• Status bar
• Line numbers
• User-definable modes

Phase 3: Built-in LSP + Tree-sitter

• Tree-sitter integration
• Syntax highlighting engine
• LSP client (tower-lsp)
• Diagnostics display
• Completions popup
• Goto definition/hover

Phase 4: Advanced Editing

• Multiple selections
• Macros
• Marks
• Registers
• Split windows
• TUI mode (ratatui)

Phase 5: Polish & Plugins

• Plugin system
• Theme system
• GUI mode (egui)
• Performance optimization
• Documentation
• CI/CD with static builds

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please see our SPECIFICATION.md for the full design document.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: cargo test
5. Format code: cargo fmt
6. Submit a pull request

Acknowledgments

MicroHX draws inspiration from:

• Helix - Modal editing, object-verb keybindings
• Kakoune - Multiple selections, select-then-act
• Neovim - Lua configuration, plugin system
• Sublime Text - Performance, multiple cursors
• zed - GPU acceleration, performance