`edf725e`

Temporarily track sprint docs for laptop transfer

Authored by

espadonne 4 months ago

SHA: edf725ec24728981e045517f34c61f507c709cbb
Parents: 32aaf43
Tree: 2ae0740

10 changed files

Status	File	+
A	`docs/sprints/sprint-0-setup.md`	135
A	`docs/sprints/sprint-1-basic-wm.md`	198
A	`docs/sprints/sprint-2-smart-split.md`	220
A	`docs/sprints/sprint-3-workspaces.md`	241
A	`docs/sprints/sprint-4-lua-config.md`	279
A	`docs/sprints/sprint-5-floating.md`	271
A	`docs/sprints/sprint-6-ipc.md`	348
A	`docs/sprints/sprint-7-multimonitor.md`	282
A	`docs/sprints/sprint-8-ewmh.md`	427
A	`docs/sprints/sprint-9-mvp-polish.md`	334

docs/sprints/sprint-0-setup.mdadded

 +# Sprint 0: Project Setup
++
 +**Goal:** Buildable skeleton that connects to X server and appears in the display manager greeter.
++
 +## Objectives
++
 +- Initialize Rust project with proper workspace structure
 +- Establish logging and error handling patterns
 +- Connect to X server and become a window manager
 +- Create a stable event loop
 +- Make gar selectable from the login greeter
++
 +## Tasks
++
 +### 0.1 Initialize Cargo Project
 +- [ ] Create `Cargo.toml` with workspace members (gar, garctl)
 +- [ ] Set up `src/main.rs` entry point
 +- [ ] Set up `src/lib.rs` for library code
 +- [ ] Create module structure skeleton
++
 +**Dependencies to add:**
 +```toml
 +[dependencies]
 +x11rb = { version = "0.13", features = ["allow-unsafe-code"] }
 +tracing = "0.1"
 +tracing-subscriber = "0.3"
 +thiserror = "1.0"
 +```
++
 +### 0.2 Logging Infrastructure
 +- [ ] Initialize tracing subscriber in main
 +- [ ] Set up log levels (RUST_LOG environment variable)
 +- [ ] Add structured logging for key events
 +- [ ] Log to file for debugging sessions
++
 +### 0.3 X Server Connection
 +- [ ] Create `src/x11/mod.rs` module
 +- [ ] Create `src/x11/connection.rs`
 +- [ ] Connect to X server using `x11rb::connect()`
 +- [ ] Get root window and screen info
 +- [ ] Handle connection errors gracefully
++
 +**Key code pattern:**
 +```rust
 +use x11rb::connection::Connection;
 +use x11rb::rust_connection::RustConnection;
++
 +pub fn connect() -> Result<(RustConnection, usize), Error> {
 +    let (conn, screen_num) = x11rb::connect(None)?;
 +    Ok((conn, screen_num))
 +}
 +```
++
 +### 0.4 Become Window Manager
 +- [ ] Request SubstructureRedirect on root window
 +- [ ] Handle "another WM running" error gracefully
 +- [ ] Set up necessary event masks on root window
++
 +**Critical X11 concept:** Only ONE client can have SubstructureRedirect on the root window. This is how X11 ensures only one window manager runs.
++
 +```rust
 +let change = ChangeWindowAttributesAux::new()
 +    .event_mask(EventMask::SUBSTRUCTURE_REDIRECT | EventMask::SUBSTRUCTURE_NOTIFY);
 +conn.change_window_attributes(root, &change)?.check()?;
 +```
++
 +### 0.5 Event Loop
 +- [ ] Create `src/x11/events.rs`
 +- [ ] Implement basic event loop structure
 +- [ ] Handle ConfigureRequest (pass through for now)
 +- [ ] Handle MapRequest (map windows for now)
 +- [ ] Log all received events
 +- [ ] Clean shutdown on SIGTERM/SIGINT
++
 +**Event loop pattern:**
 +```rust
 +loop {
 +    let event = conn.wait_for_event()?;
 +    match event {
 +        Event::ConfigureRequest(e) => handle_configure_request(&conn, e)?,
 +        Event::MapRequest(e) => handle_map_request(&conn, e)?,
 +        _ => tracing::trace!("Unhandled event: {:?}", event),
 +    }
 +}
 +```
++
 +### 0.6 Desktop Entry
 +- [ ] Create `gar.desktop` file
 +- [ ] Install to `/usr/share/xsessions/` (or document install location)
 +- [ ] Test selection from GDM/LightDM/SDDM
++
 +**Desktop entry content:**
 +```ini
 +[Desktop Entry]
 +Name=gar
 +Comment=Tiling window manager with smart splits
 +Exec=gar
 +Type=XSession
 +```
++
 +## Acceptance Criteria
++
 +1. `cargo build` succeeds without errors
 +2. `cargo run` connects to X server (or fails gracefully if one isn't available)
 +3. Running in a nested X session (Xephyr) shows gar as the WM
 +4. `gar.desktop` can be created and would appear in a greeter
 +5. Existing windows are not lost (ConfigureRequest/MapRequest passthrough)
 +6. Logs show event activity
++
 +## Testing Strategy
++
 +**Manual testing with Xephyr:**
 +```bash
 +# Terminal 1: Start nested X server
 +Xephyr -br -ac -noreset -screen 1280x720 :1
++
 +# Terminal 2: Run gar in nested session
 +DISPLAY=:1 cargo run
++
 +# Terminal 3: Launch apps in nested session
 +DISPLAY=:1 xterm
 +```
++
 +## Notes
++
 +- Keep this sprint minimal - just enough to have a working foundation
 +- Don't implement actual window management yet (Sprint 1)
 +- Focus on correctness over features
 +- Document any X11 quirks encountered
++
 +## Resources
++
 +- [x11rb documentation](https://docs.rs/x11rb/latest/x11rb/)
 +- [X11 Protocol Reference](https://www.x.org/releases/current/doc/xproto/x11protocol.html)
 +- [ICCCM Spec](https://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/ICCCM/icccm.html)

docs/sprints/sprint-1-basic-wm.mdadded

 +# Sprint 1: Basic Window Management
++
 +**Goal:** Manage windows in a single workspace with manual tiling using a BSP tree.
++
 +## Objectives
++
 +- Track window lifecycle (create, destroy)
 +- Implement Binary Space Partition tree data structure
 +- Tile windows using the BSP tree
 +- Basic focus handling (click-to-focus)
 +- One hardcoded keybind to test input grabbing
++
 +## Prerequisites
++
 +- Sprint 0 complete (X connection, event loop working)
++
 +## Tasks
++
 +### 1.1 Window Tracking
 +- [ ] Create `src/core/window.rs`
 +- [ ] Define `Window` struct to track window state
 +- [ ] Create window registry (HashMap<XWindow, Window>)
 +- [ ] Handle MapRequest: add window to registry
 +- [ ] Handle UnmapNotify: remove window from registry
 +- [ ] Handle DestroyNotify: clean up window
++
 +**Window struct:**
 +```rust
 +pub struct Window {
 +    pub id: x11rb::protocol::xproto::Window,
 +    pub x: i16,
 +    pub y: i16,
 +    pub width: u16,
 +    pub height: u16,
 +    pub mapped: bool,
 +}
 +```
++
 +### 1.2 BSP Tree Data Structure
 +- [ ] Create `src/core/tree.rs`
 +- [ ] Implement `SplitDirection` enum (Horizontal, Vertical)
 +- [ ] Implement `Node` enum (Internal, Leaf)
 +- [ ] Implement tree traversal methods
 +- [ ] Implement node insertion (always vertical for now)
 +- [ ] Implement node removal
 +- [ ] Implement geometry calculation from tree
++
 +**Core tree structure:**
 +```rust
 +#[derive(Debug, Clone, Copy)]
 +pub enum SplitDirection {
 +    Horizontal,  // Top/Bottom
 +    Vertical,    // Left/Right
 +}
++
 +#[derive(Debug)]
 +pub enum Node {
 +    Internal {
 +        split: SplitDirection,
 +        ratio: f32,
 +        left: Box<Node>,
 +        right: Box<Node>,
 +    },
 +    Leaf {
 +        window: Option<WindowId>,
 +    },
 +}
 +```
++
 +### 1.3 Geometry Calculation
 +- [ ] Calculate window geometries from BSP tree
 +- [ ] Pass root geometry (screen size minus any reserved space)
 +- [ ] Recursively divide space based on splits and ratios
 +- [ ] Return list of (WindowId, Rect) pairs
++
 +**Algorithm:**
 +```rust
 +impl Node {
 +    pub fn calculate_geometries(&self, rect: Rect) -> Vec<(WindowId, Rect)> {
 +        match self {
 +            Node::Leaf { window: Some(id) } => vec![(*id, rect)],
 +            Node::Leaf { window: None } => vec![],
 +            Node::Internal { split, ratio, left, right } => {
 +                let (left_rect, right_rect) = rect.split(*split, *ratio);
 +                let mut result = left.calculate_geometries(left_rect);
 +                result.extend(right.calculate_geometries(right_rect));
 +                result
 +            }
 +        }
 +    }
 +}
 +```
++
 +### 1.4 Apply Geometries to X11
 +- [ ] Create function to configure window geometry
 +- [ ] Use `ConfigureWindow` request
 +- [ ] Handle border width in calculations
 +- [ ] Apply all geometries after tree changes
++
 +```rust
 +fn apply_geometry(conn: &impl Connection, window: Window, rect: Rect) -> Result<()> {
 +    let aux = ConfigureWindowAux::new()
 +        .x(rect.x as i32)
 +        .y(rect.y as i32)
 +        .width(rect.width as u32)
 +        .height(rect.height as u32);
 +    conn.configure_window(window, &aux)?;
 +    Ok(())
 +}
 +```
++
 +### 1.5 Window Insertion
 +- [ ] Find the focused leaf node
 +- [ ] Insert new window next to focused window
 +- [ ] If no focused window, insert at root
 +- [ ] Split vertically (for now - smart split is Sprint 2)
 +- [ ] Recalculate and apply all geometries
++
 +### 1.6 Window Removal
 +- [ ] Find and remove window from tree
 +- [ ] Collapse parent if only one child remains
 +- [ ] Handle removing last window (empty tree)
 +- [ ] Update focus to sibling or parent's other child
 +- [ ] Recalculate and apply geometries
++
 +### 1.7 Focus Handling
 +- [ ] Track currently focused window
 +- [ ] Handle ButtonPress on windows (click-to-focus)
 +- [ ] Set input focus using `SetInputFocus`
 +- [ ] Visual feedback: different border color for focused window
 +- [ ] Grab button on unfocused windows, ungrab on focused
++
 +```rust
 +// Set focus
 +conn.set_input_focus(InputFocus::PARENT, window, CURRENT_TIME)?;
++
 +// Visual feedback
 +let border_color = if focused { 0x5294e2 } else { 0x2d2d2d };
 +conn.change_window_attributes(window, &ChangeWindowAttributesAux::new()
 +    .border_pixel(border_color))?;
 +```
++
 +### 1.8 Basic Keyboard Grab
 +- [ ] Grab Mod4+Return (super+enter) globally
 +- [ ] On keypress, spawn terminal (hardcoded: `alacritty` or `xterm`)
 +- [ ] Use `std::process::Command` to spawn
++
 +```rust
 +// Grab the key
 +conn.grab_key(
 +    false,
 +    root,
 +    ModMask::M4,  // Super/Win key
 +    keycode_for_return,
 +    GrabMode::ASYNC,
 +    GrabMode::ASYNC,
 +)?;
 +```
++
 +## Acceptance Criteria
++
 +1. Opening windows tiles them vertically (side by side)
 +2. Closing a window removes it and re-tiles remaining windows
 +3. Clicking a window focuses it (border color changes)
 +4. Mod+Enter spawns a terminal
 +5. Windows properly fill available screen space
 +6. No crashes on rapid window open/close
++
 +## Testing Strategy
++
 +```bash
 +# In Xephyr session
 +DISPLAY=:1 cargo run &
++
 +# Open multiple terminals
 +DISPLAY=:1 xterm &
 +DISPLAY=:1 xterm &
 +DISPLAY=:1 xterm &
++
 +# Verify: 3 windows tiled vertically
 +# Click each to verify focus changes
 +# Close middle window, verify remaining 2 expand
 +```
++
 +## Edge Cases to Handle
++
 +- First window (empty tree)
 +- Last window closed (empty tree again)
 +- Rapid window creation
 +- Windows that set their own size (override redirect)
 +- Transient windows (handle in later sprint)
++
 +## Notes
++
 +- Keep split ratio at 0.5 for now (equal splits)
 +- Vertical-only splits for now (Sprint 2 adds smart splitting)
 +- No gaps yet (Sprint 8)
 +- Focused border color hardcoded (Sprint 4 makes configurable)

docs/sprints/sprint-2-smart-split.mdadded

 +# Sprint 2: Smart Split + Keyboard Navigation
++
 +**Goal:** Implement the core differentiating feature (intelligent split direction) and full keyboard-based window navigation.
++
 +## Objectives
++
 +- Automatic split direction based on window dimensions
 +- Full keyboard navigation (vim-style hjkl)
 +- Keyboard-based window operations
 +- This is what makes gar different from i3
++
 +## Prerequisites
++
 +- Sprint 1 complete (BSP tree, basic window management)
++
 +## The Smart Split Algorithm
++
 +This is the key feature that Hyprland has and i3 lacks:
++
 +```
 +When inserting a new window:
 +1. Get dimensions of the target area (width, height)
 +2. If width > height → split Vertical (creates side-by-side windows)
 +3. If height >= width → split Horizontal (creates stacked windows)
 +```
++
 +**Visual example:**
 +```
 +┌─────────────────────────┐     ┌────────────┬────────────┐
 +│                         │     │            │            │
 +│    Wide container       │ --> │   Left     │   Right    │
 +│    (width > height)     │     │            │   (new)    │
 +│                         │     │            │            │
 +└─────────────────────────┘     └────────────┴────────────┘
 +       Split VERTICAL
++
 +┌───────────┐                   ┌───────────┐
 +│           │                   │   Top     │
 +│   Tall    │                   ├───────────┤
 +│ container │    ────────>      │  Bottom   │
 +│ (h >= w)  │                   │   (new)   │
 +│           │                   │           │
 +└───────────┘                   └───────────┘
 +       Split HORIZONTAL
 +```
++
 +## Tasks
++
 +### 2.1 Implement Smart Split
 +- [ ] Modify `insert_window` in tree.rs
 +- [ ] Calculate container dimensions before inserting
 +- [ ] Choose split direction based on width vs height
 +- [ ] Add unit tests for split direction logic
++
 +```rust
 +impl Node {
 +    fn determine_split_direction(rect: &Rect) -> SplitDirection {
 +        if rect.width > rect.height {
 +            SplitDirection::Vertical
 +        } else {
 +            SplitDirection::Horizontal
 +        }
 +    }
++
 +    pub fn insert_window(&mut self, window: WindowId, rect: Rect) {
 +        let direction = Self::determine_split_direction(&rect);
 +        // ... rest of insertion logic
 +    }
 +}
 +```
++
 +### 2.2 Keyboard Input Infrastructure
 +- [ ] Create `src/input/mod.rs` and `src/input/keybinds.rs`
 +- [ ] Define keybind action enum
 +- [ ] Create keybind registry
 +- [ ] Grab all configured keys on startup
 +- [ ] Dispatch to actions on KeyPress event
++
 +```rust
 +pub enum Action {
 +    FocusDirection(Direction),
 +    SwapDirection(Direction),
 +    ResizeDirection(Direction, i32),
 +    CloseWindow,
 +    Equalize,
 +    Exec(String),
 +}
++
 +pub enum Direction {
 +    Left, Right, Up, Down,
 +}
 +```
++
 +### 2.3 Focus Navigation
 +- [ ] Implement directional focus (Mod+h/j/k/l)
 +- [ ] Find window in given direction from focused
 +- [ ] Handle edge cases (no window in direction)
 +- [ ] Update focus and visual feedback
++
 +**Algorithm for finding window in direction:**
 +```rust
 +fn find_window_in_direction(
 +    tree: &Node,
 +    from: WindowId,
 +    direction: Direction,
 +) -> Option<WindowId> {
 +    // 1. Get geometry of 'from' window
 +    // 2. Get geometries of all windows
 +    // 3. Filter to windows in the given direction
 +    // 4. Return closest window in that direction
 +}
 +```
++
 +### 2.4 Window Closing
 +- [ ] Implement Mod+Shift+Q to close focused window
 +- [ ] Send WM_DELETE_WINDOW if supported (ICCCM)
 +- [ ] Fall back to XKillClient if not
 +- [ ] Remove from tree after close
++
 +```rust
 +fn close_window(conn: &impl Connection, window: Window) -> Result<()> {
 +    // Check if window supports WM_DELETE_WINDOW
 +    if supports_delete_window(conn, window)? {
 +        send_delete_window_message(conn, window)?;
 +    } else {
 +        conn.kill_client(window)?;
 +    }
 +    Ok(())
 +}
 +```
++
 +### 2.5 Resize Splits
 +- [ ] Implement Mod+Ctrl+h/j/k/l to resize
 +- [ ] Find the split that affects the focused window in that direction
 +- [ ] Adjust ratio by fixed increment (e.g., 0.05)
 +- [ ] Clamp ratio between 0.1 and 0.9
 +- [ ] Recalculate and apply geometries
++
 +```rust
 +fn resize_in_direction(tree: &mut Node, window: WindowId, dir: Direction, delta: f32) {
 +    // Find the nearest ancestor split in the given direction
 +    // Adjust its ratio
 +}
 +```
++
 +### 2.6 Equalize Splits
 +- [ ] Implement Mod+E to equalize
 +- [ ] Set all split ratios to 0.5
 +- [ ] Recursive traversal of tree
 +- [ ] Recalculate and apply geometries
++
 +```rust
 +fn equalize(node: &mut Node) {
 +    match node {
 +        Node::Internal { ratio, left, right, .. } => {
 +            *ratio = 0.5;
 +            equalize(left);
 +            equalize(right);
 +        }
 +        Node::Leaf { .. } => {}
 +    }
 +}
 +```
++
 +### 2.7 Swap Windows
 +- [ ] Implement Mod+Shift+h/j/k/l to swap
 +- [ ] Find window in direction
 +- [ ] Swap the two windows in the tree
 +- [ ] Recalculate and apply geometries
++
 +```rust
 +fn swap_windows(tree: &mut Node, a: WindowId, b: WindowId) {
 +    // Find both leaf nodes
 +    // Swap their window IDs
 +}
 +```
++
 +## Keybind Summary
++
 +| Keybind | Action |
 +|---------|--------|
 +| Mod+h/j/k/l | Focus left/down/up/right |
 +| Mod+Shift+h/j/k/l | Swap with left/down/up/right |
 +| Mod+Ctrl+h/j/k/l | Resize split in direction |
 +| Mod+Shift+Q | Close focused window |
 +| Mod+E | Equalize all splits |
 +| Mod+Return | Spawn terminal |
++
 +## Acceptance Criteria
++
 +1. New windows split intelligently based on container shape
 +2. All keyboard navigation works as specified
 +3. Window swapping maintains tree structure
 +4. Resize adjusts the correct split
 +5. Equalize makes all windows same size
 +6. Closing windows works cleanly
++
 +## Testing Strategy
++
 +```bash
 +# Test smart splits
 +# Open terminal in empty workspace → full screen
 +# Open second terminal → should split vertically (side by side)
 +# Focus right window, open third → right window splits horizontally (stacked)
++
 +# Test navigation
 +# Mod+h/l should move focus left/right
 +# Mod+j/k should move focus up/down
++
 +# Test resize
 +# Mod+Ctrl+l should make focused window wider
 +# Mod+E should reset to equal sizes
 +```
++
 +## Notes
++
 +- This sprint establishes the core UX that differentiates gar
 +- Navigation should feel snappy (no perceptible delay)
 +- Consider adding Mod+Arrow keys as alternative to hjkl
 +- Direction finding algorithm is the trickiest part - test thoroughly

docs/sprints/sprint-3-workspaces.mdadded

 +# Sprint 3: Multiple Workspaces
++
 +**Goal:** Implement named workspaces with switching and window movement.
++
 +## Objectives
++
 +- Multiple independent workspaces, each with its own BSP tree
 +- Keyboard-based workspace switching
 +- Move windows between workspaces
 +- EWMH workspace properties for status bar integration
++
 +## Prerequisites
++
 +- Sprint 2 complete (smart split, keyboard navigation)
++
 +## Tasks
++
 +### 3.1 Workspace Data Structure
 +- [ ] Create `src/core/workspace.rs`
 +- [ ] Define `Workspace` struct
 +- [ ] Create `WorkspaceManager` to hold all workspaces
 +- [ ] Initialize default workspaces (1-10)
++
 +```rust
 +pub struct Workspace {
 +    pub id: WorkspaceId,
 +    pub name: String,
 +    pub tree: Node,
 +    pub floating: Vec<Window>,
 +    pub focused: Option<WindowId>,
 +    pub visible: bool,
 +}
++
 +pub struct WorkspaceManager {
 +    workspaces: Vec<Workspace>,
 +    active: WorkspaceId,
 +}
 +```
++
 +### 3.2 Workspace Initialization
 +- [ ] Create 10 default workspaces (named "1" through "10")
 +- [ ] Set workspace 1 as active on startup
 +- [ ] Existing windows go to workspace 1
++
 +```rust
 +impl WorkspaceManager {
 +    pub fn new() -> Self {
 +        let workspaces = (1..=10)
 +            .map(|i| Workspace {
 +                id: WorkspaceId(i),
 +                name: i.to_string(),
 +                tree: Node::empty(),
 +                floating: Vec::new(),
 +                focused: None,
 +                visible: i == 1,
 +            })
 +            .collect();
 +        Self { workspaces, active: WorkspaceId(1) }
 +    }
 +}
 +```
++
 +### 3.3 Workspace Switching
 +- [ ] Implement Mod+1 through Mod+9 (and Mod+0 for 10)
 +- [ ] Hide windows on old workspace
 +- [ ] Show windows on new workspace
 +- [ ] Restore focus to previously focused window
 +- [ ] Update EWMH _NET_CURRENT_DESKTOP
++
 +```rust
 +fn switch_workspace(&mut self, conn: &impl Connection, target: WorkspaceId) -> Result<()> {
 +    if target == self.active {
 +        return Ok(());
 +    }
++
 +    // Hide current workspace windows
 +    for window in self.current_workspace().all_windows() {
 +        conn.unmap_window(window)?;
 +    }
++
 +    // Show target workspace windows
 +    self.active = target;
 +    for window in self.current_workspace().all_windows() {
 +        conn.map_window(window)?;
 +    }
++
 +    // Restore focus
 +    if let Some(focused) = self.current_workspace().focused {
 +        set_focus(conn, focused)?;
 +    }
++
 +    Ok(())
 +}
 +```
++
 +### 3.4 Move Window to Workspace
 +- [ ] Implement Mod+Shift+1 through Mod+Shift+9
 +- [ ] Remove window from current workspace tree
 +- [ ] Add window to target workspace tree
 +- [ ] If target workspace is not visible, unmap window
 +- [ ] Optionally follow window to new workspace (configurable later)
++
 +```rust
 +fn move_to_workspace(
 +    &mut self,
 +    conn: &impl Connection,
 +    window: WindowId,
 +    target: WorkspaceId,
 +) -> Result<()> {
 +    // Remove from current
 +    self.current_workspace_mut().tree.remove(window);
++
 +    // Add to target
 +    self.workspace_mut(target).tree.insert(window);
++
 +    // Hide if target not visible
 +    if target != self.active {
 +        conn.unmap_window(window)?;
 +    }
++
 +    // Retile both workspaces
 +    self.apply_layout(conn, self.active)?;
 +    self.apply_layout(conn, target)?;
++
 +    Ok(())
 +}
 +```
++
 +### 3.5 Per-Workspace Trees
 +- [ ] Modify window insertion to use active workspace
 +- [ ] Modify window removal to find correct workspace
 +- [ ] Ensure tree operations target correct workspace
 +- [ ] Handle window destroy when on non-active workspace
++
 +### 3.6 EWMH Workspace Support
 +- [ ] Set `_NET_NUMBER_OF_DESKTOPS` on root
 +- [ ] Set `_NET_DESKTOP_NAMES` with workspace names
 +- [ ] Set `_NET_CURRENT_DESKTOP` when switching
 +- [ ] Set `_NET_WM_DESKTOP` on each window
 +- [ ] Handle `_NET_CURRENT_DESKTOP` client messages (pagers)
++
 +```rust
 +fn set_ewmh_workspace_hints(conn: &impl Connection, manager: &WorkspaceManager) -> Result<()> {
 +    let root = get_root(conn);
++
 +    // Number of desktops
 +    conn.change_property32(
 +        PropMode::REPLACE,
 +        root,
 +        atoms._NET_NUMBER_OF_DESKTOPS,
 +        AtomEnum::CARDINAL,
 +        &[manager.workspaces.len() as u32],
 +    )?;
++
 +    // Desktop names
 +    let names: Vec<u8> = manager.workspaces
 +        .iter()
 +        .flat_map(|ws| ws.name.bytes().chain(std::iter::once(0)))
 +        .collect();
 +    conn.change_property8(
 +        PropMode::REPLACE,
 +        root,
 +        atoms._NET_DESKTOP_NAMES,
 +        atoms.UTF8_STRING,
 +        &names,
 +    )?;
++
 +    // Current desktop
 +    conn.change_property32(
 +        PropMode::REPLACE,
 +        root,
 +        atoms._NET_CURRENT_DESKTOP,
 +        AtomEnum::CARDINAL,
 +        &[manager.active.0 as u32 - 1], // 0-indexed for EWMH
 +    )?;
++
 +    Ok(())
 +}
 +```
++
 +### 3.7 Handle Existing Windows on Startup
 +- [ ] Query existing windows on WM start
 +- [ ] Check `_NET_WM_DESKTOP` for previous workspace assignment
 +- [ ] Place windows in appropriate workspaces
 +- [ ] Map windows in active workspace only
++
 +## Keybind Summary
++
 +| Keybind | Action |
 +|---------|--------|
 +| Mod+1-9 | Switch to workspace 1-9 |
 +| Mod+0 | Switch to workspace 10 |
 +| Mod+Shift+1-9 | Move window to workspace 1-9 |
 +| Mod+Shift+0 | Move window to workspace 10 |
++
 +## Acceptance Criteria
++
 +1. Can switch between 10 workspaces
 +2. Each workspace maintains its own window layout
 +3. Moving window to another workspace works
 +4. Status bars (polybar) can display workspace info
 +5. Windows hidden/shown correctly on switch
 +6. Focus restored correctly when switching back
++
 +## Testing Strategy
++
 +```bash
 +# Test workspace switching
 +# Mod+1 - should be on workspace 1
 +# Open xterm
 +# Mod+2 - switch to workspace 2 (empty)
 +# Open xterm - should be alone
 +# Mod+1 - back to workspace 1, original xterm visible
++
 +# Test window movement
 +# On workspace 1 with xterm
 +# Mod+Shift+2 - moves xterm to workspace 2
 +# Mod+2 - verify xterm is there
++
 +# Test polybar integration
 +polybar example  # Should show workspace indicators
 +```
++
 +## Status Bar Integration
++
 +For polybar, create an i3-compatible module (we'll implement IPC in Sprint 6):
++
 +```ini
 +[module/workspaces]
 +type = internal/xworkspaces
 +label-active = %name%
 +label-occupied = %name%
 +label-empty = %name%
 +```
++
 +## Notes
++
 +- 0-indexed for EWMH, 1-indexed for user display
 +- Consider urgent workspace highlighting (Sprint 8)
 +- Named workspaces beyond 1-10 come with Lua config (Sprint 4)
 +- Multi-monitor workspace assignment comes in Sprint 7

docs/sprints/sprint-4-lua-config.mdadded

 +# Sprint 4: Lua Configuration
++
 +**Goal:** User-configurable keybinds, settings, and startup applications via Lua scripting.
++
 +## Objectives
++
 +- Load and execute Lua configuration file
 +- Expose gar API to Lua (keybinds, settings, rules)
 +- Support config hot-reload
 +- Provide sensible default configuration
++
 +## Prerequisites
++
 +- Sprint 3 complete (workspaces)
++
 +## Lua API Design
++
 +```lua
 +-- ~/.config/gar/init.lua
++
 +-- Settings
 +gar.set("border_width", 2)
 +gar.set("border_color_focused", "#5294e2")
 +gar.set("border_color_unfocused", "#2d2d2d")
 +gar.set("gap_inner", 5)
 +gar.set("gap_outer", 10)
++
 +-- Keybindings
 +gar.bind("mod+Return", function() gar.exec("alacritty") end)
 +gar.bind("mod+d", function() gar.exec("rofi -show drun") end)
 +gar.bind("mod+shift+q", gar.close_window)
 +gar.bind("mod+h", function() gar.focus("left") end)
 +gar.bind("mod+j", function() gar.focus("down") end)
 +gar.bind("mod+k", function() gar.focus("up") end)
 +gar.bind("mod+l", function() gar.focus("right") end)
++
 +-- Workspace bindings (loop)
 +for i = 1, 9 do
 +    gar.bind("mod+" .. i, function() gar.workspace(i) end)
 +    gar.bind("mod+shift+" .. i, function() gar.move_to_workspace(i) end)
 +end
++
 +-- Window rules
 +gar.rule({ class = "Firefox" }, { workspace = 2 })
 +gar.rule({ class = "Spotify" }, { floating = true })
 +gar.rule({ type = "dialog" }, { floating = true })
++
 +-- Startup applications
 +gar.exec_once("picom")
 +gar.exec_once("polybar")
 +gar.exec_once("dunst")
 +```
++
 +## Tasks
++
 +### 4.1 Lua Integration Setup
 +- [ ] Add `mlua` dependency
 +- [ ] Create `src/config/mod.rs` and `src/config/lua.rs`
 +- [ ] Initialize Lua state
 +- [ ] Create `gar` global table
 +- [ ] Handle Lua errors gracefully
++
 +```rust
 +use mlua::{Lua, Result as LuaResult};
++
 +pub struct LuaConfig {
 +    lua: Lua,
 +}
++
 +impl LuaConfig {
 +    pub fn new() -> LuaResult<Self> {
 +        let lua = Lua::new();
++
 +        // Create gar global table
 +        lua.globals().set("gar", lua.create_table()?)?;
++
 +        Ok(Self { lua })
 +    }
 +}
 +```
++
 +### 4.2 Configuration Loading
 +- [ ] Find config file (`~/.config/gar/init.lua`)
 +- [ ] Fall back to default config if not found
 +- [ ] Execute Lua file
 +- [ ] Handle syntax errors with helpful messages
++
 +```rust
 +impl LuaConfig {
 +    pub fn load(&self, wm: &mut WindowManager) -> Result<()> {
 +        let config_path = dirs::config_dir()
 +            .map(|p| p.join("gar/init.lua"))
 +            .filter(|p| p.exists());
++
 +        let source = match config_path {
 +            Some(path) => std::fs::read_to_string(path)?,
 +            None => include_str!("../../config/default.lua").to_string(),
 +        };
++
 +        self.lua.load(&source).exec()?;
 +        Ok(())
 +    }
 +}
 +```
++
 +### 4.3 Settings API
 +- [ ] Implement `gar.set(key, value)`
 +- [ ] Store settings in Rust-side config struct
 +- [ ] Support: border_width, border colors, gaps
 +- [ ] Validate values (types, ranges)
++
 +```rust
 +// Register gar.set
 +let set_fn = lua.create_function(|_, (key, value): (String, mlua::Value)| {
 +    // Send to config channel or store in shared state
 +    Ok(())
 +})?;
 +gar_table.set("set", set_fn)?;
 +```
++
 +**Supported settings:**
 +| Setting | Type | Default | Description |
 +|---------|------|---------|-------------|
 +| border_width | int | 2 | Window border width in pixels |
 +| border_color_focused | string | "#5294e2" | Focused window border color |
 +| border_color_unfocused | string | "#2d2d2d" | Unfocused window border color |
 +| gap_inner | int | 0 | Gap between windows |
 +| gap_outer | int | 0 | Gap around screen edge |
++
 +### 4.4 Keybind API
 +- [ ] Implement `gar.bind(keyspec, callback)`
 +- [ ] Parse keyspec string ("mod+shift+q")
 +- [ ] Register callback function
 +- [ ] Grab keys via X11
++
 +```rust
 +// Key specification parser
 +fn parse_keyspec(spec: &str) -> Result<(Modifiers, Keycode)> {
 +    // "mod+shift+q" -> (MOD4 | SHIFT, keycode_q)
 +    let parts: Vec<&str> = spec.to_lowercase().split('+').collect();
 +    // ...
 +}
 +```
++
 +### 4.5 Built-in Actions
 +- [ ] `gar.focus(direction)` - focus in direction
 +- [ ] `gar.swap(direction)` - swap with direction
 +- [ ] `gar.resize(direction, amount)` - resize split
 +- [ ] `gar.close_window()` - close focused window
 +- [ ] `gar.workspace(n)` - switch workspace
 +- [ ] `gar.move_to_workspace(n)` - move window
 +- [ ] `gar.exec(cmd)` - spawn command
 +- [ ] `gar.exec_once(cmd)` - spawn only if not running
 +- [ ] `gar.reload()` - reload config
++
 +### 4.6 Window Rules
 +- [ ] Implement `gar.rule(match, actions)`
 +- [ ] Match by: class, instance, title, type
 +- [ ] Actions: workspace, floating, border, size, position
 +- [ ] Apply rules on window creation
++
 +```rust
 +pub struct WindowRule {
 +    pub match_class: Option<Regex>,
 +    pub match_instance: Option<Regex>,
 +    pub match_title: Option<Regex>,
 +    pub match_type: Option<WindowType>,
++
 +    pub workspace: Option<WorkspaceId>,
 +    pub floating: Option<bool>,
 +    pub border_width: Option<u32>,
 +    // ...
 +}
 +```
++
 +### 4.7 Config Reload
 +- [ ] Implement `gar.reload()` function
 +- [ ] Bind to Mod+Shift+R by default
 +- [ ] Clear existing keybinds
 +- [ ] Re-execute config file
 +- [ ] Apply new settings immediately
 +- [ ] Report errors without crashing
++
 +### 4.8 Default Configuration
 +- [ ] Create `config/default.lua`
 +- [ ] Include sensible defaults for all settings
 +- [ ] Include essential keybinds (focus, close, workspaces)
 +- [ ] Document all options in comments
++
 +## Default Configuration
++
 +```lua
 +-- config/default.lua
 +-- Default gar configuration
++
 +-- Appearance
 +gar.set("border_width", 2)
 +gar.set("border_color_focused", "#5294e2")
 +gar.set("border_color_unfocused", "#2d2d2d")
 +gar.set("gap_inner", 0)
 +gar.set("gap_outer", 0)
++
 +-- Mod key (mod = Super/Win key)
 +local mod = "mod"
++
 +-- Core keybindings
 +gar.bind(mod .. "+Return", function() gar.exec("xterm") end)
 +gar.bind(mod .. "+shift+q", gar.close_window)
 +gar.bind(mod .. "+shift+r", gar.reload)
 +gar.bind(mod .. "+shift+e", gar.exit)
++
 +-- Focus navigation
 +gar.bind(mod .. "+h", function() gar.focus("left") end)
 +gar.bind(mod .. "+j", function() gar.focus("down") end)
 +gar.bind(mod .. "+k", function() gar.focus("up") end)
 +gar.bind(mod .. "+l", function() gar.focus("right") end)
++
 +-- Window movement
 +gar.bind(mod .. "+shift+h", function() gar.swap("left") end)
 +gar.bind(mod .. "+shift+j", function() gar.swap("down") end)
 +gar.bind(mod .. "+shift+k", function() gar.swap("up") end)
 +gar.bind(mod .. "+shift+l", function() gar.swap("right") end)
++
 +-- Resize
 +gar.bind(mod .. "+ctrl+h", function() gar.resize("left", 0.05) end)
 +gar.bind(mod .. "+ctrl+j", function() gar.resize("down", 0.05) end)
 +gar.bind(mod .. "+ctrl+k", function() gar.resize("up", 0.05) end)
 +gar.bind(mod .. "+ctrl+l", function() gar.resize("right", 0.05) end)
 +gar.bind(mod .. "+e", gar.equalize)
++
 +-- Workspaces
 +for i = 1, 9 do
 +    gar.bind(mod .. "+" .. i, function() gar.workspace(i) end)
 +    gar.bind(mod .. "+shift+" .. i, function() gar.move_to_workspace(i) end)
 +end
 +gar.bind(mod .. "+0", function() gar.workspace(10) end)
 +gar.bind(mod .. "+shift+0", function() gar.move_to_workspace(10) end)
++
 +-- Window rules
 +gar.rule({ type = "dialog" }, { floating = true })
 +gar.rule({ type = "splash" }, { floating = true })
 +```
++
 +## Acceptance Criteria
++
 +1. Config loads from `~/.config/gar/init.lua`
 +2. Falls back to default if no config exists
 +3. All keybinds configurable via Lua
 +4. Settings (borders, gaps) apply immediately
 +5. Window rules work for class/type matching
 +6. Mod+Shift+R reloads config without restart
 +7. Syntax errors reported clearly, don't crash WM
++
 +## Testing Strategy
++
 +```bash
 +# Create test config
 +mkdir -p ~/.config/gar
 +cat > ~/.config/gar/init.lua << 'EOF'
 +gar.set("border_width", 4)
 +gar.set("border_color_focused", "#ff0000")
 +gar.bind("mod+t", function() print("test") end)
 +EOF
++
 +# Start gar, verify:
 +# - 4px borders
 +# - Red focus color
 +# - Mod+t prints to log
++
 +# Test reload
 +# Modify config, Mod+Shift+R, verify changes apply
 +```
++
 +## Notes
++
 +- Lua 5.4 via mlua with vendored feature (no system dependency)
 +- Consider sandboxing Lua (disable os.execute, io.*, etc.)
 +- exec_once needs to track spawned processes
 +- Error messages should include line numbers

docs/sprints/sprint-5-floating.mdadded

 +# Sprint 5: Floating Windows
++
 +**Goal:** Full floating window support with mouse interaction.
++
 +## Objectives
++
 +- Toggle windows between tiled and floating
 +- Mouse-based move and resize for floating windows
 +- Automatic floating for dialogs and certain window types
 +- Proper stacking order (floating above tiled)
++
 +## Prerequisites
++
 +- Sprint 4 complete (Lua configuration)
++
 +## Tasks
++
 +### 5.1 Floating Window State
 +- [ ] Add floating window list to Workspace
 +- [ ] Track floating window geometry separately
 +- [ ] Floating windows don't participate in BSP tree
 +- [ ] Track stacking order for floating windows
++
 +```rust
 +pub struct Workspace {
 +    pub tree: Node,                    // Tiled windows
 +    pub floating: Vec<FloatingWindow>, // Floating windows
 +    pub focused: Option<WindowId>,
 +    // ...
 +}
++
 +pub struct FloatingWindow {
 +    pub id: WindowId,
 +    pub geometry: Rect,
 +    pub z_order: u32,
 +}
 +```
++
 +### 5.2 Toggle Floating
 +- [ ] Implement Mod+Shift+Space to toggle
 +- [ ] When floating: remove from tree, add to floating list
 +- [ ] When tiling: remove from floating list, insert to tree
 +- [ ] Preserve position when floating
 +- [ ] Use smart split when returning to tiled
++
 +```rust
 +fn toggle_floating(&mut self, window: WindowId) {
 +    if self.is_floating(window) {
 +        // Move to tiled
 +        let float_win = self.floating.remove(/* ... */);
 +        self.tree.insert(window);
 +    } else {
 +        // Move to floating
 +        let geometry = self.get_window_geometry(window);
 +        self.tree.remove(window);
 +        self.floating.push(FloatingWindow {
 +            id: window,
 +            geometry,
 +            z_order: self.next_z_order(),
 +        });
 +    }
 +}
 +```
++
 +### 5.3 Mouse Move (Mod+LeftClick)
 +- [ ] Grab Mod+Button1 on all windows
 +- [ ] On press: record start position
 +- [ ] On motion: update window position
 +- [ ] On release: finalize position
 +- [ ] Only works for floating windows
++
 +```rust
 +fn handle_button_press(&mut self, event: ButtonPressEvent) {
 +    if event.detail == 1 && event.state.contains(ModMask::M4) {
 +        // Start move operation
 +        self.drag_state = Some(DragState::Move {
 +            window: event.child,
 +            start_x: event.root_x,
 +            start_y: event.root_y,
 +            start_geometry: self.get_geometry(event.child),
 +        });
 +        self.conn.grab_pointer(/* ... */)?;
 +    }
 +}
++
 +fn handle_motion(&mut self, event: MotionNotifyEvent) {
 +    if let Some(DragState::Move { window, start_x, start_y, start_geometry }) = &self.drag_state {
 +        let dx = event.root_x - start_x;
 +        let dy = event.root_y - start_y;
 +        let new_x = start_geometry.x + dx;
 +        let new_y = start_geometry.y + dy;
 +        self.configure_window(window, new_x, new_y, None, None)?;
 +    }
 +}
 +```
++
 +### 5.4 Mouse Resize (Mod+RightClick)
 +- [ ] Grab Mod+Button3 on all windows
 +- [ ] Determine resize corner based on click position
 +- [ ] On motion: adjust size (and position for top/left edges)
 +- [ ] Enforce minimum window size
 +- [ ] Only works for floating windows
++
 +```rust
 +fn determine_resize_edge(window_geometry: Rect, click_x: i16, click_y: i16) -> ResizeEdge {
 +    let center_x = window_geometry.x + window_geometry.width as i16 / 2;
 +    let center_y = window_geometry.y + window_geometry.height as i16 / 2;
++
 +    match (click_x < center_x, click_y < center_y) {
 +        (true, true) => ResizeEdge::TopLeft,
 +        (false, true) => ResizeEdge::TopRight,
 +        (true, false) => ResizeEdge::BottomLeft,
 +        (false, false) => ResizeEdge::BottomRight,
 +    }
 +}
 +```
++
 +### 5.5 Auto-Float Rules
 +- [ ] Float `_NET_WM_WINDOW_TYPE_DIALOG`
 +- [ ] Float `_NET_WM_WINDOW_TYPE_SPLASH`
 +- [ ] Float `_NET_WM_WINDOW_TYPE_TOOLTIP`
 +- [ ] Float `_NET_WM_WINDOW_TYPE_UTILITY`
 +- [ ] Float windows with WM_TRANSIENT_FOR set
 +- [ ] Respect size hints for floating position
++
 +```rust
 +fn should_float(conn: &impl Connection, window: Window) -> Result<bool> {
 +    let window_type = get_window_type(conn, window)?;
++
 +    let float_types = [
 +        atoms._NET_WM_WINDOW_TYPE_DIALOG,
 +        atoms._NET_WM_WINDOW_TYPE_SPLASH,
 +        atoms._NET_WM_WINDOW_TYPE_TOOLTIP,
 +        atoms._NET_WM_WINDOW_TYPE_UTILITY,
 +        atoms._NET_WM_WINDOW_TYPE_POPUP_MENU,
 +    ];
++
 +    if float_types.contains(&window_type) {
 +        return Ok(true);
 +    }
++
 +    // Check transient
 +    if get_transient_for(conn, window)?.is_some() {
 +        return Ok(true);
 +    }
++
 +    Ok(false)
 +}
 +```
++
 +### 5.6 Stacking Order
 +- [ ] Floating windows above tiled
 +- [ ] Most recently focused floating on top
 +- [ ] Use `ConfigureWindow` with `stack_mode` and `sibling`
 +- [ ] Maintain stacking order on focus changes
++
 +```rust
 +fn raise_window(&self, conn: &impl Connection, window: Window) -> Result<()> {
 +    conn.configure_window(
 +        window,
 +        &ConfigureWindowAux::new().stack_mode(StackMode::ABOVE),
 +    )?;
 +    Ok(())
 +}
++
 +fn restack_floating(&self, conn: &impl Connection) -> Result<()> {
 +    // Stack in z_order, lowest first
 +    let mut sorted: Vec<_> = self.floating.iter().collect();
 +    sorted.sort_by_key(|w| w.z_order);
++
 +    for (i, window) in sorted.iter().enumerate() {
 +        if i > 0 {
 +            conn.configure_window(
 +                window.id,
 +                &ConfigureWindowAux::new()
 +                    .stack_mode(StackMode::ABOVE)
 +                    .sibling(sorted[i - 1].id),
 +            )?;
 +        }
 +    }
 +    Ok(())
 +}
 +```
++
 +### 5.7 Floating Focus
 +- [ ] Tab cycles through floating windows
 +- [ ] Focus follows click for floating
 +- [ ] Raise on focus
 +- [ ] Handle focus between tiled and floating
++
 +```rust
 +fn focus_next_floating(&mut self) {
 +    if self.floating.is_empty() {
 +        return;
 +    }
++
 +    let current_idx = self.floating
 +        .iter()
 +        .position(|w| Some(w.id) == self.focused)
 +        .unwrap_or(0);
++
 +    let next_idx = (current_idx + 1) % self.floating.len();
 +    let next_window = self.floating[next_idx].id;
++
 +    self.set_focus(next_window);
 +    self.raise_window(next_window);
 +}
 +```
++
 +### 5.8 Lua Integration
 +- [ ] Add `floating` property to window rules
 +- [ ] Add `gar.toggle_floating()` function
 +- [ ] Add `gar.float_geometry(x, y, w, h)` for rules
++
 +```lua
 +-- Float Firefox PiP
 +gar.rule(
 +    { class = "firefox", title = "Picture-in-Picture" },
 +    { floating = true, geometry = { x = 100, y = 100, width = 400, height = 300 } }
 +)
++
 +-- Keybind
 +gar.bind("mod+shift+space", gar.toggle_floating)
 +```
++
 +## Keybind Summary
++
 +| Keybind | Action |
 +|---------|--------|
 +| Mod+Shift+Space | Toggle floating |
 +| Mod+LeftClick drag | Move floating window |
 +| Mod+RightClick drag | Resize floating window |
++
 +## Acceptance Criteria
++
 +1. Mod+Shift+Space toggles between tiled/floating
 +2. Can drag floating windows with Mod+LeftClick
 +3. Can resize floating windows with Mod+RightClick
 +4. Dialogs automatically float
 +5. Floating windows stay above tiled
 +6. Focus works correctly between tiled/floating
++
 +## Testing Strategy
++
 +```bash
 +# Test toggle
 +# Open xterm, verify tiled
 +# Mod+Shift+Space, verify floating (doesn't affect layout)
 +# Mod+Shift+Space again, verify back in tile
++
 +# Test mouse
 +# Float a window
 +# Mod+LeftClick drag - should move
 +# Mod+RightClick drag - should resize
++
 +# Test auto-float
 +# Open a dialog (e.g., Firefox preferences)
 +# Should automatically float
++
 +# Test stacking
 +# Have tiled windows
 +# Float one
 +# Floating should be on top
 +```
++
 +## Notes
++
 +- Consider minimum size constraints
 +- Handle fullscreen windows (Sprint 8)
 +- Floating geometry should be remembered when toggling
 +- Resize should work from any edge (not just corner)

docs/sprints/sprint-6-ipc.mdadded

 +# Sprint 6: IPC System
++
 +**Goal:** External control via Unix socket with JSON protocol.
++
 +## Objectives
++
 +- Unix socket server for IPC
 +- JSON-based command/response protocol
 +- Command-line tool (`garctl`) for interaction
 +- Event subscription for external tools
++
 +## Prerequisites
++
 +- Sprint 5 complete (floating windows)
++
 +## Protocol Design
++
 +### Message Format
++
 +```json
 +// Command (client -> server)
 +{
 +    "type": "command",
 +    "command": "focus",
 +    "args": { "direction": "left" }
 +}
++
 +// Response (server -> client)
 +{
 +    "type": "response",
 +    "success": true,
 +    "data": { /* optional result */ }
 +}
++
 +// Error response
 +{
 +    "type": "response",
 +    "success": false,
 +    "error": "Window not found"
 +}
++
 +// Event (server -> subscribed clients)
 +{
 +    "type": "event",
 +    "event": "window_focus",
 +    "data": { "window_id": 12345, "title": "Terminal" }
 +}
 +```
++
 +### Commands
++
 +| Command | Args | Description |
 +|---------|------|-------------|
 +| focus | direction | Focus window in direction |
 +| swap | direction | Swap with window in direction |
 +| resize | direction, amount | Resize split |
 +| close | - | Close focused window |
 +| workspace | number | Switch to workspace |
 +| move_to_workspace | number | Move window to workspace |
 +| toggle_floating | - | Toggle floating state |
 +| reload | - | Reload configuration |
 +| exit | - | Exit gar |
 +| get_tree | - | Get window tree |
 +| get_workspaces | - | Get workspace info |
 +| get_focused | - | Get focused window |
 +| subscribe | events[] | Subscribe to events |
++
 +### Events
++
 +| Event | Data | Description |
 +|-------|------|-------------|
 +| window_new | window info | New window created |
 +| window_close | window_id | Window closed |
 +| window_focus | window info | Focus changed |
 +| window_move | window_id, workspace | Window moved |
 +| workspace_focus | workspace info | Workspace changed |
 +| mode | mode name | Mode changed (later) |
++
 +## Tasks
++
 +### 6.1 Socket Server Setup
 +- [ ] Create `src/ipc/mod.rs`, `server.rs`, `protocol.rs`
 +- [ ] Add tokio dependency for async I/O
 +- [ ] Create Unix socket at `$XDG_RUNTIME_DIR/gar.sock`
 +- [ ] Handle multiple concurrent clients
 +- [ ] Clean up socket on exit
++
 +```rust
 +use tokio::net::{UnixListener, UnixStream};
++
 +pub struct IpcServer {
 +    listener: UnixListener,
 +    clients: Vec<Client>,
 +}
++
 +impl IpcServer {
 +    pub async fn new() -> Result<Self> {
 +        let path = std::env::var("XDG_RUNTIME_DIR")
 +            .map(|dir| format!("{}/gar.sock", dir))
 +            .unwrap_or_else(|_| "/tmp/gar.sock".to_string());
++
 +        // Remove existing socket
 +        let _ = std::fs::remove_file(&path);
++
 +        let listener = UnixListener::bind(&path)?;
 +        Ok(Self { listener, clients: Vec::new() })
 +    }
 +}
 +```
++
 +### 6.2 Protocol Types
 +- [ ] Define message types with serde
 +- [ ] Implement JSON serialization
 +- [ ] Handle malformed messages gracefully
++
 +```rust
 +use serde::{Deserialize, Serialize};
++
 +#[derive(Debug, Deserialize)]
 +#[serde(tag = "type")]
 +pub enum Request {
 +    #[serde(rename = "command")]
 +    Command { command: String, args: serde_json::Value },
 +}
++
 +#[derive(Debug, Serialize)]
 +#[serde(tag = "type")]
 +pub enum Response {
 +    #[serde(rename = "response")]
 +    Success { success: bool, data: Option<serde_json::Value> },
 +    #[serde(rename = "response")]
 +    Error { success: bool, error: String },
 +}
++
 +#[derive(Debug, Serialize)]
 +#[serde(tag = "type")]
 +pub enum Event {
 +    #[serde(rename = "event")]
 +    Event { event: String, data: serde_json::Value },
 +}
 +```
++
 +### 6.3 Command Dispatch
 +- [ ] Parse incoming commands
 +- [ ] Map to window manager actions
 +- [ ] Execute and return result
 +- [ ] Handle unknown commands
++
 +```rust
 +impl IpcServer {
 +    fn dispatch(&self, wm: &mut WindowManager, cmd: &str, args: Value) -> Response {
 +        match cmd {
 +            "focus" => {
 +                let direction = args["direction"].as_str().unwrap();
 +                wm.focus_direction(direction.parse()?)?;
 +                Response::success(None)
 +            }
 +            "get_tree" => {
 +                let tree = wm.get_tree_json();
 +                Response::success(Some(tree))
 +            }
 +            _ => Response::error(format!("Unknown command: {}", cmd)),
 +        }
 +    }
 +}
 +```
++
 +### 6.4 Query Commands
 +- [ ] `get_tree` - return workspace trees as JSON
 +- [ ] `get_workspaces` - return workspace list
 +- [ ] `get_focused` - return focused window info
 +- [ ] `get_outputs` - return monitor info (for multi-monitor)
++
 +```rust
 +fn get_tree_json(&self) -> Value {
 +    json!({
 +        "workspaces": self.workspaces.iter().map(|ws| {
 +            json!({
 +                "name": ws.name,
 +                "focused": ws.focused,
 +                "nodes": tree_to_json(&ws.tree),
 +            })
 +        }).collect::<Vec<_>>()
 +    })
 +}
 +```
++
 +### 6.5 Event Subscription
 +- [ ] Track subscribed clients per event type
 +- [ ] Broadcast events to subscribers
 +- [ ] Handle client disconnection
 +- [ ] Implement subscription command
++
 +```rust
 +struct Client {
 +    stream: UnixStream,
 +    subscriptions: HashSet<String>,
 +}
++
 +impl IpcServer {
 +    fn broadcast_event(&mut self, event: &str, data: Value) {
 +        let msg = Event { event: event.into(), data };
 +        let json = serde_json::to_string(&msg).unwrap();
++
 +        self.clients.retain(|client| {
 +            if client.subscriptions.contains(event) {
 +                client.stream.try_write(json.as_bytes()).is_ok()
 +            } else {
 +                true
 +            }
 +        });
 +    }
 +}
 +```
++
 +### 6.6 Integration with Event Loop
 +- [ ] Run IPC server alongside X event loop
 +- [ ] Use tokio runtime or poll-based approach
 +- [ ] Handle commands without blocking X events
 +- [ ] Thread-safe communication with WM state
++
 +```rust
 +// Option 1: Tokio with channels
 +fn main() {
 +    let (cmd_tx, cmd_rx) = tokio::sync::mpsc::channel(100);
 +    let (event_tx, event_rx) = tokio::sync::broadcast::channel(100);
++
 +    // Spawn IPC server task
 +    tokio::spawn(async move {
 +        ipc_server.run(cmd_tx, event_rx).await;
 +    });
++
 +    // X event loop
 +    loop {
 +        // Check for IPC commands
 +        while let Ok(cmd) = cmd_rx.try_recv() {
 +            handle_ipc_command(cmd);
 +        }
++
 +        // Handle X events
 +        let event = conn.wait_for_event()?;
 +        handle_x_event(event);
++
 +        // Broadcast events
 +        event_tx.send(/* ... */);
 +    }
 +}
 +```
++
 +### 6.7 garctl CLI Tool
 +- [ ] Create `garctl/src/main.rs`
 +- [ ] Connect to gar socket
 +- [ ] Send commands from CLI args
 +- [ ] Print responses
 +- [ ] Support event monitoring mode
++
 +```rust
 +// garctl/src/main.rs
 +use clap::Parser;
++
 +#[derive(Parser)]
 +struct Cli {
 +    #[clap(subcommand)]
 +    command: Command,
 +}
++
 +#[derive(Parser)]
 +enum Command {
 +    Focus { direction: String },
 +    Workspace { number: u32 },
 +    GetTree,
 +    Subscribe { events: Vec<String> },
 +    // ...
 +}
++
 +fn main() -> Result<()> {
 +    let cli = Cli::parse();
 +    let mut socket = UnixStream::connect(get_socket_path())?;
++
 +    let request = match cli.command {
 +        Command::Focus { direction } => {
 +            json!({ "type": "command", "command": "focus", "args": { "direction": direction } })
 +        }
 +        // ...
 +    };
++
 +    socket.write_all(serde_json::to_string(&request)?.as_bytes())?;
++
 +    let mut response = String::new();
 +    socket.read_to_string(&mut response)?;
 +    println!("{}", response);
++
 +    Ok(())
 +}
 +```
++
 +## garctl Usage
++
 +```bash
 +# Focus direction
 +garctl focus left
 +garctl focus right
++
 +# Workspaces
 +garctl workspace 2
 +garctl move-to-workspace 3
++
 +# Queries
 +garctl get-tree
 +garctl get-workspaces
 +garctl get-focused
++
 +# Events (stays open, prints events)
 +garctl subscribe window_focus workspace_focus
 +```
++
 +## Acceptance Criteria
++
 +1. Socket created at `$XDG_RUNTIME_DIR/gar.sock`
 +2. `garctl` can send commands and receive responses
 +3. All WM actions available via IPC
 +4. Query commands return proper JSON
 +5. Event subscription works for focus/workspace changes
 +6. Multiple concurrent clients supported
++
 +## Testing Strategy
++
 +```bash
 +# Start gar
 +DISPLAY=:1 cargo run
++
 +# Test command
 +garctl focus left  # Should return success
++
 +# Test query
 +garctl get-tree | jq .  # Should show tree structure
++
 +# Test events
 +garctl subscribe window_focus &
 +# Open/focus windows, events should print
 +```
++
 +## Notes
++
 +- Socket permissions should be user-only (0600)
 +- Consider i3-compatible message format for polybar compatibility
 +- Add timeout for client reads to prevent blocking
 +- Log all IPC activity for debugging

docs/sprints/sprint-7-multimonitor.mdadded

 +# Sprint 7: Multi-Monitor Support
++
 +**Goal:** Proper multi-head support with per-monitor workspaces.
++
 +## Objectives
++
 +- Detect monitors via RandR extension
 +- Assign workspaces to monitors
 +- Navigate and move windows between monitors
 +- Handle monitor hotplug (connect/disconnect)
++
 +## Prerequisites
++
 +- Sprint 6 complete (IPC system)
++
 +## Monitor Model
++
 +```
 +┌─────────────────────────────────────────────────────────────────────┐
 +│                         WorkspaceManager                             │
 +│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐         │
 +│  │  Monitor 0   │     │  Monitor 1   │     │  Monitor 2   │         │
 +│  │  "eDP-1"     │     │  "HDMI-1"    │     │  "DP-1"      │         │
 +│  │              │     │              │     │              │         │
 +│  │  WS: 1,2,3   │     │  WS: 4,5,6   │     │  WS: 7,8,9   │         │
 +│  │  Active: 1   │     │  Active: 4   │     │  Active: 7   │         │
 +│  └──────────────┘     └──────────────┘     └──────────────┘         │
 +└─────────────────────────────────────────────────────────────────────┘
 +```
++
 +## Tasks
++
 +### 7.1 Monitor Detection
 +- [ ] Create `src/core/monitor.rs`
 +- [ ] Query RandR for connected outputs
 +- [ ] Get monitor geometry (position, size)
 +- [ ] Identify primary monitor
 +- [ ] Handle disabled/mirrored outputs
++
 +```rust
 +use x11rb::protocol::randr;
++
 +pub struct Monitor {
 +    pub name: String,
 +    pub output: randr::Output,
 +    pub geometry: Rect,
 +    pub primary: bool,
 +    pub workspaces: Vec<WorkspaceId>,
 +    pub active_workspace: WorkspaceId,
 +}
++
 +fn detect_monitors(conn: &impl Connection, root: Window) -> Result<Vec<Monitor>> {
 +    let resources = conn.randr_get_screen_resources(root)?.reply()?;
 +    let mut monitors = Vec::new();
++
 +    for output in resources.outputs {
 +        let info = conn.randr_get_output_info(output, 0)?.reply()?;
++
 +        if info.connection != randr::Connection::CONNECTED {
 +            continue;
 +        }
++
 +        if let Some(crtc) = info.crtc {
 +            let crtc_info = conn.randr_get_crtc_info(crtc, 0)?.reply()?;
 +            monitors.push(Monitor {
 +                name: String::from_utf8_lossy(&info.name).to_string(),
 +                output,
 +                geometry: Rect {
 +                    x: crtc_info.x,
 +                    y: crtc_info.y,
 +                    width: crtc_info.width,
 +                    height: crtc_info.height,
 +                },
 +                primary: false, // Set later
 +                workspaces: Vec::new(),
 +                active_workspace: WorkspaceId(0),
 +            });
 +        }
 +    }
++
 +    Ok(monitors)
 +}
 +```
++
 +### 7.2 Workspace-Monitor Assignment
 +- [ ] Each monitor has a set of workspaces
 +- [ ] Default: distribute workspaces evenly
 +- [ ] Lua API: `gar.assign_workspace(ws, monitor)`
 +- [ ] Workspace shows on its assigned monitor
++
 +```rust
 +impl WorkspaceManager {
 +    fn assign_workspaces_to_monitors(&mut self) {
 +        let ws_per_monitor = self.workspaces.len() / self.monitors.len();
++
 +        for (i, monitor) in self.monitors.iter_mut().enumerate() {
 +            let start = i * ws_per_monitor + 1;
 +            let end = if i == self.monitors.len() - 1 {
 +                self.workspaces.len()
 +            } else {
 +                start + ws_per_monitor
 +            };
++
 +            monitor.workspaces = (start..=end).map(WorkspaceId).collect();
 +            monitor.active_workspace = WorkspaceId(start);
 +        }
 +    }
 +}
 +```
++
 +### 7.3 Focus Across Monitors
 +- [ ] Implement Mod+comma/period to focus monitor
 +- [ ] Track focused monitor
 +- [ ] Focus follows workspace on switch
 +- [ ] Handle case when monitor has no windows
++
 +```rust
 +fn focus_monitor(&mut self, direction: Direction) {
 +    let current_monitor = self.focused_monitor();
 +    let target = self.monitor_in_direction(current_monitor, direction)?;
++
 +    // Focus the active workspace on target monitor
 +    let workspace = self.monitors[target].active_workspace;
 +    if let Some(window) = self.workspaces[workspace].focused {
 +        self.set_focus(window);
 +    }
++
 +    self.focused_monitor = target;
 +}
 +```
++
 +### 7.4 Move Window to Monitor
 +- [ ] Implement Mod+Shift+comma/period
 +- [ ] Remove from current workspace
 +- [ ] Add to target monitor's active workspace
 +- [ ] Optionally follow window
++
 +```rust
 +fn move_to_monitor(&mut self, direction: Direction) {
 +    let window = self.focused_window()?;
 +    let target_monitor = self.monitor_in_direction(self.focused_monitor, direction)?;
 +    let target_workspace = self.monitors[target_monitor].active_workspace;
++
 +    // Move window
 +    self.current_workspace_mut().tree.remove(window);
 +    self.workspace_mut(target_workspace).tree.insert(window);
++
 +    // Update geometries
 +    self.apply_layouts()?;
 +}
 +```
++
 +### 7.5 Per-Monitor Workspace Switching
 +- [ ] Mod+N switches workspace on focused monitor
 +- [ ] Only switches within monitor's workspace set
 +- [ ] Or switches to workspace and focuses its monitor
 +- [ ] Configurable behavior via Lua
++
 +```rust
 +fn switch_workspace(&mut self, workspace: WorkspaceId) {
 +    // Find which monitor this workspace belongs to
 +    let target_monitor = self.monitors.iter()
 +        .position(|m| m.workspaces.contains(&workspace));
++
 +    match target_monitor {
 +        Some(monitor_idx) => {
 +            // Switch workspace on that monitor
 +            self.monitors[monitor_idx].active_workspace = workspace;
++
 +            // Focus that monitor
 +            self.focused_monitor = monitor_idx;
++
 +            // Update visibility
 +            self.update_workspace_visibility();
 +        }
 +        None => {
 +            tracing::warn!("Workspace {:?} not assigned to any monitor", workspace);
 +        }
 +    }
 +}
 +```
++
 +### 7.6 Monitor Hotplug
 +- [ ] Subscribe to RandR events
 +- [ ] Handle ScreenChangeNotify
 +- [ ] Detect added/removed monitors
 +- [ ] Reassign workspaces as needed
 +- [ ] Move windows from disconnected monitors
++
 +```rust
 +fn handle_randr_event(&mut self, event: randr::ScreenChangeNotifyEvent) {
 +    let new_monitors = detect_monitors(&self.conn, self.root)?;
++
 +    // Find removed monitors
 +    for old in &self.monitors {
 +        if !new_monitors.iter().any(|m| m.name == old.name) {
 +            // Monitor disconnected - move its workspaces/windows
 +            self.handle_monitor_removed(old);
 +        }
 +    }
++
 +    // Find added monitors
 +    for new in &new_monitors {
 +        if !self.monitors.iter().any(|m| m.name == new.name) {
 +            // Monitor connected - assign workspaces
 +            self.handle_monitor_added(new);
 +        }
 +    }
++
 +    self.monitors = new_monitors;
 +    self.apply_all_layouts()?;
 +}
 +```
++
 +### 7.7 EWMH Multi-Monitor
 +- [ ] Set `_NET_DESKTOP_GEOMETRY` (combined size)
 +- [ ] Set `_NET_DESKTOP_VIEWPORT` per workspace
 +- [ ] Set `_NET_WORKAREA` per monitor
 +- [ ] Update on monitor changes
++
 +### 7.8 Lua Configuration
 +- [ ] `gar.assign_workspace(ws, monitor_name)`
 +- [ ] `gar.focus_monitor(direction)` action
 +- [ ] `gar.move_to_monitor(direction)` action
 +- [ ] Configure focus-follows-workspace behavior
++
 +```lua
 +-- Assign specific workspaces to monitors
 +gar.assign_workspace(1, "eDP-1")
 +gar.assign_workspace(2, "eDP-1")
 +gar.assign_workspace(3, "HDMI-1")
 +gar.assign_workspace(4, "HDMI-1")
++
 +-- Keybinds
 +gar.bind("mod+comma", function() gar.focus_monitor("prev") end)
 +gar.bind("mod+period", function() gar.focus_monitor("next") end)
 +gar.bind("mod+shift+comma", function() gar.move_to_monitor("prev") end)
 +gar.bind("mod+shift+period", function() gar.move_to_monitor("next") end)
 +```
++
 +## Keybind Summary
++
 +| Keybind | Action |
 +|---------|--------|
 +| Mod+comma | Focus previous monitor |
 +| Mod+period | Focus next monitor |
 +| Mod+Shift+comma | Move window to previous monitor |
 +| Mod+Shift+period | Move window to next monitor |
++
 +## Acceptance Criteria
++
 +1. Multiple monitors detected correctly
 +2. Each monitor shows its own workspaces
 +3. Mod+comma/period moves focus between monitors
 +4. Mod+Shift+comma/period moves windows between monitors
 +5. Workspace switch on any monitor works
 +6. Hotplug works (monitor disconnect/reconnect)
 +7. Windows from disconnected monitor move to remaining
++
 +## Testing Strategy
++
 +```bash
 +# With multiple monitors (or Xephyr instances)
 +xrandr --listmonitors  # Verify detection
++
 +# Test focus
 +# Mod+period - focus should move to other monitor
 +# Mod+comma - focus should move back
++
 +# Test move
 +# Mod+Shift+period - window should move to other monitor
++
 +# Test hotplug (if possible)
 +# Disconnect monitor, verify workspaces/windows migrate
 +```
++
 +## Notes
++
 +- Consider "primary" monitor concept for default workspace
 +- Polybar needs per-monitor instances
 +- Handle Xinerama fallback for older setups?
 +- Monitor arrangement (which is "left"/"right") comes from xrandr

docs/sprints/sprint-8-ewmh.mdadded

 +# Sprint 8: EWMH Compliance + Polish
++
 +**Goal:** Full EWMH compliance for ecosystem integration, plus visual polish.
++
 +## Objectives
++
 +- Complete EWMH atom support for tools like polybar, rofi, dunst
 +- Proper ICCCM compliance
 +- Visual features: borders, gaps, optional title bars
 +- Urgency hints
++
 +## Prerequisites
++
 +- Sprint 7 complete (multi-monitor)
++
 +## EWMH Compliance
++
 +### Required Atoms
++
 +| Atom | Purpose | Implementation |
 +|------|---------|----------------|
 +| `_NET_SUPPORTED` | List of supported atoms | Set on root |
 +| `_NET_SUPPORTING_WM_CHECK` | WM identification | Child window |
 +| `_NET_CLIENT_LIST` | All managed windows | Update on changes |
 +| `_NET_CLIENT_LIST_STACKING` | Windows in stacking order | Update on changes |
 +| `_NET_NUMBER_OF_DESKTOPS` | Workspace count | Set on init |
 +| `_NET_DESKTOP_GEOMETRY` | Virtual desktop size | Set on init |
 +| `_NET_DESKTOP_VIEWPORT` | Viewport position | Per workspace |
 +| `_NET_CURRENT_DESKTOP` | Active workspace | Update on switch |
 +| `_NET_DESKTOP_NAMES` | Workspace names | Set on init |
 +| `_NET_ACTIVE_WINDOW` | Focused window | Update on focus |
 +| `_NET_WORKAREA` | Usable screen area | Per monitor |
 +| `_NET_WM_NAME` | WM name | "gar" |
 +| `_NET_WM_DESKTOP` | Window's workspace | Per window |
 +| `_NET_WM_STATE` | Window states | Per window |
 +| `_NET_WM_WINDOW_TYPE` | Window type | Read, respect |
++
 +## Tasks
++
 +### 8.1 EWMH Setup
 +- [ ] Create `src/x11/ewmh.rs`
 +- [ ] Intern all EWMH atoms on startup
 +- [ ] Create supporting WM check window
 +- [ ] Set `_NET_SUPPORTED` with all supported atoms
 +- [ ] Set WM name
++
 +```rust
 +pub struct EwmhAtoms {
 +    pub _NET_SUPPORTED: Atom,
 +    pub _NET_SUPPORTING_WM_CHECK: Atom,
 +    pub _NET_CLIENT_LIST: Atom,
 +    pub _NET_CLIENT_LIST_STACKING: Atom,
 +    pub _NET_NUMBER_OF_DESKTOPS: Atom,
 +    pub _NET_CURRENT_DESKTOP: Atom,
 +    pub _NET_DESKTOP_NAMES: Atom,
 +    pub _NET_ACTIVE_WINDOW: Atom,
 +    pub _NET_WM_NAME: Atom,
 +    pub _NET_WM_DESKTOP: Atom,
 +    pub _NET_WM_STATE: Atom,
 +    pub _NET_WM_STATE_FULLSCREEN: Atom,
 +    pub _NET_WM_STATE_HIDDEN: Atom,
 +    pub _NET_WM_STATE_DEMANDS_ATTENTION: Atom,
 +    pub _NET_WM_WINDOW_TYPE: Atom,
 +    pub _NET_WM_WINDOW_TYPE_DIALOG: Atom,
 +    // ... more
 +}
++
 +fn setup_ewmh(conn: &impl Connection, root: Window, atoms: &EwmhAtoms) -> Result<()> {
 +    // Create check window
 +    let check_window = conn.generate_id()?;
 +    conn.create_window(
 +        0, check_window, root,
 +        -1, -1, 1, 1, 0,
 +        WindowClass::INPUT_OUTPUT,
 +        0,
 +        &CreateWindowAux::new(),
 +    )?;
++
 +    // Set supporting WM check
 +    conn.change_property32(
 +        PropMode::REPLACE, root,
 +        atoms._NET_SUPPORTING_WM_CHECK,
 +        AtomEnum::WINDOW,
 +        &[check_window],
 +    )?;
 +    conn.change_property32(
 +        PropMode::REPLACE, check_window,
 +        atoms._NET_SUPPORTING_WM_CHECK,
 +        AtomEnum::WINDOW,
 +        &[check_window],
 +    )?;
++
 +    // Set WM name
 +    conn.change_property8(
 +        PropMode::REPLACE, check_window,
 +        atoms._NET_WM_NAME,
 +        atoms.UTF8_STRING,
 +        b"gar",
 +    )?;
++
 +    // Set supported atoms
 +    let supported = vec![
 +        atoms._NET_SUPPORTED,
 +        atoms._NET_SUPPORTING_WM_CHECK,
 +        // ... all supported atoms
 +    ];
 +    conn.change_property32(
 +        PropMode::REPLACE, root,
 +        atoms._NET_SUPPORTED,
 +        AtomEnum::ATOM,
 +        &supported,
 +    )?;
++
 +    Ok(())
 +}
 +```
++
 +### 8.2 Client List Maintenance
 +- [ ] Update `_NET_CLIENT_LIST` on window add/remove
 +- [ ] Update `_NET_CLIENT_LIST_STACKING` on stacking changes
 +- [ ] Update `_NET_ACTIVE_WINDOW` on focus change
++
 +```rust
 +fn update_client_list(&self, conn: &impl Connection) -> Result<()> {
 +    let windows: Vec<u32> = self.all_windows()
 +        .iter()
 +        .map(|w| w.id)
 +        .collect();
++
 +    conn.change_property32(
 +        PropMode::REPLACE,
 +        self.root,
 +        self.atoms._NET_CLIENT_LIST,
 +        AtomEnum::WINDOW,
 +        &windows,
 +    )?;
++
 +    Ok(())
 +}
 +```
++
 +### 8.3 Handle Client Messages
 +- [ ] Handle `_NET_ACTIVE_WINDOW` (focus requests from apps)
 +- [ ] Handle `_NET_WM_STATE` changes (fullscreen, etc.)
 +- [ ] Handle `_NET_CURRENT_DESKTOP` (pager workspace switch)
 +- [ ] Handle `_NET_CLOSE_WINDOW` (close requests)
++
 +```rust
 +fn handle_client_message(&mut self, event: ClientMessageEvent) -> Result<()> {
 +    let atom = event.type_;
++
 +    if atom == self.atoms._NET_ACTIVE_WINDOW {
 +        // Application requesting focus
 +        let window = event.window;
 +        self.focus_window(window)?;
 +    } else if atom == self.atoms._NET_WM_STATE {
 +        // State change request (e.g., fullscreen)
 +        let action = event.data.as_data32()[0];
 +        let prop = event.data.as_data32()[1];
 +        self.handle_state_change(event.window, action, prop)?;
 +    } else if atom == self.atoms._NET_CURRENT_DESKTOP {
 +        // Workspace switch request
 +        let desktop = event.data.as_data32()[0] as usize;
 +        self.switch_workspace(WorkspaceId(desktop + 1))?;
 +    }
++
 +    Ok(())
 +}
 +```
++
 +### 8.4 Window State Management
 +- [ ] Track window states (fullscreen, hidden, urgent)
 +- [ ] Update `_NET_WM_STATE` property
 +- [ ] Implement fullscreen toggle (Mod+F)
 +- [ ] Handle fullscreen requests from applications
++
 +```rust
 +fn set_fullscreen(&mut self, window: WindowId, fullscreen: bool) -> Result<()> {
 +    let win = self.get_window_mut(window)?;
++
 +    if fullscreen {
 +        // Save current geometry
 +        win.saved_geometry = Some(win.geometry);
 +        // Set to monitor size
 +        let monitor = self.get_monitor_for_window(window);
 +        win.geometry = monitor.geometry;
 +        win.states.insert(WindowState::Fullscreen);
 +    } else {
 +        // Restore geometry
 +        if let Some(saved) = win.saved_geometry.take() {
 +            win.geometry = saved;
 +        }
 +        win.states.remove(&WindowState::Fullscreen);
 +    }
++
 +    // Update X property
 +    self.update_wm_state(window)?;
 +    self.apply_geometry(window)?;
++
 +    Ok(())
 +}
 +```
++
 +### 8.5 ICCCM Compliance
 +- [ ] Create `src/x11/icccm.rs`
 +- [ ] Handle `WM_HINTS` (urgency, input, etc.)
 +- [ ] Handle `WM_NORMAL_HINTS` (size hints)
 +- [ ] Handle `WM_PROTOCOLS` (delete window, take focus)
 +- [ ] Handle `WM_TRANSIENT_FOR`
++
 +```rust
 +fn get_wm_hints(conn: &impl Connection, window: Window) -> Result<Option<WmHints>> {
 +    // Read WM_HINTS property
 +    // Parse into struct
 +}
++
 +fn get_size_hints(conn: &impl Connection, window: Window) -> Result<Option<SizeHints>> {
 +    // Read WM_NORMAL_HINTS
 +    // Extract min/max size, aspect ratio, etc.
 +}
 +```
++
 +### 8.6 Border Colors
 +- [ ] Configurable border colors via Lua
 +- [ ] Different colors: focused, unfocused, urgent
 +- [ ] Apply colors on focus change
 +- [ ] Flash urgent windows
++
 +```rust
 +fn update_border_color(&self, conn: &impl Connection, window: WindowId) -> Result<()> {
 +    let win = self.get_window(window)?;
 +    let color = if win.urgent {
 +        self.config.border_color_urgent
 +    } else if Some(window) == self.focused {
 +        self.config.border_color_focused
 +    } else {
 +        self.config.border_color_unfocused
 +    };
++
 +    conn.change_window_attributes(
 +        window,
 +        &ChangeWindowAttributesAux::new().border_pixel(color),
 +    )?;
++
 +    Ok(())
 +}
 +```
++
 +### 8.7 Gaps
 +- [ ] Inner gaps (between windows)
 +- [ ] Outer gaps (screen edge)
 +- [ ] Configurable via Lua
 +- [ ] Apply in geometry calculation
++
 +```rust
 +fn calculate_geometries_with_gaps(&self, rect: Rect, gaps: &GapConfig) -> Vec<(WindowId, Rect)> {
 +    // Shrink rect by outer gaps
 +    let work_area = Rect {
 +        x: rect.x + gaps.outer as i16,
 +        y: rect.y + gaps.outer as i16,
 +        width: rect.width - 2 * gaps.outer,
 +        height: rect.height - 2 * gaps.outer,
 +    };
++
 +    // Calculate from tree
 +    let mut geometries = self.tree.calculate_geometries(work_area);
++
 +    // Apply inner gaps
 +    for (_, geom) in &mut geometries {
 +        geom.x += gaps.inner as i16 / 2;
 +        geom.y += gaps.inner as i16 / 2;
 +        geom.width -= gaps.inner;
 +        geom.height -= gaps.inner;
 +    }
++
 +    geometries
 +}
 +```
++
 +### 8.8 Optional Title Bars
 +- [ ] Create title bar windows (reparenting)
 +- [ ] Draw window title
 +- [ ] Handle title bar clicks (focus, move)
 +- [ ] Configurable per window class
 +- [ ] Double-click to toggle maximize
++
 +```rust
 +fn create_frame(&mut self, conn: &impl Connection, window: WindowId) -> Result<Frame> {
 +    let title_height = if self.should_have_titlebar(window) {
 +        self.config.titlebar_height
 +    } else {
 +        0
 +    };
++
 +    // Create frame window
 +    let frame = conn.generate_id()?;
 +    conn.create_window(/* ... */)?;
++
 +    // Reparent client into frame
 +    conn.reparent_window(window, frame, 0, title_height)?;
++
 +    Ok(Frame { id: frame, client: window, title_height })
 +}
 +```
++
 +### 8.9 Urgency Hints
 +- [ ] Read `WM_HINTS` urgency flag
 +- [ ] Read `_NET_WM_STATE_DEMANDS_ATTENTION`
 +- [ ] Set urgent border color
 +- [ ] Indicate urgent workspace (for status bars)
 +- [ ] Clear urgency on focus
++
 +```rust
 +fn handle_urgency(&mut self, window: WindowId) -> Result<()> {
 +    let hints = get_wm_hints(&self.conn, window)?;
++
 +    if hints.map(|h| h.urgent).unwrap_or(false) {
 +        let win = self.get_window_mut(window)?;
 +        win.urgent = true;
++
 +        // Update workspace urgency
 +        let ws = self.get_workspace_for_window(window)?;
 +        self.workspaces[ws].urgent = true;
++
 +        // Update EWMH
 +        self.set_wm_state(window, StateAction::Add, self.atoms._NET_WM_STATE_DEMANDS_ATTENTION)?;
++
 +        // Update border
 +        self.update_border_color(window)?;
 +    }
++
 +    Ok(())
 +}
 +```
++
 +### 8.10 External Compositor Integration
++
 +**Goal:** Support external compositors (picom) for proper screen repainting and visual effects.
++
 +#### Background
++
 +Like i3, gar is NOT a compositing window manager. We rely on external compositors (picom, compton, xcompmgr) for:
 +- Proper screen repainting when windows close
 +- Transparency and visual effects
 +- Vsync and tear-free rendering
++
 +Without a compositor, X11 does not automatically repaint exposed areas when windows close, leading to visual artifacts (old window pixels remaining on screen).
++
 +#### Tasks
 +- [ ] Add picom launch to `gar-session.sh` (before gar starts)
 +- [ ] Add picom launch to `start-gar.sh` xinitrc
 +- [ ] Keep `clear_root_area()` as fallback for compositor-less setups
 +- [ ] Add `_NET_WM_BYPASS_COMPOSITOR` atom (for fullscreen apps to request un-redirection)
++
 +#### Session Script Changes
 +```bash
 +# Launch compositor before WM
 +picom -b --use-ewmh-active-win &
 +sleep 0.1  # Brief pause to let compositor initialize
 +```
++
 +#### Recommended Picom Flags
 +- `-b` or `--daemon`: Run as background daemon
 +- `--use-ewmh-active-win`: Use `_NET_ACTIVE_WINDOW` for focus (more reliable with tiling WMs)
 +- `--backend glx`: Better for screen tearing prevention (optional)
++
 +#### EWMH Atoms for Compositors
 +| Atom | Purpose | Who Sets It |
 +|------|---------|-------------|
 +| `_NET_WM_BYPASS_COMPOSITOR` | Un-redirect fullscreen windows | Apps (games, videos) |
 +| `_NET_ACTIVE_WINDOW` | Currently focused window | WM (gar) |
 +| `_NET_WM_OPACITY` | Window opacity hint | Apps or user tools |
++
 +#### Fallback Behavior
 +The `clear_root_area()` function remains as a fallback for users who don't have picom installed. When a compositor is running, it handles repainting automatically and `clear_root_area()` becomes a no-op in effect.
++
 +#### Acceptance Criteria
 +1. Windows close without visual artifacts when picom is running
 +2. No screen tearing during window operations
 +3. Fallback still works when picom is not installed (uses `clear_root_area()`)
 +4. Fullscreen apps (games, videos) can bypass compositor via `_NET_WM_BYPASS_COMPOSITOR`
++
 +---
++
 +## Keybind Summary
++
 +| Keybind | Action |
 +|---------|--------|
 +| Mod+F | Toggle fullscreen |
++
 +## Acceptance Criteria
++
 +1. Polybar shows workspaces correctly
 +2. Rofi can list and switch windows
 +3. Dunst notifications work properly
 +4. Applications can request fullscreen
 +5. Borders and gaps configurable and working
 +6. Urgent windows highlighted
 +7. No errors from EWMH-compliant applications
++
 +## Testing Strategy
++
 +```bash
 +# Polybar
 +# Install polybar, configure xworkspaces module
 +# Workspaces should display, clicking should switch
++
 +# Rofi
 +rofi -show window  # Should list all windows
 +# Selecting window should focus it
++
 +# Fullscreen
 +# Open Firefox, press F11
 +# Should go fullscreen correctly
 +# Press F11 again, should restore
++
 +# Urgency
 +# Set urgent hint on a window
 +# Border should change, workspace should indicate
 +```
++
 +## Notes
++
 +- EWMH spec: https://specifications.freedesktop.org/wm-spec/latest/
 +- ICCCM spec: https://tronche.com/gui/x/icccm/
 +- Title bars add complexity - consider making opt-in
 +- Test with various applications (Firefox, Chromium, mpv, etc.)

docs/sprints/sprint-9-mvp-polish.mdadded

 +# Sprint 9: MVP Polish + Testing
++
 +**Goal:** Stable, documented MVP ready for release.
++
 +## Objectives
++
 +- Robust error handling throughout
 +- Crash recovery (restart in place)
 +- Documentation (man pages, examples)
 +- Integration testing
 +- Installation packaging
++
 +## Prerequisites
++
 +- Sprint 8 complete (EWMH, polish)
++
 +## Tasks
++
 +### 9.1 Error Handling Audit
 +- [ ] Review all `unwrap()` and `expect()` calls
 +- [ ] Replace with proper error handling
 +- [ ] Add context to errors with `thiserror`
 +- [ ] Log errors appropriately
 +- [ ] Never crash on X errors (use error handler)
++
 +```rust
 +// Bad
 +let window = self.get_window(id).unwrap();
++
 +// Good
 +let window = self.get_window(id)
 +    .ok_or_else(|| Error::WindowNotFound(id))?;
++
 +// With context
 +let tree = std::fs::read_to_string(&config_path)
 +    .map_err(|e| Error::ConfigLoad { path: config_path.clone(), source: e })?;
 +```
++
 +### 9.2 X Error Handling
 +- [ ] Set up X error handler
 +- [ ] Log X errors without crashing
 +- [ ] Handle "window destroyed" race conditions
 +- [ ] Recover from non-fatal errors
++
 +```rust
 +fn setup_error_handler(conn: &impl Connection) {
 +    // X11 error handling is synchronous in x11rb
 +    // Wrap operations that might fail due to window destruction
 +}
++
 +fn safe_configure_window(
 +    conn: &impl Connection,
 +    window: Window,
 +    aux: &ConfigureWindowAux,
 +) -> Result<()> {
 +    match conn.configure_window(window, aux)?.check() {
 +        Ok(_) => Ok(()),
 +        Err(e) if is_window_error(&e) => {
 +            tracing::debug!("Window {} no longer exists", window);
 +            Ok(()) // Not a fatal error
 +        }
 +        Err(e) => Err(e.into()),
 +    }
 +}
 +```
++
 +### 9.3 Crash Recovery
 +- [ ] Implement `--replace` flag
 +- [ ] Save state before exit/crash
 +- [ ] Restore state on restart
 +- [ ] Handle SIGTERM/SIGINT gracefully
 +- [ ] Support restart-in-place (Mod+Shift+R alternative)
++
 +```rust
 +fn save_state(&self, path: &Path) -> Result<()> {
 +    let state = SavedState {
 +        workspaces: self.workspaces.iter().map(|ws| {
 +            SavedWorkspace {
 +                name: ws.name.clone(),
 +                windows: ws.all_windows(),
 +            }
 +        }).collect(),
 +        focused: self.focused,
 +    };
 +    let json = serde_json::to_string(&state)?;
 +    std::fs::write(path, json)?;
 +    Ok(())
 +}
++
 +fn restore_state(&mut self, path: &Path) -> Result<()> {
 +    let json = std::fs::read_to_string(path)?;
 +    let state: SavedState = serde_json::from_str(&json)?;
 +    // Restore workspaces and focus
 +    Ok(())
 +}
++
 +fn handle_signal(sig: i32) {
 +    match sig {
 +        SIGTERM | SIGINT => {
 +            // Save state and exit cleanly
 +            save_state(&state_path).ok();
 +            std::process::exit(0);
 +        }
 +        SIGUSR1 => {
 +            // Restart in place
 +            save_state(&state_path).ok();
 +            exec_self();
 +        }
 +        _ => {}
 +    }
 +}
 +```
++
 +### 9.4 Man Pages
 +- [ ] Create `docs/gar.1` (main man page)
 +- [ ] Create `docs/garctl.1` (CLI tool)
 +- [ ] Create `docs/gar-lua.5` (configuration)
 +- [ ] Document all keybinds and options
++
 +```man
 +.TH GAR 1 "2024" "gar" "User Commands"
 +.SH NAME
 +gar \- tiling window manager with smart splits
 +.SH SYNOPSIS
 +.B gar
 +[\fIOPTIONS\fR]
 +.SH DESCRIPTION
 +.B gar
 +is an X11 tiling window manager that automatically determines
 +the optimal split direction when creating new windows.
 +.SH OPTIONS
 +.TP
 +.B \-c, \-\-config FILE
 +Use alternate configuration file
 +.TP
 +.B \-\-replace
 +Replace currently running window manager
 +.TP
 +.B \-v, \-\-version
 +Print version and exit
 +.SH FILES
 +.TP
 +.I ~/.config/gar/init.lua
 +Default configuration file
 +.TP
 +.I $XDG_RUNTIME_DIR/gar.sock
 +IPC socket
 +.SH SEE ALSO
 +.BR garctl (1),
 +.BR gar-lua (5)
 +```
++
 +### 9.5 Example Configurations
 +- [ ] Create `examples/minimal.lua`
 +- [ ] Create `examples/i3-like.lua`
 +- [ ] Create `examples/gaps-and-borders.lua`
 +- [ ] Create `examples/polybar-integration.lua`
 +- [ ] Document each example
++
 +### 9.6 Integration Tests
 +- [ ] Set up test infrastructure with Xvfb
 +- [ ] Test window creation/destruction
 +- [ ] Test workspace switching
 +- [ ] Test keybind execution
 +- [ ] Test IPC commands
 +- [ ] Test config loading
++
 +```rust
 +// tests/integration.rs
 +use std::process::Command;
++
 +fn setup_xvfb() -> XvfbGuard {
 +    // Start Xvfb on :99
 +    // Return guard that kills on drop
 +}
++
 +#[test]
 +fn test_window_tiling() {
 +    let _xvfb = setup_xvfb();
++
 +    // Start gar
 +    let mut gar = Command::new("cargo")
 +        .args(["run", "--"])
 +        .env("DISPLAY", ":99")
 +        .spawn()
 +        .unwrap();
++
 +    // Wait for startup
 +    std::thread::sleep(Duration::from_millis(500));
++
 +    // Open windows
 +    Command::new("xterm")
 +        .env("DISPLAY", ":99")
 +        .spawn()
 +        .unwrap();
++
 +    // Verify via IPC
 +    let output = Command::new("garctl")
 +        .args(["get-tree"])
 +        .env("DISPLAY", ":99")
 +        .output()
 +        .unwrap();
++
 +    let tree: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
 +    // Assert tree structure
++
 +    gar.kill().unwrap();
 +}
 +```
++
 +### 9.7 Installation Script
 +- [ ] Create `install.sh` for manual install
 +- [ ] Create Makefile with install target
 +- [ ] Document dependencies
 +- [ ] Test on fresh system
++
 +```bash
 +#!/bin/bash
 +# install.sh
++
 +set -e
++
 +PREFIX=${PREFIX:-/usr/local}
++
 +cargo build --release
++
 +install -Dm755 target/release/gar "$PREFIX/bin/gar"
 +install -Dm755 target/release/garctl "$PREFIX/bin/garctl"
 +install -Dm644 gar.desktop "$PREFIX/share/xsessions/gar.desktop"
 +install -Dm644 docs/gar.1 "$PREFIX/share/man/man1/gar.1"
 +install -Dm644 docs/garctl.1 "$PREFIX/share/man/man1/garctl.1"
++
 +echo "Installation complete!"
 +```
++
 +### 9.8 AUR Package (optional)
 +- [ ] Create PKGBUILD
 +- [ ] Test in clean chroot
 +- [ ] Submit to AUR
++
 +```bash
 +# PKGBUILD
 +pkgname=gar
 +pkgver=0.1.0
 +pkgrel=1
 +pkgdesc="Tiling window manager with smart splits"
 +arch=('x86_64')
 +url="https://github.com/youruser/gar"
 +license=('MIT')
 +depends=('libxcb' 'lua')
 +makedepends=('rust' 'cargo')
++
 +build() {
 +    cd "$srcdir/$pkgname-$pkgver"
 +    cargo build --release
 +}
++
 +package() {
 +    cd "$srcdir/$pkgname-$pkgver"
 +    install -Dm755 target/release/gar "$pkgdir/usr/bin/gar"
 +    install -Dm755 target/release/garctl "$pkgdir/usr/bin/garctl"
 +    install -Dm644 gar.desktop "$pkgdir/usr/share/xsessions/gar.desktop"
 +}
 +```
++
 +### 9.9 README and Documentation
 +- [ ] Update README with features, screenshots
 +- [ ] Add CONTRIBUTING.md
 +- [ ] Add LICENSE file
 +- [ ] Document known issues/limitations
++
 +### 9.10 Final Testing Checklist
 +- [ ] Fresh install works
 +- [ ] All documented keybinds work
 +- [ ] Polybar integration works
 +- [ ] Rofi integration works
 +- [ ] Multi-monitor works
 +- [ ] Config reload works
 +- [ ] No memory leaks (valgrind)
 +- [ ] No crash on stress test
++
 +## Acceptance Criteria
++
 +1. No panics in release build under normal use
 +2. Man pages installed and accessible
 +3. Example configs provided and documented
 +4. Integration tests pass
 +5. Install script works on fresh Arch/Ubuntu
 +6. README provides clear getting started guide
++
 +## Testing Strategy
++
 +```bash
 +# Full test suite
 +cargo test
++
 +# Integration tests (requires Xvfb)
 +cargo test --test integration
++
 +# Memory check
 +valgrind --leak-check=full target/release/gar
++
 +# Stress test
 +for i in {1..100}; do
 +    DISPLAY=:1 xterm &
 +done
 +# Then close all, verify no issues
 +```
++
 +## MVP Feature Summary
++
 +After Sprint 9, gar will have:
++
 +- Smart split detection (the core feature)
 +- Full keyboard navigation
 +- 10 workspaces
 +- Multi-monitor support
 +- Floating window support
 +- Lua configuration
 +- IPC system with garctl
 +- EWMH compliance
 +- Configurable borders and gaps
 +- Documentation and examples
++
 +## Post-MVP Ideas (Future Sprints)
++
 +- Scratchpad windows
 +- Tabbed/stacked layouts
 +- Animations (fade, slide)
 +- Built-in bar (optional)
 +- Session save/restore
 +- Marks (like vim marks)
 +- Modes (resize mode, move mode)
 +- More layout algorithms