Skip to content

hyprland/ipc: don't preemptively create toplevel on windowtitlev2 - #1465

Open
immindich wants to merge 1 commit into
quickshell-mirror:masterfrom
immindich:fix/stale-window-names
Open

immindich wants to merge 1 commit into
quickshell-mirror:masterfrom
immindich:fix/stale-window-names

Conversation

@immindich

@immindich immindich commented Nov 9, 2026 •

Copy link
Copy Markdown

Describe your changes

When Quickshell receives one of windowtitlev2, activewindowv2, or urgent from Hyprland for a window that has not been mapped, it will preemptively add the window to Hyprland.toplevels. If the window is never mapped, then Hyprland never sends a closewindow event, so the entry will stay in the list forever. One application which does this is Steam, which sets the titles of several windows which are never mapped. After starting and exiting the Steam client, Quickshell still tracks several phantom windows:

0x61a9adccd070 [?] Steam
0x61a9ad9fc3a0 [?] OpenGL 4.5
0x61a9af083af0 [?] steamwebhelper
0x61a9aef5d710 [?] Shutdown
0x61a9aef92c10 [?] VRStream
0x61a9ad66c3a0 [?] Steam SDL Dummy OpenGL Window

My PR changes the current behavior so Quickshell will no longer preemptively add a new toplevel on a windowtitlev2 event. It does not change how any other event types are handled.

Since toplevel can now be null, the log message directly after can now get sent. I've changed it from a warning to a debug message.

This technically fixes the main problem described in #1450, although that issue also brings up the fact that refreshToplevels doesn't prune, which is not addressed by this PR.

Details and descisions

The original code had a comment:

It happens that Hyprland sends windowtitlev2 events before event "openwindow" is emitted, so let's preemptively create it

However, nothing is gained by adding the toplevel before the openwindow event, since openwindow carries the window's current title. That means that if the windowtitlev2 event comes first, the title it sets will be overwritten anyway when the window actually gets mapped.

The submitter of #1450 suggested a couple of possible fixes:

  1. Have refreshToplevels clean up stale entries. I think this is probably a change worth doing, but not really relevant to this issue. The method refreshToplevels doesn't usually get called that often and the toplevel state is supposed to be updated as the events come in.
  2. Treat toplevels created by windowtitlev2/activewindowv2/urgent as pending. I did not choose this approach because, as I mentioned earlier, there is no actual benefit from preemptively creating the window in the case of windowtitlev2. The only real world examples of this issue I have seen have involved windowtitlev2, not the other events.

AI usage

I used an LLM to identify the relevant section of the code, write test scripts, and gain a better understanding of the codebase. I've attached a script to reproduce the bug.

AI generated test script
#!/usr/bin/env python3
"""
Reproduce Steam's behaviour: create an X11 (XWayland) window, give it a title,
and never map it. Optionally rename it a few times, then destroy it.

Meanwhile, watch Hyprland's event socket and print any window events, so you
can see whether Hyprland emits windowtitlev2 (and never openwindow/closewindow)
for the unmapped window.

Usage:
  nix-shell -p 'python3.withPackages (p: [ p.xlib ])' --run \
    'python3 unmapped_titled_window.py [--hold SECONDS] [--renames N]'
"""

import argparse
import os
import socket
import threading
import time

from Xlib import X, Xatom, display

WINDOW_EVENTS = (
    b"openwindow>>",
    b"closewindow>>",
    b"windowtitle>>",
    b"windowtitlev2>>",
    b"urgent>>",
    b"activewindowv2>>",
)


def watch_hyprland_events(stop: threading.Event) -> None:
    sig = os.environ["HYPRLAND_INSTANCE_SIGNATURE"]
    runtime = os.environ.get("XDG_RUNTIME_DIR", f"/run/user/{os.getuid()}")
    path = f"{runtime}/hypr/{sig}/.socket2.sock"

    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    sock.connect(path)
    sock.settimeout(0.2)

    buf = b""
    while not stop.is_set():
        try:
            chunk = sock.recv(4096)
        except socket.timeout:
            continue
        if not chunk:
            break
        buf += chunk
        *lines, buf = buf.split(b"\n")
        for line in lines:
            if line.startswith(WINDOW_EVENTS):
                print(f"  [hypr] {line.decode(errors='replace')}", flush=True)


def set_title(d: display.Display, win, title: str) -> None:
    utf8 = d.intern_atom("UTF8_STRING")
    net_wm_name = d.intern_atom("_NET_WM_NAME")
    win.change_property(net_wm_name, utf8, 8, title.encode())
    win.change_property(Xatom.WM_NAME, Xatom.STRING, 8, title.encode("latin-1", "replace"))
    d.flush()


def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("--hold", type=float, default=3.0,
                    help="seconds to keep the window alive after the last rename")
    ap.add_argument("--renames", type=int, default=2,
                    help="number of title changes after the initial title")
    ap.add_argument("--no-destroy", action="store_true",
                    help="exit without explicitly destroying the window "
                         "(the X server still destroys it when the client disconnects)")
    args = ap.parse_args()

    stop = threading.Event()
    watcher = threading.Thread(target=watch_hyprland_events, args=(stop,), daemon=True)
    watcher.start()
    time.sleep(0.3)  # let the watcher connect before we generate events

    d = display.Display()
    screen = d.screen()
    win = screen.root.create_window(
        0, 0, 200, 200, 0,
        screen.root_depth,
        X.InputOutput,
        X.CopyFromParent,
        background_pixel=screen.black_pixel,
    )
    win.set_wm_class("qs-unmapped-poc", "QsUnmappedPoc")
    d.flush()
    print(f"created X11 window 0x{win.id:x} (never mapped)", flush=True)

    set_title(d, win, "qs-unmapped-poc initial")
    print("set title: qs-unmapped-poc initial", flush=True)

    for i in range(1, args.renames + 1):
        time.sleep(0.5)
        title = f"qs-unmapped-poc rename {i}"
        set_title(d, win, title)
        print(f"set title: {title}", flush=True)

    time.sleep(args.hold)

    if not args.no_destroy:
        win.destroy()
        d.flush()
        print(f"destroyed X11 window 0x{win.id:x}", flush=True)

    d.close()
    time.sleep(0.5)  # catch any trailing events
    stop.set()
    watcher.join(timeout=1)
    print("done. Check Hyprland.toplevels in quickshell for a leftover entry.", flush=True)


if __name__ == "__main__":
    main()

Open concerns

From further testing, it seems that Hyprland will not emit an activewindowv2 event for an unmapped window. However, it can do this for urgent, although I have not encountered this in a real application.

Participation

I will follow up on any responses to this PR and also intend to make further contributions to Quickshell in the future.

Some clients will set a window's title without ever mapping it. Since
the window is never mapped, Hyprland will never send a closewindow
event. If quickshell preemptively creates a toplevel from the
windowtitlev2 event, it will never be removed from
Hyprland.toplevels. The openwindow event already carries the window's
current title, so waiting to create the toplevel doesn't actually lose
any information.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant