Lumacs/documentation/PLAN.md

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

• Expand test coverage for existing components: LuaApi, CommandSystem, and Window.
• Implement integration tests to verify component interactions.
• Phase 3: Logging and Observability (Integrate spdlog, replace std::cerr).
• Phase 4: Dependency Management (Review sol2 dependency).
• 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.
  • GTK Completion Popover: Disabled by default via Lua configuration (user request).
  • Persistent Messages: Implemented *Messages* buffer to log all minibuffer outputs, ensuring history is accessible via buffer switching.
  • File Path Completion: Implemented robust file path autocompletion with tilde expansion and directory browsing.
  • 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.
  • 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.
  • File Loading Robustness: Fixed crash on non-existent files and added support for creating new files via open command.
• ✅ Theme System Refactoring:
  • Implemented editor:create_and_register_theme Lua API to allow theme definition from Lua.
  • Factored all hardcoded C++ themes (default, everforest-dark, dracula, solarized-dark, nord, gruvbox-light) into individual Lua files (lua/themes/*.lua).
  • Removed hardcoded theme definitions and factory methods from C++ (src/theme.cpp, include/lumacs/theme.hpp).
  • Updated init.lua to load the new individual theme files and themes_init.lua.
  • 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.
  • GTK Modeline: Fixed modeline not showing in GTK frontend and ensured per-window rendering.
  • 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 activewindow 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, 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