From f16c1a65be57bb75e3963b36580c832057719673 Mon Sep 17 00:00:00 2001
From: Julian Orth <ju.orth@gmail.com>
Date: Sun, 15 Mar 2026 16:12:24 +0100
Subject: [PATCH] docs: document mouse interactions

---
 README.md                  |  2 +-
 docs/mouse-interactions.md | 53 ++++++++++++++++++++++++++++++++++++++
 docs/setup.md              |  4 +++
 3 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 docs/mouse-interactions.md

diff --git a/README.md b/README.md
index 8dc391e7..1ab75788 100644
--- a/README.md
+++ b/README.md
@@ -24,4 +24,4 @@ Jay is free software licensed under the GNU General Public License v3.0.
 
 ## Community
 
-[Community Discord server(unofficial)](https://discord.gg/Hby736z28G)
+[Community Discord server (unofficial)](https://discord.gg/Hby736z28G)
diff --git a/docs/mouse-interactions.md b/docs/mouse-interactions.md
new file mode 100644
index 00000000..7d4b60f8
--- /dev/null
+++ b/docs/mouse-interactions.md
@@ -0,0 +1,53 @@
+# Mouse Interactions
+
+Jay supports a number of mouse-based interactions that might be hard to discover. This
+file documents all of them.
+
+- Inside a tiled container, the tiles can be resized by dragging the separators.
+
+- Floating windows can be resized by dragging the borders.
+
+- Floating windows can be moved by dragging the title.
+
+- Tiles inside containers can be moved by dragging the title.
+
+  - Dragging them onto an existing workspace moves them to that workspace.
+
+  - Dragging them onto the bar outside an existing workspace creates a new workspace.
+
+- Workspaces can be moved by dragging their titles with the mouse.
+
+- In a container in mono layout, scrolling over the title switches between tiles.
+
+- Scrolling over the bar switches between workspaces.
+
+- Double clicking on a tile title/floating window title switches between floating and
+  tiling.
+
+- Right clicking on any title in a container switches the container between mono and tiled
+  layout.
+
+- Right clicking on the title of a floating window pins/unpins the window. (Pinned windows
+  are visible on all workspaces.)
+
+- When the pin icon is visible on a floating window, left clicking the icon pins/unpins
+  the window.
+
+- When selecting a toplevel (noticeable by the purple overlay), right clicking on the
+  title of any tile in a container selects that container.
+
+- Any long running mouse interaction can be canceled by pressing escape.
+
+## Window Management Mode
+
+Window-management mode makes more interactions available. See the configurable
+`window-management-key`.
+
+- In window-management mode, floating windows, tiles, and popups can be resized by
+  dragging their contents with the right mouse button.
+
+- In window-management mode, floating windows, tiles, popups, and fullscreen windows can
+  be moved by dragging their contents with the left mouse button.
+
+- Entering window-management mode disables all pointer constraints and can therefore be
+  used to move the pointer out of windows that have grabbed the pointer.
diff --git a/docs/setup.md b/docs/setup.md
index 24680c96..2ab1f02b 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -112,6 +112,10 @@ Then restart `xdg-deskop-portal`.
   ~$ window-to-tray pavucontrol-qt
   ```
 
+# Mouse Interactions
+
+See [mouse-interactions.md](./mouse-interactions.md).
+
 # Running
 
 1. Switch to a virtual terminal by pressing `ctrl-alt-F2` (or F3, F4, ...).