Restore floating windows when the only monitor disconnects and comes back (TV standby)

[mmsmsy]

Problem

When the only display drops its connection and comes back, Hyprland moves every window to the FALLBACK output. After the reconnect, floating windows stay at their old global coordinates, thousands of pixels off-screen. For the user, it looks as if every window closed.

A TV makes this happen every day. My only display is a Samsung TV on HDMI. In standby, the TV drops the HDMI link, so Hyprland sees the monitor as unplugged. With a floating-window workflow (every window floats and is snapped to a screen quarter), each wake-up left all windows about 5760 px off-screen.

Related: #8010 (a float left off-screen after a second output is disabled, which omarchybot could not reproduce with two monitors) and #16351 (the bar breaks after the only monitor disconnects and reconnects). The case here is the single-monitor one, with FALLBACK in between. #14291 describes the same output reset with a Thunderbolt dock. #10272 pulls an off-screen float back onto a monitor, but it does not put it back in its old place.

Setup: Omarchy 4.5.0-3, Hyprland 0.56.2, kernel 7.2.15-1-omarchy, AMD RX 9070 XT, Samsung QBQ90 on HDMI-A-1.

What I use now

A small daemon that runs from autostart.lua:

• While all monitors are connected and none is FALLBACK, it saves a snapshot of each window every 3 s and on window events: workspace, floating state, position and size, plus each monitor's active workspace.
• On monitorremoved it stops saving snapshots, so the broken layout does not overwrite the good one.
• On monitoradded it waits 2 s, then puts every window of a monitor that is back to its saved workspace, floating state, position and size. It gives each monitor its workspace back. It does this again after 2 s, because Hyprland sometimes moves windows again shortly after the reconnect.
• If a saved monitor is still missing and a monitor that the snapshot does not know is connected, the daemon treats that as a replaced monitor (another screen or another port). The new monitor gets the old monitor's workspaces and floating windows, at the same relative places.
• If a saved monitor is still missing after 15 s and no new monitor can take its place, the daemon treats it as gone. The focused monitor gets its workspaces and windows. Any floating window that is on no monitor goes to the center of the focused monitor. Then the daemon saves snapshots again.
• While FALLBACK is still there, it never takes the place of a missing monitor.
• window-restore --restore runs the restore by hand.

Known limit: with more than one monitor, a screen that stays off for more than 15 s while another monitor is on counts as gone. When it comes back, its windows stay on the other monitor. (When all monitors sleep together, Hyprland shows FALLBACK and the clock does not run, so a slow screen gets 15 s after the first one wakes.)

It uses only hyprctl, jq and socat. It has worked on every TV wake-up in the two days since I added it (6 November). That is the single-monitor case. I have only one monitor, so I tested the rules for a replaced or removed monitor only with mock hyprctl output.

How to install

Omarchy's base packages already include jq and socat.

1. Save the script below as ~/.config/hypr/scripts/window-restore and make it executable: chmod +x ~/.config/hypr/scripts/window-restore
2. Add this line to ~/.config/hypr/autostart.lua (the user autostart file that every Omarchy install has):

o.exec_on_start(os.getenv("HOME") .. "/.config/hypr/scripts/window-restore")

3. Log out and in, or start it once by hand: setsid -f ~/.config/hypr/scripts/window-restore

To restore windows by hand at any time: ~/.config/hypr/scripts/window-restore --restore

Script (283 lines)

#!/bin/bash

# Puts every window back where it was after a monitor disconnects and comes
# back. The Samsung TV drops its HDMI connection when it goes to sleep, so
# Hyprland sees it as unplugged, parks everything on a placeholder output and,
# on reconnect, leaves floating windows thousands of pixels off-screen.
#
# While all monitors are connected, this snapshots each window's workspace,
# floating state, position and size every few seconds (and on window events).
# Snapshots stop as soon as a monitor disappears. When monitors come back:
#
#   - Windows of every monitor that is back go to their saved places.
#   - A monitor from the snapshot that is still missing, while a monitor the
#     snapshot does not know is connected, was replaced (another screen, or
#     another port). The new monitor gets the old monitor's workspaces and
#     windows at once, at the same relative positions.
#   - A monitor that is still missing after $grace seconds, with no new monitor
#     to take its place, was unplugged or is not in use any more. The focused
#     monitor gets its workspaces and windows.
#
# Any floating window left outside every monitor after that is centered on the
# focused monitor.
#
#   window-restore            run the daemon (started from autostart.lua)
#   window-restore --restore  reapply the last snapshot now
#
# Snapshot: ~/.local/state/window-restore/snapshot.json

