Skip to main content
Handle to an on-screen window of a machine. Obtain via [Machine.windows], [Machine.focusedWindow], or [Instance.windows]; exposes read-only metadata (title, pid), state probes (isMinimized, isMaximized), named visual-state actions (minimize, maximize, normal, close), window-relative input, and accessibility access. On Android a “window” is an application task (a recents-overview entry).

​
Constructor

​
Returns

Window

​
Properties

​
number
required
Process ID that owns this window.
​
string
required
Window title (may be empty).

​
Methods

​
backgroundButton()

Send a mouse-button event to this window without moving the system cursor or bringing the application to the foreground. Call [Window.backgroundMoveMouse] first to choose the location. Supported on macOS only.

​
Parameters

​
Button
required
​
Direction
required

​
backgroundClick()

Send a mouse-button event to (x, y) in this window without moving the system cursor or bringing the application to the foreground. Coordinates are window-frame-relative. Supported on macOS only.

​
Parameters

​
number
required
​
number
required
​
Button
required
​
Direction
required

​
backgroundKey()

Send a key event to this window without bringing its application to the foreground. Supported on macOS only.

​
Parameters

​
Key
required
​
Direction
required

​
backgroundKeyOther()

Send a platform-specific key value to this window without bringing its application to the foreground. Supported on macOS only.

​
Parameters

​
number
required
​
Direction
required

​
backgroundKeyUnicode()

Send a Unicode key event to this window without bringing its application to the foreground. Provide a single character. Supported on macOS only.

​
Parameters

​
string
required
​
Direction
required

​
backgroundMoveMouse()

Move this window’s private background pointer without moving the system cursor or bringing the application to the foreground. (x, y) are window-frame-relative. The location is retained for subsequent [Window.backgroundButton] and [Window.backgroundScroll] calls, and stays anchored to the window frame even if the window is moved in between. Supported on macOS only. Throws on other platforms or when macOS background event delivery is unavailable.

​
Parameters

​
number
required
​
number
required

​
backgroundRaw()

Send a raw keycode to this window without bringing its application to the foreground. Supported on macOS only.

​
Parameters

​
number
required
​
Direction
required

​
backgroundScroll()

Scroll this window at its private background-pointer location without bringing the application to the foreground. Call [Window.backgroundMoveMouse] first to choose the location. Supported on macOS only.

​
Parameters

​
number
required
​
number
required

​
backgroundText()

Type text into this window without bringing its application to the foreground. Supported on macOS only.

​
Parameters

​
string
required

​
boundingBox()

Live bounding box of the window on the global desktop, in the canonical coordinate space (OS-native units; see [Machine]). right and bottom are exclusive (Playwright / DOM convention). Coordinates can be negative when the window sits on a monitor that is arranged to the left of / above the primary display.

​
Returns

BoundingBox

​
button()

Press / release a mouse button at the cursor’s current location. Provided for ergonomic parity with [Window.moveMouse] — combine the two for press / drag / release patterns. Takes no coordinate argument: pair with moveMouse when you need to control where the press lands.

​
Parameters

​
Button
required
​
Direction
required

​
click()

Move the cursor to (x, y) inside this window and synthesise a mouse button event. Sugar for moveMouse(x, y); button(...). Coordinates are window-frame-relative (see [Window.moveMouse]), and are subject to the same bounds / on-screen validation: an off-frame or off-screen target throws instead of clicking the wrong location. Does not focus the window.

​
Parameters

​
number
required
​
number
required
​
Button
required
​
Direction
required

​
close()

Close the window (user-equivalent to clicking the close button / pressing Alt+F4 / Cmd+W). Android: remove the task, including its recents card.

​
focus()

Bring this window to the foreground and give it keyboard focus. Platform notes:
  • macOS: raises the window via the accessibility AXRaise action so it becomes the app’s key window, then activates the owning application with default options so that key window surfaces.
  • Windows: SetForegroundWindow + BringWindowToTop. Subject to the foreground lock — the call may be downgraded to a taskbar flash if the foreground process didn’t grant permission.
  • Linux: EWMH _NET_ACTIVE_WINDOW client message to the WM.

​
Returns

boolean

​
ground()

Locate concept inside this window’s pixels and return its global desktop coordinates [x, y] in OS-native units (may be negative on multi-monitor setups; see [Machine]), ready to feed straight into [Machine.moveMouse] / click helpers on the owning machine. Sugar for screenshot(true).ground(model, concept) — the cursor is hidden because it can occlude or distract the model. Restricts the model’s search to this window’s bounds, which is both faster (fewer pixels to upload) and more accurate (no risk of grounding onto a concept that happens to be elsewhere on the screen) than grounding a full-screen screenshot. Drop down to [Window.screenshot] + [Screenshot.ground] directly when you want to keep the cursor visible, reuse the screenshot across multiple ground calls, or shrink / compress the image before sending it. The screenshot includes any portion of the window that’s past the desktop edge (the capture reads the window’s own backing store, not a display rectangle). A concept the model locates in that off-screen region returns coordinates the OS won’t route a click to; [Window.moveMouse] catches this and errors out instead of clicking the nearest on-screen point.

​
Parameters

​
GroundingModel
required
​
string
required

​
Returns

[number, number]

​
isMaximized()

Whether the window is currently maximized (visible and zoomed / full screen). A minimized window reports false. Android: the task is on screen and occupies it fully. Platform notes:
  • Windows: IsZoomed && !IsIconic.
  • macOS: accessibility AXFullScreen && !AXMinimized. macOS has no native “maximized” concept — [Window.maximize] enters full screen on modern macOS, so this reports that state. A window manually zoomed to fill the screen (Option-click the zoom button) reports false.
  • Linux: EWMH _NET_WM_STATE contains both MAXIMIZED_HORZ and MAXIMIZED_VERT, and not HIDDEN.

