x11-overlay 0.1.0

# X11 Overlay

A lightweight, transparent overlay system for X11 window managers. Create click-through overlays with custom UI components for status displays, HUDs, and desktop enhancements.

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://www.rust-lang.org)
[![Status](https://img.shields.io/badge/status-early%20development-yellow.svg)](https://github.com/cinnes/x11-overlay)

## Features

- **Universal X11 compatibility** - Works with any EWMH-compliant window manager
- **True transparency** - Uses ARGB visuals for seamless integration
- **Click-through support** - XShape extension allows interaction with windows below
- **Text rendering** - Cairo-based text rendering with font support and layouts
- **Composite components** - Status panels, notifications, and progress bars
- **Modular architecture** - Component-based UI system for easy extensibility
- **Minimal dependencies** - Lightweight Rust implementation with essential X11 libraries
- **Development ready** - Pre-commit hooks, clippy, and rustfmt integration

## Quick Start

```bash
# Clone and build
git clone https://github.com/cinnes/x11-overlay.git
cd x11-overlay
cargo build --release

# Run the overlay
./target/release/x11-overlay
```

## Requirements

- **X11 server** with ARGB visual support
- **XShape extension** (standard on modern systems)
- **Compositor** (picom, compton, etc.) for transparency effects
- **Cairo library** for text rendering (libcairo2-dev)
- **Rust 1.70+** for building from source

## Compatibility

**Should work with EWMH-compliant window managers:**
- i3wm
- awesome
- bspwm
- openbox
- Xfce (xfwm4)
- Others supporting standard X11 protocols

## Architecture

```
src/
├── graphics/     # Rendering system (X11 + Cairo text)
├── ui/          # Component system and composite widgets
├── x11/         # X11 utilities and visual helpers
├── overlay.rs   # Core X11 window management
└── main.rs      # Application entry point
```

### Component System

Create custom overlay elements by implementing the `Component` trait:

```rust
use crate::graphics::{Color, GraphicsContext, Rectangle};
use crate::ui::Component;
use anyhow::Result;

struct StatusBar {
    position: Rectangle,
    color: Color,
}

impl Component for StatusBar {
    fn render(&self, graphics: &mut GraphicsContext) -> Result<()> {
        graphics.renderer().fill_rectangle(self.position, self.color.to_renderer_color())
    }

    fn bounds(&self) -> Rectangle {
        self.position
    }

    fn update(&mut self, _delta_time: f64) -> bool {
        false // No animation needed
    }
}
```

### Built-in Components

- **TextComponent** - Rendered text with font, color, and alignment options
- **StatusPanel** - Titled panel with multiple text lines
- **NotificationComponent** - Auto-fading notifications with icon area
- **ProgressBarComponent** - Labeled progress bars with customizable colors

## Configuration

The overlay uses standard X11 properties and can be configured through window manager rules:

```bash
# i3wm example
for_window [class="x11-overlay"] floating enable, border none
```

## Development

### Setup
```bash
# Install pre-commit hooks
git config core.hooksPath .githooks

# Run quality checks
cargo clippy
cargo fmt
# Note: Test suite is in development
```

### Project Standards
- **Error handling**: Comprehensive error contexts with `anyhow`
- **Code quality**: Clippy lints enforced, rustfmt formatting
- **Architecture**: Modular design with clear separation of concerns

## Status

**Current State**: Early development with text rendering support
- Core X11 overlay functionality implemented
- Text rendering with Cairo integration
- Component architecture with built-in widgets
- Demo application showing composite components

**Performance**: Lightweight design optimized for minimal resource usage

## Roadmap

- [ ] Image/icon support
- [ ] Enhanced layout system
- [ ] Configuration file support
- [ ] Input handling for interactive components
- [ ] Wayland compatibility layer

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Code Review Process
1. All changes require pre-commit hook approval
2. Follow established architectural patterns
3. Manual testing required (automated tests in development)

## License

Licensed under the MIT License. See [LICENSE](LICENSE) for details.

## Acknowledgments

Built with:
- [x11rb](https://github.com/psychon/x11rb) - Pure Rust X11 client library
- [cairo-rs](https://github.com/gtk-rs/gtk-rs-core/tree/master/cairo) - Cairo graphics bindings
- [anyhow](https://github.com/dtolnay/anyhow) - Flexible error handling

---

*This project follows Google's engineering standards for open source projects.*