Make multiple displays just work: arrangement, scaling and per-display workspaces

[oliverlukschander]

This is my suggestion for making multi-display setups on Omarchy Mac pleasant to use. It follows up on what we talked about on Discord. It's a proposal, not a finished decision, so I'm very happy to discuss any part of it, here, on Discord or by mail (oliver@lukschander.com), and to reshape or split it however suits you.

Summary

Plug in a display and it just works: it stays where you put it, it's sized to match, and each screen gets its own workspaces.

• The arrangement is remembered for every combination of displays. Displays are recognised by their EDID (model and serial), so the port doesn't matter.
  • Plugging in or unplugging doesn't move the screens that stay on, except to close a gap.
  • A new display joins to the right of main, bottoms flush.
• Monitor panel:
  • Drag displays to arrange them. A display dropped past the middle of another goes to that side, and an outline shows where it will land.
  • The ★ picks main, and clicking a display shows its number on it.
  • Every display has its own scale row, so the panel is the same on every screen.
  • A display turns from its row: Standard, 90°, 180° or 270°, remembered for that display.
• Scale:
  • A new display gets the scale at which text is as many millimetres tall as on main.
  • Linked displays (the default): changing any display takes the others to the same real size, and pointing at a scale shows where they'll land.
  • Per display: each display keeps its own scale. The mode stays until it's changed.
  • Super + / and Super + Alt + / step the scale, and Super + Ctrl + / matches everything to main. GDK_SCALE follows main.
• Workspaces per display:
  • Each display owns block * 10 + 1..10.
  • Super + 1..0, Super + Shift + 1..0, Super + Tab, the wheel and the swipe act on the focused display.
  • Super + D, then a number, sends the window to that display; Super + Ctrl + Alt + Arrow sends it in that direction.
  • With just the laptop, workspaces are 1–10 as before.
• A display that goes away: its windows move to main's front workspace, and go home when it returns.

How

• default/hypr/displays.lua does the work. displays/model.lua holds the pure arrangement and scale maths, tested headlessly, and displays/store.lua keeps ~/.local/state/omarchy/displays.json.
• One hl.monitor rule per display: desc: for externals, the connector for the panel. Rules are diffed, so an unchanged display isn't modeset, and the layout is re-checked on monitor.layout_changed.
• omarchy-hyprland-monitor-scaling and -clamshell hand scaling to the module while it's loaded.

Compatibility

• Hand-written rules win. A display with its own hl.monitor rule in the user's config is left alone, and those rules are re-sent after the module's. The same goes for a user's GDK_SCALE.
• Opt-outs:
  • omarchy-hyprland-toggle displays-off on turns the module off.
  • display-workspaces-off on keeps the arrangement and scaling, with global workspaces (for workspace plugins).
  • Mirroring turns the module off too.
• Existing installs: migration 1790518456 comments out the stock GDK_SCALE lines of an unchanged monitors.lua.

Interplay with quattro-upstream

• monitor-removal.lua and the Swipe into empty workspaces on Macs #633 swipe (workspace_swipe_use_r) step aside while workspaces are per display.
• Super + Shift + Alt + Arrows (move workspace to monitor) is dropped, in favour of the existing Super + Ctrl + Alt + Arrows.
• Move the Mac's desktop defaults into omarchy-mac's platform hooks #639's platform defaults set no monitor rules or GDK_SCALE, so none of them counts as the user's.
• The first commit is Make the Monitor panel's display toggle work under the Lua config #637, the Monitor panel toggle fix. Commit 6 fixes shared bar code and would apply to upstream Omarchy on its own.

Since opening: what changed and why

Using it turned up the following. Each is its own commit, 6 to 25:

• The Monitor panel closed whenever its display moved or rescaled. ScreenMoveRemap hides a moved monitor's bar for a moment, and a ModuleList was active only while visible, so every widget on that bar was rebuilt. It now follows an explicit shown.
• Two displays side by side couldn't be swapped by dragging. The drop took the nearest free spot, and above or below the other display is always nearer than its far side. It now goes to the side the display is dragged past.
• Linked / Per display flipped back when the panel closed, and changed with the desk. It was derived from which displays had been set by hand. It's now one remembered choice.
• The panel depended on where it was opened. Linked had a scale row for that display only, and on an external without DDC there was no brightness at all. Now every display has a row, and brightness falls back to the built-in panel.
• Rescaling one display made the others flicker and moved the pointer. The arrangement reflowed around main, so other displays moved along. Now only the display that's rescaled moves, and the pointer keeps its spot on its display.
• Linked followed a laptop-to-desk factor learned from scales set by hand. Linked now means real size, and it comes out the same whichever display is set.
• A display that came back at another scale lost its side. Layouts only stored positions. They now store sizes, and a layout is restored by side and alignment.
• A display on its side couldn't be turned. The module already arranged and remembered a turned display, but only a hand-written rule could turn one, and that takes the display away from the module. A display now turns from its row in the panel, in place: it keeps its side, the others stay, and it comes back turned.
• Also in the panel:
  • clicking one display identifies it alone;
  • pointing at a Linked scale previews where the other displays land;
  • each row highlights its display's current scale;
  • the panel grows with its displays instead of scrolling.

Testing

On hardware: a MacBook Pro 16" M2 Pro with a BenQ 27" 1440p on USB-C, Hyprland 0.56.2; for rotation, also a 27" 1080p BenQ standing on its side.

Before opening:

• arranging by drag, and restoring per set;
• Linked and Per display;
• per-display workspaces and every binding;
• the panel toggle and clamshell;
• unplug and replug with windows on several workspaces;
• a display coming back without EDID;
• ten off/on cycles.

Hand-written monitors.lua rules and the two toggles are covered by the tests, but weren't tried on hardware.

For this update, retested live after the fixes:

• the panel stays open while its own display rescales;
• dragging swaps sides;
• the mode survives closing the panel;
• rescaling one display leaves the other steady and the pointer in place;
• the preview matches the result, with the mouse and the keyboard;
• Linked pairs are the same from either side (laptop 3 / BenQ 1.25, laptop 2.4 / BenQ 1.0);
• the BenQ keeps its side through rescaling, and through unplug, rescale and replug;
• Per display no longer changes Linked;
• identify, and the brightness fallback;
• turning the 1080p BenQ to 90° from its row, and its coming back turned.

Tests:

• test/shell.d/hyprland-displays-test.sh runs the model, the store and the flows against a fake Hyprland.
• Every fix has test cases. Those for the bar, the drop, the remembered mode, the brightness fallback, sizes in layouts and rotation were checked to fail without their fix.
• The full suite ran when the PR was opened: 4669 checks against 4643 on an unmodified 351c9fb, with the same five files failing on both. On this head, CI's full shell suites pass, apart from files CI lists as known failures.

Known issue

After an unplug, Chromium windows from that display can draw at its old scale, in a corner of the window, until they're resized or toggled fullscreen.

• Hyprland doesn't tell a window it has left a monitor that's being removed, and Chromium keeps that monitor's scale.
• It's independent of this PR.
• A small workaround is in Have windows from an unplugged monitor redraw at their new scale #670.

Related kernel fixes (Aurora)

• An external display staying black after off and on: drm/apple: support independent dual dock DP streams on J414s aurora-silicon/linux#46. A follow-up with the full AUSPLL power-down is prepared.
• A display losing its EDID after repeated off/on or replugs: drm/apple: afk: reuse torn-down service slots, so the EDID survives reconnects aurora-silicon/linux#48.

Open for discussion

• Per-display workspaces: the default, Mac-only, or upstream in Omarchy too? Nothing in the module is Mac-specific.
• Is the flag-file opt-out right for plugins, or would you prefer a Lua global?
• The history: commits 7–25 can be folded into 2–5 if you'd rather review fewer commits.

---

Built with Claude Code over a longer session, with every behaviour tried on my own machine along the way. I can walk through any part of it in review.

🤖 Generated with Claude Code

[maralcbr]

Thanks, Oliver, this is a great proposal and clearly a lot of work. It overlaps the display contract that omacom#13362 has just introduced (displays.conf, platform files under /usr/share/omarchy-platform), so I'd like to work out together how it fits. Would you comment on omacom#13362 with how you'd see it slotting in?

[oliverlukschander]

Thanks! I commented on omacom#13362 with how I'd see it slotting in, including a test on top of it: omacom#13362 (comment)