# 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).
- ✅ **Theme System**: Comprehensive and functional.
- ✅ **Phase 15 Polishing**: Successfully addressed GTK Cleanup and Modeline Refactor.
- ✅ **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.
- ✅ **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**: `GtkCompletionPopup` logic is stubbed to fix build; needs full GTK4 migration (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.