$RT with the display already started (Screen).
Focus a window
windows returns {windows: [...], focused} — focused is the focused
window’s id; each entry carries id, geometry (x, y, w, h),
title, window_class, instance, desktop (virtual-desktop index),
focused, and states (window-manager flags). window_class filters by
class substring. window_op takes the window id and an op — focus,
close, raise, lower, move (with x/y), resize (with w/h),
maximize, unmaximize, minimize, fullscreen, unfullscreen — and
returns the window’s post-op record.
Window ops need a window manager — pass
wm at enable (or run a desktop
template, which ships one). Without a WM, windows lists what the X server
maps but placement ops have no effect.
Launch an app
apps lists the applications the template registered — each entry is
{id, name, exec, icon, categories} (a freedesktop entry). launch_app starts one by
its apps() id; uri substitutes into the app’s exec line (open a URL in
the registered browser, a file in the editor, …). wait_window blocks until
a new top-level window maps — the launch-then-act pattern — and returns
{pid, window_id, app}; timeout_ms caps the wait (default 10000 when
waiting).
Open a file
open hands a file path or URL to its registered handler — a URL to the
default browser, a PDF to the document viewer, a text file to the editor —
and returns {pid, window_id, app, mime} (mime names the detected type,
window_id is set when wait_window resolved one). Use it when you want
the platform’s routing rather than picking the app yourself.
Use the window that opened
- A
wait_windowlaunch or open is how you chain into input: the returnedwindow_idis the new top-level window, ready forwindow_opor a screenshot cropped to its geometry. appsreflects the template — a template without registered desktop entries returns an empty list, andlaunch_appthen returns404for unknown ids.- For web work prefer
browser.open— it manages the browser’s lifecycle, tabs, and headless mode.open/launch_appare for everything else.