Skip to content

Wake from the screensaver on a lone modifier tap - #13517

Open
seantimm wants to merge 2 commits into
omacom:quattrofrom
seantimm:screensaver-modifier-wake
Open

seantimm wants to merge 2 commits into
omacom:quattrofrom
seantimm:screensaver-modifier-wake

Conversation

@seantimm

@seantimm seantimm commented Sep 28, 2026 •

Copy link
Copy Markdown

What

A lone tap of Shift, Ctrl, Alt or Super (either side) now dismisses the screensaver, the way it does on macOS and Windows. Hyprland matches these binds when the key is released.

Why

omarchy-screensaver exits when a character reaches its terminal (read -n1) or focus leaves the window. A modifier key sends no character, so tapping Shift does nothing. The keys that do work are character keys, and the wake keystroke is easy to have land in whatever window takes focus next, so a Space or Enter meant to wake the screen ends up typed into an editor or chat box.

Modifiers never produce a character, which makes them the wake keys that cannot leak.

How

default/hypr/bindings/screensaver.lua binds both sides of each modifier, non-consuming, to a Lua function that looks up windows of class org.omarchy.screensaver and closes each through the window close dispatcher, hl.dsp.window.close({ window = window }). The terminal exits and the screensaver script takes its usual cleanup path (cursor restored, ttfx killed).

  • Non-consuming, so a modifier tap still reaches the focused app and existing Super/Ctrl/Alt shortcuts are unaffected.
  • The function is a no-op when no screensaver window exists, so an ordinary modifier tap costs one window lookup and no process spawn.
  • Loaded inside the omarchy_default_bindings block, so users who disable default bindings are not affected.
  • No description on the binds, so they don't clutter the keybindings menu.

Testing

  • test/shell.d/screensaver-dismiss-test.sh loads the binds against a stub hl and checks that every screensaver window gets a close request, and the focused window does not, whichever window has focus.
  • Forced the screensaver with omarchy-launch-screensaver force, injected a real keypress for each of the eight modifier keys through uinput (ydotool), and confirmed the screensaver window closed each time and the cursor became visible again.
  • Tapping Super then Space at the screensaver dismisses it and opens the launcher in one motion.
  • hyprland-default-config-test, hyprland-binding-conflicts-test, keybindings-menu-test and shell-shortcuts-test pass. The rest of ./test/all shows the same environment-related failures on a clean quattro checkout.

Known limits

  • On layouts where Right Alt is AltGr (for example de, gb, us intl) the key resolves to ISO_Level3_Shift, so Right Alt is not expected to wake the screensaver there. Not tested; the other seven keys are unaffected.
  • Dismiss screensaver on bare Ctrl while it is open #10587 also dismisses the screensaver on bare Ctrl, by a different route. The two overlap on Ctrl.

Mouse movement still does not wake the screensaver; Hyprland can't bind pointer motion, so that would need the idle service and is left for a follow-up.

🤖 Generated with Claude Code

The screensaver only exits when a character reaches its terminal, so
Shift, Ctrl, Alt and Super do nothing, and the keys that do work get
typed into whatever window takes focus next. Modifiers never produce a
character, so bind both sides of each to close the screensaver windows.
The binds are non-consuming and check for a screensaver window first,
so an ordinary modifier press still reaches the app.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@llstrk

llstrk commented Sep 29, 2026

Copy link
Copy Markdown

Automated AI review

Community review: Independent automated community review, unaffiliated with the Omarchy team, intended to help prepare PRs for their review.

Outcome: The dismiss handler closes the focused window, not the screensaver windows it looked up.

hl.dsp.window.close(window) ignores its argument

In Hyprland 0.56.2, close takes its target only from a table's window field (close({ window? })). A window object passed on its own is dropped and the close falls back to the focused window. This works when a screensaver has focus. Impact: when a screensaver window is mapped but another window has focus (for example during multi-monitor launch before the last screensaver maps, or the popup case traced in #13265), a lone modifier tap sends a close request to the user's window instead, and does not close the screensaver.

Suggested change: hl.dispatch(hl.dsp.window.close({ window = window })), with a regression test like the one below.

Reproducer (fails at 73dc00c)

Save as test/shell.d/screensaver-dismiss-test.sh and run bash test/shell.d/screensaver-dismiss-test.sh. It loads the new module against a stub hl that follows Hyprland's documented contract for hl.dsp.window.close({ window? }): the window named by the table's window field, or the focused window when that field is absent. Hyprland 0.56.2 reads only a table's window field (Internal::pushWindowUpval), so a window object passed on its own is treated as absent.

#!/bin/bash

source "$(dirname "${BASH_SOURCE[0]}")/base-test.sh"

require_command lua

# Load the screensaver bindings against a stub hl that follows Hyprland's
# documented dispatcher contract: hl.dsp.window.close({ window? }) closes the
# window named by the table's `window` field, and the focused window when that
# field is absent. Hyprland 0.56.2 reads only a table's `window` field
# (Internal::pushWindowUpval), so a window object passed on its own counts as
# "absent" there too. Tap each modifier with two screensaver windows open and
# report which windows got a close request.
closes() {
  local focused="$1"

  OMARCHY_PATH="$ROOT" FOCUSED="$focused" lua <<'LUA'
package.path = os.getenv("OMARCHY_PATH") .. "/?.lua;" .. package.path

local windows = {
  { address = "0xsaver1", class = "org.omarchy.screensaver" },
  { address = "0xsaver2", class = "org.omarchy.screensaver" },
  { address = "0xeditor", class = "dev.zed.Zed" },
}

local focused
for _, window in ipairs(windows) do
  if window.address == os.getenv("FOCUSED") then
    focused = window
  end
end

local binds = {}

hl = {
  bind = function(keys, dispatcher)
    table.insert(binds, { keys = keys, dispatcher = dispatcher })
  end,
  get_windows = function(filter)
    local found = {}
    for _, window in ipairs(windows) do
      if not (filter and filter.class) or window.class == filter.class then
        table.insert(found, window)
      end
    end
    return found
  end,
  dsp = {
    window = {
      close = function(args)
        local target = type(args) == "table" and args.window or nil
        return { close = target or focused }
      end,
    },
  },
  dispatch = function(action)
    io.write(" " .. action.close.address)
  end,
}

require("default.hypr.bindings.screensaver")

for _, bind in ipairs(binds) do
  io.write(bind.keys .. ":")
  bind.dispatcher()
  io.write("\n")
end
LUA
}

expected=$(printf '%s: 0xsaver1 0xsaver2\n' \
  "SHIFT + SHIFT_L" "SHIFT + SHIFT_R" \
  "CTRL + CONTROL_L" "CTRL + CONTROL_R" \
  "ALT + ALT_L" "ALT + ALT_R" \
  "SUPER + SUPER_L" "SUPER + SUPER_R")

# A screensaver window exists but another window has focus, as while the
# launcher is still opening screensavers on later monitors, or while a second
# screensaver is still closing after the first one went.
closed=$(closes 0xeditor)
[[ $closed == "$expected" ]] ||
  fail "a lone modifier closes the screensaver windows, not the focused window" "$closed"
pass "a lone modifier closes the screensaver windows, not the focused window"

# The ordinary case: one of the screensavers has focus.
closed=$(closes 0xsaver1)
[[ $closed == "$expected" ]] ||
  fail "a lone modifier closes every screensaver window once" "$closed"
pass "a lone modifier closes every screensaver window once"

Output at 73dc00c (exit 1):

SHIFT + SHIFT_L: 0xeditor 0xeditor
SHIFT + SHIFT_R: 0xeditor 0xeditor
CTRL + CONTROL_L: 0xeditor 0xeditor
CTRL + CONTROL_R: 0xeditor 0xeditor
ALT + ALT_L: 0xeditor 0xeditor
ALT + ALT_R: 0xeditor 0xeditor
SUPER + SUPER_L: 0xeditor 0xeditor
SUPER + SUPER_R: 0xeditor 0xeditor
not ok - a lone modifier closes the screensaver windows, not the focused window

