docs: clarify light passthrough controls

Author: devmobasa

README.md

@@ -507,9 +507,10 @@ Other desktops/window managers:
 - Bind `wayscriber --daemon-toggle` to any global shortcut key you prefer.
 
 Light passthrough controls:
-- <kbd>Ctrl+Shift+L</kbd> is a Wayscriber in-overlay shortcut, not an OS/global shortcut. It works while the overlay is focused.
-- Once light passthrough is active, normal keyboard and pointer input goes to the app underneath. Bind compositor/global shortcuts to `wayscriber --light-toggle` and `wayscriber --light-draw-toggle` for reliable control.
+- <kbd>Ctrl+Shift+L</kbd> is a Wayscriber in-overlay shortcut, not an OS/global shortcut. It works while the overlay is focused, but once passthrough is active Wayscriber may no longer receive that keypress.
+- Once light passthrough is active, normal keyboard and pointer input goes to the app underneath. Bind compositor/global shortcuts to `wayscriber --light-toggle` and `wayscriber --light-draw-toggle` for reliable control, including getting back out of passthrough.
 - Use `wayscriber --light-draw-on` on press and `wayscriber --light-draw-off` on release for draw-while-held shortcuts.
+- Hyprland and KDE examples are in [docs/SETUP.md](docs/SETUP.md#light-passthrough-controls-on-hyprland); the KDE section follows the Hyprland binding example.
 - Stock GNOME Wayland does not support this regular-app passthrough mode. Freeze may still work for still-image capture, but it is not a live passthrough replacement. A GNOME Shell extension approach would be needed for true shell-level passthrough.
 
 Use `--no-tray` or `WAYSCRIBER_NO_TRAY=1` if you don't have a system tray; otherwise right-click the tray icon for options:
@@ -736,7 +737,7 @@ The polygon tools are available from the toolbar picker; their default keybindin
 
 </details>
 
-For light passthrough, <kbd>Ctrl+Shift+L</kbd> is the default Wayscriber-level binding only while the overlay has focus. Use compositor/global shortcuts that run `wayscriber --light-toggle` and related light-draw commands once passthrough is active. On stock GNOME Wayland, regular app windows cannot provide the required click-through shell overlay. Freeze may still work for still-image capture, but it is not a live passthrough replacement.
+For light passthrough, <kbd>Ctrl+Shift+L</kbd> is the default Wayscriber-level binding only while the overlay has focus. Do not rely on it as the way back out after passthrough starts; use compositor/global shortcuts that run `wayscriber --light-toggle` and related light-draw commands once passthrough is active. On stock GNOME Wayland, regular app windows cannot provide the required click-through shell overlay. Freeze may still work for still-image capture, but it is not a live passthrough replacement.
 
 Arrow labels can auto-number when enabled in the arrow toolbar; reset with <kbd>Ctrl+Shift+R</kbd>. Step markers auto-increment and reset from the toolbar (or bind `reset_step_markers` in `config.toml`). Preset slots can be saved/cleared from the toolbar; edit names and advanced fields in `config.toml`. Blur has no default keyboard shortcut; bind `select_blur_tool` in `config.toml` if you want direct keyboard access.
 

config.example.toml

@@ -162,7 +162,7 @@ toggle_presenter_mode = ["Ctrl+Shift+M"]
 
 # Toggle light passthrough mode while the overlay has focus.
 # Once passthrough is active, use compositor/global shortcuts that call
-# `wayscriber --light-toggle` for reliable control.
+# `wayscriber --light-toggle` for reliable control, including exit.
 toggle_light_mode = ["Ctrl+Shift+L"]
 
 # Optional in-overlay toggle between light drawing and passthrough.
@@ -581,6 +581,7 @@ show_toast = true
 # Light passthrough mode requires layer-shell support:
 # - toggle_light_mode enters a minimal click-through overlay while Wayscriber has focus.
 # - wayscriber --light-toggle is the reliable compositor/global toggle once passthrough is active.
+#   Do not rely on the in-overlay Ctrl+Shift+L binding to exit after input is passed through.
 # - wayscriber --light-draw-toggle switches between drawing and passthrough.
 # - wayscriber --light-draw-on / --light-draw-off support press/release shortcuts.
 

docs/CONFIG.md

@@ -429,7 +429,7 @@ show_toast = true
 
 ### Light Passthrough Mode
 
-Light mode hides UI chrome and sets the overlay to click-through passthrough until drawing is explicitly enabled. `toggle_light_mode` defaults to <kbd>Ctrl+Shift+L</kbd>, but that is a Wayscriber in-overlay shortcut: it works while the overlay still has focus. Once passthrough is active, normal keyboard and pointer input goes to the app underneath, so compositor/global shortcuts should call the daemon commands below for reliable control.
+Light mode hides UI chrome and sets the overlay to click-through passthrough until drawing is explicitly enabled. `toggle_light_mode` defaults to <kbd>Ctrl+Shift+L</kbd>, but that is a Wayscriber in-overlay shortcut: it works while the overlay still has focus. Once passthrough is active, normal keyboard and pointer input goes to the app underneath, so do not rely on <kbd>Ctrl+Shift+L</kbd> as the way back out. Compositor/global shortcuts should call the daemon commands below for reliable control.
 
 This mode requires compositor overlay support through layer-shell. It is disabled on the xdg fallback because regular app windows cannot reliably stay visible as click-through shell overlays while keyboard and pointer input go to apps underneath. On stock GNOME Wayland, Freeze may still work for still-image capture when portal capture is available, but it is not a live passthrough replacement. True passthrough would require a GNOME Shell extension companion.
 

docs/SETUP.md

@@ -94,7 +94,7 @@ Now press <kbd>Super+D</kbd> to toggle the overlay on/off!
 ### Light passthrough controls on Hyprland
 
 Light passthrough needs compositor/global shortcuts because Wayscriber deliberately passes keyboard and pointer input to the app below while passthrough is active.
-The default <kbd>Ctrl+Shift+L</kbd> binding is a Wayscriber in-overlay shortcut, not an OS-level shortcut; use the bindings below for reliable control after passthrough starts.
+The default <kbd>Ctrl+Shift+L</kbd> binding is a Wayscriber in-overlay shortcut, not an OS-level shortcut; do not rely on it to exit after passthrough starts. Use the bindings below for reliable control.
 
 The configurator can install a native Hyprland include file for this. Manual equivalent for Arch + Hyprland: