# `T3.Previews`
[🔗](https://github.com/dl-alexandre/t3-elixir/blob/main/lib/t3/previews.ex#L1)

Previews MCP operations. Pass T3's original string-keyed argument maps.

Tool availability depends on the authenticated server, permission mode and
invocation context. In-app agent tools may not be available to outside clients.
See `T3.Catalog.tools(:previews)` for descriptions and context requirements.

# `act`

```elixir
@spec act(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Act on the chosen tab. Target with `locator='aria-ref=<ref>'` from `preview_snapshot`; `x` and `y` go together. `timeoutMs` defaults to 15000. click: `button`, `clickCount` 1 to 3. type: literal `text`, `clear=true` replaces it. hover: shows menus or tooltips. select: `values` in one native <select>, by value or label; for a custom dropdown, click it open, then click the option. drag: `source` onto `target`. upload: absolute `paths` answer the file picker `preview_status` reports, [] cancels it, or a `locator` sets an <input type=file>. press: one `key`, such as 'Enter', with `modifiers`, to the focused element; click a field first to focus it. scroll: the tab, or one container with a locator; positive `deltaY` scrolls down, positive `deltaX` right.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `close`

```elixir
@spec close(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Close one preview tab this thread owns. Use it on a tab you opened for your own check when you finish.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `dialog`

```elixir
@spec dialog(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Accept or dismiss the dialog `preview_status` reports. Pass `promptText` to accept a prompt. Needs your own tab, or an unclaimed one. Desktop hosts may not support this.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `evaluate`

```elixir
@spec evaluate(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Run JavaScript in the page. It can change page state. Returns `{value}`, up to 64 KB. Needs your tab, or an unclaimed one. To read a tab the user drives, use `preview_snapshot`. Page tools reached here: read data only, never create, save, or display. Show results with `html_render`.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `list`

```elixir
@spec list(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

List this thread's preview tabs. Only `runtime:'server'` entries can be automated here. Others are in the user's local desktop app. Never pass a non-server `tabId` to a `preview_*` tool. Tell the user that tab is on their local desktop and this environment cannot reach it.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `navigate`

```elixir
@spec navigate(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Navigate the chosen tab. Pass `url` for a website, or `target:{kind:'environment-port',port}` for a dev server. Exactly one of `url` and `target`.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `open`

```elixir
@spec open(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Open a preview tab in this thread and show it. `open=false` keeps it in the background. Reuses your current tab unless `tabId` or `reuseExistingTab=false` says otherwise. Parallel subagents in one session must each use `reuseExistingTab=false`, then their own returned `tabId`.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `resize`

```elixir
@spec resize(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Resize the chosen tab: {mode:'fill'}, {mode:'freeform',width,height}, or {mode:'preset',preset,orientation}. Changes CSS size only, not the user agent.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `set_appearance`

```elixir
@spec set_appearance(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Set `prefers-color-scheme` for the chosen tab: 'dark', 'light', or 'system' to clear the override.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `snapshot`

```elixir
@spec snapshot(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Use it only when the current request asks for browser work, including checking an edit in the browser. Never use it unasked to verify your own edit, or to repeat a snapshot from an earlier turn. Works on a tab the user is driving. Returns page state, elements, diagnostics, and screenshot size. Target one element with `locator='aria-ref=<ref>'` from `accessibilityTree`, even in frames. Refs die on navigation, a new snapshot, or handoff. Text caps near 20 KB; on your own or an unclaimed tab, `preview_evaluate` reads more. To show a screenshot when asked: `save=true`, then embed ![alt](screenshotPath).

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `start_recording`

```elixir
@spec start_recording(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Start recording the chosen tab.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `status`

```elixir
@spec status(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Report preview tab state: owner, pending dialog, URL, title, loading, viewport, and size. `tabs` lists this thread's tabs. `profiles` lists logins for `preview_open`. Read any listed tab. Act only on your tab, or an unclaimed tab with no human in control.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `stop_recording`

```elixir
@spec stop_recording(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Stop recording the chosen tab. Returns a local path to the recording file (max 50 MiB).

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

# `wait_for`

```elixir
@spec wait_for(T3.Client.t(), map()) :: {:ok, map()} | {:error, T3.Error.t()}
```

Wait until all given locator, selector, text, and URL conditions match in the chosen tab.

Requires a compatible T3 agent/thread context and runtime; not generally exposed to outside OAuth clients.

---

*Consult [api-reference.md](api-reference.md) for complete listing*