# 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

*   **Status**: Complete
*   **Goal**: Define a clean separation between `EditorCore` and any UI frontend.
*   **Achievements**:
    *   `IEditorView` interface defined in `include/lumacs/ui_interface.hpp`.
    *   `NcursesEditor` refactored to `TuiEditor` implementing `IEditorView`.
    *   `EditorCore` decoupled from specific UI implementation.

## 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`.