Initial Lime window manager

docs/attention.md

@@ -0,0 +1,78 @@
+# Application attention
+
+Lime watches ICCCM `WM_HINTS` UrgencyHint and EWMH
+`_NET_WM_STATE_DEMANDS_ATTENTION`. A request adds a quiet, clickable `! N`
+badge to every visible Head bar. There are no flashes, popups, timers, or
+automatic Activity switches. A window requesting both hints counts once.
+
+Click the badge or use **Super-y → w → a** for a searchable list across all
+Activities. The direct command search also offers “Windows needing attention”.
+Entries show the Activity and the current application title. The ordinary
+hidden-window picker marks requesting windows with `!`, and Activity search
+shows request counts in its details.
+
+## Visiting a request
+
+- A leased window is focused on the Head that already owns it. It is not
+  pulled onto the Head where you opened the picker. This also works for a
+  non-visible member of a monocle stack.
+- A hidden window is shown in its own Activity on the selected Head. If
+  necessary, Lime resumes that Activity's **draft**, not an arbitrary saved View.
+- Resuming a draft with contested windows still offers explicit partial/take
+  choices. Opening or cancelling that choice does not change either Head.
+  The target and its lease are checked again when you select an option.
+- Visiting a window behind a different fullscreen window exits that fullscreen
+  state so the requested window can actually be seen. Visiting the fullscreen
+  window itself preserves fullscreen.
+- Revealing a hidden window edits the live draft normally; it never rewrites
+  a checkpoint. Merely receiving or displaying attention changes no model state.
+
+Lime acknowledges attention when the selected, visible input target actually
+has X focus, including focus inside a child widget. Another Head's saved focus,
+root/background focus, and an open command-palette grab do not count. Clients
+using `WM_TAKE_FOCUS` keep their request until they actually answer by taking
+focus. Closing the menu after a visit then acknowledges the chosen application.
+
+Acknowledgement clears only the urgency flag and the demands-attention atom;
+other `WM_HINTS` fields, fullscreen, and unrelated EWMH state remain intact.
+Applications can cancel either source independently. Destruction and genuine
+withdrawal remove the client from the list; stale picker entries cannot revive it.
+
+## Boundaries
+
+This is **application attention**, not a desktop notification daemon or an
+unread-message counter. Applications must publish the relevant X11 hints.
+A game's fullscreen Head still hides its bar; another visible Head can show
+the badge, and the menu remains accessible. Disabling the badge or the entire
+bar does not disable the picker.
+
+Attention is adapter-local, never part of session snapshots. Surviving X
+windows have their current hints reread when adopted after a WM restart.
+Dead windows and old alerts are not resurrected from disk. Hidden
+`_NET_ACTIVE_WINDOW` requests which Lime declines become attention requests;
+the existing activation policy for already leased clients is otherwise unchanged.
+
+Configuration controls the badge's color, marker, and visibility; see
+[bar appearance](configuration.md#bar-appearance). No personal configuration
+changes are required for the default badge/menu. This addition changes backend
+structure and ASDF components: use a fresh Lime process to load it, rather than
+a function-only hot reload. Your running session is not modified by installing
+the code.
+
+## Implementation and tests
+
+`src/x11/attention.lisp` owns the live source cache and acknowledgement.
+ICCCM/EWMH adoption and property/client-message handlers feed it; focus effects
+and normal FocusIn events acknowledge it. Focus queries run only for pending
+requests, not as an idle poll. Bar/UI code consumes cached queries; the command
+layer owns visiting and the ordinary Activity/lease transitions.
+
+The owned-Xvfb smoke test is `test/x11-attention-smoke.lisp`. It covers real
+ICCCM/EWMH changes and cancellation, both message atom slots, initial hints,
+NoInput and asynchronous child focus, hidden and inactive Activities, bar clicks,
+which-key visits, independent Heads, fullscreen preservation, stale selections,
+and withdrawal/destruction. Server-free tests also cover partial/take collisions,
+stale choices, checkpoint isolation, and configurable presentation.
+
+Protocol references: [ICCCM WM_HINTS](https://www.x.org/releases/current/doc/xorg-docs/icccm/icccm.html)
+and [EWMH window state](https://specifications.freedesktop.org/wm/1.5/ar01s05.html).