From 90b460ddaabe495e48ac5074e53d7a8c8892b1fd Mon Sep 17 00:00:00 2001 From: retoor Date: Fri, 9 Jan 2026 00:18:43 +0100 Subject: [PATCH] chore: update html, md files --- README.md | 495 +++++++++++----------------------------- site/ai-features.html | 12 + site/documentation.html | 64 ++++++ site/features.html | 30 +++ site/index.html | 12 + 5 files changed, 247 insertions(+), 366 deletions(-) diff --git a/README.md b/README.md index 2357c6c..84c3504 100644 --- a/README.md +++ b/README.md @@ -1,431 +1,194 @@ # DWN - Desktop Window Manager -Author: retoor +DWN is a high-performance, X11-compliant window manager written in ANSI C. It combines the efficiency of tiling layouts with the usability of a full desktop environment, featuring integrated status bars, system tray support, and a robust notification system. -A lightweight, AI-enhanced window manager for Linux with tiling, floating, and fullscreen layouts. +## Project Vision -## Quick Start (Copy & Paste These Commands) +The Desktop Window Manager (DWN) is designed for users who seek a productive, tiling-first workflow without sacrificing modern desktop features. It adheres to EWMH and ICCCM standards, ensuring compatibility with contemporary applications while providing advanced automation capabilities through its built-in WebSocket API. -```bash -# 1. Install dependencies (enter your password when asked) -make deps +## Key Features -# 2. Build DWN -make - -# 3. Test it (opens in a safe window - won't affect your desktop) -make run -``` - -That's it! Press `Super+Backspace` to exit the test window. - ---- - -## What is DWN? - -DWN is a **window manager** - the program that controls how windows look and behave on your screen. It replaces your current desktop environment (like GNOME, KDE, or XFCE) with a faster, keyboard-driven alternative. - -**Features:** -- 3 window layouts: Tiling (windows don't overlap), Floating (like normal), Monocle (fullscreen) -- 9 virtual workspaces to organize your windows -- Built-in panels with clock, taskbar, and system tray -- XDG Autostart support (automatically starts nm-applet, blueman, etc.) -- WiFi network selector with dropdown menu (like XFCE) -- Audio volume indicator with scroll-to-adjust -- Desktop notifications -- Optional AI assistant (can launch apps by command!) -- Very fast and lightweight - ---- +* **Hybrid Layout Management**: Seamlessly switch between Tiling (Master-Stack), Monocle, and Floating modes on a per-workspace basis. +* **Virtual Workspaces**: Supports 9 independent workspaces with persistent state and layout configurations. +* **Integrated Desktop Components**: + * **Status Panel**: Built-in top and bottom panels with workspace indicators, taskbars, and system clocks. + * **System Tray**: XEmbed-compliant systray implementation. + * **Notification Daemon**: Integrated D-Bus notification server support. +* **AI Integration**: Native support for LLM-assisted window management and semantic command execution. + * **Command Palette**: Intelligent prompt-based interface for window and system management. + * **Auto-Organization**: Context-aware window placement and workspace optimization. + * **Smart Notifications**: Intelligent filtering and prioritization based on application context. + * **Semantic Search**: Deep integration with Exa for enhanced application launching and web search. +* **Extensible API**: A real-time WebSocket interface for remote control and introspection. ## Installation -### Step 1: Install Dependencies +### Prerequisites -Run this command (works on Ubuntu, Debian, Fedora, and Arch): +DWN requires the following development libraries: +* `libX11`, `libXext`, `libXinerama`, `libXrandr`, `libXft` +* `fontconfig` +* `libdbus-1` +* `libcurl` (for AI features) + +### Building ```bash +# Clone the repository +git clone https://github.com/your-repo/dwn.git +cd dwn + +# Install dependencies (automated for apt/dnf/pacman) make deps -``` -This installs everything DWN needs. You'll need to enter your password. - -**If `make deps` doesn't work**, install manually: -- Ubuntu/Debian: `sudo apt install build-essential pkg-config libx11-dev libxext-dev libxinerama-dev libxrandr-dev libdbus-1-dev libcurl4-openssl-dev xserver-xephyr dmenu network-manager alsa-utils` -- Fedora: `sudo dnf install gcc make pkg-config libX11-devel libXext-devel libXinerama-devel libXrandr-devel dbus-devel libcurl-devel xorg-x11-server-Xephyr dmenu NetworkManager alsa-utils` -- Arch: `sudo pacman -S base-devel pkg-config libx11 libxext libxinerama libxrandr dbus curl xorg-server-xephyr dmenu networkmanager alsa-utils` - -### Step 2: Build - -```bash +# Compile the project make ``` -You should see "Build successful!" at the end. +### Running -### Step 3: Test (Recommended!) - -Before installing, test DWN in a safe window: +To test DWN without affecting your current session, use the provided Xephyr-based runner: ```bash make run ``` -This opens DWN inside a window on your current desktop. You can try it out without changing anything. Press `Super+Backspace` to close it. - -### Step 4: Install +To install system-wide: ```bash sudo make install ``` -### Step 5: Use DWN +## AI-Assisted Management -1. Log out of your current session -2. At the login screen, click the **gear icon** (or session selector) near your username -3. Select **"DWN"** from the list -4. Log in! +DWN differentiates itself through deep integration with Large Language Models (LLMs) via the OpenRouter API. This allows for semantic understanding of your workflow and proactive window management. ---- +### Features +* **Natural Language Commands**: Control your workspace using plain English (e.g., "move all browser windows to workspace 3", "arrange my coding environment"). +* **Intelligent Context**: The AI is aware of your active windows, workspace layouts, and historical usage patterns. +* **Workflow Optimization**: Proactive suggestions for layout changes based on your current activity (coding vs. browsing vs. communication). +* **Semantic App Launcher**: Find and launch applications based on intent rather than just binary names. -## Basic Controls +To use AI features, configure your API keys in `config.ini`: +```ini +[ai] +enabled = true +model = anthropic/claude-3-sonnet +openrouter_key = YOUR_API_KEY +exa_key = YOUR_EXA_KEY +``` -### Essential Shortcuts (Memorize These!) +## WebSocket API -| Keys | What it does | -|------|--------------| -| `Ctrl + Alt + T` | Open a terminal | -| `Super` or `Alt + F2` | Open app launcher | -| `Super + E` | Open file manager | -| `Super + B` | Open web browser | -| `Alt + Tab` | Switch between windows | -| `Alt + F4` | Close current window | -| `Super + Backspace` | **Exit DWN** (important!) | -| `Super + S` | **Show all shortcuts** | -| `Super + T` | **Start interactive tutorial** | -| `Super + Shift + D` | **Demo mode** (automated feature showcase) | +DWN exposes a powerful WebSocket API that allows external applications to monitor state and control the window manager programmatically. -### Workspaces +### Connectivity +* **Default Port**: `8777` +* **Endpoint**: `ws://localhost:8777/ws` +* **Protocol**: JSON-RPC style messages -| Keys | What it does | -|------|--------------| -| `Ctrl + Alt + Right` | Next workspace | -| `Ctrl + Alt + Left` | Previous workspace | -| `F1` to `F9` | Switch to workspace 1-9 | -| `Shift + F1` to `Shift + F9` | Move window to workspace 1-9 | +The API is disabled by default. It can be enabled in the configuration file: +```ini +[api] +enabled = true +port = 8777 +``` -### Window Management +### API Commands -| Keys | What it does | -|------|--------------| -| `Alt + F9` | Toggle minimize/restore | -| `Alt + F10` | Toggle maximize | -| `Alt + F11` | Toggle fullscreen | -| `Super + F9` | Toggle floating mode | -| `Alt + Tab` | Cycle windows forward | -| `Alt + Shift + Tab` | Cycle windows backward | +All commands are sent as JSON objects containing a `command` field. -### Layout Control (Super key shortcuts) +#### 1. `get_status` +Retrieves the current state of the window manager. +* **Response**: Returns an object with version, current workspace ID, and total client count. -| Keys | What it does | -|------|--------------| -| `Super + Space` | Change layout mode (tiling → floating → monocle) | -| `Super + H` | Shrink main area | -| `Super + L` | Expand main area | -| `Super + I` | Add window to main area | -| `Super + D` | Remove window from main area | -| `Super + Left` | Snap window to left half (50% width) | -| `Super + Right` | Snap window to right half (50% width) | +#### 2. `get_workspaces` +Lists all workspaces and their current configuration. +* **Response**: An array of workspace objects (ID, Name, Layout, Client Count). -### AI Features (Optional) +#### 3. `get_clients` +Lists all managed windows across all workspaces. +* **Response**: An array of client objects containing: + * `window`: X11 Window ID + * `title`: Window title + * `class`: Window class + * `workspace`: Workspace ID + * `geometry`: x, y, width, height + * `focused`: Boolean indicating focus state -| Keys | What it does | -|------|--------------| -| `Super + A` | Show AI context info | -| `Super + Shift + A` | Ask AI to do something (e.g., "open firefox") | -| `Super + Shift + E` | Exa semantic web search | +#### 4. `switch_workspace` +Changes the active workspace. +* **Parameters**: `{"command": "switch_workspace", "workspace": }` -### News Ticker +#### 5. `run_command` +Executes an arbitrary shell command. +* **Parameters**: `{"command": "run_command", "exec": ""}` -The bottom panel displays a scrolling news ticker. Navigate articles with these shortcuts: +#### 6. `focus_client` +Focuses a specific window and switches to its workspace if necessary. +* **Parameters**: `{"command": "focus_client", "window": }` -| Keys | What it does | -|------|--------------| -| `Super + Down` | Next news article | -| `Super + Up` | Previous news article | -| `Super + Return` | Open current article in browser | +### Example Usage (Python) -### Other Shortcuts +```python +import websocket +import json -| Keys | What it does | -|------|--------------| -| `Print` | Take screenshot (xfce4-screenshooter) | +ws = websocket.create_connection("ws://localhost:8777/ws") ---- +# Switch to workspace 2 +ws.send(json.dumps({ + "command": "switch_workspace", + "workspace": 2 +})) -## System Tray +# Get all clients +ws.send(json.dumps({"command": "get_clients"})) +result = ws.recv() +print(json.loads(result)) -The top panel includes a system tray on the right side with support for external application icons plus built-in battery, audio, and WiFi indicators. +ws.close() +``` -### XEmbed System Tray (External Application Icons) +### Advanced API Examples -DWN implements the freedesktop.org XEmbed System Tray protocol, allowing external applications to dock their status icons in the panel - just like XFCE, GNOME, or KDE. This means applications like: +The `scripts/api_examples/` directory contains several sophisticated applications leveraging the WebSocket API: -- **Telegram** - Shows notification icon when messages arrive -- **nm-applet** - NetworkManager GUI applet -- **blueman-applet** - Bluetooth manager -- **pasystray** - PulseAudio volume control -- **udiskie** - USB device automounter -- **clipit/parcellite** - Clipboard managers - -...will automatically appear in your system tray when launched. - -Simply start any application with tray icon support and it will dock itself in the panel. Click on icons to interact with them - clicks are forwarded to the application. - -### Battery Indicator - -Shows battery percentage on laptops with color coding: -- **Green**: > 50% -- **Yellow**: 20-50% -- **Red**: < 20% -- **Blue**: Charging - -### WiFi Indicator - -Located in the top-right corner of the panel, showing your current connection status. - -| Action | What it does | -|--------|--------------| -| **Click** on WiFi icon | Open dropdown with available networks | -| **Click** on a network | Connect to that network | -| **Click** on connected network | Disconnect | - -The dropdown shows: -- Available WiFi networks with signal strength -- `●` marker next to the currently connected network -- Networks are sorted and updated automatically - -**Note:** Requires NetworkManager (`nmcli`) to be installed. - -### Audio Indicator - -Shows current volume level next to the WiFi indicator. - -| Action | What it does | -|--------|--------------| -| **Left-click** | Toggle mute/unmute | -| **Scroll up** | Increase volume by 5% | -| **Scroll down** | Decrease volume by 5% | - -**Note:** Requires ALSA utilities (`amixer`) to be installed. - ---- +* **Window Picker (`window_picker_fzf.py`)**: A terminal-based window switcher using `fzf`. It allows for fuzzy-searching through all open windows across all workspaces and jumping to the selected one. +* **Web Remote (`web_remote.html`)**: A standalone, mobile-friendly HTML5 dashboard. Control your window manager from a tablet or phone on the same network. +* **Session Manager (`session_manager.py`)**: Save and restore your window layouts. Snapshots current open applications and their workspace assignments for easy restoration. +* **Auto-Manager (`listen.py`)**: A background service that monitors workspace occupancy and proactively suggests moving windows if a workspace becomes too crowded. ## Configuration -DWN can be customized by editing a config file. +DWN looks for a configuration file at `~/.config/dwn/config.ini`. If not found, it falls back to `/etc/dwn/config.ini`. -### Create Your Config +Refer to `config/config.example` for a documented template of all available options, including color schemes, keybindings, and autostart commands. -```bash -mkdir -p ~/.config/dwn -cp /etc/dwn/config.example ~/.config/dwn/config -``` +## Development -### Edit Your Config +DWN is built with modularity in mind. Each major component is isolated in its own source file to facilitate easier debugging and feature additions. -Open `~/.config/dwn/config` in any text editor. Here are common changes: +### Key Components +* `src/main.c`: The core event loop and X11 event dispatcher. +* `src/client.c`: Window management logic (framing, focus, resizing). +* `src/layout.c`: Tiling and floating layout algorithms. +* `src/api.c`: WebSocket server and JSON command handler. +* `src/ai.c`: OpenRouter API integration and semantic logic. -**Change terminal:** -```ini -[general] -terminal = gnome-terminal -``` -Options: `xfce4-terminal`, `gnome-terminal`, `konsole`, `alacritty`, `xterm` +### Coding Standards +* Strict adherence to ANSI C (C89/C90) for maximum compatibility. +* No external dependencies beyond standard X11 and networking libraries. +* Formatting is enforced via `clang-format`. Run `make format` before submitting patches. -**Change app launcher:** -```ini -[general] -launcher = rofi -show run -``` +## Codebase Structure -**Change layout:** -```ini -[layout] -default = floating -``` -Options: `tiling`, `floating`, `monocle` - -**Change window gaps:** -```ini -[appearance] -gap = 10 -border_width = 2 -``` - -**Configure autostart:** -```ini -[autostart] -enabled = true -xdg_autostart = true -path = ~/.config/dwn/autostart.d -``` - -DWN automatically starts applications from XDG autostart directories: -- `/etc/xdg/autostart/` - System apps (nm-applet, blueman, etc.) -- `~/.config/autostart/` - User apps -- `~/.config/dwn/autostart.d/` - DWN-specific symlinks - -To add custom autostart apps: -```bash -mkdir -p ~/.config/dwn/autostart.d -ln -s /usr/bin/telegram-desktop ~/.config/dwn/autostart.d/ -``` - ---- - -## AI Features (Optional) - -DWN has an AI assistant that can run commands for you. For example, you can press `Super+Shift+A`, type "open chrome", and it will launch Chrome. - -### AI Command Setup (OpenRouter) - -1. Go to [openrouter.ai](https://openrouter.ai) and create a free account -2. Get your API key -3. Add it to your shell config: - -```bash -echo 'export OPENROUTER_API_KEY="your-key-here"' >> ~/.bashrc -source ~/.bashrc -``` - -4. Make sure dmenu is installed: `sudo apt install dmenu` - -### Exa Semantic Search Setup - -1. Go to [dashboard.exa.ai](https://dashboard.exa.ai/api-keys) and create an account -2. Get your API key -3. Add it to your shell config: - -```bash -echo 'export EXA_API_KEY="your-key-here"' >> ~/.bashrc -source ~/.bashrc -``` - -### Usage - -- Press `Super + A` to see AI context info about your current task -- Press `Super + Shift + A` to ask the AI to do something: - - "open firefox" - launches Firefox - - "run terminal" - opens a terminal - - "what time is it" - answers your question -- Press `Super + Shift + E` to search the web semantically: - - Type a question like "how to configure nginx" - - Select a result to open in browser - ---- - -## Troubleshooting - -### "make: command not found" - -Install build tools: -```bash -sudo apt install build-essential -``` - -### "X11 libraries not found" or build errors - -Install dependencies: -```bash -make deps -``` - -### Can't find DWN at login screen - -Make sure you ran `sudo make install`, then: -```bash -ls /usr/share/xsessions/dwn.desktop -``` - -If missing: -```bash -sudo cp scripts/dwn.desktop /usr/share/xsessions/ -``` - -### Terminal shortcut doesn't work - -Install the default terminal: -```bash -sudo apt install xfce4-terminal -``` - -Or change terminal in config (see Configuration section). - -### Screen is blank after login - -DWN started but there's nothing to show. Press `Ctrl+Alt+T` to open a terminal. - -### How do I get back to my normal desktop? - -1. Press `Super+Backspace` to exit DWN -2. At login screen, select your previous desktop (GNOME, KDE, etc.) - -### AI says "dmenu not found" - -```bash -sudo apt install dmenu -``` - -### WiFi indicator not working - -Make sure NetworkManager is installed and running: -```bash -sudo apt install network-manager -sudo systemctl enable --now NetworkManager -``` - -### Audio indicator not working - -Make sure ALSA utilities are installed: -```bash -sudo apt install alsa-utils -``` - ---- - -## Uninstall - -```bash -sudo make uninstall -``` - -Then select a different desktop at the login screen. - ---- - -## All Make Commands - -| Command | What it does | -|---------|--------------| -| `make help` | Show all commands | -| `make deps` | Install dependencies | -| `make` | Build DWN | -| `make debug` | Build with debug symbols | -| `make run` | Test in a window | -| `make install` | Install system-wide | -| `make uninstall` | Remove from system | -| `make clean` | Delete build files | -| `make format` | Format source code | -| `make check` | Run static analysis | - ---- +* `src/`: Core implementation logic. +* `include/`: Header files and internal API definitions. +* `config/`: Configuration templates. +* `scripts/`: Deployment and utility scripts. +* `site/`: Technical documentation and architecture overviews. ## License -MIT License - do whatever you want with it. - -## Credits - -- Inspired by [dwm](https://dwm.suckless.org/) and [XFCE](https://xfce.org/) -- AI powered by [OpenRouter](https://openrouter.ai/) +This project is licensed under the MIT License - see the `LICENSE` file for details. \ No newline at end of file diff --git a/site/ai-features.html b/site/ai-features.html index 7f298d4..e309eb6 100644 --- a/site/ai-features.html +++ b/site/ai-features.html @@ -84,6 +84,18 @@ Find relevant content instantly.

