# Lumacs Development Plan: Current State and Refactoring Roadmap

This document unifies the project's refactoring plan with the detailed development state and review findings. It serves as the single source of truth for the codebase's current status, identified areas for improvement, and the roadmap for future development.

## Architecture
```
    [Lua 5.4 Engine]
         ^  |
         |  v
    [Lua API Bridge] <-- C++ bindings for buffers, windows, keybindings, themes
         ^  |
         |  v
    [Editor Core] <-- Buffer management, kill ring, face system, modeline
         ^  |
         |  v
    [UI Interface] <-- Abstract UI layer
         ^  |
         |  v
    [GTK4 Frontend] <-- Primary GUI (with TUI fallback available)
         |
         v
    [Terminal/Display]
```

## File Manifest

```
Lumacs/
├── CMakeLists.txt           # Build configuration
├── init.lua                 # Main Lua initialization
├── themes.lua              # Theme definitions
├── include/lumacs/
│   ├── editor_core.hpp     # Core editor logic
│   ├── buffer.hpp          # Text buffer management
│   ├── lua_api.hpp         # C++/Lua bridge
│   ├── gtk_editor.hpp      # GTK4 frontend
│   ├── tui_editor.hpp      # TUI fallback
│   ├── keybinding.hpp      # Key handling
│   ├── theme.hpp           # Theme/face system
│   ├── command_system.hpp  # Command registry & completion engine
│   ├── modeline.hpp        # NEW: Modeline framework
│   ├── i_editor_notifier.hpp # NEW: Decoupling interface
│   ├── i_window_manager.hpp  # NEW: Decoupling interface
│   └── [other headers]
├── src/
│   ├── main.cpp            # Entry point
│   ├── editor_core.cpp     # Core functionality
│   ├── lua_api.cpp         # Lua bindings
│   ├── gtk_editor.cpp      # GTK implementation
│   ├── command_system.cpp  # Command execution & completion
│   ├── modeline.cpp            # NEW: Modeline implementation
│   └── [other .cpp files]
├── tests/
├── examples/
├── scripts/
└── documentation/
```

## Core Refactoring Goals

1.  **Decompose the `EditorCore` God Object:** The `EditorCore` class currently handles a vast array of responsibilities, leading to high coupling and reduced modularity. The primary goal is to break down this monolithic class into smaller, more specialized, and cohesive components (manager classes, services).
2.  **Enhance Testing Infrastructure and Coverage:** The existing custom testing framework is basic and test coverage is limited. The goal is to migrate to a modern, standard C++ testing framework and significantly increase test coverage, especially for newly modularized components.
3.  **Implement Robust Logging:** Replace ad-hoc `std::cerr` debug outputs with a proper logging system for better debuggability and runtime insight.
4.  **Refine Dependency Management:** Address potential stability risks associated with external dependencies.

## Detailed Plan and Subtasks

### Phase 1: Modularity and Decoupling (EditorCore Decomposition) ✅ Completed

*   **Subtask 1.1: Identify and Extract Sub-systems:** ✅ Completed
    *   ✅ **Buffer Management**: Extracted into `BufferManager` (class, header, and implementation). `EditorCore` now delegates buffer-related operations to `BufferManager`.
    *   ✅ **Window Management**: Extracted into `WindowManager` (class, header, and implementation). `EditorCore` now delegates window-related operations to `WindowManager`.
    *   ✅ **Kill Ring Management**: Extracted into `KillRingManager` (class, header, and implementation). `EditorCore` now delegates kill-ring-related operations to `KillRingManager`.
    *   ✅ **Registers Management**: Extracted into `RegisterManager` (class, header, and implementation). `EditorCore` now delegates register-related operations to `RegisterManager`.
    *   ✅ **Keyboard Macro Management**: Extracted into `MacroManager` (class, header, and implementation). `EditorCore` now delegates macro-related operations to `MacroManager`.
    *   ✅ **Rectangle Operations Management**: Extracted into `RectangleManager` (class, header, and implementation). `EditorCore` now delegates rectangle-related operations to `RectangleManager`.
