GNOME Shell enumeration & activation API research

[jonocodes]

Part of #116

Question

What APIs does GNOME Shell offer an extension for (a) enumerating open windows with stable identities (app_id, wm_class, title, workspace), (b) signals for window open/close/title-change, and (c) activating/raising a window — and how fragile are they across shell versions? Survey prior art: the 'Window Calls' family of extensions, gnome-shell's own global.get_window_actors / Shell.AppSystem, and how they expose these over D-Bus. Capture findings as a research doc in the repo.

[jonocodes]

Research complete. Findings doc: docs/research/gnome-shell-window-apis.md on branch research/118-gnome-shell-window-apis.

Key findings:

• Enumeration: extensions run in-process with full Mutter access — the only sanctioned path on Wayland. global.get_window_actors() (or display.get_tab_list() for MRU app windows) yields Meta.Windows with a full identity tuple: get_id() (unique per compositor session — the raise handle), get_wm_class(), get_gtk_application_id() (nullable), get_sandboxed_app_id() (best for Flatpak/Snap), get_title(), get_pid(), get_workspace(). Shell.WindowTracker.get_window_app(win).get_id() gives the cross-session-stable .desktop id (heuristic: sandboxed id → GTK app id → WM_CLASS → PID) and beats hand-rolled wm_class matching.
• Signals: Meta.Display::window-created for opens (title may arrive late — also hook notify::title), per-window ::unmanaging/::unmanaged for closes, notify::title for renames. Our extension already uses notify::focus-window.
• Activation: Main.activateWindow(win) is canonical — defaults timestamp to global.get_current_time() and handles cross-workspace via workspace.activate_with_focus(). In-process, so no focus-stealing-prevention issues.
• Prior art: Window Calls exports ~18 methods on org.gnome.Shell.Extensions.Windows (JSON List(), Activate(winid) keyed on get_id()) with zero version branching — validates our JSON-over-D-Bus design.
• Fragility: the Meta/Shell APIs involved have been stable across GNOME 40–48. The churn is mechanical: GNOME 45's ESM migration (already behind us) and the exact-match shell-version gate requiring a metadata bump every release. org.gnome.Shell.Eval is locked down since 41 and Introspect is portal-allowlisted, so a real extension is required — confirming deckd's architecture.

Net: low API risk, recurring packaging chore. Extending deckd-focus@local with ListWindows/WindowsChanged/ActivateWindow(id) is additive.