Focus windows through Hyprland so scrolling layouts follow, plus workspace/urgent/launch feedback

[assada]

Why

Clicking an icon in the dock went through the Wayland activate request (Toplevel.activate()), which only hands over keyboard focus. On Hyprland's scrolling layout that is not enough: the workspace switches, the window takes focus, and the window itself stays parked off-screen. The click reads as "nothing happened".

Measured on a workspace with tiledLayout: "scrolling" and three columns on a 1536px logical viewport:

slack                 at [-1459, 38]  size [1462, 814]   <- focused, off-screen
org.telegram.desktop  at [   17, 38]  size [1457, 814]   <- what you actually see
org.gnome.Nautilus    at [ 2958, 38]  size [ 733, 814]

Routing focus through the compositor's own dispatcher moves the viewport with the focus:

hl.dsp.focus({ window = "address:0x557f72140cb0" })
slack: at [-1459, 38] -> at [12, 38]

The same path fixes wheel cycling, the right-click window list, and windows sitting on special workspaces. When no Hyprland address is available it falls back to the Wayland request, so nothing regresses on a compositor without hyprland-toplevel-mapping-v1.

Two compatibility details worth knowing, both verified against Hyprland 0.56.2:

• Hyprland 0.56 moved dispatchers to Lua. hyprctl dispatch focuswindow address:0x... now answers error: ')' expected near 'address'. Quickshell exposes Hyprland.usingLua, so both syntaxes are sent from one helper rather than sniffing versions.
• HyprlandToplevel.address returns the address without the 0x prefix (557f72140cb0) while Hyprland's selectors expect address:0x…, so the address is normalised in one place.

What else is in here

Everything below is built on the same live Hyprland handles that the focus fix needs, which is why it travels with it. Urgency and workspace are read straight off those handles, so a window moving between workspaces or raising its urgent hint needs no model rebuild.

Workspace hints. When an app's windows all live somewhere else, its tooltip names the workspace (Slack [3]), and every row in the right-click window list carries the same label ([3] Slack — DM). Parked and starting windows read the same way: Files [minimized], Slack [starting…]. An earlier draft put a numbered badge in the corner of each icon; on a normal desktop that fires on almost every icon at once and reads like an unread count, so it was dropped in favour of the tooltip.

Urgent highlights (showUrgentHint, default on). A window asking for attention pulses its indicator dot and icon ring in the theme's urgent colour until you focus it. Hyprland clears the hint itself on focus.

Launch feedback. Clicking a cold app pulses its icon until the window shows up, or until waiting stops being informative (12s). Pending launches are tracked by window-count growth, so "new window" on an already-running app pulses too. Practical effect: one click on a slow Electron app stops becoming three.

Click active to minimize (clickToMinimize, default off). Clicking the app you are already in is otherwise a dead click. With the option on, a single-window app is parked on a hidden special:minimized workspace and clicking the icon again brings it back to the workspace it came from. Multi-window apps keep cycling, which stays the more useful answer.

Hyprland has no real minimize, so this is a special workspace by necessity — but the workspace name is the state, so a shell restart cannot strand a window: with no remembered origin it simply returns to the workspace you are on. It uses its own special:minimized rather than special:scratchpad, so it never disturbs windows a user has deliberately parked in their scratchpad. Left off by default because on a tiling WM it reflows the layout, which should be a deliberate choice.

Middle click opens a new window — the usual dock convention, and the button was free.

Dwell delays. The reveal strip fired the instant the pointer crossed the bottom 6px, so travelling to the bottom of a window summoned the dock on the way past; there is now a short dwell (revealDelay, 160ms). Tooltips appeared with no delay, so sweeping across the dock flashed a label for every icon (tooltipDelay, 450ms). Set either to 0 for the previous behaviour.

Two rendering fixes

Menu rows are drawn at one width. Every ContextRow sized itself from its own label, and the Column took the maximum, so hover and checked fills stepped in and out down the menu. Measured from a screenshot of the settings menu: 232 / 225 / 225 / 273px. The +26px allowance also applied only when a row was checked, so a row changed width when you toggled it. Rows now report an implicit width, the menu takes the widest piece of content, and every row draws at that width — identical fills by construction. Only implicit widths are read, so feeding the result back into the rows cannot loop. The mark column is always reserved as well, so labels share one left edge and toggling a row shifts nothing.

A custom dock colour no longer hides the dock's own chrome. Color.bar.text is tuned for the bar's background, not for bgColor. With a light theme and a dark card the launcher glyph drew dark-on-dark: glyph strokes at 0.06–0.20 luminance on a 0.28 background, about 1.3:1. The dock colour is now measured against the theme foreground and the glyph, indicators, separator, and card outline flip to the readable side only when the two land on the same side of the scale:

Theme	bgColor	Chrome
light	theme	dark — unchanged
light	custom dark	light
dark	custom light	dark
dark	theme	light — unchanged

"theme" and "none" keep using Color.bar.text exactly as before, so default installs render identically.

Internals

• DockModel.cycleAppWindow / activateApp are replaced by a pure pickAppWindow that only chooses a window and leaves the acting to the host — which is what let one focusToplevel handle the scrolling layout, minimized windows, and the Wayland fallback in a single place. It also fixes backwards wheel cycling on an unfocused app, which used to land on the second-to-last window instead of the last.
• The two duplicated tooltip blocks became one HoverTooltip inline component (~50 lines to ~30, and the item tooltip now hides behind an open context menu, which only the button tooltip did before).
• buildEntries takes a resolver and carries the Hyprland handle per window. The model is rebuilt on both ToplevelManager.toplevels and Hyprland.toplevels changes, debounced at 40ms, because Hyprland resolves its handle slightly apart from the Wayland announcement.

Compatibility

• Defaults preserve existing behaviour except the two dwell delays (160ms / 450ms), both tunable to 0.
• No new dependencies. Hyprland.dispatch is used in-process — no hyprctl subprocess per click.
• Version bumped to 1.5.0 in manifest.json; happy to drop that commit if you version releases yourself.

Docs

README gains the new config keys, the middle-click row, the automatic-contrast note, and one factual fix: the screen row described the default as the focused monitor while the code picks Quickshell.screens[0].

Testing

Hyprland 0.56.2, Quickshell 0.3.0, Omarchy shell, single 1920x1080 monitor at 1.25 scale, light theme with a custom dark bgColor.

• Focus dispatch verified against the live compositor, including the scroll-into-view result quoted above, and Hyprland.usingLua confirmed true in steady state with all toplevels mapped to their Wayland handles.
• Window-targeted hl.dsp.window.move with follow = false / follow = true verified on a throwaway window, including that the special workspace disappears cleanly once the last window leaves it.
• Contrast fix verified by screenshot and pixel measurement: glyph strokes at 0.77 luminance on a 0.26 card, where they were 0.06–0.20 before.
• Shell restarted and hot-reloaded repeatedly with a clean journal — no QML warnings, no binding loops.
• Not verified with my own eyes: the settings menu itself. It opens on right-click and this box has no input-injection tool, so the row-width fix is argued from the layout rather than from a screenshot. Worst case rowWidth resolves to 0 and rows fall back to their implicit width, i.e. today's behaviour.