updating README

README.md

@@ -1,58 +1,97 @@
-# Lumacs 
+# Lumacs
 
 <img src="resources/logo_small.png" width="90" height="90">
 
-
-A modern text editor in C++20, inspired by Emacs with powerful Lua scripting support.
+A modern, highly customizable text editor engine written in C++20, deeply inspired by Emacs and featuring powerful Lua 5.4 scripting support. Lumacs emphasizes a clear separation between its core logic and UI, making it both flexible and extensible.
 
 ## Features
 
-### ✅ **Implemented (Polishing & Refactoring Phase)**
-- **Core Editing**: Kill ring, mark/region, undo/redo
-- **Buffer Management**: Multiple buffers, window splits  
-- **Advanced Features**: Registers, keyboard macros, rectangles, minibuffer history
-- **Search**: Incremental search with highlighting
-- **Theme System**: Dracula, Everforest, Nord, Solarized, Gruvbox, and default themes
-- **UI**: GTK4 Frontend (primary) and Ncurses TUI (fallback)
-- **Modeline**: Modular, extensible status bar
-- **Lua Scripting**: Extensive Lua API for customization
-
-### 🔄 **Planned**
-- Language modes (Python, C++, JavaScript)
-- Plugin system expansion
-- Advanced completion UI
+Lumacs aims to provide a rich, Emacs-like editing experience with a focus on configurability and modern C++ practices.
+
+### ✅ Implemented Features (Functional, some require refactoring)
+
+The editor currently boasts a wide array of functional features, though ongoing refactoring efforts (detailed in the [Development Plan](documentation/PLAN.md)) aim to enhance their modularity, maintainability, and extensibility.
+
+-   **Core Emacs Editing DNA**:
+    *   **Buffer Management**: Robust handling of multiple buffers, including switching, listing, and closing.
+    *   **Kill Ring**: Complete Emacs-style cut/copy/paste (kill, yank, yank-pop) operations.
+    *   **Mark & Region**: Full functionality for setting marks, defining regions, and extracting text.
+    *   **Registers**: Emacs-like named registers for storing and inserting text.
+    *   **Rectangles**: Comprehensive operations for killing, yanking, and manipulating rectangular blocks of text.
+    *   **Text Editing**: Basic insertion, deletion, and replacement, handling multi-line scenarios and buffer events.
+    *   **Undo/Redo**: Functionality for reverting and re-applying changes.
+    *   **Window Splits**: Dynamic horizontal and vertical window splitting, closing, and navigation, with robust layout management and focus handling in the GTK frontend.
+    *   **Input System**: Functional keyboard input handling across GTK and TUI, including modifiers.
+    *   **Cursor System**: UI-agnostic cursor position/movement logic, with blinking, inverted block cursor rendering in GTK.
+    *   **Scrolling System**: Full vertical and horizontal scrolling with auto-adjustment to keep the cursor in view, supporting page-up/down.
+
+-   **Advanced UI & System Integration**:
+    *   **Theme System**: A robust and flexible theming engine with 6 professional themes (Dracula, Everforest, Nord, Solarized, Gruvbox, Default). Supports named faces, inheritance, minibuffer selection with fuzzy completion, and a comprehensive Lua API for customization.
+    *   **Minibuffer & Command System**: A functional interactive minibuffer with tab completion, history navigation, and command execution. A comprehensive C++ command registry with fuzzy matching and a powerful Lua API for command registration and execution are in place.
+    *   **Syntax Highlighting**: Pango-based text rendering with syntax highlighting based on a face system.
+    *   **Text-Cursor Alignment**: Precise Pango-based text measurement ensures accurate cursor alignment.
+    *   **Clean Exit**: Robust application shutdown, including proper GTK resource cleanup.
+    *   **Modeline**: Modular and extensible status bar with UI-agnostic content generation, integrated into GTK rendering.
+    *   **GTK Frontend**: Primary GUI using GTK4 / gtkmm, supporting Pango/Cairo rendering.
+    *   **Ncurses TUI**: Functional terminal user interface serving as a fallback.
+
+### ⚠️ Partially Implemented / Needs Refactoring
+
+Certain features, while present, are identified for significant refactoring to align with architectural goals and enhance robustness/extensibility.
+
+-   **Keyboard Macros**: Recording functionality is implemented, but macro playback is currently a `TODO`.
+-   **Minibuffer Logic**: While functional, the minibuffer's state management, completion logic, history, and command dispatch are highly coupled and duplicated across UI frontends. This requires centralization into a UI-agnostic `MinibufferManager`.
+-   **Keybinding System**: Functional, but needs canonical key representation refinement, prefix lookup optimization (e.g., using a Trie), and tighter integration with the Command System to centralize execution.
+-   **Command System**: The C++ registry is robust, but requires enhanced argument handling (e.g., `InteractiveSpec` for dynamic prompting, type-safe arguments), consolidation of command string parsing, and refined completion integration (externalizing specific completers).
+-   **GTK Frontend (`GtkEditor`)**: The `GtkEditor` remains a "God Object" in some aspects. Decoupling rendering concerns into specialized components and moving C++ fallback keybindings to Lua are key refactoring targets.
+-   **ThemeElement Usage**: The legacy `ThemeElement` enum is still present in some rendering logic and needs to be fully transitioned to the unified `Face` system.
+
+### 🔄 Planned Enhancements (Post-Refactoring)
+
+Once current refactoring efforts are complete, the following are planned:
+
+-   **Advanced Completion UI**: Implement a popup completion window with descriptions and better visual feedback.
+-   **Plugin Management**: Implement dynamic loading and lifecycle management of Lua plugins.
+-   **Lua Debugging**: Integrate basic debugging support for Lua scripts.
+-   **Command Aliases**: Allow users to define custom command aliases in their configuration.
+-   **Language Modes**: Expand support for various language modes (Python, C++, JavaScript).
 
 ## Tech Stack
 
-- **Core**: C++20
-- **UI**: GTK4 / gtkmm (GUI), Ncurses (TUI)
-- **Scripting**: Lua 5.4 + sol2 bindings
-- **Build**: CMake 3.20+
+-   **Core**: C++20
+-   **UI**: GTK4 / gtkmm (GUI), Ncurses (TUI)
+-   **Scripting**: Lua 5.4 with `sol2` bindings
+-   **Build**: CMake 3.20+
 
 ## Quick Start
 
 ### Building
+
 ```bash
 cmake -B build -S .
 cmake --build build -j4
 ```
 
 ### Running
+
 ```bash
 ./build/lumacs [file]
 ```
 
 ### Key Bindings
-- **Theme Switching**: `M-x theme-selection`
-- **Window Splits**: `C-x 2` (horizontal), `C-x 3` (vertical), `C-x 0` (close)
-- **Buffers**: `C-x b` (switch), `C-x k` (kill), `C-x C-b` (list)
-- **Advanced**: `F3/F4` (macros), `C-x r s/i` (registers), `C-x r k/y/t` (rectangles)
+
+Common Emacs-like keybindings are supported. Refer to `init.lua` for the full default keymap.
+
+-   **Theme Switching**: `M-x set-theme` (then use Tab for completion)
+-   **Window Splits**: `C-x 2` (horizontal), `C-x 3` (vertical), `C-x 0` (close window), `C-x o` (next window)
+-   **Buffers**: `C-x b` (switch buffer), `C-x k` (kill buffer), `C-x C-b` (list buffers)
+-   **Advanced**: `F3` (start macro), `F4` (end macro/call macro), `C-x r s` (copy to register), `C-x r i` (insert register), `C-x r k` (kill rectangle), `C-x r y` (yank rectangle)
 
 ## Documentation
 
-- [Architecture Overview](documentation/ARCHITECTURE.md)
-- [Development State](DEV_STATE.md)
+-   [Architecture Overview](documentation/ARCHITECTURE.md)
+-   [Development Plan](documentation/PLAN.md)
 
 ## License
 
-MIT
+MIT