*   **Subtask 1.2: Migrate Responsibilities:** ✅ Completed
    *   All relevant member variables and methods from `EditorCore` have been moved to their respective new manager classes.
    *   `EditorCore` now holds `std::unique_ptr` instances of these new manager classes.
    *   Refactor `EditorCore` methods have been refactored to delegate calls to the appropriate manager classes.
*   **Subtask 1.3: Define Clear Interfaces:** ✅ Completed
    *   Interaction between `EditorCore` and the new manager classes occurs through well-defined, minimal interfaces.
*   **Subtask 1.4: Manage Dependencies between new Modules:** ✅ Completed
    *   Introduced `IEditorNotifier` and `IWindowManager` interfaces. `EditorCore` implements these interfaces.
    *   `BufferManager` and `WindowManager` now depend on these interfaces instead of the concrete `EditorCore` class, breaking the strong circular dependency.

### Phase 2: Testing Infrastructure Upgrade and Coverage Expansion

*   **Subtask 2.1: Select and Integrate a Standard Testing Framework:** ✅ Completed
    *   **Recommendation:** Google Test. Integrated into the CMake build system.
    *   Removed the custom `test_framework.hpp`.
*   **Subtask 2.2: Migrate Existing Tests:** ✅ Completed
    *   `test_buffer.cpp` and `test_editor_core.cpp` have been converted to Google Test format.
*   **Subtask 2.3: Expand Test Coverage:** ✅ Completed
    *   ✅ Write unit tests for all new manager classes created in Phase 1. Focus on testing their individual functionalities in isolation.
    *   ✅ Increase test coverage for existing components, especially CommandSystem, and Window. (LuaApi coverage expanded and fixed)
    *   ✅ Implement integration tests to verify the interactions between the modularized components and the overall editor behavior.

### Phase 3: Logging and Observability ✅ Completed

*   **Subtask 3.1: Integrate a C++ Logging Library:** ✅ Completed
    *   **Recommendation:** spdlog or loguru. Integrate the chosen library into the CMake build system.
    *   Included `spdlog` via FetchContent in `CMakeLists.txt`.
    *   Created `Logger` wrapper class in `include/lumacs/logger.hpp` and `src/logger.cpp`.
*   **Subtask 3.2: Replace `std::cerr` Calls:** ✅ Completed
    *   Replace all instances of `std::cerr` for debug/error output with appropriate calls to the new logging library.
    *   Updated `src/main.cpp`, `src/plugin_manager.cpp`, `src/buffer_manager.cpp`, `src/gtk_editor.cpp`, `src/editor_core.cpp`, `src/command_system.cpp`, `src/window_manager.cpp`, `src/macro_manager.cpp`, and `src/lua_api.cpp`.
    *   Define different log levels (e.g., DEBUG, INFO, WARN, ERROR) and configure log sinks (e.g., console, file).

### Phase 4: Dependency Management ✅ Completed

*   **Subtask 4.1: Review `sol2` Dependency:** ✅ Completed
    *   Investigated `sol2` releases and updated `CMakeLists.txt` to use `GIT_TAG v3.5.0` instead of `develop` for improved stability.
    *   Confirmed build and tests pass with the new tag.

## Current Development Roadmap

- [x] Expand test coverage for existing components: `LuaApi`, `CommandSystem`, and `Window`.
- [x] Implement integration tests to verify component interactions.
- [x] Phase 3: Logging and Observability (Integrate spdlog, replace std::cerr).
- [x] Phase 4: Dependency Management (Review `sol2` dependency).
- [x] Address Circular Dependency (Phase 1.4 refinement).

## Current State Summary

- ✅ **Phase 1-5**: Complete Emacs-like core functionality
- ✅ **Phase 6 Core**: GTK4 frontend with text rendering
- ✅ **Phase 7 Optimization**: Render caching and performance tuning
- ✅ **Phase 8 Mouse**: Full mouse support (click-move, scroll, drag-select)
- ✅ **Phase 9 Advanced UI**: Removed Context Menus and Hover Tooltips
- ✅ **Core Emacs Features**:
    - **Kill Ring, Mark & Region, Buffer Management, Registers, Keyboard Macros**: All substantially implemented (Keyboard macro playback is a TODO).
    - **Rectangles**: Well-implemented for kill, yank, and string operations.
    - **Input System**: Minibuffer input processing (including cursor movement and basic editing) is now centralized in `MinibufferManager`. Integrations for command argument handling are fully implemented as part of Phase C.
    - **Cursor System**: Functional and robust; core position/movement logic is UI-agnostic within the `Window` class, while UI rendering (blinking, inverted block style) is handled correctly by `GtkEditor`.
    - **Text Editing**: Core editing operations (insert, erase, replace) in the `Buffer` class are comprehensive, robust, and correctly handle multi-line scenarios, state updates and events.
    - **Keybinding System**: Fully refactored and completed (Phase B).
- ✅ **GTK Enhancements**: (Fully completed - Phase A).
- ✅ **Minibuffer & Command System**: Minibuffer core logic, history management, and completion are fully centralized and integrated with the Command System (Phases Z and C completed).
    - **Advanced Completion UI**: Completed (Implemented popup completion window with descriptions and better visual feedback).
    - **Minibuffer & Popover Polish**: ✅ Fixed. Exposed ISearch direction control, fixed TUI rendering and Backspace, fixed GTK minibuffer double-rendering and disappearance, polished GTK Popover positioning and focus management, fixed GTK crash on completion mismatch, and fixed minibuffer cursor not moving after Tab completion.
    - [x] **GTK Completion Popover**: Disabled by default via Lua configuration (user request).
    - [x] **Persistent Messages**: Implemented `*Messages*` buffer to log all minibuffer outputs, ensuring history is accessible via buffer switching.
    - [x] **File Path Completion**: Implemented robust file path autocompletion with tilde expansion and directory browsing.
    - [x] **GTK Minibuffer Cursor**: Fixed cursor rendering to be a proper block cursor positioned correctly at the editing point, not a line at the end of the text.
    - [x] **TUI Cursor**: Replaced software block cursor with standard hardware cursor (`curs_set(2)`). Added fallback software cursor with forced `A_REVERSE` to ensure visibility on all terminals.
    - [x] **File Loading Robustness**: Fixed crash on non-existent files and added support for creating new files via open command.
- ✅ **Theme System Refactoring**:
    - [x] Implemented `editor:create_and_register_theme` Lua API to allow theme definition from Lua.
    - [x] Factored all hardcoded C++ themes (`default`, `everforest-dark`, `dracula`, `solarized-dark`, `nord`, `gruvbox-light`) into individual Lua files (`lua/themes/*.lua`).
    - [x] Removed hardcoded theme definitions and factory methods from C++ (`src/theme.cpp`, `include/lumacs/theme.hpp`).
    - [x] Updated `init.lua` to load the new individual theme files and `themes_init.lua`.
    - [x] **RESOLVED**: Fixed theme functionality issues. Root causes were:
        - **Sol2 lambda binding issue**: The `create_and_register_theme` method binding was missing the `EditorCore&` first parameter, causing empty theme names.
        - **Missing set-theme command**: Added `set-theme` command to `defaults.hpp` as a fundamental command that theme switching functions depend on.
        - **Active theme access issue**: Fixed incorrect `active_theme` property access in `lua/themes/themes_init.lua` - changed from `editor.theme_manager.active_theme` to `editor.theme_manager:active_theme()` function calls.
        - **Theme system fully functional**: All 6 themes (default, dracula, everforest-dark, gruvbox-light, nord, solarized-dark) load correctly, theme switching works via `M-x set-theme`, `C-x t` keybindings work (including `C-x t l` for listing), and theme cycling is operational.
        - **Theme Cache Invalidation**: ✅ Fixed. Implemented `EditorEvent::ThemeChanged` and `GtkRenderer::invalidate_cache()` to ensure UI updates immediately when a new theme is applied.
