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

```bash
# 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)

```bash
# 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`:

```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

```bash
# 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

```bash
# Generate docs
cargo doc --open

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

### Code Style

```bash
# Format code
cargo fmt

# Lint
cargo clippy -- -D warnings
```

## Roadmap

### Phase 1: Core Foundation (Current)
- [x] Basic buffer management (ropey)
- [x] Modal system (Normal, Insert, Visual)
- [x] Object-verb keybindings (Helix-style)
- [x] Lua config loading (mlua)
- [x] CLI mode with crossterm
- [x] File open/save
- [x] 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](LICENSE) for details.

## Contributing

Contributions are welcome! Please see our [SPECIFICATION.md](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](https://helix-editor.com/) - Modal editing, object-verb keybindings
- [Kakoune](https://kakoune.org/) - Multiple selections, select-then-act
- [Neovim](https://neovim.io/) - Lua configuration, plugin system
- [Sublime Text](https://www.sublimetext.com/) - Performance, multiple cursors
- [zed](https://zed.dev/) - GPU acceleration, performance