​
Returns

boolean

​
isMinimized()

Whether the window is currently minimized (Android: the task is backgrounded). Platform notes:
  • Windows: IsIconic.
  • macOS: reads the accessibility AXMinimized attribute.
  • Linux: EWMH _NET_WM_STATE contains _NET_WM_STATE_HIDDEN.

​
Returns

boolean

​
maximize()

Put the window into the maximized visual state: on-screen and maximized / full screen. A minimized window is shown maximized. No-op when already maximized. Platform notes:
  • Windows: ShowWindow(SW_MAXIMIZE).
  • macOS: sets AXFullScreen. A minimized window is un-minimized first.
  • Linux: EWMH _NET_WM_STATE add of MAXIMIZED_HORZ + MAXIMIZED_VERT, then maps the window if it was iconified.

​
minimize()

Put the window into the minimized visual state (Dock / taskbar / backgrounded). No-op when already minimized. Platform notes:
  • Windows: ShowWindow(SW_MINIMIZE).
  • macOS: sets the accessibility AXMinimized attribute. A full-screen window is taken out of full screen first; otherwise the attribute is ignored.
  • Linux: ICCCM WM_CHANGE_STATE → IconicState.

​
moveMouse()

Move the cursor to a point inside this window. (x, y) are window-frame-relative, in OS-native units (physical pixels on Windows/Linux, logical points on macOS) — (0, 0) is the top-left of [Window.boundingBox], which includes the title bar and other OS chrome. Two validation passes run before any input is synthesized, and either failing throws:
  1. (x, y) must lie inside the window frame ([0, width) × [0, height)).
  2. The resulting global point must fall on at least one connected display. Windows dragged partly off-screen can map an in-frame point to a coordinate the OS would silently clamp to a display edge — erroring out is strictly more useful than moving the cursor somewhere unintended and clicking the wrong thing.
Does not focus the window. Call [Window.focus] (or [Instance.focus]) first if the click target requires the window to be active. On Android there is no real cursor: the point is recorded and the next [Window.button] press/release becomes a tap or swipe there. Input is routed to the window’s own pointer: the host’s global mouse for local windows, the device’s emulated pointer for Android windows.

​
Parameters

​
number
required
​
number
required

​
node()

Root accessibility node for this window.

​
Returns

AccessibilityNode

​
normal()

Put the window into the normal visual state: on-screen, neither minimized nor maximized. A minimized or maximized window is shown at its restored size. No-op when already normal. Platform notes:
  • Windows: ShowWindow(SW_SHOWNORMAL).
  • macOS: clears AXMinimized if needed, then clears AXFullScreen.
  • Linux: EWMH _NET_WM_STATE remove of MAXIMIZED_HORZ + MAXIMIZED_VERT, then maps the window if it was iconified.

​
scoredSearch()

Search this window’s accessibility subtree by concept text, using bag-of-words paired-Jaccard scoring against each node’s overallDescription (simulang_rs::AXNodeSynthetic::summary_with_context). Mirrors simulang_rs::Window::scored_search, which resolves the window’s accessibility root and walks it (on Windows this prebuilds the cached UIA subtree so the walk costs a single IPC). Returns every node whose score equals the maximum found and exceeds threshold.
  • order – TraversalOrder.DepthFirst or TraversalOrder.BreadthFirst
  • max_nodes – upper bound on nodes visited (uses .take() over the walk)
  • collapse_structural – hoist empty structural wrappers out of the walk before scoring
  • query – natural-language concept Jaccard-compared against each node’s overallDescription
  • threshold – minimum score to keep a node
Returned nodes are full AccessibilityNode handles — call action methods (activate, setValue, …) directly on them, walk children with .children(), or render a snapshot with .snapshot().

​
Parameters

​
TraversalOrder
required
​
number
required
​
boolean
required
​
string
required
​
number
required

​
Returns

AccessibilityNode[]

​
screen()

The screen this window lives on: locally the connected display containing the largest area of [Window.boundingBox] (the same heuristic the OS uses to decide a window’s “owning” screen), on Android the device’s screen. Locally this throws if the window has no measurable overlap with any connected display — for example when the window is fully off-screen, minimised to an off-screen state, or on a virtual desktop with no attached display. There is no “correct” screen to pick in that case; callers that prefer a fallback can wrap in try / catch and call [Machine.mainScreen].

​
Returns

Screen

​
screenshot()

Capture just this window’s pixels. Local windows read from their own backing store, so overlapping windows do not bleed through and the whole window is captured even where it is occluded or extends past a display edge — partially off-screen and multi-display-spanning windows are captured in full. The window must be on-screen at capture time: a minimized or fully off-display window throws, because there is nothing to capture. On Android the capture is the physical screen, so the task must be the visible one (hideCursor is ignored — a phone has no cursor).

​
Parameters

​
boolean
required

​
Returns

Screenshot

​
scroll()

Scroll the wheel by (deltaX, deltaY) ticks at the cursor’s current location. Positive deltaY scrolls down; positive deltaX scrolls right. Does not reposition the cursor first — pair with [Window.moveMouse] if you need scrolling to happen at a specific point inside the window.

​
Parameters

​
number
required
​
number
required

​
snapshot()

Render the window’s accessibility subtree as an indented Playwright-style aria snapshot. One line per node, two spaces of indentation per depth level, in pre-order DFS. Roles are emitted raw (AXWindow on macOS, UIA.ControlType.* on Windows), with title and value appended when non-empty. No refs are assigned — for ref-based interaction use [AccessibilityTree.snapshot] instead.

​
Returns

string