Floating windows (e.g. Steam) can render off-screen — a Lua auto-recovery script

[krys-anto]

The problem

Floating windows can end up placed almost entirely off-screen — most of the
window sits past the edge of every connected monitor, so it looks like the
app never opened. I hit this with the Steam client window (spawned at a
negative x coordinate, past the left edge of both my monitors) and had to
dig through hyprctl clients -j to even find it. It's easy to mistake for a
frozen/crashed app rather than a placement bug.

A fix, using Hyprland's native Lua config hooks

Since Omarchy configures Hyprland in Lua, this can be fixed entirely in user
config with no external daemon: a small script that watches floating windows
(tiled ones are left alone — the layout engine already keeps those on-screen)
and snaps one back on-screen if more than half its area falls outside every
monitor's usable rect.

Algorithm: for each floating window, compute its overlap area against each
monitor's usable rect (monitor bounds minus reserved bar/panel space). If
total visible area is under 50%, pick the monitor with the most overlap (or,
if it overlaps none at all, the nearest monitor by center distance), then
clamp the window's position into that monitor's bounds. It's the same
overlap-then-clamp approach used to keep a body inside level bounds in 2D
collision code.

It runs two ways: instantly on window.open (catches a window placed
off-screen the moment it's created, before you ever see it), and as a
lightweight periodic sweep (catches a window dragged off-screen mid-session,
since there's no native "window moved" event to hook).

-- ~/.config/hypr/floating-guard.lua
-- Keeps floating windows from ending up mostly off-screen (e.g. Steam's
-- client window spawning at a negative x coordinate past both monitors).
-- Tiled windows are untouched -- the layout engine already keeps those
-- on-screen, so we only ever look at floating ones.
--
-- Algorithm: for each floating window, compute how much of its area
-- overlaps the usable rect of each monitor (monitor bounds minus reserved
-- bar/panel space). If less than half the window's area is visible across
-- all monitors combined, pick the monitor with the most overlap (or, if it
-- overlaps none, the monitor whose center is nearest), then clamp the
-- window's position into that monitor's bounds. This is the same
-- overlap/clamp approach used to keep a physics body inside level bounds in
-- 2D collision code -- AABB vs AABB, then push back onto the nearest valid
-- edge.

local CHECK_INTERVAL_MS = 3000
local MIN_VISIBLE_FRACTION = 0.5
local LOG_PATH = os.getenv("HOME") .. "/.local/state/omarchy/floating-guard.log"

local function log(line)
  local f = io.open(LOG_PATH, "a")
  if f then
    f:write(os.date("%Y-%m-%d %H:%M:%S") .. " " .. line .. "\n")
    f:close()
  end
end

local function usable_rect(mon)
  local r = mon.reserved
  return {
    x = mon.position.x + r.left,
    y = mon.position.y + r.top,
    w = mon.size.width - r.left - r.right,
    h = mon.size.height - r.top - r.bottom,
  }
end

local function overlap_area(rect_a, rect_b)
  local ox1 = math.max(rect_a.x, rect_b.x)
  local oy1 = math.max(rect_a.y, rect_b.y)
  local ox2 = math.min(rect_a.x + rect_a.w, rect_b.x + rect_b.w)
  local oy2 = math.min(rect_a.y + rect_a.h, rect_b.y + rect_b.h)
  if ox2 <= ox1 or oy2 <= oy1 then
    return 0
  end
  return (ox2 - ox1) * (oy2 - oy1)
end

local function rect_center(r)
  return r.x + r.w / 2, r.y + r.h / 2
end

local function clamp(v, lo, hi)
  if hi < lo then
    return lo
  end
  if v < lo then
    return lo
  end
  if v > hi then
    return hi
  end
  return v
end

local function fix_window(win)
  if not win or not win.floating or not win.mapped or win.hidden then
    return
  end

  local at, size = win.at, win.size
  local rect = { x = at.x, y = at.y, w = size.x, h = size.y }
  local win_area = rect.w * rect.h
  if win_area <= 0 then
    return
  end

  local monitors = hl.get_monitors()
  local total_overlap = 0
  local best_mon, best_overlap = nil, -1
  local nearest_mon, best_dist = nil, math.huge
  local wcx, wcy = rect_center(rect)

  for _, mon in ipairs(monitors) do
    local u = usable_rect(mon)
    local ov = overlap_area(rect, u)
    total_overlap = total_overlap + ov
    if ov > best_overlap then
      best_overlap, best_mon = ov, mon
    end
    local mcx, mcy = rect_center(u)
    local dist = (wcx - mcx) ^ 2 + (wcy - mcy) ^ 2
    if dist < best_dist then
      best_dist, nearest_mon = dist, mon
    end
  end

  if total_overlap >= win_area * MIN_VISIBLE_FRACTION then
    return
  end

  local target_mon = (best_overlap > 0) and best_mon or nearest_mon
  if not target_mon then
    return
  end
  local u = usable_rect(target_mon)

  local new_x = math.floor(clamp(rect.x, u.x, u.x + u.w - rect.w))
  local new_y = math.floor(clamp(rect.y, u.y, u.y + u.h - rect.h))

  if new_x == rect.x and new_y == rect.y then
    return
  end

  local prev = hl.get_active_window()

  hl.dispatch(hl.dsp.focus({ window = "address:" .. win.address }))
  hl.dispatch(hl.dsp.window.move({ x = new_x, y = new_y }))
  if prev and prev.address ~= win.address then
    hl.dispatch(hl.dsp.focus({ window = "address:" .. prev.address }))
  end

  log(
    string.format(
      "moved %s (%s) from %d,%d to %d,%d on %s",
      win.class or "?",
      win.title or "?",
      rect.x,
      rect.y,
      new_x,
      new_y,
      target_mon.name or "?"
    )
  )
end

local function sweep_all()
  for _, win in ipairs(hl.get_windows()) do
    fix_window(win)
  end
end

hl.on("window.open", function(win)
  -- Give the app a moment to finish sizing/placing itself before checking.
  hl.timer(function()
    fix_window(win)
  end, { timeout = 300, type = "oneshot" })
end)

hl.on("monitor.added", sweep_all)
hl.on("monitor.removed", sweep_all)

local function schedule_sweep()
  hl.timer(function()
    sweep_all()
    schedule_sweep()
  end, { timeout = CHECK_INTERVAL_MS, type = "oneshot" })
end

schedule_sweep()

Install: save as ~/.config/hypr/floating-guard.lua, add
require("hypr.floating-guard") to hyprland.lua, hyprctl reload.

Suggestion

Would this be worth including as an opt-in default, so anyone hitting this
doesn't have to go digging through hyprctl clients -j to figure out their
app didn't actually crash?

It would fit the existing omarchy toggle pattern (same mechanism as
nightlight/idle): wrap the hl.on/timer registration behind a toggle state
file under ~/.local/state/omarchy/toggles/, wire up
omarchy-toggle-floating-guard, and default it on (or off, if the
maintainers would rather this be explicit opt-in). No code changes needed
beyond that — the script itself doesn't need to know it's toggleable, it just
wouldn't get required (or its setup would no-op) when the toggle is off.

Tested on Omarchy 4.0.2-1 / Hyprland 0.56.2. Happy to open a PR — including
wiring up the toggle — if this seems like a good fit.