add Hyprland desktop with XMonad-style layouts

Manage the desktop through native Lua and UWSM with Grid, Monocle, Tabs and Scrolling layouts. Add workspace-local navigation, bounded scrolling focus and a runtime Grid ratio defaulting to 1.20.

Configure the HDR OLED and portrait LG, HDMI recovery, NVIDIA suspend handling, independent locking and Plasma fallback. Fix Waybar workspace IPC and provide immediate per-output layout status.

Include desktop controls, screenshots, usage documentation and controller/panel regression tests. Use the authorized local illustris flake input.
This commit is contained in:
illustris committed 2026-10-04 09:43:45 +05:30
1 parent 6b0298e662
commit 3fcf3c9c57
18 files changed
+2101 -16

No files matched your search

+546
View File
@@ -0,0 +1,546 @@
local geometry = require("geometry")
local D = { modes = {}, orders = {}, ratios = {}, hdr = true, lg_enabled = true }
desktop = D
local layouts = { grid = "lua:grid", monocle = "monocle", tabbed = "lua:tabbed", scrolling = "scrolling" }
local cycle = { "grid", "monocle", "tabbed", "scrolling" }
local busy, queued, recovering = false, false, false
local recovery_epoch, lg_mode = 0, "1920x1080@60"
local timers = {}
local outputs = { oled = "desc:Dell Inc. AW3225QF JR11YZ3", lg = "desc:LG Electronics LG HDR 4K 0x000404F0" }
local signature = (os.getenv("HYPRLAND_INSTANCE_SIGNATURE") or "verify"):gsub("[^%w_-]", "_")
local state_path = (os.getenv("XDG_RUNTIME_DIR") or "/tmp") .. "/hypr-desktop-" .. signature .. ".state"
local function later(ms, fn)
-- --verify-config has no event loop; upstream cannot clean up Lua timers there.
if not os.getenv("HYPRLAND_INSTANCE_SIGNATURE") then return end
local timer
timer = hl.timer(function()
timers[timer] = nil
fn()
end, { timeout = ms, type = "oneshot" })
timers[timer] = true
end
local function key(ws) return tostring(ws.id) end
local function wid(w) return tostring(w.stable_id) end
local function dispatch(action) return hl.dispatch(action) end
local function active_workspace()
return hl.get_active_special_workspace() or hl.get_active_workspace()
end
local function selector(ws) return ws.special and ("special:" .. ws.name:gsub("^special:", "")) or tostring(ws.id) end
local function save()
local f = io.open(state_path .. ".tmp", "w")
if not f then return end
f:write("hdr ", D.hdr and "1" or "0", "\nlg ", D.lg_enabled and "1" or "0", "\n")
for id, mode in pairs(D.modes) do
f:write("mode ", id, " ", mode, "\n")
if D.orders[id] then f:write("order ", id, " ", table.concat(D.orders[id], ","), "\n") end
end
for id, ratio in pairs(D.ratios) do f:write("ratio ", id, " ", string.format("%.2f", ratio), "\n") end
local function panel(output, ws)
if ws then
f:write("panel ", output, " ", key(ws), " ", D.mode(ws), " ", string.format("%.2f", D.grid_ratio(ws)), "\n")
end
end
panel("*", active_workspace())
for _, m in ipairs(hl.get_monitors()) do
panel(m.name, hl.get_active_special_workspace(m) or hl.get_active_workspace(m))
end
f:close()
os.rename(state_path .. ".tmp", state_path)
end
-- Session state is data, never executable Lua. A fresh compositor gets Grid.
local f = io.open(state_path, "r")
if f then
for line in f:lines() do
local id, mode = line:match("^mode (%-?%d+) (%a+)$")
if id and layouts[mode] then D.modes[id] = mode end
local rid, ratio = line:match("^ratio (%-?%d+) ([%d.]+)$")
ratio = tonumber(ratio)
if rid and ratio and ratio >= 0.25 and ratio <= 4 then D.ratios[rid] = ratio end
local oid, order = line:match("^order (%-?%d+) ([%d,]+)$")
if oid then
D.orders[oid] = {}
for item in order:gmatch("%d+") do table.insert(D.orders[oid], item) end
end
if line == "hdr 0" then D.hdr = false end
if line == "lg 0" then D.lg_enabled = false end
end
f:close()
end
local function ordered(windows, id, retain_missing)
local present, result, order = {}, {}, {}
for _, w in ipairs(windows) do present[wid(w)] = w end
for _, w_id in ipairs(D.orders[id] or {}) do
if present[w_id] then
result[#result + 1] = present[w_id]
order[#order + 1] = w_id
present[w_id] = nil
elseif retain_missing then
order[#order + 1] = w_id
end
end
for _, w in ipairs(windows) do
if present[wid(w)] then
result[#result + 1] = w
order[#order + 1] = wid(w)
present[wid(w)] = nil
end
end
D.orders[id] = order
return result
end
local function tiled(ws)
return ordered(hl.get_windows({ workspace = ws, floating = false, mapped = true }), key(ws))
end
function D.mode(ws) return D.modes[key(ws or active_workspace())] or "grid" end
function D.grid_ratio(ws)
ws = ws or active_workspace()
return ws and D.ratios[key(ws)] or geometry.default_ratio
end
function D.grid_ratio_set(ratio)
assert(type(ratio) == "number" and ratio >= 0.25 and ratio <= 4, "Grid ratio must be between 0.25 and 4")
local ws = active_workspace()
if not ws then return end
D.ratios[key(ws)] = math.floor(ratio * 100 + 0.5) / 100
if D.mode(ws) == "grid" then dispatch(hl.dsp.layout("reorder")) end
save()
end
function D.grid_ratio_adjust(delta)
D.grid_ratio_set(math.max(0.25, math.min(4, D.grid_ratio() + delta)))
end
local function dissolve(ws)
for _, group in ipairs(ws:get_groups()) do
local w = group.current
if w then dispatch(hl.dsp.group.toggle({ window = w })) end
end
end
local function tabs(ws)
local windows = tiled(ws)
if #windows == 0 then return end
local layout = windows[1].layout
-- Workspace rules apply on the next event-loop turn. Grouping while
-- Monocle still owns the targets strands its inactive input flags.
if layout and layout.name and layout.name ~= layouts.tabbed then
later(15, function() if D.mode(ws) == "tabbed" then tabs(ws) end end)
return
end
local active = hl.get_active_window()
local root = windows[1]
-- One native group supplies real tabs, hiding and input isolation.
if not root.group then dispatch(hl.dsp.group.toggle({ window = root })) end
local group = root.group
if not group then return end
for i = 2, #windows do
local w = windows[i]
if w.group ~= group then
if w.group then dispatch(hl.dsp.group.toggle({ window = w })) end
group:add(w)
end
end
if active and active.workspace == ws and not active.floating then
dispatch(hl.dsp.focus({ window = active }))
end
end
local function reconcile()
if busy then return end
busy = true
for _, ws in ipairs(hl.get_workspaces()) do
local mode = D.mode(ws)
D.modes[key(ws)] = mode
if mode == "tabbed" then tabs(ws) else tiled(ws) end
end
save()
busy = false
end
local function schedule()
if queued or busy then return end
queued = true
later(30, function() queued = false; reconcile() end)
end
function D.layout_set(mode)
assert(layouts[mode], "expected grid, monocle, tabbed, or scrolling")
local ws = active_workspace()
if not ws then return end
local old, active = D.mode(ws), hl.get_active_window()
local order = D.orders[key(ws)]
D.modes[key(ws)] = mode
busy = true
if old == "tabbed" and mode ~= "tabbed" then dissolve(ws) end
D.orders[key(ws)] = order
hl.workspace_rule({ workspace = selector(ws), layout = layouts[mode] })
if mode == "tabbed" then tabs(ws) end
busy = false
save()
local function finish()
if D.mode(ws) ~= mode then return end
local windows = tiled(ws)
local layout = windows[1] and windows[1].layout
if layout and layout.name and layout.name ~= layouts[mode] then later(15, finish); return end
busy = true
if mode == "tabbed" then tabs(ws) end
if active and active.mapped and active.workspace == ws and active_workspace() == ws then
dispatch(hl.dsp.focus({ window = active }))
end
busy = false
save()
end
later(15, finish)
end
function D.layout_cycle()
local current = D.mode()
for i, mode in ipairs(cycle) do
if mode == current then D.layout_set(cycle[i % #cycle + 1]); return end
end
end
local function detach(w)
if w and w.group then w.group:remove(w) end
end
function D.move(workspace)
local w = hl.get_active_window()
if not w then return end
local source = w.workspace
local source_selector, source_special = selector(source), source.special
local remaining = {}
for _, other in ipairs(tiled(source)) do
if other ~= w then remaining[#remaining + 1] = other end
end
busy = true
detach(w)
dispatch(hl.dsp.window.move({ window = w, workspace = workspace, silent = true }))
-- Moving its last window can destroy a special workspace immediately.
if #remaining > 0 then dispatch(hl.dsp.focus({ window = remaining[1] }))
elseif not source_special then dispatch(hl.dsp.focus({ workspace = source_selector })) end
busy = false
schedule()
end
function D.float(action)
local w = hl.get_active_window()
if not w then return end
busy = true
if action ~= "disable" then detach(w) end
dispatch(hl.dsp.window.float({ window = w, action = action or "toggle" }))
busy = false
schedule()
end
function D.scratchpad()
dispatch(hl.dsp.workspace.toggle_special("magic"))
local ws = hl.get_active_special_workspace()
if ws and ws.name == "special:magic" then
local windows = hl.get_windows({ workspace = ws, mapped = true })
if #windows > 0 then dispatch(hl.dsp.focus({ window = windows[1] })) end
end
end
function D.focus_step(delta)
local ws = active_workspace()
if not ws then return end
local windows = tiled(ws)
local active, index = hl.get_active_window(), nil
for i, w in ipairs(windows) do if w == active then index = i; break end end
if #windows > 0 then
dispatch(hl.dsp.focus({ window = windows[index and (index - 1 + delta) % #windows + 1 or 1] }))
end
end
local function spatial_direction(windows, active, direction)
local boxes, index = {}, nil
for i, w in ipairs(windows) do
local at, size = w.at, w.size
boxes[i] = { x = at.x, y = at.y, w = size.x, h = size.y }
if w == active then index = i end
end
if not index then
local at, size = active.at, active.size
index = #boxes + 1
boxes[index] = { x = at.x, y = at.y, w = size.x, h = size.y }
end
local next_index = geometry.neighbor(boxes, index, direction, active.floating)
return next_index and windows[next_index]
end
local function scroll_direction(windows, active, direction)
local layout = active.layout
if not layout or not layout.column then return active end
local column, row = layout.column.index, layout.index_in_column
local horizontal = direction == "left" or direction == "right"
local delta = (direction == "left" or direction == "up") and -1 or 1
local candidates = {}
for _, w in ipairs(windows) do
local other = w.layout
if other and other.column then
if horizontal and other.column.index == column + delta then
candidates[#candidates + 1] = w
elseif not horizontal and other.column.index == column and other.index_in_column == row + delta then
return w
end
end
end
return spatial_direction(candidates, active, direction) or candidates[1] or active
end
function D.direction(direction)
local ws, active = active_workspace(), hl.get_active_window()
if not ws then return end
local mode = D.mode(ws)
if mode == "tabbed" or mode == "monocle" then
D.focus_step((direction == "left" or direction == "up") and -1 or 1)
return
end
local windows = {}
for _, w in ipairs(hl.get_windows({ workspace = ws, mapped = true })) do
if not w.hidden and w.accepts_input ~= false then windows[#windows + 1] = w end
end
if #windows == 0 then return end
if not active or active.workspace ~= ws or not active.mapped or active.hidden then
-- A tape drag or native focus message can leave the viewport unfocused.
local first = windows[1]
for _, w in ipairs(windows) do
local col = w.layout and w.layout.column
local current = first.layout and first.layout.column
if col and (not current or col.index < current.index) then first = w end
end
dispatch(hl.dsp.focus({ window = first }))
return
end
local target
if mode == "scrolling" and not active.floating then
target = scroll_direction(windows, active, direction)
else
target = spatial_direction(windows, active, direction)
end
-- Explicit focus brings the tape into view before warping the cursor.
-- Native scrolling focus can warp into empty space and clear input focus.
if target then dispatch(hl.dsp.focus({ window = target })) end
end
function D.master(promote)
local ws, active = active_workspace(), hl.get_active_window()
if not ws then return end
local windows = tiled(ws)
if #windows == 0 then return end
if not promote then dispatch(hl.dsp.focus({ window = windows[1] })); return end
for i, w in ipairs(windows) do
if w == active then
local order = D.orders[key(ws)]
order[1], order[i] = order[i], order[1]
save()
if D.mode(ws) == "grid" then dispatch(hl.dsp.layout("reorder"))
elseif D.mode(ws) == "tabbed" then busy = true; dissolve(ws); tabs(ws); busy = false
else dispatch(hl.dsp.window.swap({ target = windows[1], window = active })) end
return
end
end
end
function D.swap_step(delta)
local ws, active = active_workspace(), hl.get_active_window()
if not ws or not active then return end
local windows = tiled(ws)
for i, w in ipairs(windows) do
if w == active then
local j = (i - 1 + delta) % #windows + 1
local order = D.orders[key(ws)]
order[i], order[j] = order[j], order[i]
save()
if D.mode(ws) == "grid" then dispatch(hl.dsp.layout("reorder"))
elseif D.mode(ws) == "tabbed" then busy = true; dissolve(ws); tabs(ws); busy = false
else dispatch(hl.dsp.window.swap({ target = windows[j], window = active })) end
return
end
end
end
hl.layout.register("grid", {
recalculate = function(ctx)
if #ctx.targets == 0 then return end
local windows, targets = {}, {}
for _, target in ipairs(ctx.targets) do
if target.window then
windows[#windows + 1] = target.window
targets[wid(target.window)] = target
end
end
if #windows == 0 then return end
-- During layout changes targets arrive one at a time. Sorting that
-- temporary subset must not discard the workspace's complete order.
windows = ordered(windows, key(windows[1].workspace), true)
local boxes = geometry.grid(ctx.area, #windows, D.grid_ratio(windows[1].workspace))
for i, w in ipairs(windows) do targets[wid(w)]:place(boxes[i]) end
end,
layout_msg = function(_, msg) return msg == "reorder" end,
})
hl.layout.register("tabbed", {
recalculate = function(ctx)
for _, target in ipairs(ctx.targets) do target:place(ctx.area) end
end,
})
local function display(kind)
for _, m in ipairs(hl.get_monitors()) do
if kind == "oled" and m.description:find("AW3225QF", 1, true) and m.serial == "JR11YZ3" then return m end
if kind == "lg" and m.description:find("LG HDR 4K", 1, true) then return m end
end
end
function D.monitors()
if recovering then return end
local oled, lg = display("oled"), display("lg")
local refresh = 239.991
if oled then
refresh = 0
for _, mode in ipairs(oled.available_modes) do
if mode.width == 3840 and mode.height == 2160 then refresh = math.max(refresh, mode.refresh_rate) end
end
if refresh == 0 then refresh = 239.991 end
end
local dual = D.lg_enabled and lg ~= nil
hl.monitor({ output = outputs.oled, mode = string.format("3840x2160@%.3f", refresh),
position = dual and "0x1680" or "0x0", scale = 1, bitdepth = 10,
cm = D.hdr and "hdredid" or "srgb", sdr_max_luminance = 265, sdrbrightness = 1, sdrsaturation = 1 })
hl.monitor({ output = outputs.lg, mode = lg_mode, position = "3840x0", scale = 1,
transform = 3, bitdepth = 8, cm = "srgb", disabled = not D.lg_enabled })
end
local function cancel_recovery()
recovery_epoch = recovery_epoch + 1
recovering = false
lg_mode = "1920x1080@60"
D.lg_recovery = "pending"
end
function D.display_profile(dual)
D.lg_enabled = dual
-- Explicitly move workspaces before disabling; reconnecting does not move them back.
if not dual then
cancel_recovery()
local lg, oled = display("lg"), display("oled")
if lg and oled then
for _, ws in ipairs(hl.get_workspaces()) do
if ws.monitor == lg then dispatch(hl.dsp.workspace.move({ workspace = selector(ws), monitor = oled.name })) end
end
end
end
D.monitors()
if dual then later(300, D.recover_lg) end
save()
end
function D.hdr_toggle() D.hdr = not D.hdr; D.monitors(); save() end
function D.monitor_focus(kind, move)
local m = display(kind)
if not m then return end
if move then
if m.active_workspace then D.move(tostring(m.active_workspace.id)) end
else dispatch(hl.dsp.focus({ monitor = m.name })) end
end
-- Monitor rules apply asynchronously. Hold each rung only after its mode is active.
function D.recover_lg()
if not os.getenv("HYPRLAND_INSTANCE_SIGNATURE") or not D.lg_enabled or not display("lg") or recovering then return end
recovering = true
recovery_epoch = recovery_epoch + 1
local epoch = recovery_epoch
D.lg_recovery = "settling"
local steps = {
{ mode = false, hold = 1000 },
{ mode = "1920x1080@60", width = 1920, height = 1080, refresh = 60, hold = 3000 },
{ mode = "3840x2160@30", width = 3840, height = 2160, refresh = 30, hold = 3000 },
{ mode = "3840x2160@60", width = 3840, height = 2160, refresh = 60, hold = 1000 },
}
local function valid() return epoch == recovery_epoch and D.lg_enabled end
local rung
rung = function(index)
if not valid() then return end
local step = steps[index]
if not step then
recovering = false
D.lg_recovery = "ready"
D.monitors()
return
end
D.lg_recovery = step.mode or "off"
if step.mode then lg_mode = step.mode end
hl.monitor({ output = outputs.lg, disabled = not step.mode, mode = lg_mode })
local function await_mode(attempt)
if not valid() then return end
local lg = display("lg")
local applied = not step.mode and not lg or step.mode and lg
and lg.width == step.width and lg.height == step.height
and math.abs(lg.refresh_rate - step.refresh) < 0.1 and lg.dpms_status
if applied then
later(step.hold, function() rung(index + 1) end)
elseif attempt < 50 then
later(100, function() await_mode(attempt + 1) end)
else
cancel_recovery()
D.lg_recovery = "failed"
D.monitors()
end
end
later(100, function() await_mode(1) end)
end
-- Match the X11 helper's wake settling time before tearing down the HDMI link.
later(3000, function() rung(1) end)
end
function D.wake()
dispatch(hl.dsp.dpms({ action = "enable" }))
D.recover_lg()
end
local function restore()
for id, mode in pairs(D.modes) do
hl.workspace_rule({ workspace = id, layout = layouts[mode] })
end
D.monitors()
D.recover_lg()
schedule()
end
for _, event in ipairs({ "window.open", "window.close", "window.move_to_workspace", "window.update_rules", "workspace.created" }) do
hl.on(event, schedule)
end
hl.on("workspace.active", function() save(); schedule() end)
hl.on("workspace.special_active", save)
hl.on("monitor.focused", save)
hl.on("config.reloaded", function() later(40, restore) end)
hl.on("monitor.added", function(m)
if recovering then return end
local lg_added = m.description:find("LG HDR 4K", 1, true) ~= nil
later(300, function()
if recovering then return end
D.monitors()
if lg_added then D.recover_lg() end
end)
end)
hl.on("monitor.removed", function(m)
if m.description:find("LG HDR 4K", 1, true) and not (recovering and D.lg_recovery == "off") then cancel_recovery() end
later(300, D.monitors)
end)
hl.on("hyprland.start", function() restore(); hl.exec_cmd("uwsm finalize") end)
hl.monitor({ output = outputs.oled, mode = "3840x2160@239.991", position = "0x1680", scale = 1,
bitdepth = 10, cm = D.hdr and "hdredid" or "srgb", sdr_max_luminance = 265,
sdrbrightness = 1, sdrsaturation = 1 })
hl.monitor({ output = outputs.lg, mode = lg_mode, position = "3840x0", scale = 1,
transform = 3, bitdepth = 8, cm = "srgb", disabled = not D.lg_enabled })
return D