- ✅ **Phase 15 Polishing**: Successfully addressed GTK Cleanup and Modeline Refactor.
    - [x] **GTK Modeline**: Fixed modeline not showing in GTK frontend and ensured per-window rendering.
    - [x] **GTK Split Crash**: Fixed segmentation fault when splitting windows by using robust context widget management in `GtkRenderer`.
- ✅ **Plugin Management**: Implemented dynamic loading and lifecycle management of Lua plugins.
- ✅ **Lua Debugging**: Integrated basic remote debugging support for Lua scripts via MobDebug.
- ✅ **Command Aliases**: Implemented support for user-defined command aliases.
- ✅ **EditorCore Decomposition (Buffer Management)**: Extracted buffer management into a dedicated `BufferManager` class.
- ✅ **EditorCore Decomposition (Window Management)**: Extracted window management into a dedicated `WindowManager` class.
- ✅ **EditorCore Decomposition (Kill Ring Management)**: Extracted kill ring management into a dedicated `KillRingManager` class.
- ✅ **EditorCore Decomposition (Registers Management)**: Extracted registers management into a dedicated `RegisterManager` class.
- ✅ **EditorCore Decomposition (Keyboard Macro Management)**: Extracted keyboard macro management into a dedicated `MacroManager` class.
- ✅ **EditorCore Decomposition (Rectangle Operations Management)**: Extracted rectangle operations management into a dedicated `RectangleManager` class.
- ✅ **Testing Infrastructure (Framework Integration)**: Integrated Google Test and removed custom test framework.
- ✅ **Testing Infrastructure (Migrate Existing Tests)**: Converted `test_buffer.cpp` and `test_editor_core.cpp` to Google Test format.
- ✅ **Build Fixes**: Resolved circular dependencies, missing definitions, and GTK4 incompatibilities across the codebase.
- ✅ **Regression Fixes**: Resolved build failures in `GtkRenderer` (undeclared identifier, unused variable) and `TuiEditor` (missing implementation due to file corruption). Restored TUI hardware cursor support.
- ✅ **LuaApi Test Coverage**: Expanded, and `sol2` binding issues for C++ managed objects (non-copyable) resolved via manual Lua C functions for core interactions.

## Technical Debt/Notes

- **Lua Bridge**: The lua_api.cpp contains the critical C++/Lua boundary code
- **GTK Threading**: All GTK operations must stay on main thread
- **Memory Management**: Using RAII and smart pointers throughout C++ code
- **Face System**: Themes are fully integrated with Pango text rendering
- **Cursor Implementation**: Blinking timer with 500ms intervals, proper cleanup on exit
- **Scrolling Architecture**: Viewport system with 3-line vertical and 5-column horizontal margins
- **Build System**: CMake-based with proper dependency management
- **Rendering Performance**: ✅ Fixed. Implemented line-based rendering cache in GtkRenderer to optimize drawing of unchanged text lines, especially during scrolling and minor edits. Dynamic elements like cursor and selection are composited on top.
- **Focus Stability**: GTK frontend caches active_window_ during redraw cycles to prevent race conditions in multi-window async rendering
- **GTK Popup**: Refined with max height and scroll-to-selection. Uses `Gtk::Popover`.
- **TUI ISearch**: ISearch highlighting temporarily disabled in TUI.
- **Backspace Bug**: ✅ Fixed. Was a logical error in Lua's `lumacs_backward_delete_char` function regarding position calculation for `erase_char` and cursor update.
- **`EditorCoreTest.MoveCursorRight` Disabled**: ✅ Fixed. Re-enabled and passing.



## General Instructions for the LLM Executor

*   **Adherence to Project Conventions:**
    *   **Style:** Maintain the existing C++ coding style, formatting, and naming conventions (e.g., `snake_case` for functions/variables, `PascalCase` for classes).
    *   **Modern C++:** Continue to leverage C++20 features, `std::unique_ptr`/`std::shared_ptr`, `const` correctness, and move semantics where appropriate.
    *   **CMake:** Integrate any new libraries or changes cleanly into the existing CMake build system.
