Repository Guidelines

Project Structure & Module Organization

This repo is a Rust TUI editor prototype built around ratatui 0.30, crossterm, and tokio. The application entry point is src/main.rs. Local workspace crates live under crates/: ratatui-code-editor provides the editor widget and tui-tree-widget provides the explorer tree. Treat src/main.rs as app orchestration only; push reusable editing, workspace, and UI logic into focused modules or local crates instead of growing one monolithic file.

Build, Test, and Development Commands

Use:

• cargo run to launch the TUI
• cargo check for fast compile validation
• cargo fmt to format changes
• cargo clippy --all-targets --all-features before finishing non-trivial work
• cargo test when editing crate logic that already has tests or clearly needs them

There is no CI config in the tree yet, so local verification is the gate.

Ratatui-TUI Conventions

Bake in the ratatui-tui skill by default for this repo. Prefer The Elm Architecture shape: model/state, typed actions/messages, update, and view. Keep event ingestion async with EventStream + tokio::select!. Use StatefulWidget state types for explorer, lists, tables, and scrollbars instead of ad hoc cursor bookkeeping where possible.

Styling should use Stylize helpers like .bold(), .cyan(), .dim(), not verbose Style construction unless necessary. Avoid hardcoded pure white/black defaults. Ensure panic hooks always restore the terminal and mouse capture state.

Coding Style & Safety

Avoid unwrap() outside tests. Propagate errors with anyhow::Result or color_eyre-style context. Keep terminal-facing behavior exact: cursor math, scrolling, tab width, and selection rendering are correctness issues, not polish. Skip .git, target, and symlink loops when scanning the workspace.

Testing Guidelines

Prefer focused unit tests in the local crates for editor actions, history, cursor math, and tree behavior. For TUI changes, verify both compile correctness and interactive behavior with cargo run.

Commit & PR Guidelines

Git history is unavailable because this branch has no commits yet. Use conventional subjects such as feat: add workspace save flow, fix: correct cursor rendering, or docs: refresh repo guidelines.

@RTK.md