From c304e41e13f8f8bb7e4c4ce7fe6c32ec97bc5603 Mon Sep 17 00:00:00 2001
From: Babken Egoian <101829110+green2grey@users.noreply.github.com>
Date: Mon, 6 Jul 2026 00:23:07 -0700
Subject: [PATCH] docs: add per-compositor Quick Preview keybind recipes

niri, Hyprland, and Sway snippets using the newest-screenshot recipe
(compositors don't know the file-manager selection; see caveat C).
Documents the toggle behavior (one bind opens and closes, PR #5) and the
layer-rule-vs-window-rule matching distinction: layer rules match the
namespace 'quickview', window rules match the app ID and only apply on
the no-layer-shell fallback path. niri snippet validated with
'niri validate'.
---
 templates/keybind-examples.md | 53 +++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/templates/keybind-examples.md b/templates/keybind-examples.md
index d82653e..b4069df 100644
--- a/templates/keybind-examples.md
+++ b/templates/keybind-examples.md
@@ -25,3 +25,56 @@ If your file manager supports desktop actions, the provided `quickview.desktop`
 Compositors can bind keys to commands, but they generally do *not* know which file is selected inside your file manager.
 This approach works best if you have a helper that can query the selected file (desktop-specific).
 
+The recipes below sidestep that limitation with the most common use case:
+previewing the **newest screenshot**. Adjust the glob to your screenshot
+directory.
+
+QuickView is single-instance: pressing the bind while a preview is already
+open **closes it** (toggle), so one bind is enough for both open and dismiss.
+
+> Rule-matching cheat sheet: **layer rules** match the layer-surface
+> namespace `quickview` (the normal path on wlroots compositors), while
+> **window rules** match the app ID `io.github.Green2Grey2.QuickView` — those
+> only apply on the fallback path when gtk4-layer-shell is unavailable.
+> They are different matchers; a window rule will not catch the layer surface.
+
+#### niri
+
+```kdl
+binds {
+    Mod+Shift+Space {
+        spawn "sh" "-c" "quickview --quick-preview \"$(ls -t ~/Pictures/Screenshots/* | head -n1)\"";
+    }
+}
+```
+
+Optional cosmetics for the overlay (matches the layer-surface namespace):
+
+```kdl
+layer-rule {
+    match namespace="quickview"
+    // e.g. shadow { on; }
+}
+```
+
+#### Hyprland
+
+```conf
+bind = SUPER SHIFT, SPACE, exec, quickview --quick-preview "$(ls -t ~/Pictures/Screenshots/* | head -n1)"
+
+# Optional cosmetics (layer surface, normal path):
+layerrule = blur, quickview
+
+# Fallback path only (no layer shell): keep the borderless window floating.
+windowrulev2 = float, class:^(io\.github\.Green2Grey2\.QuickView)$
+```
+
+#### Sway
+
+```conf
+bindsym $mod+Shift+space exec quickview --quick-preview "$(ls -t ~/Pictures/Screenshots/* | head -n1)"
+
+# Fallback path only (no layer shell): keep the borderless window floating.
+for_window [app_id="io.github.Green2Grey2.QuickView"] floating enable
+```
+