Super + Shift + E

+
+
📝
+

Auto-Organization

+

Context-aware window placement and workspace optimization + based on your current workflow.

+
+
+
🔔
+

Smart Notifications

+

Intelligent filtering and prioritization of system notifications + using application context.

+

Setting Up OpenRouter

diff --git a/site/documentation.html b/site/documentation.html index 153b5ab..2501fd8 100644 --- a/site/documentation.html +++ b/site/documentation.html @@ -62,6 +62,7 @@

  • Reference
      +
    • WebSocket API
    • Keyboard Shortcuts
    • Configuration
    • AI Features
      • @@ -340,6 +341,69 @@ the current article with Super + Return. Both panels can be hidden in the configuration if you prefer a minimal setup.

      +

      WebSocket API

      +

      + DWN exposes a real-time WebSocket API (default port 8777) that allows for + complete programmatic control of the window manager. +

      +
      +

      Connecting

      +

      Endpoint: ws://localhost:8777/ws

      +

      The API must be enabled in your configuration:

      + 
      [api]
+enabled = true
+port = 8777
      +
      +

      Supported Commands

      +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandDescription
      get_statusGet WM version and current workspace ID
      get_workspacesList all workspaces and their client counts
      get_clientsGet details of all managed windows
      switch_workspaceChange to a specific workspace ID
      run_commandExecute a shell command
      focus_clientFocus a specific window by ID
      +
      + +

      Advanced Examples

      +

      + Check the scripts/api_examples/ directory in the source tree for + sophisticated implementations: +

      +
        +
      • Window Picker (window_picker_fzf.py) - Fuzzy finder for windows.
        • +
      • Session Manager (session_manager.py) - Save/restore window layouts.
        • +
      • Web Remote (web_remote.html) - Browser-based dashboard.
        • +
      • Auto-Manager (listen.py) - Proactive workspace optimization.
        • +
      +

      Next Steps

      Now that you know the basics, explore these topics:

        diff --git a/site/features.html b/site/features.html index 901fb61..9f2bdf6 100644 --- a/site/features.html +++ b/site/features.html @@ -291,6 +291,36 @@ +
        +
        +

        Extensible API

        +

        + DWN exposes a real-time WebSocket API that allows for complete programmatic + control and monitoring of your desktop environment. +

        +
        +
        +

        💡 Real-time Monitoring

        +

        Subscribe to window manager events and state changes. Build custom dashboards, + status bars, or automation scripts.

        +
        +
        +

        🎫 Remote Control

        +

        Change workspaces, focus windows, and launch applications programmatically + from any language that supports WebSockets.

        +
        +
        +

        💻 Integration Ready

        +

        Native support for JSON-RPC style commands makes it easy to integrate with + external tools, mobile apps, or web interfaces.

        +
        +
        +
        +

        Detailed API documentation and examples are available in the + Documentation section.

        +
        +
        +

        Standards Compliance

        diff --git a/site/index.html b/site/index.html index 903a0d8..2e4e25d 100644 --- a/site/index.html +++ b/site/index.html @@ -85,6 +85,12 @@

        Optional AI command palette and semantic web search. Control your desktop with natural language and get intelligent suggestions.

        +
        +
        💬
        +

        Extensible API

        +

        Real-time WebSocket interface for programmatic control. Build custom + dashboards, mobile remotes, and automated workflows.

        +
        🔔

        Notification Daemon

        @@ -181,6 +187,12 @@ echo "exec dwn" >> ~/.xinitrc
        AI-powered command palette for natural language control
        +
        +
        + [WebSocket API Dashboard] +
        +
        Real-time WebSocket API for custom integrations
        +