Initial Commit

1 files changed, 636 insertions, 0 deletions

diff --git a/docs/PLATFORM_IMPLEMENTATION.md b/docs/PLATFORM_IMPLEMENTATION.md
new file mode 100644
index 0000000..4e70767
--- /dev/null
+++ b/docs/PLATFORM_IMPLEMENTATION.md
@@ -0,0 +1,636 @@
+# SRDWM Platform Implementation Guide
+
+## Overview
+This document outlines the proper implementation approach for each platform, recognizing that **Wayland/XWayland is fundamentally different from X11** and requires completely different technologies and approaches.
+
+## Platform Architecture Differences
+
+### Linux: X11 vs Wayland
+- **X11**: Traditional X11 window management with Xlib/XCB
+- **Wayland**: Modern display protocol requiring wlroots or similar compositor framework
+- **XWayland**: X11 applications running on Wayland (requires special handling)
+
+### Windows vs macOS vs Linux
+- **Windows**: Win32 API with global hooks and window subclassing
+- **macOS**: Core Graphics/AppKit with accessibility APIs and event taps
+- **Linux**: X11 or Wayland with different event systems
+
+## Linux Implementation
+
+### X11 Backend
+```cpp
+// X11-specific implementation using Xlib/XCB
+class X11Platform : public Platform {
+private:
+    Display* display_;
+    Window root_;
+    std::map<Window, Window*> window_map_;
+    
+public:
+    bool initialize() override {
+        display_ = XOpenDisplay(nullptr);
+        if (!display_) return false;
+        
+        root_ = DefaultRootWindow(display_);
+        setup_event_handling();
+        return true;
+    }
+    
+    void setup_event_handling() {
+        // X11 event masks and handlers
+        XSelectInput(display_, root_, 
+            SubstructureRedirectMask | SubstructureNotifyMask |
+            KeyPressMask | KeyReleaseMask |
+            ButtonPressMask | ButtonReleaseMask |
+            PointerMotionMask);
+    }
+    
+    bool poll_events(std::vector<Event>& events) override {
+        XEvent xevent;
+        while (XPending(display_)) {
+            XNextEvent(display_, &xevent);
+            convert_x11_event(xevent, events);
+        }
+        return true;
+    }
+    
+    void convert_x11_event(const XEvent& xevent, std::vector<Event>& events) {
+        switch (xevent.type) {
+            case MapRequest:
+                handle_map_request(xevent.xmaprequest);
+                break;
+            case ConfigureRequest:
+                handle_configure_request(xevent.xconfigurerequest);
+                break;
+            case KeyPress:
+                handle_key_press(xevent.xkey);
+                break;
+            // ... other event types
+        }
+    }
+};
+```
+
+### Wayland Backend (using wlroots)
+```cpp
+// Wayland implementation using wlroots
+class WaylandPlatform : public Platform {
+private:
+    struct wl_display* display_;
+    struct wlroots_backend* backend_;
+    struct wlroots_compositor* compositor_;
+    struct wlroots_output* output_;
+    struct wlroots_input_device* input_device_;
+    
+public:
+    bool initialize() override {
+        // Initialize wlroots backend
+        backend_ = wlroots_backend_create();
+        if (!backend_) return false;
+        
+        // Create compositor
+        compositor_ = wlroots_compositor_create(backend_);
+        if (!compositor_) return false;
+        
+        // Setup output and input
+        setup_output();
+        setup_input();
+        
+        return true;
+    }
+    
+    void setup_output() {
+        // Create and configure output
+        output_ = wlroots_output_create(compositor_);
+        wlroots_output_set_mode(output_, 1920, 1080, 60);
+        wlroots_output_commit(output_);
+    }
+    
+    void setup_input() {
+        // Setup input devices
+        input_device_ = wlroots_input_device_create(compositor_);
+        wlroots_input_device_set_capabilities(input_device_, 
+            WLROOTS_INPUT_DEVICE_CAP_KEYBOARD | 
+            WLROOTS_INPUT_DEVICE_CAP_POINTER);
+    }
+    
+    bool poll_events(std::vector<Event>& events) override {
+        // wlroots event loop
+        wlroots_backend_dispatch(backend_);
+        
+        // Process wlroots events
+        struct wlroots_event* event;
+        while ((event = wlroots_backend_get_event(backend_))) {
+            convert_wlroots_event(event, events);
+            wlroots_event_destroy(event);
+        }
+        
+        return true;
+    }
+    
+    void convert_wlroots_event(struct wlroots_event* event, std::vector<Event>& events) {
+        switch (wlroots_event_get_type(event)) {
+            case WLROOTS_EVENT_NEW_SURFACE:
+                handle_new_surface(event);
+                break;
+            case WLROOTS_EVENT_SURFACE_COMMIT:
+                handle_surface_commit(event);
+                break;
+            case WLROOTS_EVENT_KEYBOARD_KEY:
+                handle_keyboard_key(event);
+                break;
+            // ... other event types
+        }
+    }
+};
+```
+
+### XWayland Support
+```cpp
+// XWayland support for running X11 apps on Wayland
+class XWaylandManager {
+private:
+    struct wlroots_xwayland* xwayland_;
+    struct wlroots_xwayland_server* xwayland_server_;
+    
+public:
+    bool initialize(struct wlroots_compositor* compositor) {
+        // Create XWayland server
+        xwayland_server_ = wlroots_xwayland_server_create(compositor);
+        if (!xwayland_server_) return false;
+        
+        // Setup XWayland
+        xwayland_ = wlroots_xwayland_create(xwayland_server_);
+        if (!xwayland_) return false;
+        
+        return true;
+    }
+    
+    void handle_xwayland_surface(struct wlroots_surface* surface) {
+        // Handle X11 windows running on Wayland
+        // These need special treatment for proper integration
+    }
+};
+```
+
+## Windows Implementation
+
+### Win32 API Integration
+```cpp
+// Windows implementation using Win32 API
+class WindowsPlatform : public Platform {
+private:
+    HINSTANCE h_instance_;
+    std::map<HWND, Window*> window_map_;
+    HHOOK keyboard_hook_;
+    HHOOK mouse_hook_;
+    
+public:
+    bool initialize() override {
+        h_instance_ = GetModuleHandle(nullptr);
+        
+        // Register window class
+        if (!register_window_class()) return false;
+        
+        // Setup global hooks
+        setup_global_hooks();
+        
+        return true;
+    }
+    
+    bool register_window_class() {
+        WNDCLASSEX wc = {};
+        wc.cbSize = sizeof(WNDCLASSEX);
+        wc.lpfnWndProc = window_proc;
+        wc.hInstance = h_instance_;
+        wc.lpszClassName = L"SRDWM_Window";
+        wc.hCursor = LoadCursor(nullptr, IDC_ARROW);
+        
+        return RegisterClassEx(&wc) != 0;
+    }
+    
+    void setup_global_hooks() {
+        // Global keyboard hook
+        keyboard_hook_ = SetWindowsHookEx(WH_KEYBOARD_LL, 
+            keyboard_proc, h_instance_, 0);
+        
+        // Global mouse hook
+        mouse_hook_ = SetWindowsHookEx(WH_MOUSE_LL, 
+            mouse_proc, h_instance_, 0);
+    }
+    
+    static LRESULT CALLBACK window_proc(HWND hwnd, UINT msg, 
+                                       WPARAM wparam, LPARAM lparam) {
+        switch (msg) {
+            case WM_CREATE:
+                // Handle window creation
+                break;
+            case WM_DESTROY:
+                // Handle window destruction
+                break;
+            case WM_SIZE:
+                // Handle window resizing
+                break;
+            // ... other messages
+        }
+        return DefWindowProc(hwnd, msg, wparam, lparam);
+    }
+    
+    static LRESULT CALLBACK keyboard_proc(int nCode, WPARAM wparam, LPARAM lparam) {
+        if (nCode >= 0) {
+            KBDLLHOOKSTRUCT* kbhs = (KBDLLHOOKSTRUCT*)lparam;
+            // Handle global keyboard events
+            handle_global_keyboard(wparam, kbhs);
+        }
+        return CallNextHookEx(nullptr, nCode, wparam, lparam);
+    }
+    
+    static LRESULT CALLBACK mouse_proc(int nCode, WPARAM wparam, LPARAM lparam) {
+        if (nCode >= 0) {
+            MSLLHOOKSTRUCT* mhs = (MSLLHOOKSTRUCT*)lparam;
+            // Handle global mouse events
+            handle_global_mouse(wparam, mhs);
+        }
+        return CallNextHookEx(nullptr, nCode, wparam, lparam);
+    }
+};
+```
+
+## macOS Implementation
+
+### Core Graphics/AppKit Integration
+```cpp
+// macOS implementation using Core Graphics and AppKit
+class MacOSPlatform : public Platform {
+private:
+    CGEventTap event_tap_;
+    std::map<CGWindowID, Window*> window_map_;
+    
+public:
+    bool initialize() override {
+        // Request accessibility permissions
+        if (!request_accessibility_permissions()) return false;
+        
+        // Setup event tap
+        setup_event_tap();
+        
+        // Setup window monitoring
+        setup_window_monitoring();
+        
+        return true;
+    }
+    
+    bool request_accessibility_permissions() {
+        // Check if accessibility is enabled
+        const void* keys[] = { kAXTrustedCheckOptionPrompt };
+        const void* values[] = { kCFBooleanTrue };
+        
+        CFDictionaryRef options = CFDictionaryCreate(
+            kCFAllocatorDefault, keys, values, 1, nullptr, nullptr);
+        
+        bool trusted = AXIsProcessTrustedWithOptions(options);
+        CFRelease(options);
+        
+        return trusted;
+    }
+    
+    void setup_event_tap() {
+        // Create event tap for global events
+        event_tap_ = CGEventTapCreate(
+            kCGSessionEventTap,
+            kCGHeadInsertEventTap,
+            kCGEventTapOptionDefault,
+            CGEventMaskBit(kCGEventKeyDown) | 
+            CGEventMaskBit(kCGEventKeyUp) |
+            CGEventMaskBit(kCGEventLeftMouseDown) |
+            CGEventMaskBit(kCGEventLeftMouseUp) |
+            CGEventMaskBit(kCGEventMouseMoved),
+            event_tap_callback,
+            this);
+        
+        if (event_tap_) {
+            CFRunLoopSourceRef run_loop_source = 
+                CFMachPortCreateRunLoopSource(kCFAllocatorDefault, event_tap_, 0);
+            CFRunLoopAddSource(CFRunLoopGetCurrent(), run_loop_source, kCFRunLoopCommonModes);
+            CGEventTapEnable(event_tap_, true);
+        }
+    }
+    
+    static CGEventRef event_tap_callback(CGEventTapProxy proxy, CGEventType type, 
+                                        CGEventRef event, void* user_info) {
+        MacOSPlatform* platform = static_cast<MacOSPlatform*>(user_info);
+        return platform->handle_event_tap(proxy, type, event);
+    }
+    
+    CGEventRef handle_event_tap(CGEventTapProxy proxy, CGEventType type, CGEventRef event) {
+        switch (type) {
+            case kCGEventKeyDown:
+                handle_key_event(event, true);
+                break;
+            case kCGEventKeyUp:
+                handle_key_event(event, false);
+                break;
+            case kCGEventLeftMouseDown:
+                handle_mouse_event(event, true);
+                break;
+            case kCGEventLeftMouseUp:
+                handle_mouse_event(event, false);
+                break;
+            case kCGEventMouseMoved:
+                handle_mouse_motion(event);
+                break;
+        }
+        return event;
+    }
+    
+    void setup_window_monitoring() {
+        // Monitor window creation/destruction
+        CGWindowListCopyWindowInfo(kCGWindowListOptionOnScreenOnly | 
+                                  kCGWindowListExcludeDesktopElements, 
+                                  kCGNullWindowID);
+    }
+};
+```
+
+## Platform Detection and Selection
+
+### Automatic Platform Detection
+```cpp
+// Platform factory with automatic detection
+class PlatformFactory {
+public:
+    static std::unique_ptr<Platform> create_platform() {
+        #ifdef _WIN32
+            return std::make_unique<WindowsPlatform>();
+        #elif defined(__APPLE__)
+            return std::make_unique<MacOSPlatform>();
+        #else
+            // Linux: detect X11 vs Wayland
+            return detect_linux_platform();
+        #endif
+    }
+    
+private:
+    static std::unique_ptr<Platform> detect_linux_platform() {
+        // Check environment variables
+        const char* wayland_display = std::getenv("WAYLAND_DISPLAY");
+        const char* xdg_session_type = std::getenv("XDG_SESSION_TYPE");
+        
+        if (wayland_display || (xdg_session_type && strcmp(xdg_session_type, "wayland") == 0)) {
+            // Try Wayland first
+            auto wayland_platform = std::make_unique<WaylandPlatform>();
+            if (wayland_platform->initialize()) {
+                std::cout << "Using Wayland backend" << std::endl;
+                return wayland_platform;
+            }
+            std::cout << "Wayland initialization failed, falling back to X11" << std::endl;
+        }
+        
+        // Fall back to X11
+        auto x11_platform = std::make_unique<X11Platform>();
+        if (x11_platform->initialize()) {
+            std::cout << "Using X11 backend" << std::endl;
+            return x11_platform;
+        }
+        
+        std::cerr << "Failed to initialize any platform backend" << std::endl;
+        return nullptr;
+    }
+};
+```
+
+## Dependencies and Build System
+
+### CMake Configuration
+```cmake
+# Platform-specific dependencies
+if(WIN32)
+    # Windows dependencies
+    find_package(PkgConfig REQUIRED)
+    set(PLATFORM_LIBS user32 gdi32)
+    
+elseif(APPLE)
+    # macOS dependencies
+    find_library(COCOA_LIBRARY Cocoa)
+    find_library(CARBON_LIBRARY Carbon)
+    find_library(IOKIT_LIBRARY IOKit)
+    set(PLATFORM_LIBS ${COCOA_LIBRARY} ${CARBON_LIBRARY} ${IOKIT_LIBRARY})
+    
+else()
+    # Linux dependencies
+    find_package(PkgConfig REQUIRED)
+    
+    # X11 dependencies
+    pkg_check_modules(X11 REQUIRED x11 xcb xcb-keysyms)
+    
+    # Wayland dependencies (optional)
+    pkg_check_modules(WAYLAND wayland-client wayland-cursor)
+    pkg_check_modules(WLROOTS wlroots)
+    
+    if(WAYLAND_FOUND AND WLROOTS_FOUND)
+        add_definitions(-DWAYLAND_ENABLED)
+        set(PLATFORM_LIBS ${PLATFORM_LIBS} ${WAYLAND_LIBRARIES} ${WLROOTS_LIBRARIES})
+    endif()
+    
+    set(PLATFORM_LIBS ${PLATFORM_LIBS} ${X11_LIBRARIES})
+endif()
+```
+
+### Package Dependencies
+```bash
+# Ubuntu/Debian
+sudo apt install libx11-dev libxcb1-dev libxcb-keysyms1-dev
+sudo apt install libwayland-dev libwlroots-dev
+
+# Arch Linux
+sudo pacman -S xorg-server-devel wayland wlroots
+
+# Fedora
+sudo dnf install libX11-devel libxcb-devel wayland-devel wlroots-devel
+```
+
+## Event Handling Differences
+
+### X11 Event System
+```cpp
+// X11 events are synchronous and direct
+void X11Platform::handle_map_request(const XMapRequestEvent& event) {
+    Window* window = create_window(event.window);
+    if (window) {
+        window_map_[event.window] = window;
+        // X11 window is now managed
+    }
+}
+```
+
+### Wayland Event System
+```cpp
+// Wayland events are asynchronous and callback-based
+void WaylandPlatform::handle_new_surface(struct wlroots_event* event) {
+    struct wlroots_surface* surface = wlroots_event_get_surface(event);
+    
+    // Create window for new surface
+    Window* window = create_window_from_surface(surface);
+    if (window) {
+        surface_window_map_[surface] = window;
+    }
+}
+```
+
+### Windows Event System
+```cpp
+// Windows uses message-based event system
+LRESULT WindowsPlatform::window_proc(HWND hwnd, UINT msg, WPARAM wparam, LPARAM lparam) {
+    switch (msg) {
+        case WM_CREATE:
+            // Window creation
+            break;
+        case WM_DESTROY:
+            // Window destruction
+            break;
+    }
+    return DefWindowProc(hwnd, msg, wparam, lparam);
+}
+```
+
+### macOS Event System
+```cpp
+// macOS uses event taps and accessibility APIs
+CGEventRef MacOSPlatform::handle_event_tap(CGEventTapProxy proxy, CGEventType type, CGEventRef event) {
+    switch (type) {
+        case kCGEventKeyDown:
+            // Handle key press
+            break;
+        case kCGEventMouseMoved:
+            // Handle mouse movement
+            break;
+    }
+    return event;
+}
+```
+
+## Window Management Differences
+
+### X11 Window Management
+```cpp
+// X11: Direct window manipulation
+void X11Platform::set_window_position(Window* window, int x, int y) {
+    XMoveWindow(display_, window->get_x11_handle(), x, y);
+}
+
+void X11Platform::set_window_size(Window* window, int width, int height) {
+    XResizeWindow(display_, window->get_x11_handle(), width, height);
+}
+```
+
+### Wayland Window Management
+```cpp
+// Wayland: Surface-based management
+void WaylandPlatform::set_window_position(Window* window, int x, int y) {
+    struct wlroots_surface* surface = window->get_wayland_surface();
+    wlroots_surface_set_position(surface, x, y);
+}
+
+void WaylandPlatform::set_window_size(Window* window, int width, int height) {
+    struct wlroots_surface* surface = window->get_wayland_surface();
+    wlroots_surface_set_size(surface, width, height);
+}
+```
+
+### Windows Window Management
+```cpp
+// Windows: Win32 API calls
+void WindowsPlatform::set_window_position(Window* window, int x, int y) {
+    HWND hwnd = window->get_win32_handle();
+    SetWindowPos(hwnd, nullptr, x, y, 0, 0, 
+                 SWP_NOSIZE | SWP_NOZORDER | SWP_NOACTIVATE);
+}
+
+void WindowsPlatform::set_window_size(Window* window, int width, int height) {
+    HWND hwnd = window->get_win32_handle();
+    SetWindowPos(hwnd, nullptr, 0, 0, width, height, 
+                 SWP_NOMOVE | SWP_NOZORDER | SWP_NOACTIVATE);
+}
+```
+
+### macOS Window Management
+```cpp
+// macOS: Core Graphics API calls
+void MacOSPlatform::set_window_position(Window* window, int x, int y) {
+    CGWindowID window_id = window->get_macos_window_id();
+    CGPoint position = CGPointMake(x, y);
+    
+    // Use accessibility APIs to move window
+    AXUIElementRef element = AXUIElementCreateApplication(
+        window->get_macos_pid());
+    
+    if (element) {
+        AXUIElementSetAttributeValue(element, kAXPositionAttribute, &position);
+        CFRelease(element);
+    }
+}
+```
+
+## Testing and Validation
+
+### Platform-Specific Testing
+```cpp
+// Test each platform independently
+class PlatformTest {
+public:
+    static void test_x11_platform() {
+        auto platform = std::make_unique<X11Platform>();
+        assert(platform->initialize());
+        // Test X11-specific functionality
+    }
+    
+    static void test_wayland_platform() {
+        auto platform = std::make_unique<WaylandPlatform>();
+        assert(platform->initialize());
+        // Test Wayland-specific functionality
+    }
+    
+    static void test_windows_platform() {
+        auto platform = std::make_unique<WindowsPlatform>();
+        assert(platform->initialize());
+        // Test Windows-specific functionality
+    }
+    
+    static void test_macos_platform() {
+        auto platform = std::make_unique<MacOSPlatform>();
+        assert(platform->initialize());
+        // Test macOS-specific functionality
+    }
+};
+```
+
+## Best Practices
+
+### 1. **Platform Abstraction**
+- Keep platform-specific code isolated
+- Use common interfaces for cross-platform functionality
+- Implement platform detection automatically
+
+### 2. **Wayland vs X11**
+- **Never mix X11 and Wayland APIs**
+- Use wlroots for Wayland (don't implement from scratch)
+- Handle XWayland as a special case within Wayland
+
+### 3. **Event Handling**
+- Respect each platform's event model
+- Don't force synchronous behavior on asynchronous platforms
+- Handle platform-specific quirks gracefully
+
+### 4. **Window Management**
+- Use platform-native APIs for best performance
+- Don't try to emulate one platform's behavior on another
+- Handle platform-specific window states properly
+
+### 5. **Testing**
+- Test each platform independently
+- Use CI/CD with multiple platform targets
+- Validate platform-specific features thoroughly
+
+This implementation approach ensures that SRDWM works correctly on each platform while respecting the fundamental differences between X11, Wayland, Windows, and macOS.
+
+