*   **Granular Git Commits:**
    *   Make frequent, small, and atomic commits. Each commit should represent a single logical change.
    *   **Commit Message Format:** Follow conventional commit message guidelines (e.g., `feat:`, `fix:`, `refactor:`, `test:`, `docs:` prefixes). Explain *why* the change was made, not just *what* was changed.
    *   Example: `refactor(editor_core): Extract buffer management into BufferManager class`
*   **Keep Repository Tidy:**
    *   Ensure all new files are placed in logical directories (`include/lumacs/`, `src/`, `tests/`).
    *   Remove old, unused code or files.
    *   Update relevant documentation (e.g., `README.md`, `documentation/`) if changes impact the project's architecture or build process.
*   **Incremental Approach:**
    *   Address one subtask at a time. Do not attempt large, sweeping changes in a single step.
    *   After each significant refactoring step, ensure the project still builds and all existing tests pass before moving to the next step.
*   **Verification:**
    *   Always run build, linting, and tests after each significant change. Identify the project's specific commands for these (e.g., `cmake --build build`, `ctest`).
    *   Ensure strict compiler warnings remain enabled and no new warnings are introduced.
*   **User Interaction:**
    *   If any ambiguity or complex decision arises during the refactoring process, clarify with the user.

---

## Phase 6: Architecture Review Improvements (December 2024)

Based on the comprehensive architectural review in [REVIEW.md](./REVIEW.md), the following issues have been identified for resolution.

### High Priority Issues

| # | Issue | Status | Notes |
|---|-------|--------|-------|
| 6.1 | Remove production debug logging in TUI | 🟢 Completed | Replaced with spdlog (trace level) |
| 6.2 | Extract Lua callback wrapper helper | 🟢 Completed | Added `wrap_lua_callback()` helper method |
| 6.3 | Move yank state to KillRingManager | 🟢 Completed | Yank state now tracked in KillRingManager |
| 6.4 | Extract ISearchManager from MinibufferManager | 🟢 Completed | MinibufferManager now delegates to ISearchManager |
| 6.5 | Extract common mode activation logic | 🟢 Completed | Created ModeActivator class for TUI/GTK |

### Medium Priority Issues

| # | Issue | Status | Notes |
|---|-------|--------|-------|
| 6.6 | Create narrow interfaces for MacroManager/RectangleManager | 🔴 Not Started | Reduce EditorCore coupling |
| 6.7 | Add user-visible Lua error reporting | 🔴 Not Started | Push errors to *Messages* buffer |
| 6.8 | Create TUI header file for consistency | 🔴 Not Started | Match GtkEditor pattern |
| 6.9 | Add plugin metadata/manifest support | 🔴 Not Started | Version, dependencies |
| 6.10 | Create mock implementations for testing | 🔴 Not Started | IEditorNotifier, ICommandTarget mocks |

### Low Priority Issues (Technical Debt)

| # | Issue | Status | Notes |
|---|-------|--------|-------|
| 6.11 | Use unordered_map for Trie nodes | 🔴 Not Started | Performance optimization |
| 6.12 | Split large files | 🔴 Not Started | lua_api.cpp, editor_core.cpp |
| 6.13 | Clean up EditorCore constructor comments | 🔴 Not Started | After refactoring |

### Legend

- 🔴 Not Started
- 🟡 In Progress
- 🟢 Completed
- ⏸️ Blocked

### Change Log (Phase 6)

| Date | Issue # | Description | Build Status |
|------|---------|-------------|--------------|
| 2025-12-04 | 6.1 | Replaced debug_log with spdlog in tui_editor.cpp | ✅ Pass |
| 2025-12-04 | 6.2 | Added wrap_lua_callback() helper in lua_api.cpp | ✅ Pass |
| 2025-12-04 | 6.3 | Moved yank state to KillRingManager | ✅ Pass |
| 2025-12-04 | 6.4 | Extracted ISearchManager from MinibufferManager | ✅ Pass |
| 2025-12-04 | 6.5 | Created ModeActivator for TUI/GTK mode handling | ✅ Pass |

---

## Phase 7: Lua Integration Improvements (December 2024)

Comprehensive overhaul of the Lua integration to provide a complete Emacs-like editing experience out of the box.

### Goals

1. **defaults.hpp should be complete** - User shouldn't need to redefine core functionality
2. **init.lua should only extend** - Not duplicate or override core commands
3. **Emacs-compatible keybindings** - C-s = isearch, C-x C-s = save, etc.
4. **Proper mode system namespace** - Use `lumacs.*` to avoid global pollution
5. **All essential Emacs commands** - navigation, editing, mark/region, etc.

### Issues

| # | Issue | Status | Notes |
|---|-------|--------|-------|
| 7.1 | Rewrite defaults.hpp with complete Emacs defaults | 🟢 Completed | 60+ commands, 50+ keybindings, ~950 lines |
| 7.2 | Fix C-s binding (isearch-forward not save) | 🟢 Completed | C-s=isearch, C-x C-s=save |
| 7.3 | Add keyboard-quit (C-g) | 🟢 Completed | Deactivates mark, cancels operations |
| 7.4 | Add missing Emacs commands | 🟢 Completed | open-line, transpose-chars/words/lines, delete-indentation |
| 7.5 | Namespace mode system under lumacs.* | 🟢 Completed | lumacs.major_modes, lumacs.minor_modes, etc. |
| 7.6 | Simplify init.lua to extend-only | 🟢 Completed | Reduced from 1434 to ~200 lines |
| 7.7 | Add recenter command (C-l) | 🟢 Completed | Placeholder - needs C++ viewport support |
| 7.8 | Add what-cursor-position (C-x =) | 🟢 Completed | Shows line, column, character info |

### Implementation Details (Phase 7)

**defaults.hpp now includes:**
- Complete mode system (`lumacs.define_major_mode`, `lumacs.define_minor_mode`, etc.)
- Fundamental mode with default comment syntax
- All core navigation commands (C-n/p/f/b, M-f/b, C-v/M-v, M-</>)
- Mark and region operations (C-@, C-x C-x, C-x h)
- Kill ring operations (C-k, C-w, M-w, C-y, M-y, M-d, M-Backspace)
- Case conversion (M-u, M-l, M-c, C-x C-u, C-x C-l)
- Transpose commands (C-t, M-t, C-x C-t)
- Window management (C-x 0/1/2/3, C-x o)
- Buffer management (C-x b, C-x k, C-x C-b)
- File operations (C-x C-f, C-x C-s)
- ISearch (C-s, C-r)
- Registers (C-x r s, C-x r i)
- Rectangles (C-x r k, C-x r y, C-x r t)
- Keyboard macros (F3, F4)
- Comment DWIM (M-;)
- Self-insert command for printable characters

**init.lua now only contains:**
- Major mode loading (lua_mode, c_cpp_mode)
- Theme loading (9 themes)
- User-defined minor modes (auto-save, line-numbers)
- Custom keybindings (C-c prefix)
- Custom commands (auto-theme, eval-expression)
- Configuration overrides section

### Change Log (Phase 7)

| Date | Issue # | Description | Build Status |
|------|---------|-------------|--------------|
| 2025-12-04 | 7.1-7.8 | Complete Lua integration overhaul | ✅ Pass (32 tests) |

---

## Phase 8: Platform Compatibility and Stability (December 2024)

Focused on ensuring Lumacs runs correctly on different platforms and configurations, addressing critical bugs and conflicts.

### Issues

| # | Issue | Status | Notes |
|---|-------|--------|-------|
| 8.1 | Fix GTK3/GTK4 Conflict with Raylib | 🟢 Completed | Split binary into `lumacs` (GTK) and `lumacs-raylib` (Raylib) |

### Change Log (Phase 8)

| Date | Issue # | Description | Build Status |
|------|---------|-------------|--------------|
| 2025-12-26 | 8.1 | Resolved GTK3 (Raylib) vs GTK4 (Lumacs) symbol conflict by creating separate `lumacs` and `lumacs-raylib` binaries. Refactored `gtk_editor` to isolate GTK dependencies. | ✅ Pass |