state_dir="${XDG_STATE_HOME:-$HOME/.local/state}/window-restore"
snapshot="$state_dir/snapshot.json"
socket="$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock"
interval=3 # seconds between periodic snapshots
grace=15   # seconds before a missing monitor counts as gone
mkdir -p "$state_dir"

# Logical geometry of a monitor (scale and rotation applied), as jq.
geometry='{name, x, y,
  w: ((if .transform % 2 == 1 then .height else .width end) / .scale | floor),
  h: ((if .transform % 2 == 1 then .width else .height end) / .scale | floor)}'

monitors_ok() {
  # At least one real monitor and no placeholder output.
  hyprctl monitors -j | jq -e 'length > 0 and all(.[]; .name != "FALLBACK")' >/dev/null
}

take_snapshot() {
  monitors_ok || return
  local data
  data="$(jq -n \
    --argjson clients "$(hyprctl clients -j)" \
    --argjson monitors "$(hyprctl monitors -j)" "{
      monitors: [\$monitors[] | $geometry + {workspace: .activeWorkspace.name, focused}],
      windows: [\$clients[] as \$c
        | \$c | select(.mapped and (.workspace.id > 0 or (.workspace.name | startswith(\"special:\"))))
        | {address, workspace: .workspace.name, floating, at, size,
           monitor: ([\$monitors[] | select(.id == \$c.monitor)][0].name)}]
    }" 2>/dev/null)" || return
  # Re-check: if a monitor dropped while we were reading, the data is suspect.
  monitors_ok || return
  printf '%s\n' "$data" >"$snapshot.tmp" && mv "$snapshot.tmp" "$snapshot"
}

dispatch() {
  hyprctl dispatch "$1" >/dev/null
}

# Current clients, monitors and workspaces as one JSON object.
current() {
  jq -n --argjson clients "$(hyprctl clients -j)" \
    --argjson monitors "$(hyprctl monitors -j)" \
    --argjson workspaces "$(hyprctl workspaces -j)" \
    "{clients: \$clients, workspaces: \$workspaces,
      monitors: [\$monitors[] | $geometry + {focused}]}"
}

# Names of snapshot monitors that are not connected now (one per line).
missing_monitors() {
  [[ -s $snapshot ]] || return
  jq -r --argjson now "$(hyprctl monitors -j)" \
    '.monitors[].name as $n | select(all($now[]; .name != $n)) | $n' "$snapshot"
}

restore() {
  [[ -s $snapshot ]] || return
  monitors_ok || return

  local now
  now="$(current)"

  # One line per window to fix: address, workspace, floating, x, y, w, h.
  # Only windows whose monitor is connected; relocate() handles the others.
  # Positions are shifted if the window's monitor itself moved.
  local addr ws floating x y w h cur_ws cur_floating
  while IFS=$'\t' read -r addr ws floating x y w h cur_ws cur_floating; do
    [[ -n $addr ]] || continue
    local win="address:$addr"
    if [[ $ws != "$cur_ws" ]]; then
      dispatch "hl.dsp.window.move({ window = \"$win\", workspace = \"$ws\", follow = false })"
    fi
    if [[ $floating != "$cur_floating" ]]; then
      dispatch "hl.dsp.window.float({ window = \"$win\", action = \"$([[ $floating == true ]] && echo on || echo off)\" })"
    fi
    if [[ $floating == true ]]; then
      dispatch "hl.dsp.window.resize({ window = \"$win\", x = $w, y = $h })"
      dispatch "hl.dsp.window.move({ window = \"$win\", x = $x, y = $y })"
    fi
  done < <(jq -r --argjson now "$now" '
    .monitors as $old
    | .windows[] as $w
    | ($now.clients[] | select(.address == $w.address)) as $c
    | ([$old[] | select(.name == $w.monitor)][0]) as $om
    | ([$now.monitors[] | select(.name == $w.monitor)][0]) as $nm
    | select($nm != null)
    | (if $om then [$nm.x - $om.x, $nm.y - $om.y] else [0, 0] end) as $d
    | select($c.workspace.name != $w.workspace or $c.floating != $w.floating
             or ($w.floating and ($c.at != [$w.at[0] + $d[0], $w.at[1] + $d[1]] or $c.size != $w.size)))
    | [$w.address, $w.workspace, $w.floating, $w.at[0] + $d[0], $w.at[1] + $d[1],
       $w.size[0], $w.size[1], $c.workspace.name, $c.floating]
    | @tsv' "$snapshot")

  # Give each connected monitor back the workspace it was showing, then
  # refocus the monitor that had focus.
  local name mws
  while IFS=$'\t' read -r name mws; do
    dispatch "hl.dsp.focus({ monitor = \"$name\" })"
    dispatch "hl.dsp.focus({ workspace = \"$mws\" })"
  done < <(jq -r --argjson now "$now" '
    [.monitors[] | select(.name as $n | any($now.monitors[]; .name == $n))]
    | sort_by(.focused) | .[] | [.name, .workspace] | @tsv' "$snapshot")
}

# Give the workspaces and windows of missing snapshot monitors to other
# monitors. Missing monitors pair up with monitors the snapshot does not know
# (left to right). With $1 = all, the rest go to the focused monitor and stray
# floating windows are pulled back on screen. Prints the number of missing
# monitors that still have no target.
relocate() {
  local mode="${1:-new}" now
  [[ -s $snapshot ]] || { echo 0; return; }
  # While the FALLBACK placeholder is still there, it must not take a missing
  # monitor's place. Report one monitor still without a target and wait.
  monitors_ok || { echo 1; return; }
  now="$(current)"

  local kind a b c d e
  while IFS=$'\t' read -r kind a b c d e; do
    case $kind in
    ws) dispatch "hl.dsp.workspace.move({ workspace = \"$a\", monitor = \"$b\" })" ;;
    win)
      dispatch "hl.dsp.window.resize({ window = \"address:$a\", x = $d, y = $e })"
      dispatch "hl.dsp.window.move({ window = \"address:$a\", x = $b, y = $c })"
      ;;
    left) echo "$a" ;;
    esac
  done < <(jq -r --argjson now "$now" --arg mode "$mode" '
    . as $snap
    | ($now.monitors | map(.name)) as $names
    | ([$snap.monitors[] | select(.name as $n | $names | index($n) | not)] | sort_by(.x, .y)) as $miss
    | ([$now.monitors[] | select(.name as $n | [$snap.monitors[].name] | index($n) | not)] | sort_by(.x, .y)) as $new
    | ([$now.monitors[] | select(.focused)][0] // $now.monitors[0]) as $f
    | [range(0; $miss | length) as $i
        | if $i < ($new | length) then {from: $miss[$i], to: $new[$i]}
          elif $mode == "all" then {from: $miss[$i], to: $f}
          else empty end] as $pairs
    | ($pairs | map(.from.name)) as $moved
    | (
        # Workspaces that lived on a moved monitor: the one it showed, and the
        # ones its windows were on.
        ($pairs[] as $p
          | ([$p.from.workspace] + [$snap.windows[] | select(.monitor == $p.from.name) | .workspace]
             | unique[]) as $wsname
          | $now.workspaces[] | select(.name == $wsname and .id > 0)
          | ["ws", (.id | tostring), $p.to.name] | @tsv),
        # Floating windows of a moved monitor: same relative place and size,
        # scaled to the new monitor and kept inside it.
        ($pairs[] as $p
          | $snap.windows[] | select(.monitor == $p.from.name and .floating) as $w
          | $now.clients[] | select(.address == $w.address and .floating)
          | ([($w.size[0] * $p.to.w / $p.from.w | floor), $p.to.w] | min) as $nw
          | ([($w.size[1] * $p.to.h / $p.from.h | floor), $p.to.h] | min) as $nh
          | ([$p.to.x + (($w.at[0] - $p.from.x) * $p.to.w / $p.from.w | floor), $p.to.x + $p.to.w - $nw] | min) as $nx
          | ([$p.to.y + (($w.at[1] - $p.from.y) * $p.to.h / $p.from.h | floor), $p.to.y + $p.to.h - $nh] | min) as $ny
          | ["win", $w.address, ([$nx, $p.to.x] | max), ([$ny, $p.to.y] | max), $nw, $nh] | @tsv),
        # With mode all: any floating window whose center is on no monitor
        # goes to the center of the focused monitor.
        (if $mode == "all" then
          $now.clients[]
          | select(.mapped and .floating and .workspace.id > 0)
          | select(.address as $a | [$snap.windows[] | select(.monitor as $m | $moved | index($m))] | map(.address) | index($a) | not)
          | (.at[0] + .size[0] / 2) as $cx | (.at[1] + .size[1] / 2) as $cy
          | select(all($now.monitors[]; $cx < .x or $cx >= .x + .w or $cy < .y or $cy >= .y + .h))
          | ([.size[0], $f.w] | min) as $nw | ([.size[1], $f.h] | min) as $nh
          | ["win", .address, ($f.x + ($f.w - $nw) / 2 | floor), ($f.y + ($f.h - $nh) / 2 | floor), $nw, $nh] | @tsv
        else empty end),
        (["left", (($miss | length) - ($pairs | length) | tostring)] | @tsv)
      )' "$snapshot")
}

if [[ ${1:-} == "--restore" ]]; then
  restore
  relocate new >/dev/null
  exit 0
fi

# Only one daemon per Hyprland session.
exec 9>"$XDG_RUNTIME_DIR/window-restore-$HYPRLAND_INSTANCE_SIGNATURE.lock"
flock -n 9 || exit 0

take_snapshot
frozen=0

# After a reconnect: restore what is back, hand replaced monitors' windows to
# the new monitors, and resume snapshots when nothing is left to wait for.
settle() {
  restore
  local left
  left="$(relocate new)"
  if [[ ${left:-0} == 0 ]]; then
    frozen=0
    missing_since=
    take_snapshot
    last=$SECONDS
  fi
}

while true; do
  socat -U - "UNIX-CONNECT:$socket" 2>/dev/null 9>&- | while true; do
    if read -r -t "$interval" event; then
      case "$event" in
      monitorremoved\>\>FALLBACK | monitoradded\>\>FALLBACK) ;;
      monitorremoved\>\>*)
        frozen=1
        ;;
      monitoradded\>\>*)
        frozen=1
        # Let Hyprland finish moving workspaces back, then restore twice:
        # some windows get repositioned again shortly after reconnect.
        sleep 2
        restore
        sleep 2
        settle
        ;;
      openwindow\>\>* | closewindow\>\>* | movewindow*\>\>* | changefloatingmode\>\>*)
        ((frozen)) || { take_snapshot; last=$SECONDS; }
        ;;
      esac
    else
      (($? > 128)) || break # EOF: socket closed
    fi
    # While frozen with only real monitors connected, wait for missing ones.
    # The clock starts when the layout is usable again (not at the removal),
    # so a monitor that wakes up later than the others still gets $grace.
    if ((frozen && SECONDS - ${checked:-0} >= 1)); then
      checked=$SECONDS
      if monitors_ok && [[ -z $(missing_monitors) ]]; then
        # Every monitor is back, but settle() could not finish (FALLBACK was
        # still there when it ran). Finish it now.
        missing_since=
        settle
      elif monitors_ok; then
        missing_since=${missing_since:-$SECONDS}
        if ((SECONDS - missing_since >= grace)); then
          relocate all >/dev/null
          frozen=0
          missing_since=
          take_snapshot
          last=$SECONDS
        fi
      else
        missing_since=
      fi
    fi
    # Periodic snapshot, also catches floating windows dragged with the mouse.
    # Checked on every event too, since title changes can arrive non-stop.
    if ((!frozen && SECONDS - ${last:-0} >= interval)); then
      take_snapshot
      last=$SECONDS
    fi
  done
  # Hyprland went away (exit or restart): stop with it.
  [[ -S $socket ]] || exit 0
  sleep 1
done

Suggestion

Ship something like this in Omarchy, or handle the case in the shell, so that a monitor reconnect never leaves windows off-screen. I can turn the script into a PR that follows AGENTS.md, if that is a direction you want.