docs(window-switcher): write down what the build cost to learn

The component is finished and on the user's ALT+TAB, so what is left is the
part that would otherwise have to be rediscovered. Most of the time this
build took went to three things that report success and then do nothing:
Hyprland 0.56.2 evaluating dispatch arguments as Lua, so the
documented-looking `focuswindow address:0x...` is a silent syntax error; a
focus dispatched while the overlay still holds an exclusive keyboard grab
being accepted and ignored; and a sort on a `focusHistoryID` property that
does not exist, comparing NaN and leaving an arbitrary order that looks
plausible. None of them logs anything.

Those six, plus the missing `0x` prefix, the empty `toplevels` before
`refreshToplevels()` and `ScreencopyView` reporting (-1, -1) rather than
(0, 0), generalise past this component, so they go in AGENTS.md next to the
other notes that exist because a commit message explained itself once. The
card geometry and the blank icon square are specific to the grid and stay in
the component README.

Also corrects the counts that four components made true and five do not: the
component lists, "the other three use ExclusionMode.Ignore", and the Theme
symlink note.

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

1 files changed, 35 insertions, 6 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 3a2e504..6a58d76 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,10 +8,11 @@ Quickshell components for a Hyprland desktop, one per directory, each a
 complete shell in its own right. They are not modules of a single bar: any of
 them runs alone, and running one does not require the others.
 
-    volume-osd/     volume for output and input, plus what is playing
-    vm-manager/     libvirt drawer: state, live stats, snapshots
-    appearance/     wallpaper picker and colour scheme switcher
-    mail-overview/  notmuch unread counts per account, waybar icon and drawer
+    volume-osd/       volume for output and input, plus what is playing
+    vm-manager/       libvirt drawer: state, live stats, snapshots
+    appearance/       wallpaper picker and colour scheme switcher
+    mail-overview/    notmuch unread counts per account, waybar icon and drawer
+    window-switcher/  open windows as live previews in a grid, on ALT+TAB
 
 They are started from `~/.config/hypr/sections/autostart.lua` and keep running
 for the whole session.
@@ -102,6 +103,31 @@ changing that component. The ones that generalise:
   `block.allocation` is qcow2 growth on the host, not usage inside the guest.
   The real numbers come from qemu-guest-agent, and the panel shows a dash
   rather than substituting the host-side ones.
+- **Hyprland 0.56.2 evaluates dispatch arguments as Lua.** `dispatch
+  focuswindow address:0x...` is a syntax error rather than a command, and it
+  fails silently unless stderr is read. The working form is `dispatch
+  hl.dsp.focus({ window = "address:0x..." })`. This is why
+  `~/bin/hypr-windows.sh` is written the way it is, and its syntax was misread
+  as legacy oddity worth modernising.
+- **A focus dispatched while an overlay holds the keyboard is accepted and then
+  ignored.** A layer surface with `keyboardFocus: Exclusive` grabs the
+  keyboard, and the compositor will not move window focus out from under that
+  grab. The dispatch reports `ok`, nothing moves, and no log line says
+  otherwise. Closing in the same turn does not help either, because a `close()`
+  that clears a property leaves the surface alive until the frame after. Focus
+  after the overlay is really gone, which `window-switcher` does with a 60ms
+  timer.
+- **`HyprlandToplevel` has no `focusHistoryID` property.** It reads
+  `undefined`, so a sort on it compares `NaN` and silently does nothing,
+  leaving a plausible looking list in arbitrary order. The value is on
+  `lastIpcObject`.
+- **`HyprlandToplevel.address` omits the `0x`** that `hyprctl clients` prints
+  and that every dispatch requires.
+- **`Hyprland.toplevels` reads 0 until `refreshToplevels()` is called.**
+- **An uncaptured `ScreencopyView` reports `sourceSize` of `QSize(-1, -1)`**,
+  not `(0, 0)`. An aspect ratio guard has to test for a positive height: the
+  obvious rewrites, `!== 0` or a truthiness check, all pass on `-1` and produce
+  a negative ratio.
 
 ## Theme
 
@@ -128,7 +154,7 @@ they never had. A symlink rather than a shared import path because a singleton
 outside the config directory needs a `qmldir`, which is the same friction that
 keeps the palette parsed rather than imported; quickshell follows the link and
 resolves the singleton with no qmldir and no consumer change. Editing any
-component's `Theme.qml` edits all four. Do not replace a link with a copy.
+component's `Theme.qml` edits all five. Do not replace a link with a copy.
 
 ## Blur
 
@@ -144,9 +170,12 @@ A panel that should sit below waybar rather than over it wants
 exclusive zone without the component knowing the bar's height. Measured with
 `hyprctl layers`: waybar at `y=-540 h=42`, a `Normal` overlay on the same
 screen at `y=-498 h=1038`, starting exactly where the bar ends, so the
-backdrop never dims it. `mail-overview` does this; the other three use
+backdrop never dims it. `mail-overview` does this; the other four use
 `ExclusionMode.Ignore` and cover the whole screen.
 
+`window-switcher` is the fifth, with namespace `quickshell-window-switcher` and
+a `blur-window-switcher` rule of its own.
+
 ## Reloading
 
 | | How |