> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simular.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Window

> Handle to an on-screen window of a machine.

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

```typescript
Window(): Window
```

### Returns

`Window`

## Properties

<ResponseField name={"pid"} type={"number"} required>
  Process ID that owns this window.
</ResponseField>

<ResponseField name={"title"} type={"string"} required>
  Window title (may be empty).
</ResponseField>

## Methods

### backgroundButton()

```typescript
backgroundButton(button: Button, direction: Direction): void
```

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

<ResponseField name={"button"} type={"Button"} required />

<ResponseField name={"direction"} type={"Direction"} required />

### backgroundClick()

```typescript
backgroundClick(x: number, y: number, button: Button, direction: Direction): void
```

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

<ResponseField name={"x"} type={"number"} required />

<ResponseField name={"y"} type={"number"} required />

<ResponseField name={"button"} type={"Button"} required />

<ResponseField name={"direction"} type={"Direction"} required />

### backgroundKey()

```typescript
backgroundKey(key: Key, direction: Direction): void
```

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

#### Parameters

<ResponseField name={"key"} type={"Key"} required />

<ResponseField name={"direction"} type={"Direction"} required />

### backgroundKeyOther()

```typescript
backgroundKeyOther(value: number, direction: Direction): void
```

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

#### Parameters

<ResponseField name={"value"} type={"number"} required />

<ResponseField name={"direction"} type={"Direction"} required />

### backgroundKeyUnicode()

```typescript
backgroundKeyUnicode(value: string, direction: Direction): void
```

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

#### Parameters

<ResponseField name={"value"} type={"string"} required />

<ResponseField name={"direction"} type={"Direction"} required />

### backgroundMoveMouse()

```typescript
backgroundMoveMouse(x: number, y: number): void
```

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

<ResponseField name={"x"} type={"number"} required />

<ResponseField name={"y"} type={"number"} required />

### backgroundRaw()

```typescript
backgroundRaw(keycode: number, direction: Direction): void
```

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

#### Parameters

<ResponseField name={"keycode"} type={"number"} required />

<ResponseField name={"direction"} type={"Direction"} required />

### backgroundScroll()

```typescript
backgroundScroll(deltaX: number, deltaY: number): void
```

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

<ResponseField name={"deltaX"} type={"number"} required />

<ResponseField name={"deltaY"} type={"number"} required />

### backgroundText()

```typescript
backgroundText(text: string): void
```

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

#### Parameters

<ResponseField name={"text"} type={"string"} required />

### boundingBox()

```typescript
boundingBox(): 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()

```typescript
button(button: Button, direction: Direction): void
```

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

<ResponseField name={"button"} type={"Button"} required />

<ResponseField name={"direction"} type={"Direction"} required />

### click()

```typescript
click(x: number, y: number, button: Button, direction: Direction): void
```

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

<ResponseField name={"x"} type={"number"} required />

<ResponseField name={"y"} type={"number"} required />

<ResponseField name={"button"} type={"Button"} required />

<ResponseField name={"direction"} type={"Direction"} required />

### close()

```typescript
close(): void
```

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

### focus()

```typescript
focus(): boolean
```

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()

```typescript
ground(model: GroundingModel, concept: string): [number, number]
```

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

<ResponseField name={"model"} type={"GroundingModel"} required />

<ResponseField name={"concept"} type={"string"} required />

#### Returns

`[number, number]`

### isMaximized()

```typescript
isMaximized(): boolean
```

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()

```typescript
isMinimized(): boolean
```

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()

```typescript
maximize(): void
```

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()

```typescript
minimize(): void
```

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()

```typescript
moveMouse(x: number, y: number): void
```

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

<ResponseField name={"x"} type={"number"} required />

<ResponseField name={"y"} type={"number"} required />

### node()

```typescript
node(): AccessibilityNode
```

Root accessibility node for this window.

#### Returns

`AccessibilityNode`

### normal()

```typescript
normal(): void
```

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()

```typescript
scoredSearch(order: TraversalOrder, maxNodes: number, collapseStructural: boolean, query: string, threshold: number): AccessibilityNode[]
```

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

<ResponseField name={"order"} type={"TraversalOrder"} required />

<ResponseField name={"maxNodes"} type={"number"} required />

<ResponseField name={"collapseStructural"} type={"boolean"} required />

<ResponseField name={"query"} type={"string"} required />

<ResponseField name={"threshold"} type={"number"} required />

#### Returns

`AccessibilityNode[]`

### screen()

```typescript
screen(): 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()

```typescript
screenshot(hideCursor: boolean): 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

<ResponseField name={"hideCursor"} type={"boolean"} required />

#### Returns

`Screenshot`

### scroll()

```typescript
scroll(deltaX: number, deltaY: number): void
```

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

<ResponseField name={"deltaX"} type={"number"} required />

<ResponseField name={"deltaY"} type={"number"} required />

### snapshot()

```typescript
snapshot(): string
```

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`