From 306bcb0d52a94619ccbd04dd8bd06bae291c5951 Mon Sep 17 00:00:00 2001
From: Martin Kleine <24376955+datenzar@users.noreply.github.com>
Date: Mon, 9 Feb 2026 09:12:00 +0100
Subject: [PATCH] docs: clarify Linux gtk-layer-shell runtime requirements
 (#748)

---
 BUILD.md  |  3 ++-
 README.md | 11 +++++++++++
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/BUILD.md b/BUILD.md
index c93fcec..235417a 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -32,12 +32,13 @@ This guide covers how to set up the development environment and build Handy from
   ```bash
   # Ubuntu/Debian
   sudo apt update
-  sudo apt install build-essential libasound2-dev pkg-config libssl-dev libvulkan-dev vulkan-tools glslc libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev patchelf cmake
+  sudo apt install build-essential libasound2-dev pkg-config libssl-dev libvulkan-dev vulkan-tools glslc libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libgtk-layer-shell0 libgtk-layer-shell-dev patchelf cmake
 
   # Fedora/RHEL
   sudo dnf groupinstall "Development Tools"
   sudo dnf install alsa-lib-devel pkgconf openssl-devel vulkan-devel \
     gtk3-devel webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel \
+    gtk-layer-shell gtk-layer-shell-devel \
     cmake
 
   # Arch Linux
diff --git a/README.md b/README.md
index 264d9de..23a28b2 100644
--- a/README.md
+++ b/README.md
@@ -105,6 +105,17 @@ Without these tools, Handy falls back to enigo which may have limited compatibil
 
 **Other Notes:**
 
+- **Runtime library dependency (`libgtk-layer-shell.so.0`)**:
+  - Handy links `gtk-layer-shell` on Linux. If startup fails with `error while loading shared libraries: libgtk-layer-shell.so.0`, install the runtime package for your distro:
+
+    | Distro        | Package to install         | Example command                              |
+    | ------------- | -------------------------- | -------------------------------------------- |
+    | Ubuntu/Debian | `libgtk-layer-shell0`      | `sudo apt install libgtk-layer-shell0`      |
+    | Fedora/RHEL   | `gtk-layer-shell`          | `sudo dnf install gtk-layer-shell`          |
+    | Arch Linux    | `gtk-layer-shell`          | `sudo pacman -S gtk-layer-shell`            |
+
+  - For building from source on Ubuntu/Debian, you may also need `libgtk-layer-shell-dev`.
+
 - The recording overlay is disabled by default on Linux (`Overlay Position: None`) because certain compositors treat it as the active window. When the overlay is visible it can steal focus, which prevents Handy from pasting back into the application that triggered transcription. If you enable the overlay anyway, be aware that clipboard-based pasting might fail or end up in the wrong window.
 - If you are having trouble with the app, running with the environment variable `WEBKIT_DISABLE_DMABUF_RENDERER=1` may help
 - You can manage global shortcuts outside of Handy and still control the app via signals. Sending `SIGUSR2` to the Handy process toggles recording on/off, which lets Wayland window managers or other hotkey daemons keep ownership of keybindings. Example (Sway):