Output with line 10 changed to hl.dispatch(hl.dsp.window.close({ window = window })) (exit 0):

ok - a lone modifier closes the screensaver windows, not the focused window
ok - a lone modifier closes every screensaver window once

Running the same stub with a screensaver focused at 73dc00c prints 0xsaver1 0xsaver1 for every key: both close requests go to the focused screensaver and the second screensaver gets none; it goes away through exit_screensaver's pkill, not through this bind.

Details
  • Source path: hlWindowClose passes argument 1 to Internal::pushWindowUpval, which pushes nil unless the argument is a table (src/config/lua/bindings/LuaBindingsInternal.cpp:323-332). A window returned by hl.get_windows is userdata, so the selector is nil and the action resolves to the focused window. Hyprland's own tests use hl.dsp.window.close({ window = 'class:slave1' }).
  • With a screensaver focused, every close request goes to that one screensaver. The other screensaver windows get no close request; they go away through exit_screensaver's pkill, not through this bind.

Verified:

  • The eight key names parse, and non_consuming is a real bind option.
  • hl.get_windows({ class = "org.omarchy.screensaver" }) matches the class exactly and returns mapped windows only.
  • The module loads only inside the omarchy_default_bindings block, and the keybindings menu skips Lua binds without a description, which these are.
  • The listed existing tests pass at the head.

Optional notes:

  • Test coverage: no existing test runs the new callbacks. With the wrong close target, and also with the require moved outside the omarchy_default_bindings block, hyprland-default-config-test, hyprland-binding-conflicts-test, keybindings-menu-test and shell-shortcuts-test all still pass. The test above catches the first case.
  • Key matching: in Hyprland 0.56.2 a bind like SHIFT + SHIFT_L does not match a lone press, because the key's own modifier is not yet in the mask (src/devices/Keyboard.cpp:31-42, KeybindManager.cpp:652); it fires on release (:736-746). On AltGr layouts (for example de, gb, us intl), Right Alt resolves to ISO_Level3_Shift, so ALT + ALT_R does not match and Right Alt does not wake the screensaver there. Updating the file comment and PR description ("press", "either side") keeps them accurate. Source reading and an xkb keysym probe only.
  • Overlap: open Dismiss screensaver on bare Ctrl while it is open #10587 also binds bare Ctrl to dismiss the screensaver. Picking one approach avoids two dismiss paths for Ctrl.

Review information

Test scope: Source review of the PR and Hyprland 0.56.2, plus existing and new stub tests in a sandbox, at 73dc00c4; not tested on a live desktop.

AI process: Opus 5.5 Medium coordination and synthesis, Opus 5.5 Xhigh technical review and final fact check, GPT 6 Sol Xhigh search for related issues, Opus 5.5 Medium editorial check.

Opt out: To stop receiving these reviews, reply to this comment saying so.

hl.dsp.window.close takes its target from a table's window field. A window
object passed on its own is ignored and the close falls back to the focused
window, so a modifier tap while another window had focus closed that window.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@seantimm

Copy link
Copy Markdown
Author

Thanks, the main finding is right. Fixed in 0731b76.

  • Close target: confirmed against the Hyprland 0.56.2 source. The bind now calls hl.dsp.window.close({ window = window }), and your reproducer is added as test/shell.d/screensaver-dismiss-test.sh. It fails at 73dc00c and passes at the new head.
  • Key matching: confirmed on a live desktop. With a Left Shift injected through uinput, the screensaver stayed up while the key was held and closed on release. The file comment and the PR description now say "tap" and note that the binds match on release.
  • Right Alt on AltGr layouts: not tested here (plain us layout), so it is listed in the description as a known limit and no bind was added for it.
  • Dismiss screensaver on bare Ctrl while it is open #10587: noted in the description. Which approach to take for Ctrl is the maintainers' call.

The unfocused case is covered by the stub test only. On a single monitor the screensaver exits when it loses focus, so I could not set that case up live.

@seantimm seantimm changed the title Wake from the screensaver on a lone modifier press Wake from the screensaver on a lone modifier tap Sep 29, 2026
@omarchybot omarchybot added the enhancement New feature or request label Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants