hyprland-canvas

KO | EN

gitlite — search

#developer-tools #large-language-models #agents #automation #react #monitoring #tensorflow #chatgpt #cross-platform #codex

hyprland-canvas

(★ 9)

Infinite canvas for Hyprland — pan floating windows like an infinite desktop

File Explorer

ZIP Download

- - ci.yml
- __init__.py
- __main__.py
- config.py
- daemon.py
- debug.py
- hypr.py
- ipc.py
- navigation.py
- panning.py
- toggle_state.py
- __init__.py
- test_config.py
- test_daemon.py
- test_daemon_extra.py
- test_debug.py
- test_hypr.py
- test_ipc.py
- test_main.py
- test_navigation.py
- test_navigation_extra.py
- test_panning.py
.gitignore
.python-version
config.yml
LICENSE
pyproject.toml
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Infinite canvas for Hyprland — pan all floating windows like an infinite desktop.

Drag the canvas with **SUPER+SHIFT+LMB**, navigate between windows, toggle canvas mode per workspace. Runs as an unprivileged user daemon — communicates directly with Hyprland via its IPC socket and Lua API.

## Why

Hyprland has no built-in infinite desktop. This daemon provides one by communicating with Hyprland the right way:

- **Direct Unix socket IPC** to Hyprland (~0.1ms per frame) — no subprocess overhead
- **Hyprland Lua API** (`hl.dsp.window.move`) moves windows without focusing them — no cursor warp or flicker
- Runs as an unprivileged user daemon — no special permissions needed
- Has a **Unix socket IPC** for keyboard-driven commands (navigate, toggle, invert)

## Features

| Feature | Keybind | Description |
|---------|---------|-------------|
| Pan canvas | SUPER+SHIFT+LMB | Drag to pan all floating windows |
| Edge-scroll | SUPER+LMB | Drag a floating window toward the screen edge — camera follows (engages only for a confirmed drag of the window under the cursor) |
| Navigate | SUPER+SHIFT+Arrows | Spatial jump to nearest window in direction (up/down/left/right), auto-pan to center |
| Canvas toggle | SUPER+SHIFT+C | Toggle all windows on workspace to/from floating |
| Toggle single | SUPER+SHIFT+V | Toggle focused window floating ↔ tiled |
| Invert | SUPER+SHIFT+G | Invert pan direction |

## Install

**uv (recommended):**
```bash
git clone https://github.com/zyrophix/hyprland-canvas.git
cd hyprland-canvas
uv tool install .
```

**pipx:**
```bash
git clone https://github.com/zyrophix/hyprland-canvas.git
cd hyprland-canvas
pipx install .
```

**Run from source (no install):**
```bash
git clone https://github.com/zyrophix/hyprland-canvas.git
cd hyprland-canvas
uv run canvasd
```

This gives you two commands:
- `canvasd` — the daemon
- `canvas-ctl` — send commands to the daemon

## Updating

After pulling new code, reinstall and restart the daemon — an old installed copy keeps running until you do:

```bash
git pull
uv tool install . --force --reinstall   # or: pipx install . --force
```

## Usage

### 1. Start the daemon

```bash
canvasd
```

### 2. Add Hyprland keybinds

Hyprland 0.55+ uses Lua for config. Add these binds:

```lua
-- Canvas: pan (mouse binds)
hl.key.bind({"SUPER", "SHIFT"}, "mouse:272", function()
    os.execute("canvas-ctl pan-start")
end, { mouse = true })

hl.key.bind({"SUPER", "SHIFT"}, "mouse:272", function()
    os.execute("canvas-ctl pan-stop")
end, { mouse = true, release = true })

-- Canvas: edge-scroll (drag window to screen edge → camera follows)
hl.bind("SUPER + mouse:272", function()
    hl.dispatch(hl.dsp.window.drag())
    hl.exec_cmd("canvas-ctl edge-start")
end, { mouse = true })

hl.bind("SUPER + mouse:272", function()
    hl.exec_cmd("canvas-ctl edge-stop")
end, { mouse = true, release = true })

-- Canvas: navigation (4-dir spatial)
hl.key.bind({"SUPER", "SHIFT"}, "left", function()
    os.execute("canvas-ctl nav-left")
end)
hl.key.bind({"SUPER", "SHIFT"}, "right", function()
    os.execute("canvas-ctl nav-right")
end)
hl.key.bind({"SUPER", "SHIFT"}, "up", function()
    os.execute("canvas-ctl nav-up")
end)
hl.key.bind({"SUPER", "SHIFT"}, "down", function()
    os.execute("canvas-ctl nav-down")
end)

-- Canvas: toggle & invert
hl.key.bind({"SUPER", "SHIFT"}, "C", function()
    os.execute("canvas-ctl canvas-toggle")
end)
hl.key.bind({"SUPER", "SHIFT"}, "V", function()
    os.execute("canvas-ctl canvas-toggle-single")
end)
hl.key.bind({"SUPER", "SHIFT"}, "G", function()
    os.execute("canvas-ctl toggle")
end)
```

### 3. Control commands

```bash
canvas-ctl ping              # check if daemon is running
canvas-ctl status            # show pan direction and state
canvas-ctl pan-start         # start panning (called by mouse bind)
canvas-ctl pan-stop          # stop panning (called by mouse release bind)
canvas-ctl nav-left          # navigate to nearest window left
canvas-ctl nav-right         # navigate to nearest window right
canvas-ctl nav-up            # navigate to nearest window up
canvas-ctl nav-down          # navigate to nearest window down
canvas-ctl canvas-toggle     # toggle floating on current workspace (alias for -all)
canvas-ctl canvas-toggle-all # toggle all windows on workspace (explicit)
canvas-ctl canvas-toggle-single # toggle focused window only
canvas-ctl toggle            # invert pan direction
canvas-ctl edge-start       # start edge-scroll (called by mouse bind)
canvas-ctl edge-stop        # stop edge-scroll (called by mouse release bind)
```

## Configuration

All defaults are built into the daemon (`DEFAULT_CONFIG` in `canvas/config.py`) — it runs fine with no config file. The repo's `config.yml` is a ready-to-copy template; installed wheels/pipx/uv-tool packages do not include it. To customize, create `~/.config/canvas/config.yml`:

```yaml
speed: 1.6                    # pan speed multiplier
invert:
  enabled: true               # true = grab canvas (intuitive), false = follow cursor
edge_scroll:
  enabled: true               # auto-pan when dragging window past screen edge
  ramp_distance: 50            # px of overflow to reach full speed
  speed: 20.0                  # max px/frame at full overflow (~1200 px/s at 60fps)
  grab_dead_zone: 5            # px the window must actually move before camera may engage
  # max_speed: 30             # optional: cap per-frame edge-scroll delta (pixels)
navigation:
  cooldown: 0.2               # seconds between nav commands
  protected_apps:             # these windows are skipped during navigation
    - brave-browser
    - chromium
    - firefox
canvas:
  preserve_geometry: true     # remember floating window positions/sizes on OFF,
                              # restore them on the next ON; tiled placement itself
                              # is always layout-owned
```

Invalid values (wrong type, zero/negative numbers) are rejected at daemon startup with the exact offending keys listed on stderr.

## Architecture

```
canvasd (daemon)
├── hypr.py        Direct Unix socket IPC to Hyprland
├── panning.py     Cursor polling, pan state, edge-scroll state
├── navigation.py  Window navigation, canvas toggle
├── ipc.py         Unix socket server for canvas-ctl
├── config.py      YAML config with deep merge
└── daemon.py      Main loop, wires modules together
```

Key design decisions:

- **Cursor polling** — reads cursor position from Hyprland IPC, works on any Wayland setup
- **`hl.dsp.window.move({window=w})` without focus** — passing a window object bypasses auto-focus, so no cursor warp or feedback loop
- **Direct socket IPC** — a fresh Unix-socket connection per command (~0.1ms locally) instead of spawning a subprocess every frame
- **Workspace-scoped** — pan, edge-scroll and navigation only move floating windows on the current workspace; other workspaces are never touched
- **Ground-truth, direction-aware edge pan** — modeled after compositor-level implementations (driftwm, hevel): the camera assists only while a *confirmed* drag (window under cursor + focus match + moved past `grab_dead_zone`) pushes the window *toward* an edge or holds it there; pulling the window away from a boundary stops that side's assist immediately. The dragged window's real geometry is polled from Hyprland every frame — no cursor-derived guessing, so clicks on borders/gaps or holds without movement never move the camera on their own
- **Idle timeout** (500ms) — auto-stops panning if Hyprland drops a mouse release event during active drag

## Debugging

Run the daemon with structured tracing to diagnose input/camera issues:

```bash
CANVAS_DEBUG=1 canvasd 2>&1 | tee /tmp/canvas-debug.log   # summary
CANVAS_DEBUG=2 canvasd 2>&1 | tee /tmp/canvas-debug.log   # per-window details (class/title/at/size)
```

Trace lines are `<seconds> EVENT key=value …`. Useful events (level 1):

- `CMD` — every IPC command with `cmd` + `result`
- `STATE_LOAD / STATE_SAVE` — toggle snapshot counts per workspace
- `SNAPSHOT_CREATE` — `ws, count, addrs, preserve_geometry`
- `TOGGLE_ON / TOGGLE_OFF` — `ws, count, addrs` on canvas-toggle
- `TILE_START / FLOAT_START` — `ws, targets` before Lua dispatch
- `TILE_DONE / FLOAT_DONE` — after dispatch
- `EDGE_START_DECISION`, `EDGE_SESSION_TICK` (10Hz), `EDGE_CONFIRMED`, `EDGE_DISARM`

Level 2 adds per-window details: `SNAPSHOT_CREATE_DETAIL`, `TOGGLE_ON_DETAIL`, `STATE_LOAD_DETAIL`, `TILE_START_LIVE`, `TILE_WINDOW`-style live vs saved geometry with `class/title` (truncated to 30-40 chars).

## Requirements

- Hyprland 0.55+ (Lua config with `hl.*` API)
- Python 3.12+
- PyYAML

## License

MIT

hyprland-canvas

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README