docs(window-switcher): dispatch args are Lua, and focus raises in monocle

Two findings from testing against the running compositor, both of which
would have cost time during implementation.

Hyprland 0.56.2 evaluates dispatch arguments as Lua, so the form this
design previously specified, dispatch focuswindow address:0x..., is a
syntax error rather than a command. It fails silently unless stderr is
read: the window does not focus and nothing is reported. hypr-windows.sh
was written with hl.dsp.focus({ window = "..." }) for that reason, and
this design had misread that as legacy oddity.

The fullscreen batch sequence from that script is not carried over.
Workspaces 1 and 8 are monocle and 4 and 5 are scrolling, so a stacked
window is the normal case here rather than an edge case, and the worry
was that focus would land without the window becoming visible. Tested
with two stacked windows on workspace 1: focus alone raised the buried
one, confirmed on screen in both directions, so no alterzorder and no
batch sequence are needed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SYg4wYHq5XNbiVmMeKRb1S

1 files changed, 31 insertions, 6 deletions

diff --git a/docs/superpowers/specs/2026-09-12-window-switcher-design.md b/docs/superpowers/specs/2026-09-12-window-switcher-design.md
index 0fabe2f..5689ace 100644
--- a/docs/superpowers/specs/2026-09-12-window-switcher-design.md
+++ b/docs/superpowers/specs/2026-09-12-window-switcher-design.md
@@ -11,9 +11,10 @@ title and address in four columns. It says which windows exist, not what is in
 them. A preview grid answers "which window did I mean" by showing it, which is
 the whole reason a switcher exists.
 
-The replacement is therefore not a bug fix. The script's odd-looking
-`hl.dsp.focus({ window = "address:..." })` dispatch is confirmed working, so
-nothing is being repaired here, only improved.
+The replacement is therefore not a bug fix. The script's
+`hl.dsp.focus({ window = "address:..." })` dispatch is not the legacy oddity it
+resembles, it is the only form this Hyprland accepts, and it works. Nothing is
+being repaired here, only improved.
 
 ## What it looks like
 
@@ -132,6 +133,21 @@ A fourth is specific to this component: `HyprlandToplevel.address` reads
 `1140f190`, without the `0x` that `hyprctl clients` reports, while dispatches
 need the prefix.
 
+A fifth cost half an hour of this design and would have cost more during
+implementation. **Hyprland 0.56.2 evaluates dispatch arguments as Lua**, so the
+documented-looking form is a syntax error:
+
+    dispatch focuswindow address:0x11971b20
+    → error: ')' expected near 'address'
+
+    dispatch hl.dsp.focus({ window = "address:0x11971b20" })
+    → ok
+
+The first fails silently unless stderr is checked: the window simply does not
+focus and nothing is reported. This is why `hypr-windows.sh` is written the way
+it is, and its syntax was wrongly read as legacy oddity earlier in this design.
+Both focus and close go through the `hl.dsp.*` form.
+
 ## What was verified before writing this
 
 Against Hyprland 0.56.2 and quickshell 0.3.1, in a scratch config:
@@ -149,6 +165,10 @@ Against Hyprland 0.56.2 and quickshell 0.3.1, in a scratch config:
 - DP-3 reports `transform=1`, and the window on it measures 1076x1916 against
   2556x1034 on DP-1. Both orientations are live at once, which is what the
   fitted card box exists for.
+- Layouts vary per workspace, from `workspaces.lua`: 1 and 8 are `monocle`,
+  4 and 5 are `scrolling`, the rest are the default `master`. Focusing a
+  stacked window on a `monocle` workspace raises it without further help.
+- Dispatch arguments are Lua on this version, see the trap above.
 
 ## Theme
 
@@ -163,9 +183,14 @@ which is fine.
 ## Deliberately left out
 
 - **The fullscreen dance.** The script has a `--batch` sequence for focusing a
-  window when another is fullscreen on the same workspace. Whether plain
-  `focuswindow` still needs it is unknown; it goes back in only if a fullscreen
-  window is actually observed staying on top.
+  window when another is fullscreen on the same workspace. It is not carried
+  over. Workspaces 1 and 8 are `monocle` and 4 and 5 are `scrolling`, so
+  stacking is the normal state here rather than an edge case, and the concern
+  was that focus would land without the window becoming visible. Tested with
+  two stacked windows on workspace 1: `hl.dsp.focus` alone raised the buried
+  one, confirmed on screen in both directions. No `alterzorder` and no batch
+  sequence. It goes back in only if a fullscreen window is actually observed
+  staying on top.
 - **Multi-monitor overlays.** The overlay paints on DP-1 only. DP-3's windows
   still appear as cards, and being portrait they are the reason the card box is
   a fitted 16:10 rather than the shape of a preview.