docs: Add GUI Frontend Roadmap for GTK4 (gtkmm)

documentation/GUI_ROADMAP.md

@@ -0,0 +1,91 @@
+# GUI Frontend Roadmap: Lumacs with GTK4 (gtkmm)
+
+This document outlines the phased approach to integrate a graphical frontend into Lumacs, utilizing GTK4 with its C++ bindings (gtkmm). The goal is to provide a rich, native user experience while leveraging the existing C++ core and Lua extensibility.
+
+## Phase 0: Preparation (Current State)
+
+*   **Status**: Complete
+*   **Description**: Core editor logic (EditorCore, Buffer) is decoupled from the UI. An abstract `Face` system is implemented, allowing for UI-agnostic styling definitions.
+*   **Key Achievements**:
+    *   Abstract `Face` system in `include/lumacs/face.hpp`
+    *   `Theme` system refactored to manage `Face` definitions
+    *   `Buffer` stores `face_name` for styling ranges
+    *   `NcursesEditor` renders Faces to best of its ability (colors, bold, italic)
+
+## Phase 1: Abstract UI Interface Extraction
+
+*   **Goal**: Define a clean separation between `EditorCore` and any UI frontend.
+*   **Tasks**:
+    1.  **Define `IEditorView` Interface**: Create an abstract base class (e.g., `IEditorView` or `EditorFrontend`) in `include/lumacs/ui_interface.hpp` that `EditorCore` will interact with. This interface will declare methods for:
+        *   Receiving buffer content updates.
+        *   Receiving cursor position changes.
+        *   Receiving messages.
+        *   Requesting input (e.g., for minibuffer).
+        *   Triggering UI mode changes (Command, FindFile, etc.).
+        *   Rendering updates.
+    2.  **Refactor `NcursesEditor`**:
+        *   Rename `NcursesEditor` to `TuiEditor`.
+        *   Make `TuiEditor` implement `IEditorView`.
+        *   Modify `EditorCore` to hold a pointer/reference to `IEditorView` instead of tightly coupled `NcursesEditor` logic.
+        *   Update `main.cpp` (or `main_ncurses.cpp`) to instantiate `TuiEditor` and pass it to `EditorCore`.
+    3.  **Refine `EditorEvent` Usage**: Ensure `EditorCore` communicates solely via `IEditorView` or its existing event system (`EditorEvent`).
+*   **Output**: A decoupled `EditorCore` that can interact with any `IEditorView` implementation.
+*   **Dependencies**: Existing C++ codebase.
+
+## Phase 2: GTK4 Environment Setup & Basic Window
+
+*   **Goal**: Integrate GTK4 into the build system and display a minimal window.
+*   **Tasks**:
+    1.  **Update `CMakeLists.txt`**: Add `find_package(PkgConfig REQUIRED)` and `pkg_check_modules(GTKMM REQUIRED gtkmm-4.0)`. Add GTKMM include directories and link libraries.
+    2.  **Create `main_gtk.cpp`**: A new entry point for the GTK frontend.
+    3.  **Implement `GtkEditor` Stub**: Create a placeholder class `GtkEditor` that inherits from `IEditorView`.
+    4.  **Basic GTK Window**: In `main_gtk.cpp`, initialize GTK, create a simple `Gtk::Application` and `Gtk::Window`, and show it.
+    5.  **Conditional Build**: Configure CMake to allow building either `lumacs` (TUI) or `lumacs-gtk` (GUI) executables based on a flag (e.g., `-DBUILD_GUI=ON`).
+*   **Output**: A separate `lumacs-gtk` executable that opens an empty GTK window.
+*   **Dependencies**: `gtkmm-4.0` development libraries.
+
+## Phase 3: Displaying Buffer Content
+
+*   **Goal**: Render the active buffer's text content within the GTK window.
+*   **Tasks**:
+    1.  **`Gtk::DrawingArea`**: Use a `Gtk::DrawingArea` to draw text.
+    2.  **Pango/Cairo Integration**: Learn how to use Pango for text layout and Cairo for drawing on the `DrawingArea`.
+    3.  **Text Display**: Get the current buffer content from `EditorCore` and render it.
+    4.  **Scrolling**: Implement basic vertical scrolling.
+*   **Output**: A GTK window displaying the text of the active buffer.
+*   **Dependencies**: `Pango`, `Cairo`.
+
+## Phase 4: Styling with Faces
+
+*   **Goal**: Implement the `Face` system within `GtkEditor` to render styled text.
+*   **Tasks**:
+    1.  **Pango Attributes**: Map Lumacs `FaceAttributes` to Pango attributes (foreground, background, weight, slant, underline, font family, font size).
+    2.  **Styled Text Rendering**: Iterate through `StyledRange` objects from the `Buffer` and apply the corresponding Pango attributes before drawing text segments.
+    3.  **Theme Integration**: Ensure the active theme's face definitions are applied to the rendered text.
+*   **Output**: A GTK window displaying syntax-highlighted and styled text according to the active theme.
+
+## Phase 5: Input Handling & Minibuffer
+
+*   **Goal**: Capture keyboard input and integrate with the minibuffer and other interactive UI elements.
+*   **Tasks**:
+    1.  **Keyboard Input**: Connect GTK keyboard events to `EditorCore`'s key processing.
+    2.  **Cursor Display**: Render a blinking cursor in the `DrawingArea`.
+    3.  **Minibuffer Input**: Implement a `Gtk::Entry` for the minibuffer (command input, find file, etc.).
+    4.  **Completion Popup**: Implement a GTK popup for minibuffer completion suggestions.
+*   **Output**: Fully interactive text editor with working cursor and minibuffer.
+
+## Phase 6: Full UI Feature Parity
+
+*   **Goal**: Implement all existing features of `TuiEditor` (window splits, status lines, messages, marks, regions) in `GtkEditor`.
+*   **Tasks**:
+    1.  **Status Line/Modelines**: Render status bars for each window.
+    2.  **Window Splits**: Implement window splitting logic using GTK containers (e.g., `Gtk::Paned` or `Gtk::Grid`).
+    3.  **Selection/Regions**: Visually render active text selections.
+    4.  **Context Menus/Dialogs**: Implement GTK equivalents for any UI popups.
+*   **Output**: A fully functional GUI frontend with feature parity to the TUI.
+
+## Future Considerations
+
+*   **High-DPI Support**: Ensure crisp rendering on high-resolution displays.
+*   **Accessibility**: Integrate with GTK's accessibility features.
+*   **Native File Dialogs**: Use `Gtk::FileChooserDialog` for `find-file` and `save-as`.