# Lumacs Architecture

## Overview

Lumacs is a modular, extensible text editor engine inspired by Emacs, written in C++20 and scriptable via Lua 5.4. It strictly separates core logic from the user interface, allowing for multiple frontends (GTK4, TUI).

## High-Level Design

The system follows a **Core-Manager-View** architecture. The `EditorCore` acts as the central hub but delegates actual logic to specialized Manager classes. Dependencies are managed via Dependency Injection (DI) and interfaces to prevent circular coupling.

```mermaid
graph TD
    User[User Input] -->|Events| UI[UI Frontend]
    UI -->|Key Strings| LuaAPI[Lua API]
    LuaAPI -->|Process| KeyBinding[KeyBindingManager]
    KeyBinding -->|Command Name| CommandSystem[CommandSystem]
    CommandSystem -->|Execute| Core[EditorCore]
    
    %% Gave subgraph a unique ID 'CoreSystem' and a label string
    subgraph CoreSystem ["Core Subsystems"]
        Core -->|Delegate| BufferMgr[BufferManager]
        Core -->|Delegate| WindowMgr[WindowManager]
        Core -->|Delegate| MinibufferMgr[MinibufferManager]
        Core -->|Delegate| MacroMgr[MacroManager]
        Core -->|Delegate| PluginMgr[PluginManager]
        Core -->|Delegate| ThemeMgr[ThemeManager]
    end
    
    BufferMgr -->|Manage| Buffer[Buffer]
    WindowMgr -->|Manage| Window[Window]
    
    Core -.->|Notify| IEditorNotifier
    IEditorNotifier -.-> UI
    
    UI -->|Render| Renderer["Renderer (GTK/TUI)"]
    Renderer -->|Read| Buffer
```

## Core Components

### 1. EditorCore (`editor_core.hpp`)
The application root.
- **Role**: Owner of all Manager subsystems.
- **Interfaces**: Implements `IEditorNotifier` (events) and `IWindowManager` (layout access) and `ICommandTarget`.
- **State**: Holds the global editor configuration and delegates functionality to managers.

### 2. Managers (The Logic Layer)
Functionality is partitioned into specialized managers:
- **`BufferManager`**: Creates, loads, and manages the lifecycle of `Buffer` objects.
- **`WindowManager`**: Manages the window layout tree (`LayoutNode`), splits, and focus.
- **`CommandSystem`**: Registry of commands (C++ and Lua). Handles execution and interactive argument reading.
- **`KeyBindingManager`**: Trie-based key sequence resolution. Maps `C-x C-f` -> `find-file`.
- **`MinibufferManager`**: Handles the command line / prompt area logic, including completion and interactive search (ISearch).
- **`MacroManager`**: Records and plays back keyboard macros.
- **`PluginManager`**: Discovers and loads Lua plugins.
- **`ThemeManager`**: Manages color themes and face definitions.
- **`KillRingManager`**: Manages the kill ring (clipboard history).
- **`RegisterManager`**: Manages text registers.
- **`RectangleManager`**: Handles rectangular edit operations.

### 3. Data Structures
- **`Buffer`**: Stores text as a list of strings (Gap Buffer concept abstract). Manages syntax highlighting (`StyledRange`), undo/redo stack, and mark/region.
- **`Window`**: A view into a buffer. Tracks cursor position (`Position`) and scroll viewport (`Viewport`).
- **`LayoutNode`**: A node in the binary tree representing window splits.

### 4. Interfaces & Decoupling
To avoid circular dependencies (e.g., `BufferManager` needing `EditorCore` needing `BufferManager`), we use interfaces:
- **`IEditorNotifier`**: Allows subsystems to emit events (`BufferModified`, `Message`) without knowing about `EditorCore`.
- **`IWindowManager`**: Allows `BufferManager` to query window state without depending on the concrete `WindowManager`.
- **`ICommandTarget`**: Abstract interface for objects that can receive commands.
- **`IEditorView`**: Abstract base for UI frontends.

### 5. Lua Integration (`lua_api.cpp`)
- **Binding**: Uses `sol2` to bind C++ classes (`EditorCore`, `Buffer`, `Window`, `Config`, `Theme`) to Lua.
- **Initialization Cascade**:
    1.  **Baked-in Defaults (`src/defaults.hpp`)**: Loads essential keybindings and mode infrastructure from binary memory. Ensures the editor is always functional.
    2.  **User Config (`init.lua`)**: Loads the user's configuration file (if found), overriding defaults.
- **Extension**: `init.lua` (and the embedded defaults) implements the "Standard Library" of the editor (Major Modes, default keybindings).

## User Interface (Frontends)

### GTK4 Frontend (`src/ui/`)
- **`GtkEditor`**: The main application window. Handles input events and forwards them to Core.
- **`GtkRenderer`**: High-performance text renderer using **Cairo** and **Pango**.
    - **Caching**: Implements a line-based cache (`Cairo::ImageSurface`) to minimize Pango layout re-computation.
    - **Layers**: Background -> Cached Text -> Syntax Highlighting -> Selection -> Cursor.
- **`GtkCompletionPopup`**: A `Gtk::Popover` widget for showing autocompletion candidates.

### TUI Frontend
- **`TuiEditor`**: Ncurses-based fallback. Renders text grid and handles terminal input sequences.

## Event Flow (The "Golden Path")

1.  **Input**: User presses a key (e.g., `C-f`).
2.  **Capture**: `GtkEditor` captures the event via `Gtk::EventControllerKey` (Phase: Capture).
3.  **Normalization**: Key is converted to a string `"C-f"`.
4.  **Processing**: Passed to `LuaApi::process_key` which delegates to `KeyBindingManager::process_key`.
5.  **Resolution**: Trie traversal finds command `"forward-char"`.
6.  **Recording**: If macro recording is active, `KeyBindingManager` notifies `MacroManager`.
7.  **Execution**: `CommandSystem` executes the C++ lambda for `forward-char`.
8.  **Update**: `EditorCore` delegates to method (e.g., `move_right`), which updates the `Window` cursor.
9.  **Notification**: `EditorCore` emits `EditorEvent::CursorMoved`.
10. **Render**: `GtkEditor` receives event, queues redraw. `GtkRenderer` updates the screen.

## Styling System

- **Themes**: JSON-like structures (in C++ or Lua) defining colors for semantic tags (`ThemeElement`).
- **Faces**: Specific style attributes (foreground, background, bold, italic).
- **Application**:
    1.  `Buffer` stores `StyledRange` (semantic tag + range).
    2.  `GtkRenderer` queries the active `Theme` to map tags to Pango attributes.
    3.  Pango renders the text with attributes.

## Build System

- **CMake**: Manages build configuration.
- **Dependencies**:
    - `gtkmm-4.0` (UI)
    - `lua` (Scripting)
    - `sol2` (Bindings)
    - `spdlog` (Logging)
    - `ncurses` (TUI)
    - `gtest` (Testing)