# Tapir documentation

> Tapir snapshots the Semantics tree of a running Flutter app and drives it by stable refs, from the CLI or an AI agent.

# Getting Started

Everything you need to add `tapir` to your project, capture your first
snapshot, and drive real user gestures from an AI agent or CLI session.

- [Pick your path](#pick-your-path)
- [What is tapir?](#what-is-tapir)
- [What problem does it solve?](#what-problem-does-it-solve)
- [When to use it](#when-to-use-it)
- [Requirements](#requirements)
- [High-level workflow](#high-level-workflow)
- [Related Documentation](#related-documentation)

## Pick your path

- [**Installation**](https://anilcancakir.com/tapir/docs/getting-started/installation.md): Wire TapirPlugin into a Flutter app and connect
  the MCP tools to your AI client.
- [**Quickstart**](https://anilcancakir.com/tapir/docs/getting-started/quickstart.md): 3-step walkthrough from zero to driving the example
  app with snap, tap, and screenshot.
- [**MCP setup**](https://anilcancakir.com/tapir/docs/mcp/setup.md): Register the tapir MCP tools in Claude Code, Cursor,
  Windsurf, or any MCP-compliant client.
- [**Driving real apps: gotchas for agents**](https://anilcancakir.com/tapir/docs/getting-started/driving-real-apps-gotchas.md): the
  recurring traps in real-app E2E sessions (stale refs, nested text fields,
  cumulative exceptions, stuck overlays) and the workaround each one has built in.

## What is tapir?

`tapir` is a Flutter E2E driver that gives an AI agent (or a CLI session)
eyes and hands over a running Flutter app. It works by registering a set of VM
Service extensions under the `ext.tapir.*` namespace during debug builds, then
exposing those extensions as MCP tools and CLI commands. The agent snaps a
Semantics YAML to identify widget references, then drives gestures, text input,
scrolling, and navigation against those references without any test instrumentation
in the production widget tree.

What sets it apart from `flutter_test`-based integration tests is that it operates
against the live running app, not a test-hosted widget. The agent sees the same UI
the user sees: real platform chrome, real routing, real auth state. This makes it
suitable for exploratory workflows where the agent does not know the widget tree in
advance and needs to discover it interactively.

## What problem does it solve?

Writing Flutter integration tests requires knowing the widget tree structure upfront,
hard-coding `find.byKey` / `find.byType` locators, and re-running the full suite
every time the UI changes. That works well for regression coverage but poorly for
exploratory agent-driven automation, where the agent needs to navigate an unfamiliar
UI, read its current state, and take adaptive actions.

`tapir` solves this by exporting the Semantics tree as a YAML snapshot
with stable `e<N>` (snapshot-frozen) and re-resolvable `q<N>` (minted by `tapir:find` or `tapir:observe`) ref
tokens. The agent reads the snapshot, locates the target element by semantic role or
label, and passes the ref token to an action extension. No test harness setup, no
build step, no `flutter drive` orchestration needed.

## When to use it

- **AI agent walkthroughs**: give Claude Code, Cursor, or Windsurf hands-on control
  of your Flutter app so it can inspect, fill forms, and verify flows during
  development or review.
- **Manual E2E scripting**: drive gestures and input from a terminal session without
  writing widget tests, useful for ad-hoc QA against a staging build.
- **Screenshot pipelines**: capture consistent screenshots of specific app states for
  documentation, design review, or visual regression baselines.
- **CI smoke checks**: run a small set of tapir commands in CI to confirm critical
  paths render without crash, complementing (not replacing) widget unit tests.

## Requirements

| Dependency | Minimum Version | Notes |
|:-----------|:----------------|:------|
| Dart       | `^3.13.0`       | The floor `material_ui` needs; Flutter 3.50 deprecates `package:flutter/material.dart` in its favour. |
| Flutter    | `>= 3.47.0`     | The Semantics APIs and `RepaintBoundary` render-tree walk used internally. |
| dowel | `^0.0.21` | Provides the MCP server, CLI framework, and `registerExtensionIdempotent`. |

`tapir` requires Flutter. It cannot run on a pure-Dart environment because
it synthesises pointer events against a live widget tree and walks the Semantics tree
at runtime. The `dowel` CLI is the recommended host for the MCP server
and all tapir CLI commands; install it before adding `tapir`.

## High-level workflow

The typical agent session follows three phases:

```
1. Capture snapshot   --  tapir_snap / tapir:snap
   Walks the Semantics tree and emits a YAML file with every
   visible widget, its ref token, role, label, bounds, and
   any enricher-contributed metadata (a `wind:` block, `magicRoute`, ...).

2. Identify a ref     --  read the YAML / tapir_find
   The agent scans the snapshot for the target widget by label
   or role, reads its ref token (e1, q3, ...).
   tapir_find re-resolves a token without a full re-snap.

3. Drive an action    --  tapir_tap / tapir_type / tapir_scroll / ...
   The agent passes the ref token to an action tool. The extension
   looks up the live element, checks the actionability gate,
   synthesises the event,
   and returns the result or a structured error.
```

After an action the agent re-snaps to observe the updated UI and continues the loop.
Screenshot requests can be inserted at any point to capture a PNG of the current
viewport.

## Related Documentation

- [Installation](https://anilcancakir.com/tapir/docs/getting-started/installation.md): new here? Start with adding the package and wiring `TapirPlugin.install()`.
- [Quickstart](https://anilcancakir.com/tapir/docs/getting-started/quickstart.md): already installed? Run a first snap, tap and screenshot.
- [Commands](https://anilcancakir.com/tapir/docs/commands/index.md): every `tapir:*` command grouped by intent.
- [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md): how tapir decides whether a widget is safe to act on.

---

# Installation

Add `tapir` to a Flutter app, wire `TapirPlugin.install()` behind a `!kReleaseMode` guard, and optionally register the MCP server for your AI client.

The recommended path is one command, `dart run tapir tapir:install`, which patches `lib/main.dart` and registers the plugin with dowel; the manual route is described step by step below.

- [Quick Reference](#quick-reference)
- [Requirements](#requirements)
- [Add the package](#add-the-package)
- [Wire TapirPlugin](#wire-tapirplugin)
- [Optional integrations](#optional-integrations)
- [Register with dowel (automatic)](#register-with-dowel)
- [Wire MCP tools](#wire-mcp-tools)
- [Verify installation](#verify-installation)
- [Gotchas](#gotchas)
- [Related Documentation](#related-documentation)

## Quick Reference

| Step | Command | Result |
|:-----|:--------|:-------|
| 1. Add the packages | `dart pub add dowel` and `flutter pub add tapir` | Both are direct dependencies. |
| 2. Wire the app | `dart run tapir tapir:install` | `lib/main.dart` gains a `!kReleaseMode` block with `TapirPlugin.install()`; dowel registers the plugin. |
| 3. Register the MCP server (optional) | `dart run tapir mcp:install` | A `.mcp.json` entry at the project root. |
| 4. Start the app | `dart run tapir start --device=chrome` | dowel records the session that every `tapir:*` command dials. |
| 5. Take a snapshot | `dart run tapir tapir:snap` | A YAML tree with `[ref=eN]` tokens. |

## Requirements

`tapir` is a Flutter package. It requires a Flutter app target for the
VM Service extensions to register against. Pure-Dart environments are not supported.

| Dependency | Minimum | Recommended |
|:-----------|:--------|:------------|
| Dart       | `^3.13.0` | latest stable |
| Flutter    | `>= 3.47.0` | latest stable |
| dowel | `^0.0.21` | latest |

Install `dowel` first if it is not already in your project. It provides
the MCP server, the CLI framework, and the `registerExtensionIdempotent` helper that
tapir uses internally for hot-restart safety.

```bash
dart pub add dowel
```

## Add the package

Add `tapir` using the Flutter CLI:

```bash
flutter pub add tapir
```

Alternatively, add it manually to `pubspec.yaml`:

```yaml
dependencies:
  tapir: ^0.0.24
```

Then fetch dependencies:

```bash
flutter pub get
```

## Wire TapirPlugin

The recommended path is the CLI installer. From your project root, run:

```bash
dart run tapir tapir:install
```

This patches your `lib/main.dart` automatically: it adds the `kReleaseMode` import, wraps `TapirPlugin.install()` in a `!kReleaseMode` guard, injects `WidgetsFlutterBinding.ensureInitialized()` when missing, and detects Magic-stack apps so `MagicTapirIntegration.install()` lands AFTER `Magic.init(...)` when the resolved `magic_devtools` ships `tapir.dart` (an older `magic_devtools` gets a warning and no Magic lines instead). The command is idempotent; re-running it is safe. See [`tapir:install`](https://anilcancakir.com/tapir/docs/commands/tapir-install.md) for the full sub-step list and the anchor strings the injector searches for.

### Manual wiring (when you'd rather edit `main.dart` yourself)

Skip the CLI installer and edit `lib/main.dart` directly. Call `TapirPlugin.install()` inside a `!kReleaseMode` guard, after `WidgetsFlutterBinding.ensureInitialized()` and before `runApp()`. The guard is mandatory: release builds tree-shake the entire subsystem, so tapir never ships to end users. It is `!kReleaseMode` rather than `kDebugMode` so a profile build carries tapir too, which is the build `tapir:perf_run` measures; an app wired under `kDebugMode` keeps working in debug, and `tapir:install` leaves that block alone, but it registers no `ext.tapir.*` in a profile build until the guard is changed by hand.

```dart
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:tapir/tapir.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  if (!kReleaseMode) {
    TapirPlugin.install();
  }

  runApp(const MyApp());
}
```

`TapirPlugin.install()` is idempotent: calling it more than once (for example during hot restart) is safe and registers each VM Service extension only once.

## Optional integrations

Call additional `install()` methods inside the same `!kReleaseMode` block to enrich
snapshots with framework-specific metadata. Both integrations are independent; install
either, both, or neither depending on your stack.

| Integration | Package | Enrichment |
|:------------|:--------|:-----------|
| `MagicTapirIntegration.install()` | `magic_devtools` (a release built on tapir) | MagicForm field values, validation state, named route per node. |
| `Wind.installDebugResolver()` (in `package:wind_kit/wind_kit.dart`) | `wind_kit` (any release that ships `Wind.installDebugResolver()`) | Wind state surfaces through the neutral `WindDebugRegistry` bridge; tapir emits the six core fields (breakpoint, brightness, platform, states, bgColor, textColor) automatically without enricher registration. |

```dart
import 'package:magic_devtools/tapir.dart'; // magic_devtools only
import 'package:wind_kit/wind_kit.dart'; // wind_kit only
// ...
if (!kReleaseMode) {
  TapirPlugin.install();
  MagicTapirIntegration.install(); // magic-stack only (from magic_devtools)
  Wind.installDebugResolver();    // wind UI only (from wind_kit)
}
```

`package:magic_devtools/tapir.dart` exists only in a `magic_devtools` release built on
tapir; an older release has no tapir integration yet, so upgrade `magic_devtools` first.
`tapir:install` writes the Magic lines only when the resolved package ships `tapir.dart`
and otherwise warns.

See [Magic integration](https://anilcancakir.com/tapir/docs/plugins/magic-integration.md) and
[Wind integration](https://anilcancakir.com/tapir/docs/plugins/wind-integration.md) for the full enricher field reference.

## Register with dowel (automatic)

`tapir:install` already handles this for you as Phase 2 of its run. Right after the `lib/main.dart` patch lands, it chains `dart run tapir install` (scaffolds `bin/dispatcher.dart` + `./bin/dowel` fastcli, ~50ms warm AOT) followed by `dart run tapir plugin:install tapir` (registers `TapirDowelProvider` and auto-purges the AOT bundle cache). Both sub-process calls skip when their idempotency markers already exist (`bin/dispatcher.dart` and `.dowel/installed/tapir.json` respectively), so re-running `tapir:install` is a fast no-op.

If the chained calls fail (no `dart` on PATH, partial pub-cache, restricted sandbox), `tapir:install` falls through with a warning and exits 0; the `lib/main.dart` patch already landed, so `dart run tapir <cmd>` still works. You can finish the setup manually:

```bash
dart run tapir install                # only if Phase 2 was skipped
dart run tapir plugin:install tapir   # idempotent; refreshes barrels on re-run
```

After Phase 2 lands, `./bin/dowel list` shows every `tapir:*` command and `./bin/dowel mcp:serve` exposes every `tapir_*` tool.

The optional `mcp:install` step in the next section writes the plugin-aware `.mcp.json` payload by default. When fastcli (`./bin/dowel`) is present, the entry uses `./bin/dowel mcp:serve`; when it is absent, the wrapper's `--invocation=tapir` pass-through causes `mcp:install` to write `dart run tapir mcp:serve` instead. Either way, no manual `.mcp.json` edit is needed.

## Wire MCP tools

With dowel registered, expose the tapir MCP tools to your AI client by writing the `.mcp.json` entry:

```bash
dart run tapir mcp:install
```

This writes (or updates) a `.mcp.json` file at the project root. Claude Code,
Cursor, and Windsurf all pick up `.mcp.json` automatically from the working directory.
The payload depends on your scaffold state:

- **fastcli present** (`./bin/dowel` exists, POSIX): writes `./bin/dowel mcp:serve`, the fastest startup (~50ms warm AOT).
- **fastcli absent**: the wrapper injects `--invocation=tapir` automatically, so the entry writes `dart run tapir mcp:serve` (~3s startup, no scaffold required).

See [Fallback invocations](https://anilcancakir.com/tapir/docs/mcp/setup.md#fallback-invocations) for the full precedence table.

## Verify installation

Start your Flutter app through dowel, so the session (the VM Service URI every `tapir:*` command dials) is recorded for this project:

```bash
dart run tapir start --device=chrome
```

Then capture the first Semantics snapshot:

```bash
dart run tapir tapir:snap
```

A successful snap prints a YAML tree of lines such as `- button "Sign in" [ref=e2]`.
Each interactive node carries a `[ref=eN]` token (`e1`, `e2`, ...) that you pass to action
commands. If the command exits with an error, confirm that `TapirPlugin.install()` is
reachable in your `main.dart` and that the app runs in a debug or profile build (a
release build tree-shakes tapir, so no `ext.tapir.*` extension registers). Stop the app with
`dart run tapir stop` when you are done.

## Gotchas

| Mistake | Fix |
|:--------|:----|
| `TapirPlugin.install()` sits outside a `!kReleaseMode` guard. | Wrap it: `if (!kReleaseMode) { TapirPlugin.install(); }`. A `kDebugMode` guard works in debug but registers no `ext.tapir.*` in a profile build. |
| `MagicTapirIntegration.install()` runs before `Magic.init(...)`. | Call it after `Magic.init(...)`: it queries `Magic.find<X>()`, which only resolves once the container is ready. `tapir:install` places it correctly. |
| The app was started with a plain `flutter run`, and `tapir:snap` finds no app. | Start it with `dart run tapir start`, which records the session the `tapir:*` commands dial. |
| `./bin/dowel` is missing after `tapir:install`. | Phase 2 was skipped with a warning. Run `dart run tapir install` and `dart run tapir plugin:install tapir`; `dart run tapir <cmd>` works meanwhile. |
| The snapshot has no `wind:` block. | Call `Wind.installDebugResolver()` inside the same `!kReleaseMode` block (`tapir:install` does not add it), then snap with `dart run tapir tapir:snap --includeEnrichers`: enrichers are off by default, so a plain snapshot never carries the block. |
| `.mcp.json` points at the wrong launcher. | Re-run `dart run tapir mcp:install` rather than editing the file; it picks `./bin/dowel mcp:serve` or `dart run tapir mcp:serve` from the scaffold state. |

## Related Documentation

- [Quickstart](https://anilcancakir.com/tapir/docs/getting-started/quickstart.md): a first snap, tap and screenshot against the bundled example app.
- [tapir:install](https://anilcancakir.com/tapir/docs/commands/tapir-install.md): the sub-steps and anchor strings behind the installer.
- [MCP setup](https://anilcancakir.com/tapir/docs/mcp/setup.md): wire the server into an AI client and the fallback invocations.
- [Magic integration](https://anilcancakir.com/tapir/docs/plugins/magic-integration.md) and [Wind integration](https://anilcancakir.com/tapir/docs/plugins/wind-integration.md): the enricher fields each integration adds.

---

# Quickstart

A three-step walkthrough from zero to driving the bundled `example/` Flutter app with a snapshot, a tap and a screenshot through the tapir CLI.

Prerequisites: Flutter 3.47 or newer (Dart 3.13, the package and example floor) and a clone of the repository. The `example/` app already calls `TapirPlugin.install()` inside `!kReleaseMode` and resolves `tapir` from the parent directory. To drive your own app instead, follow [Installation](https://anilcancakir.com/tapir/docs/getting-started/installation.md) first.

- [1. Start the example app and capture a snapshot](#1-start-the-example-app)
- [2. Tap a widget using its ref token](#2-tap-a-widget)
- [3. Capture a screenshot](#3-capture-a-screenshot)
- [Gotchas](#gotchas)
- [Related Documentation](#related-documentation)

---

## 1. Start the example app and capture a snapshot

Start the app through dowel, so the session (the VM Service URI every `tapir:*` command dials) is recorded. The `--cdp-port` makes web screenshots reliable in step 3; on a native target (`--device=macos`, for example) leave it out:

```bash
cd example
flutter pub get
dart run tapir start --device=chrome --cdp-port=9333
```

Once the app is up, run `tapir:snap` in the same directory to walk the live Semantics tree. The example has many widgets, so narrow the walk with `--grep` to the counter button:

```bash
dart run tapir tapir:snap --grep=Counter
```

The command connects to the running app via the VM Service and prints the snapshot to stdout. An illustrative output (ancestor lines trimmed):

```yaml
- button "Counter: 0" [ref=e1]
```

Each interactive node carries a `[ref=eN]` token (here `e1`). Tokens are tied to the snapshot that issued them: a node that appears again in a later `tapir:snap` may keep its token, a node that was rebuilt gets a new one, so read the refs from the latest snapshot. They are what you pass to action commands in the next step.

---

## 2. Tap a widget using its ref token

Pass the ref token from the snapshot to `tapir:tap`:

```bash
dart run tapir tapir:tap --ref=e1
```

The extension looks up `e1` in the snapshot registry, runs the actionability gate (see [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md): the widget must be enabled, have a non-zero rect, be on-viewport, stable, and receive pointer events), then synthesises a pointer-down and pointer-up pair at the widget's centre. The app responds as if a real user tapped the button.

A successful tap prints one line:

```
✓ Tapped e1
```

When nothing observable changed, the line reads `Tapped e1 (no observable change)`; read it before concluding the tap worked. Add `--json` for the full envelope, which carries the `effect` block.

If the widget fails the actionability gate, the command exits with an error message:

```
Widget ref=e1 is not actionable: not enabled
```

Re-snap after a tap to confirm the UI updated. The refreshed snapshot shows the button as `Counter: 1`; read its ref again, because it may or may not match the earlier one:

```bash
dart run tapir tapir:snap --grep=Counter
```

---

## 3. Capture a screenshot

Capture an image of the current viewport to verify the app state visually or to save a baseline:

```bash
dart run tapir tapir:screenshot --output=counter_after_tap.png
```

On web with `--cdp-port` the command captures through Chrome DevTools Protocol; on a native target it asks the app's `RepaintBoundary` for a frame. The file lands relative to your current working directory, and the format follows the `--output` extension.

Expected output:

```
✓ Wrote 48213 bytes (47.1 KB, png) to counter_after_tap.png
```

Open the file to confirm the button reads `Counter: 1`. You now have the full snap, tap and screenshot loop working end to end. Stop the app with `dart run tapir stop`.

---

## Gotchas

| Mistake | Fix |
|:--------|:----|
| Running `flutter run` by hand, then `tapir:snap` finds no app. | Start the app with `dart run tapir start`, which records the session the `tapir:*` commands dial. |
| Tapping an `eN` ref from an earlier snapshot after the screen changed. | Re-snap and use the ref from that snapshot, or mint a `qN` handle with `tapir:find` that survives rebuilds. |
| The web screenshot hangs or returns an error. | Start with `--cdp-port=<port>` so the CLI captures through Chrome DevTools Protocol. |
| The tap printed `no observable change`. | Nothing changed in the target's own subtree or the route; that does not prove the handler did not fire. Re-snap and check the intended result before retrying. |

## Related Documentation

- [Commands](https://anilcancakir.com/tapir/docs/commands/index.md): every `tapir:*` command with its flags.
- [MCP setup](https://anilcancakir.com/tapir/docs/mcp/setup.md): let Claude Code or Cursor call the tapir tools directly during a conversation.
- [Magic integration](https://anilcancakir.com/tapir/docs/plugins/magic-integration.md) and [Wind integration](https://anilcancakir.com/tapir/docs/plugins/wind-integration.md): enrich snapshots with framework-specific metadata (`MagicTapirIntegration.install()`, `Wind.installDebugResolver()`).
- [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md): how tapir decides whether a widget is safe to interact with.

---

# Driving real apps: gotchas for agents

The recurring traps of a long real-app E2E session, each with the workaround `tapir` has built in.

Every agent re-discovers these the hard way. Read the page once before driving a non-trivial
app; it will save you a dozen dead-end round trips.

- [Quick Reference](#quick-reference)
- [1. Refs go stale on rebuild](#1-refs-go-stale-on-rebuild)
- [2. Text fields may snapshot nested](#2-text-fields-may-snapshot-nested)
- [3. tapir:console captures debugPrint in-package now](#3-tapirconsole)
- [4. tapir:exceptions is cumulative](#4-tapirexceptions-is-cumulative)
- [5. restart preserves the CDP port](#5-restart-preserves-the-cdp-port)
- [6. Overlays get stuck](#6-overlays-get-stuck)
- [7. A green tick is dispatch, not effect](#7-a-green-tick-is-dispatch-not-effect)
- [8. A hidden desktop app](#8-a-hidden-desktop-app)
- [Related Documentation](#related-documentation)

## Quick Reference

| Trap | Use |
|:-----|:----|
| An `e<N>` ref fails after a rebuild or navigation. | Re-snap with `tapir:snap`, or mint a `q<N>` handle with `tapir:find` / `tapir:observe`. |
| A text field snapshots as two nested `textbox` nodes. | Target the node marked `typeable: true`, or use `tapir:fill`. |
| `tapir:console` misses `debugPrint` output. | Nothing to do: `TapirPlugin.install()` captures it in-package. |
| `tapir:exceptions` keeps reporting an old error. | Pass `--since=<iso8601>` recorded before the action. |
| A web restart loses the CDP port. | Nothing to do: `restart` reuses the recorded `cdpPort`. |
| A dialog, sheet or menu blocks the next screen. | Run `tapir:reset_overlays`. |
| A green tick with no visible result. | Read the `effect` block on the response. |
| A hidden desktop app reports no change. | Nothing by default; read `framesForced` and `warnings` on the response. |

---

## 1. Refs go stale on rebuild

`e<N>` refs from `tapir:snap` freeze the widget at snapshot time. A navigation,
a modal open/close, a `setState`, or any significant rebuild invalidates them:
the next action on a stale `e<N>` fails with a not-found or stale envelope.

**Workaround:**

- Re-snap (`tapir:snap`) after any action that changes the screen, and use the
  fresh refs.
- For a target that survives re-renders (a stable `Text`, accessibility label,
  or `Key`), prefer `tapir:find` / `tapir:observe`, which mint a re-resolvable
  `q<N>` handle that re-walks the live tree on every action call. `q<N>`
  handles survive rebuild, route push, and snapshot disposal as long as the
  predicates still match.
- Pointer verbs (`tapir:tap`, `tapir:hover`, `tapir:drag`, ...) now dispatch at the
  element's LIVE rect, not the cached snapshot rect, so a target that merely
  shifted slots (same `Element`/`RenderObject`) is still hit correctly. The
  false-success class (gate passes, pointer lands on the stale position,
  `onTap` never fires) is gone for slot shifts.
- An `e<N>` ref whose widget was rebuilt is relocated by its label when the live
  tree still has the same number of nodes with that label on the same route,
  and the response names it under `reresolved`. When the count differs, or
  you have navigated to another route, the ref still fails as
  `defunct (element no longer mounted)`; re-snap.

---

## 2. Text fields may snapshot nested

A wind `WInput` (and any `TextField` wrapped in `Semantics(textField: true)`)
historically snapshotted as TWO nested `textbox` nodes, because `RenderEditable`
unconditionally owns its own `textField` Semantics node and `MergeSemantics`
cannot absorb it. Agents naturally targeted the inner leaf, where `tapir:type`
threw a `-32000`.

**Workaround:**

- `tapir:snap` now collapses the nested pair (by render-object containment, never
  label/value equality, so two sibling fields sharing a label stay distinct) and
  emits a single ref for the outer node, marked `typeable: true`. Target the
  node carrying `typeable: true`.
- Better: use `tapir:fill --ref=<ref> --text=<value>`, which focuses, clears,
  types, and settles in one call (and retries once on a stale handle). It
  resolves the right editable for you and composes the gated focus/clear/type
  handlers, so you do not re-build the focus + clear + type + settle dance.

---

## 3. tapir:console captures debugPrint in-package now

`tapir:console` historically surfaced full structured logs only when
`crumbs` was installed and wired.

**Workaround:**

- `TapirPlugin.install()` now chains a `debugPrint` override that records every
  `debugPrint(...)` / `print(...)` call into a bounded in-package ring buffer,
  so those entries appear in `tapir:console` even without crumbs.
- When crumbs IS installed it enriches the output with `Logger.root.onRecord`
  entries and its other watchers. Direct `dart:developer log()` calls that
  bypass `debugPrint` still require the crumbs `LogWatcher`.

---

## 4. tapir:exceptions is cumulative

`tapir:exceptions` returns the full exception history by default, so a single
pre-existing error keeps re-appearing after every action and produces false
positives when you are checking whether YOUR action raised something new.

**Workaround:**

- Record the current time before the action, then pass
  `tapir:exceptions --since=<iso8601>` afterwards to get only exceptions raised
  strictly after that timestamp. Unparseable `since` values are treated as
  absent (full list).

---

## 5. restart preserves the CDP port

When dowel was started with `--cdp-port` (the web path that backs
`tapir:screenshot` CDP fallback, `tapir:resize`, `tapir:device`), a naive restart
used to drop the port, breaking those CDP-routed tools until you restarted with
the flag again.

**Workaround:**

- `dowel restart` (and bare `start`) now re-read the prior `cdpPort` from
  this project's session state (`state.json` under `~/.dowel/sessions/`) and reuse it as the default, so CDP stays wired across
  restarts. An explicit `--cdp-port` still wins.

---

## 6. Overlays get stuck

A left-over dialog, bottom sheet, dropdown menu, or barrier modal blocks the
next screen from rendering, and a single `tapir:modal` (dismiss-modals) does not
clear overlays that are not `PopupRoute`s.

**Workaround:**

- Use `tapir:reset_overlays`, which runs three idempotent layers: dismiss every
  `PopupRoute`, press `Escape` (for shortcut-driven overlays), then tap a
  Cancel/Dismiss/Close/OK/Done affordance as a last resort. Safe to call
  speculatively between flows; the response (`popped`, `escaped`,
  `dismissTapped`) tells you which layer cleared the screen.

---

## 7. A green tick is dispatch, not effect

`✓ Tapped e7` and `✓ Filled e5` say the event left tapir, not that the widget
took it. A number field can swallow a fill and keep nothing; a button the gate
accepted can have an `onTap` that never fires.

**Workaround:**

- Read the `effect` block on the response: `effect.changed` for `tap` and
  `scroll`, `effect.verified` and `effect.value` for `type`, `fill` and `clear`.
- In summary mode `tapir:fill` and `tapir:type` exit `1` when `effect.verified` is
  false, and `tapir:navigate`, `tapir:navigate_back` and `tapir:scroll` say so when
  nothing happened. With `--json` or `--includeSnapshot` you get the raw
  envelope and read the field yourself.

---

## 8. A hidden desktop app

A hidden, minimised or occluded window moves the app to `AppLifecycleState.hidden`
and stops frame production, so a tap used to report "no observable change", a
snapshot went stale and a screenshot returned the last cached frame. This is
not specific to a browser tab.

**Workaround:**

- Nothing, by default: tapir delivers `resumed` and forces a frame at the start of
  each verb, and a response that did so carries `framesForced: true`. Verified on
  macOS with the window hidden. The app's own lifecycle observers see `resumed`.
- If a response still carries a `warnings` block, tapir could not force frames
  (`--dart-define=TAPIR_FORCE_FRAMES=false`, a `detached` app, a wake that
  produced no frame, or any hidden web tab). Bring the
  window to front and retry.
- An asleep macOS display can still starve frames; `caffeinate -u -t 3` wakes it
  (unverified for tapir). See [Frame production](https://anilcancakir.com/tapir/docs/reference/frame-production.md).

---

## Related Documentation

- [tapir:fill](https://anilcancakir.com/tapir/docs/commands/tapir-fill.md) and [tapir:reset_overlays](https://anilcancakir.com/tapir/docs/commands/tapir-reset-overlays.md): the two built-in workarounds for nested text fields and stuck overlays.
- [tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md): the `effect` block and `--until`.
- [tapir:exceptions](https://anilcancakir.com/tapir/docs/commands/index.md#console-and-exceptions) and [tapir:find](https://anilcancakir.com/tapir/docs/commands/tapir-find.md): the `--since` delta and the re-resolvable `q<N>` handle.
- [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md): why an action is refused and with which reason.
- [Reference: Frame production](https://anilcancakir.com/tapir/docs/reference/frame-production.md): the hidden-window and backgrounded-tab failure mode.

---

# Commands

Every `tapir` command, grouped by intent, with its boot mode and the VM Service extension behind it.

Every command is invoked as `dart run tapir <name>` (Flutter-free wrapper at `bin/tapir.dart`), or via the consumer-side dowel dispatcher (`./bin/dowel <name>` / `dart run dowel <name>`) once the project has run `tapir:install`. Commands are auto-discovered through `TapirDowelProvider`; nothing wires by hand.

Need a quick reminder of what a command does without leaving the terminal? Run `dart run dowel list` for the full registry grouped by namespace, or `dart run dowel help <name>` for the per-command flag surface. This page exists for the deeper view: the boot mode, the backing VM Service extension, and the grouping rationale.

- [How to read this page](#how-to-read-this-page)
- [Snapshot and screenshot](#snapshot-and-screenshot)
- [Gestures](#gestures)
- [Inputs](#inputs)
- [Navigation](#navigation)
- [Find](#find)
- [Diagnostics](#diagnostics)
- [Install](#install)
- [CDP](#cdp)
- [Click variants](#click-variants)
- [Focus and blur](#focus-and-blur)
- [Console and exceptions](#console-and-exceptions)
- [Observe](#observe)
- [Hot reload and snap](#hot-reload-and-snap)
- [Batch](#batch)
- [Performance](#performance)
- [Boot mode and deep-dives](#boot-mode-and-deep-dives)
- [Related Documentation](#related-documentation)

## How to read this page

Each group section ships a single table with four columns:

- **Command** is the canonical name you type after `dart run tapir` (or via the dowel dispatcher).
- **Description** is a one-line summary of the command; `dart run dowel list` prints each command's own wording, which differs for a few.
- **Boot Mode** is the `CommandBoot` value the dispatcher reads before invoking `handle()`. `none` means pure CLI: no VM Service connection. `connected` means the command dials the VM Service URI recorded for this project's dowel session and fails fast if no app is running.
- **VM Extension** is the `ext.tapir.*` method the command calls over the VM Service. `none` for commands that operate purely on the consumer filesystem.

Deep-dive pages exist for the commands whose flag surface, return shape, or composition rules outgrow a single table row; the tables below link them. The other commands share this index page; reach for `dart run dowel help <name>` for their full flag surface.

## Snapshot and screenshot

The two foundational read commands. `tapir:snap` walks the Semantics tree and emits YAML with `[ref=eN]` tokens that every subsequent action command consumes. `tapir:screenshot` captures a frame of the running app and writes it to a file.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| [`tapir:snap`](https://anilcancakir.com/tapir/docs/commands/tapir-snap.md) | Capture Semantics tree YAML of the running Flutter app with [ref=eN] tokens. | connected | ext.tapir.snap |
| [`tapir:screenshot`](https://anilcancakir.com/tapir/docs/commands/tapir-screenshot.md) | Capture a screenshot of the running Flutter app to a file. | connected | ext.tapir.screenshot |

## Gestures

Pointer-driven actions that synthesise touch, mouse, or pen events at a widget located by ref token. `tapir:tap`, `tapir:hover` and `tapir:drag` route through the actionability gate (see [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md)) before the event leaves the VM. `tapir:scroll` skips the gate on purpose: it acts on the parent scrollable, so it can bring an off-viewport target into view (see [Intentional gate skips](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md#intentional-gate-skips)).

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| [`tapir:tap`](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md) | Tap a widget by ref token (from prior tapir:snap). | connected | ext.tapir.tap |
| `tapir:hover` | Hover the pointer over a widget by ref token (from prior tapir:snap). | connected | ext.tapir.hover |
| `tapir:drag` | Drag from one widget to another using ref tokens from a prior tapir:snap. | connected | ext.tapir.drag |
| `tapir:scroll` | Scroll inside a scrollable widget by ref token from a prior tapir:snap. | connected | ext.tapir.scroll |

## Inputs

Keyboard-shaped actions. `tapir:type` emits a character sequence; `tapir:press_key` synthesises a single hardware-key event; `tapir:clear` empties the focused text field; `tapir:select_option` calls the `onChanged` of a `DropdownButton`; `tapir:set_checkbox` sets a checkbox, switch or radio from its Semantics checked or toggled state.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| `tapir:type` | Type text into a focused widget by ref token. | connected | ext.tapir.type |
| [`tapir:fill`](https://anilcancakir.com/tapir/docs/commands/tapir-fill.md) | Focus, clear, type, and settle a text field by ref in one call (retries once on a stale handle). | connected | ext.tapir.fill |
| `tapir:press_key` | Synthesise a hardware-key event on the currently focused widget. | connected | ext.tapir.press_key |
| `tapir:clear` | Empty the text content of the focused widget by ref. | connected | ext.tapir.clear |
| `tapir:select_option` | Select an option in a DropdownButton by ref token (calls its `onChanged`). | connected | ext.tapir.select_option |
| `tapir:set_checkbox` | Set the checked state of a checkbox, switch or radio by ref, from any library. | connected | ext.tapir.set_checkbox |
| `tapir:wait` | Wait for a text, text-gone, or expression condition in the running app. | connected | ext.tapir.wait_for |
| `tapir:wait_for_network_idle` | Wait until the running app reports zero in-flight HTTP requests for a contiguous idleMs window. | connected | ext.tapir.wait_for_network_idle |

## Navigation

Route-table manipulation against the active `Navigator`. `tapir:modal` dismisses any open modal, sheet, or dialog. `tapir:close_app` ends the session via `SystemNavigator.pop()`.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| `tapir:navigate` | Navigate the running app to a named route via the active Navigator. | connected | ext.tapir.navigate |
| `tapir:navigate_back` | Pop the topmost route off the active Navigator (mirrors browser back). | connected | ext.tapir.navigate_back |
| `tapir:get_routes` | Print the mounted Router's location (`uri`), the top page name and a title hint as JSON. | connected | ext.tapir.get_routes |
| `tapir:modal` | Dismiss all open modals, bottom sheets, and dialogs in the running app. | connected | ext.tapir.dismiss_modals |
| [`tapir:reset_overlays`](https://anilcancakir.com/tapir/docs/commands/tapir-reset-overlays.md) | Reset to a clean screen: dismiss modals + Escape + Cancel-tap fallback (idempotent). | connected | ext.tapir.reset_overlays |
| `tapir:close_app` | Gracefully close the running app via SystemNavigator.pop(). | connected | ext.tapir.close_app |

## Find

The Playwright Locator surface: mint a re-resolvable `q<N>` handle backed by text, semanticsLabel, or key predicates. Every action call against a `q<N>` handle re-walks the live tree, so the handle survives intermediate rebuilds.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| [`tapir:find`](https://anilcancakir.com/tapir/docs/commands/tapir-find.md) | Mint a re-resolvable q-handle by text / semanticsLabel / key (Playwright Locator pattern). | connected | ext.tapir.find |

## Diagnostics

Pure-CLI checks that verify the consumer wiring and the running session health. Neither command dials the VM Service.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| [`tapir:doctor`](https://anilcancakir.com/tapir/docs/commands/tapir-doctor.md) | Verify tapir plugin runtime + consumer wiring health | none | none |

## Install

The one-shot bootstrap. Patches the consumer's `lib/main.dart`, then chains `dowel install` and `plugin:install tapir` on a best-effort basis; `tapir` ships its own Flutter-free CLI entry point, so the chain only adds the faster `./bin/dowel` path. Idempotent on re-run.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| [`tapir:install`](https://anilcancakir.com/tapir/docs/commands/tapir-install.md) | Wire TapirPlugin.install() into lib/main.dart AND chain dowel install + plugin:install so ./bin/dowel surfaces every tapir:* command (idempotent on re-run; Phase 2 chain is best-effort). | none | none |

## CDP

Chrome DevTools Protocol commands that manipulate the browser viewport directly. Web target only; desktop and mobile no-op gracefully.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| `tapir:device` | Emulate a device profile (viewport + DPR + touch + user agent) via Chrome DevTools Protocol. The emulation lasts only as long as the command's CDP session, which closes on exit; only the window size stays. | none | none (CDP direct) |
| `tapir:resize` | Resize the running Flutter web app viewport via Chrome DevTools Protocol. Chrome drops the override when the command exits; `--hold` keeps it until Ctrl-C or Chrome exits. | none | none (CDP direct) |

## Click variants

Pointer gestures that go beyond the primary tap. All three route through the actionability gate.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| `tapir:dblclick` | Fire a double-click at the widget identified by a snapshot ref. | connected | ext.tapir.dblclick |
| `tapir:triple_click` | Fire three primary clicks (~100ms apart) at the widget identified by --ref. | connected | ext.tapir.triple_click |
| `tapir:right_click` | Fire a right (secondary mouse button) click at the widget identified by --ref. | connected | ext.tapir.right_click |

## Focus and blur

Keyboard-focus shaping. `tapir:focus` requests focus on a ref; `tapir:blur` releases the currently focused widget.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| `tapir:focus` | Request keyboard focus on the widget identified by --ref. | connected | ext.tapir.focus |
| `tapir:blur` | Remove keyboard focus from the currently-focused widget. | connected | ext.tapir.blur |

## Console and exceptions

Diagnostics readers backed by tapir's own in-package capture plus an optional crumbs augmentation.

`tapir:console` reads from tapir's in-package `debugPrint` ring buffer (populated by `installLogCapture()`,
wired by `TapirPlugin.install()`). This buffer captures every call that routes through the `debugPrint` global
callback (`debugPrint(...)`, `print(...)`, and any Flutter framework path that calls `debugPrint`). It does NOT
capture direct `dart:developer` `log()` calls that bypass `debugPrint`; those require the crumbs
`LogWatcher`. When crumbs is wired the two sources are merged and deduped; crumbs also adds `package:logging`
(`Logger.root.onRecord`) and any other watcher it ships.

`tapir:exceptions` is similar: tapir's own `FlutterError.onError` capture (non-fatal errors including overflow)
is always present; crumbs augments when wired.

The `--since=<iso8601>` flag on `tapir:exceptions` (and the matching `since` param on `tapir_exceptions` MCP)
lets agents compute true before/after deltas: record the time before an action, then call
`tapir:exceptions --since=<time>` afterwards to see only exceptions raised by that action.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| `tapir:console` | Read recent log entries (in-package debugPrint capture; augmented by crumbs when wired). | connected | ext.tapir.console |
| `tapir:exceptions [--limit=<n>] [--since=<iso8601>]` | Read recent exception entries (in-package FlutterError capture + crumbs when wired). Optionally filter to entries strictly after `--since`. | connected | ext.tapir.exceptions |

## Observe

The Stagehand observe-once-act-many surface. Returns a structured candidate list of every interactive widget on screen; the agent decides which refs to act on. No server-side LLM.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| [`tapir:observe`](https://anilcancakir.com/tapir/docs/commands/tapir-observe.md) | Return a structured candidate list of every interactive widget on screen (Stagehand observe-once-act-many; no server-side LLM). | connected | ext.tapir.observe |

## Hot reload and snap

The single-round-trip composite that hot-reloads the running app and then captures snapshot, screenshot, and recent exceptions in one shot. Dispatched via the `dowel:` substrate routing prefix to avoid a same-isolate deadlock. The reload itself is a keystroke, not a VM Service `reloadSources` call: the command writes `r` to the stdin FIFO recorded in the session state and waits for the "Reloaded N libraries" line in the `flutter run` log. A session started by `dart run tapir start` has that FIFO; one started by plain `flutter run` does not, and the command reports it as missing.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| `tapir:hot_reload_and_snap` | Hot reload the running app, then capture snapshot + screenshot + recent exceptions in a single round-trip. | connected | `r` written to the `flutter run` stdin FIFO, then `ext.tapir.snap`, `ext.tapir.screenshot`, `ext.tapir.exceptions` |

## Batch

One call, several verbs. `tapir:run` takes each step as a verb line, runs them in order on the one VM connection, and prints a summary line per step plus the last step's output. Steps may be any connected-boot verb except `tapir:run` itself.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| [`tapir:run`](https://anilcancakir.com/tapir/docs/commands/tapir-run.md) | Run several tapir verbs in one call, e.g. tapir:run "tap --ref=e5" "snap --grep Counter". | connected | each step's own extension |

## Performance

One measurement session and its drill-down. `tapir:perf_begin` opens it (`--mode=attribution` profiles builds, `--mode=timing` touches no flag), you drive one interaction, `tapir:perf_end` closes it with a bounded report of ranked insights, and `tapir:perf_insight` returns the rows behind one of them. `tapir:perf_run` repeats a scenario from a clean start and writes the medians to a file, `tapir:perf_compare` judges one such file against another, and `tapir:perf_trace` writes a session's timeline for Perfetto. `tapir:perf_campaign` runs a whole campaign of scenarios, each from a cold start.

| Command | Description | Boot Mode | VM Extension |
|---------|-------------|-----------|--------------|
| [`tapir:perf_begin`](https://anilcancakir.com/tapir/docs/commands/tapir-perf-begin.md) | Open a performance measurement session: zero the frame, wind and magic counters and, in attribution mode, switch on build profiling. | connected | ext.tapir.perf_begin |
| [`tapir:perf_end`](https://anilcancakir.com/tapir/docs/commands/tapir-perf-end.md) | Close the performance measurement session and report frames, ranked blocks, counters and insights. | connected | ext.tapir.perf_end |
| [`tapir:perf_insight`](https://anilcancakir.com/tapir/docs/commands/tapir-perf-insight.md) | Drill into one insight of the last perf_end report: title, summary, the rows behind it, estimated savings and the next step. | connected | ext.tapir.perf_insight |
| [`tapir:perf_run`](https://anilcancakir.com/tapir/docs/commands/tapir-perf-run.md) | Run a perf scenario N times from a clean start and write medians, spread, insights and every repeat to <out>/<scenario>-<label>.json. | connected | ext.tapir.perf_begin + perf_end (+ semantics_hold) |
| [`tapir:perf_compare`](https://anilcancakir.com/tapir/docs/commands/tapir-perf-compare.md) | Compare two tapir:perf_run files on counts per painted frame (and timing-mode ms) and print a verdict table. | none | none |
| [`tapir:perf_trace`](https://anilcancakir.com/tapir/docs/commands/tapir-perf-trace.md) | Write the last closed perf session as a Chrome Trace JSON file (ui.perfetto.dev, chrome://tracing) and print its path. | connected | ext.tapir.perf_trace |
| [`tapir:perf_campaign`](https://anilcancakir.com/tapir/docs/commands/tapir-perf-campaign.md) | Run every scenario of a perf campaign on one platform, each from a cold start (hooks, Android preparation, after_start, tapir:perf_run, retries), and summarise which passed. | none | none (starts the app through dowel) |

## Boot mode and deep-dives

`tapir:install`, `tapir:doctor`, `tapir:perf_compare`, `tapir:perf_campaign`, `tapir:device` and `tapir:resize` run with `CommandBoot.none` (the last two dial Chrome DevTools Protocol directly rather than the VM Service). Every other command is `CommandBoot.connected`: it dials the VM Service URI recorded for the project's dowel session and fails fast when the running app cannot be reached.

These commands earn their own pages: [tapir:install](https://anilcancakir.com/tapir/docs/commands/tapir-install.md), [tapir:run](https://anilcancakir.com/tapir/docs/commands/tapir-run.md), [tapir:snap](https://anilcancakir.com/tapir/docs/commands/tapir-snap.md), [tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md), [tapir:fill](https://anilcancakir.com/tapir/docs/commands/tapir-fill.md), [tapir:reset_overlays](https://anilcancakir.com/tapir/docs/commands/tapir-reset-overlays.md), [tapir:screenshot](https://anilcancakir.com/tapir/docs/commands/tapir-screenshot.md), [tapir:find](https://anilcancakir.com/tapir/docs/commands/tapir-find.md), [tapir:doctor](https://anilcancakir.com/tapir/docs/commands/tapir-doctor.md), [tapir:observe](https://anilcancakir.com/tapir/docs/commands/tapir-observe.md), [tapir:perf_begin](https://anilcancakir.com/tapir/docs/commands/tapir-perf-begin.md), [tapir:perf_end](https://anilcancakir.com/tapir/docs/commands/tapir-perf-end.md), [tapir:perf_insight](https://anilcancakir.com/tapir/docs/commands/tapir-perf-insight.md), [tapir:perf_run](https://anilcancakir.com/tapir/docs/commands/tapir-perf-run.md), [tapir:perf_compare](https://anilcancakir.com/tapir/docs/commands/tapir-perf-compare.md), [tapir:perf_trace](https://anilcancakir.com/tapir/docs/commands/tapir-perf-trace.md), [tapir:perf_campaign](https://anilcancakir.com/tapir/docs/commands/tapir-perf-campaign.md). Slug rule: the URL replaces the `:` separator with `-`. The other commands share this index page; reach for `dart run dowel help <name>` for their full flag surface.

## Related Documentation

- [Installation](https://anilcancakir.com/tapir/docs/getting-started/installation.md): add `tapir` to an app and wire `TapirPlugin.install()`.
- [Quickstart](https://anilcancakir.com/tapir/docs/getting-started/quickstart.md): a first snap, tap and screenshot.
- [MCP tool reference](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md): the same verbs as `tapir_*` tools, with their schemas.
- [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md): the checks every gesture command runs first.

---

# tapir:install

One-shot bootstrap that patches a Flutter app's `lib/main.dart` for `tapir` and registers the plugin with dowel.

It runs in two phases, both idempotent:

1. **Patch `lib/main.dart`**: inject the imports (including `import 'package:magic_devtools/tapir.dart';` when applicable), `WidgetsFlutterBinding.ensureInitialized()`, and a `!kReleaseMode`-gated `TapirPlugin.install()` block before `runApp(` (debug and profile builds carry tapir, so `tapir:perf_run` can measure a profile build; release tree-shakes it). Magic-stack apps additionally wire `MagicTapirIntegration.install()` after `Magic.init(` when `magic_devtools:` is present in `pubspec.yaml` and the resolved `magic_devtools` ships `lib/tapir.dart`.
2. **Chain fastcli setup**: best-effort `dart run tapir install` (scaffolds `bin/dispatcher.dart` + `./bin/dowel` AOT wrapper) + `dart run tapir plugin:install tapir` (registers `TapirDowelProvider`). Both sub-process calls are skipped when their idempotency markers already exist (`bin/dispatcher.dart` for the scaffold, `.dowel/installed/tapir.json` for the plugin record). Failures are swallowed with a warning; the Phase 1 patch always succeeds on its own, so the consumer can still drive tapir via `dart run tapir <cmd>` even when the chain skipped.

Together, the two phases mean a fresh consumer needs only:

```bash
flutter pub add tapir
dart run tapir tapir:install
```

When Phase 2 succeeded, `./bin/dowel list` surfaces every `tapir:*` command and `./bin/dowel mcp:serve` exposes every `tapir_*` MCP tool. A Phase 2 subprocess that fails does not change the exit code: the installer still exits `0`, prints a warning, and leaves the dispatcher or the plugin registration missing, so check that `bin/dispatcher.dart` exists and `./bin/dowel list` shows the `tapir:*` commands. To retry, run the commands the warning names:

```bash
dart run tapir install
dart run tapir plugin:install tapir
```

- [Synopsis](#synopsis)
- [Arguments](#arguments)
- [Returns](#returns)
- [Anchor modes](#anchor-modes)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:install
```

`tapir:install` accepts no positional arguments and no flags. The command reads `lib/main.dart` and `pubspec.yaml` from the current working directory and injects the runtime wiring snippets that fit the detected stack.

---

## Arguments

`tapir:install` takes no options. Its two inputs come from the current working directory:

| Input | Purpose |
|-------|---------|
| `lib/main.dart` | Target file for snippet injection. |
| `pubspec.yaml` | Inspected for a `magic_devtools:` dependency entry. Drives the conditional Magic wiring described under [Anchor modes](#anchor-modes). |
| `.dart_tool/package_config.json` | Read only when the Magic wiring applies, to find the resolved `magic_devtools` and check that it ships `lib/tapir.dart`. The nearest one at or above the project is used, so a pub workspace member reads the workspace root's; an unreadable or invalid one counts as unresolved and gets the warning. |

---

## Returns

`tapir:install` returns an integer exit code via `Future<int>`:

| Exit code | Meaning |
|-----------|---------|
| `0` | Success. `lib/main.dart` was either updated with the required snippets or already contained them. The command prints a `tapir:install complete` success line, including when a Phase 2 subprocess failed (that case prints a warning above it). |
| `1` | `lib/main.dart` not found at the resolved path. The command prints an error advising the operator to run `tapir:install` from a Flutter project root. |

No structured payload is emitted. Status flows through `DowelOutput.info` / `success` / `error` so it surfaces with the same `ℹ` / `✓` / `✗` symbols as every other dowel command.

---

## Anchor modes

The injector picks one of two anchor strings depending on what `lib/main.dart` already contains:

- **Magic-stack apps** (`lib/main.dart` contains `await Magic.init(`): `TapirPlugin.install()` is wired BEFORE `Magic.init(` so the driver is live during Magic boot. When `magic_devtools:` is also a pubspec dependency or dev_dependency, `import 'package:magic_devtools/tapir.dart';` is added and `MagicTapirIntegration.install()` is injected AFTER `Magic.init()` (the integration queries `Magic.find<X>()` for the form and nav enrichers, which only resolves once the container is ready). Both lines are written only when the resolved `magic_devtools` (from `.dart_tool/package_config.json`) ships `lib/tapir.dart`. A `magic_devtools` release that predates tapir does not, and importing it would leave a `lib/main.dart` that does not compile, so the installer skips the Magic lines and warns: upgrade `magic_devtools` to a release built on tapir first, then rerun `dart run tapir tapir:install`.
- **Vanilla apps** (no `Magic.init` anchor): `TapirPlugin.install()` is wired immediately before `runApp(`.

The installer does not wire Wind. When the consumer uses `wind_kit`, add `Wind.installDebugResolver()` by hand inside the same `!kReleaseMode` block as `TapirPlugin.install()`. `wind_kit` ships no tapir-specific integration class; tapir reads wind state through the neutral `WindDebugRegistry` bridge at snap time, independent of the Magic detection, so a magic-free app with that call still gets the wind metadata block.

An app wired before the guard moved keeps its `if (kDebugMode)` block: the installer checks for the `TapirPlugin.install()` and `MagicTapirIntegration.install()` calls themselves, not for the snippet, so a re-run adds neither a second block nor an unused `kReleaseMode` import. That app works in debug but registers no `ext.tapir.*` in a profile build; change the guard to `!kReleaseMode` by hand to measure one.

The full sub-step list (from the source docblock):

1. Add the two required imports (`kReleaseMode` from `package:flutter/foundation.dart`, only when a block is about to be injected; the `package:tapir/tapir.dart` barrel).
2. Inject `WidgetsFlutterBinding.ensureInitialized()` (skip when already present) plus the `!kReleaseMode`-gated tapir block before the canonical install anchor, unless `TapirPlugin.install()` is already called.
3. When pubspec has `magic_devtools:` (dependency or dev_dependency), the resolved `magic_devtools` ships `lib/tapir.dart`, AND main.dart has `await Magic.init(`, inject `import 'package:magic_devtools/tapir.dart';` and `MagicTapirIntegration.install()` AFTER that call, unless it is already called.

---

## Examples

### 1. Fresh install in a vanilla Flutter app

```bash
flutter create my_app
cd my_app
flutter pub add tapir
dart run tapir tapir:install
```

Expected output (illustrative):

```
 ℹ Wiring TapirPlugin into lib/main.dart...
 ℹ Scaffolding fastcli (dowel install)...
 ℹ Registering tapir as a dowel plugin...
✓ tapir:install complete. Run `dart run tapir <cmd>` to invoke tapir commands (or `./bin/dowel <cmd>` once fastcli is ready).
```

Diff against `lib/main.dart`:

```dart
import 'package:flutter/foundation.dart' show kReleaseMode;
import 'package:tapir/tapir.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  if (!kReleaseMode) {
    TapirPlugin.install();
  }
  runApp(const MyApp());
}
```

### 2. Re-running on an already-installed project

```bash
dart run tapir tapir:install
```

The injector early-returns on every duplicate snippet. The output still prints `tapir:install complete`; the file is left untouched.

### 3. Magic-stack app with the wind resolver

When pubspec lists `magic_devtools:` and the resolved release ships `lib/tapir.dart`, the post-install `lib/main.dart` looks like this, with the `Wind.installDebugResolver()` line and its import added by hand:

```dart
import 'package:flutter/foundation.dart' show kReleaseMode;
import 'package:tapir/tapir.dart';
import 'package:magic_devtools/tapir.dart';
import 'package:wind_kit/wind_kit.dart'; // added by hand

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  if (!kReleaseMode) {
    TapirPlugin.install();
    Wind.installDebugResolver(); // added by hand
  }
  await Magic.init(MyApp.new);
  if (!kReleaseMode) {
    MagicTapirIntegration.install(); // magic_devtools wiring
  }
}
```

---

## Related Documentation

- [Getting Started: Installation](https://anilcancakir.com/tapir/docs/getting-started/installation.md): step-by-step walkthrough from `dart pub add` to first snapshot.
- [tapir:doctor](https://anilcancakir.com/tapir/docs/commands/tapir-doctor.md): verify the post-install wiring is healthy and the running session can be reached.
- [Plugins: Magic integration](https://anilcancakir.com/tapir/docs/plugins/magic-integration.md): full surface of `MagicTapirIntegration` and which enrichers it ships.
- [Plugins: Wind integration](https://anilcancakir.com/tapir/docs/plugins/wind-integration.md): the six-field `wind:` block surfaced through the neutral `WindDebugRegistry` bridge.

---

# tapir:run

Run several tapir verbs against the running app in one call.

Every step is a verb line, so an agent that already knows its next three moves (tap a button, fill a field, read the result) spends one round trip instead of three, and gets one summary line per step instead of three full outputs.

`tapir:run` runs each step through the verb's own command class, so a step accepts exactly the options the standalone command accepts. The steps share the one VM Service connection of the call.

- [Synopsis](#synopsis)
- [Step grammar](#step-grammar)
- [Output](#output)
- [Exit codes](#exit-codes)
- [MCP form](#mcp-form)
- [Working with refs](#working-with-refs)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:run [--continue] "<step>" ["<step>" ...]
```

`tapir:run` requires a running Flutter session (`CommandBoot.connected`). Each step is one positional argument, so quote it. With no step it prints `No steps given` and exits `1`.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--continue` | flag | `false` | Run every step even after one fails, and exit with the first non-zero code. Without it the batch stops at the first failing step. |

---

## Step grammar

A step is a verb followed by the options of that verb, for example `tap --ref=e5` or `fill --ref=q1 --text="a b"`.

- The line is split the way a POSIX shell would: whitespace separates tokens, single quotes keep everything literal, double quotes keep whitespace and honour `\"` and `\\`, and a backslash outside quotes escapes the next character. An unterminated quote or a trailing backslash fails that step.
- A bare verb gets the `tapir:` prefix (`tap` means `tapir:tap`). A name with a colon is used as given.
- The tokens after the verb are parsed by the verb's own argument parser, so a mistyped option fails that step with the parser's message.

Three kinds of step are rejected, each as a failed step with exit `1`:

- `tapir:run` inside a `tapir:run`.
- A verb that does not exist (`unknown verb tapir:tapp`).
- A verb that does not run on the connected app: any command that does not boot connected, such as `tapir:resize`, `tapir:device`, `tapir:install`, `tapir:doctor`, `tapir:perf_campaign` and `tapir:perf_compare`. Call those on their own.

A step that ends or restarts the app (`tapir:close_app`, `tapir:perf_run`) is accepted, but every later step then talks to a dead connection and fails, so make it the last step.

A step that fails does so with the verb's own exit code (`tap` with no `--ref` returns `1` from its own check) and a verb that throws exits `3`; the batch carries on only with `--continue`.

---

## Output

One summary line per step, then the last step's output:

```
[1/3] tap --ref=e8 ok: Tapped e8
[2/3] fill --ref=q1 --text="a b" ok: Filled q1
[3/3] snap --grep Total ok
- text "Total: 42"
```

- The text after `ok:` is the first non-empty output line of the step, cut to 120 characters (`...` marks the cut). The rest of a step's output stays out of your context.
- The last step's full output follows the summary, because it is the state you act on next; its own summary line carries no digest, so the first output line is not printed twice. A step that produced no output prints only its summary line.
- A failing step prints `[N/M] <step> failed (exit C)` followed by its whole output, then the batch stops, or goes on with `--continue`.
- A step's stderr lines (the frame-production banner, the `tapPointOutsideOwner` warning) are captured into its output with an `[ERROR]` prefix, so a warning is not lost.
- When the batch fails, the last line, on stderr, is `step N failed (exit C): <step>` for the first failing step.

---

## Exit codes

| Exit code | Meaning |
|-----------|---------|
| `0` | Every step exited `0`. |
| `1` | No steps were given; or the first failing step failed on its grammar (nested run, unknown verb, not a connected verb, bad option, bad quoting) or returned `1` itself. |
| `3` | The first failing step threw (for example a VM Service error). |
| `75` | The first failing step ran before `ext.tapir.*` was registered; retry once the app has booted. |
| other | The exit code of the first failing step. |

Without `--continue` the batch ends at that step. With it, every step runs and the exit code is still the first non-zero one.

---

## MCP form

The `tapir_run` tool takes the same steps as a list and routes through the substrate command `dowel:tapir:run`.

```json
{
  "name": "tapir_run",
  "arguments": {
    "steps": ["tap --ref=e5", "fill --ref=q1 --text=\"a b\"", "snap --grep Total"],
    "continue": false
  }
}
```

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `steps` | array<string> | yes | Verb lines, run in order, without the `tapir:` prefix. |
| `continue` | boolean | no | Keep running after a failing step (default `false`). |

The response is the same text the CLI prints.

---

## Working with refs

`eN` refs are scoped to one snapshot, and a batch cannot read a snapshot it has not taken yet. So:

- Use refs you already hold from a snapshot taken before the call.
- Between steps that change the screen, prefer a `q<N>` handle (`tapir:find`), `--text` or `--key`, which survive a rebuild, over an `eN` ref the first step may invalidate.
- End the batch with `snap` (or a `--snapshot=diff` action) and read the new refs from its output.
- Add `--snapshot=diff` to the last action step to see only what the batch changed; see [tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md).

---

## Examples

### 1. Fill a form and read the result

```bash
dart run tapir tapir:run \
  "fill --ref=q1 --text=alice@example.com" \
  "fill --ref=q2 --text=hunter2" \
  "tap --ref=q3" \
  "snap --interactiveOnly"
```

### 2. Keep going past a failure

```bash
dart run tapir tapir:run --continue "tap --ref=e5" "press_key --key=Escape" "snap"
```

All three steps run. The exit code is the first failing step's, or `0`.

---

## Related Documentation

- [Commands index](https://anilcancakir.com/tapir/docs/commands/index.md): every verb a step may name.
- [tapir:snap](https://anilcancakir.com/tapir/docs/commands/tapir-snap.md): the usual last step.
- [tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md): `--snapshot=diff` for a cheap read of what a step changed.
- [MCP tool reference](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_run): the `tapir_run` schema.

---

# tapir:doctor

Verify the `tapir` runtime and the consumer-side wiring health in a single pure-CLI pass.

`tapir:doctor` does not dial the VM Service; every check runs against the consumer's filesystem, the dowel session state file, and a small set of environment probes. Seven lightweight checks run in order, each emitting one row via the `DowelOutput` facade (a coloured `✓` / `⚠` / `✗` / `ℹ` symbol in TTY mode, plain text under buffered or null output).

- [Synopsis](#synopsis)
- [Arguments](#arguments)
- [Returns](#returns)
- [The seven checks](#the-seven-checks)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:doctor
```

`tapir:doctor` accepts no positional arguments and no flags. It runs the seven checks below against the cwd and exits with a status code derived from the single ERROR-class check (the Semantics tree probe).

`CommandBoot.none`: no VM Service connection. The command can run before `dowel start` (some checks will downgrade to "Skipped (no Chrome attached)" but the command itself completes cleanly).

---

## Arguments

`tapir:doctor` takes no options. Its probes read the session state file, `lib/main.dart` and the `TAPIR_DISABLE` compile-time constant, and nothing on the command line changes them.

---

## Returns

`tapir:doctor` returns an integer exit code via `Future<int>`:

| Exit code | Meaning |
|-----------|---------|
| `0` | Every check that can ERROR passed. WARN and INFO rows do not fail the doctor. |
| `1` | The Semantics-tree probe (check 4) returned false. This is the only ERROR-class check; failure indicates `TapirPlugin.install()` did not run. |

No structured JSON envelope is emitted; the output is row-per-check via `DowelOutput.success` / `warning` / `error` / `info`.

---

## The seven checks

### 1. Hot-restart staleness

Reads the session's `state.json`, locates the live Chrome PID via `captureChromePid`, and compares Chrome's `ps -o lstart=` start time against `state.json.startedAt`. Drift over 30 s means a hot-restart spawned a fresh Chrome after the CLI wrote `state.json`; the cached isolate id will be stale, so the check WARNs and asks the operator to restart the CLI. Downgrades to an INFO "Skipped" row when no state.json exists, no Chrome can be found, or the lstart probe fails (POSIX-only).

### 2. TAPIR_DISABLE env-var

Reads the compile-time `--dart-define=TAPIR_DISABLE=<value>` constant of the doctor process itself, not of the running app: the doctor is a separate Dart process, so a define passed to `flutter run` or `dart run tapir start` is invisible to it. The check therefore confirms the define only when it was also passed to the doctor (`dart run --define=TAPIR_DISABLE=<value> tapir tapir:doctor`). Non-empty values WARN with the actual value echoed back. Empty value passes with a `✓` row, which says nothing about how the app was built.

### 3. Enricher list non-empty

Reads the count of registered `TapirSnapshotEnricher` instances. Zero means no enricher is registered, for example because the consumer did not install `MagicTapirIntegration`. Wind metadata flows through the neutral `WindDebugRegistry` bridge (see [Wind integration](https://anilcancakir.com/tapir/docs/plugins/wind-integration.md)), so a wind-only app still shows a `wind:` block per ref even when this count is zero. INFO, never fails: enrichers are opt-in. The count defaults to `0` in CLI context (the pure-Dart doctor cannot reach into Flutter without pulling `dart:ui`), so `enrichers are opt-in; none registered` is the normal CLI-time outcome.

### 4. Semantics tree forced on (ERROR-class)

Reports whether `RendererBinding.instance.semanticsEnabled` is true. The only check that can fail the doctor (exit code `1`). The default probe returns `true` unconditionally because the pure-Dart CLI cannot import `package:flutter/rendering.dart` without pulling `dart:ui`; the real-runtime check belongs to a future VM-Service-attached doctor invocation.

### 5. Magic-init detection (INFO-only)

Reads `lib/main.dart` and reports one of these states:

- `Magic-stack detected, integration wired`: both `Magic.init(` and `MagicTapirIntegration.install` are present.
- `Magic detected but MagicTapirIntegration missing; wire it with tapir:install`: `Magic.init(` is present, the integration is not, and the resolved `magic_devtools` ships `lib/tapir.dart`.
- `Magic detected, but the installed magic_devtools has no tapir integration yet; upgrade it to a release built on tapir, then rerun tapir:install`: the resolved `magic_devtools` has no `lib/tapir.dart`, so there is no class to wire yet.
- `Magic detected, but no magic_devtools resolved; add a release built on tapir to dev_dependencies, run flutter pub get, then rerun tapir:install`: `.dart_tool/package_config.json` names no `magic_devtools`.
- `vanilla Flutter detected`: no `Magic.init(` anchor.

The `magic_devtools` check reads the nearest `.dart_tool/package_config.json` at or above the working directory (the workspace root's for a pub workspace member; an unreadable or invalid one reads as unresolved and never stops the doctor), the same check `tapir:install` makes before it writes the Magic lines.

INFO only; never fails the doctor regardless of the consumer stack.

### 6. Session ownership

Compares the session state's `projectRoot` against the directory the command is running from, using dowel's own ownership rule (a directory inside the recorded root counts as the owner). dowel keeps one state file per project, and `~/.dowel/state.json` is a pointer to whichever session started last; when the state read here describes another project, every `tapir:*` call from this directory would drive that app instead, and every one of them would succeed.

WARN, naming both paths. Skipped when no `projectRoot` is recorded.

A worktree checked out inside the recorded root (for example `<repo>/.claude/worktrees/<slug>`) reads as the owner, so the check stays silent while a `tapir:*` call from a worktree with no session of its own drives the app started from the main checkout. Start a session in the worktree, or pass `--state=<path>`.

### 7. CDP session health

Probes the `cdpPort` recorded in state for three failures. They matter together because they present as one symptom, a capture that never changes, and nothing else in the output distinguishes them:

| Finding | What it means |
|---|---|
| Port unreachable | A killed `flutter run` can leave its dart dev server holding the web port while its Chrome (and the debug port) is gone. The recorded port now points at nothing. |
| No page on this run's `webPort` | An orphan browser from an earlier run, still up with the old build and its own debug port. Captures come back byte-identical from it. |
| The matching page is hidden | `document.hidden` is true, so Flutter has stopped producing frames: snapshots lose their `- text` nodes and gestures cannot take effect. Send CDP `Page.bringToFront`. |

WARN in all three cases. Skipped when no `cdpPort` is recorded, which is the normal state for a native target. The visibility read targets the page whose URL carries this run's `webPort`, not whichever tab Chrome happens to list first.

See [Frame production](https://anilcancakir.com/tapir/docs/reference/frame-production.md) for the hidden-page case in full.

---

## Examples

### 1. Healthy magic-stack app on a web session

```bash
dart run tapir tapir:doctor
```

Expected output (illustrative):

```
✓ hot-restart staleness: no drift detected (Chrome PID 51234)
✓ TAPIR_DISABLE env-var: unset (runtime hooks active)
 ℹ snapshot enrichers: enrichers are opt-in; none registered
✓ Semantics tree forced on: enabled
 ℹ Magic-init detection: Magic-stack detected, integration wired
✓ Session ownership: state.json describes this project
 ℹ CDP session: Skipped (no cdpPort recorded; start with --cdp-port=N to enable tapir:resize, tapir:device and clipped web screenshots)
```

Exit code: `0`.

### 2. Pre-flight on a freshly-installed vanilla app

```bash
dart run tapir tapir:doctor
```

Expected output (illustrative):

```
 ℹ hot-restart staleness: Skipped (no Chrome attached)
✓ TAPIR_DISABLE env-var: unset (runtime hooks active)
 ℹ snapshot enrichers: enrichers are opt-in; none registered
✓ Semantics tree forced on: enabled
 ℹ Magic-init detection: vanilla Flutter detected
✓ Session ownership: state.json describes this project
 ℹ CDP session: Skipped (no cdpPort recorded; start with --cdp-port=N to enable tapir:resize, tapir:device and clipped web screenshots)
```

Exit code: `0`. Only the Semantics tree check can fail the doctor; WARN and INFO rows do not.

### 3. Consumer forgot to run `tapir:install`

The doctor cannot directly detect missing `TapirPlugin.install()` from CLI context, but on a Magic app check 5 reports `Magic detected but MagicTapirIntegration missing; wire it with tapir:install` when the magic-stack glue is absent and the resolved `magic_devtools` ships `lib/tapir.dart`. Re-run `tapir:install` to fix. With an older `magic_devtools`, check 5 says to upgrade it first instead.

---

## Related Documentation

- [tapir:install](https://anilcancakir.com/tapir/docs/commands/tapir-install.md): the bootstrap command. Re-run `tapir:install` when check 5 reports missing integration glue.
- [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md): the runtime gate that snapshot consumers rely on; not checked by the doctor today.
- [Getting Started: Installation](https://anilcancakir.com/tapir/docs/getting-started/installation.md): full bring-up walkthrough; the doctor is the verification step.

---

# tapir:snap

Capture the Semantics tree of the running Flutter app as YAML, tagging every interactive node with a `[ref=eN]` token.

`tapir:snap` is the foundational read command: every action command (`tapir:tap`, `tapir:type`, `tapir:drag`, etc.) consumes one of its `eN` refs to locate the target widget.

The `eN` namespace belongs to snapshots: a snapshot reuses the token of a Semantics node it has seen before and mints new tokens for the rest, and a token outlives its widget (an `eN` whose element left the tree is relocated by label when the count still matches, otherwise it fails as `defunct`). For long-lived handles that survive rebuilds, use `tapir:find` (which mints `qN` tokens) or `tapir:observe`.

An `eN` ref also recovers from a rebuild on its own, within limits. Each snapshot binds a label-and-index query, plus the number of nodes carrying that label, to every labelled ref. When the element behind the ref has left the tree, the action relocates the control by that query, but only if the live tree still has the same number of nodes with that label; the response then lists the ref under `reresolved` (for example `"reresolved": ["e5"]`). With a different count the ref fails as `defunct (element no longer mounted)` and you re-snap. The query has no role, so a node of another role with the same label in the same position could be matched.

Interactive nodes inside a currently-overflowing render ancestor carry an additive `overflow: true` sub-line in the YAML output. This is a live current-state check (`RenderFlex.toStringShort()` appends ` OVERFLOWING` while the constraint is violated); it is not a historical record. For the full non-fatal error history including overflow details, use `tapir:exceptions`.

Text fields collapse to a single typeable ref. A field such as a wind `WInput` produces two nested `textbox` Semantics nodes (the outer wrapper plus the `RenderEditable` leaf that always owns its own node). `tapir:snap` suppresses the inner duplicate when its render object is a render-tree descendant of the outer `textbox` node's render object, emitting one ref for the surviving node and tagging it with an additive `typeable: true` sub-line. Collapse is by render-object containment only, so two sibling fields sharing the same label stay two distinct refs. Target the node carrying `typeable: true` when typing: `tapir:type` resolves the inner `EditableText` from it.

- [Synopsis](#synopsis)
- [Arguments](#arguments)
- [Narrowing, and why the full tree is usually the wrong answer](#narrowing)
- [Returns](#returns)
- [Enricher fragments](#enricher-fragments)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:snap [--depth=<n>]
                                   [--within=<eN>]
                                   [--interactiveOnly]
                                   [--grep=<regex>]
                                   [--includeEnrichers]
                                   [--json]
```

`tapir:snap` requires a running Flutter session (`CommandBoot.connected`). It dials the VM Service URI recorded for this project's dowel session, calls `ext.tapir.snap`, and prints the snapshot YAML to stdout.

---

## Arguments

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--depth` | int (string-parsed) | unset (full tree) | Optional max tree depth. Caps the walk so very deep widget trees stay readable. Omit for the full tree. |
| `--includeEnrichers` | flag | `false` | Emit Magic and Wind enricher fragments under each ref entry. Default off matches the Playwright-style minimal snapshot; turn on when the agent needs the className tokens, route name, or form field metadata. |
| `--within` | string (`e<N>`) | unset (whole tree) | Scope the walk to one subtree. Takes an `e<N>` ref from a prior snapshot; `q<N>` query handles are not addressable here, since they re-resolve per action and have no fixed subtree. An unknown or node-less ref is an error rather than a silent widening. |
| `--interactiveOnly` | flag | `false` | Emit only nodes that carry a ref (buttons, text fields, links, headers, anything with a tap action) and drop the plain `- text` lines. |
| `--grep` | string (regex) | unset | Emit only nodes whose label or value matches, plus the ancestors that lead to them. Ancestors survive because they carry the refs you act on: a matching `- text` line has none of its own. A pattern that is not a valid regex (a label such as `Container Sample (MP4, H.264` is an unterminated group) is matched as a literal substring instead, and the envelope carries `"grepLiteral": true`. |
| `--json` | flag | `false` | Print the whole envelope as JSON instead of the tree alone, so `grepLiteral`, `warnings`, `framesForced` and `renderErrors` are readable. Text mode is unchanged. |

Every flag is serialised as a string into the VM Service params map; the command does no key translation. `tapir:snap` has no `--snapshot` option: it is the snapshot. The `--snapshot=full|diff|none` option belongs to the action verbs ([tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md), `tapir:fill`, `tapir:type`, `tapir:navigate`, `tapir:scroll`).

---

## Narrowing, and why the full tree is usually the wrong answer

A full tree costs context on any real screen, and on a shell whose sidebar repeats the labels of the pages it opens it is also the misleading answer: an exact-label lookup resolves the nav item, so the caller measures the sidebar and concludes two pages differ. That has produced confident wrong readings more than once.

```bash
# Read one region. Take its ref from a prior snapshot.
dart run tapir tapir:snap --within=e12

# Only the things you can act on.
dart run tapir tapir:snap --interactiveOnly

# Only what matches, plus the path to it.
dart run tapir tapir:snap --grep="Sign ?in"
```

The three compose. `--within=e12 --interactiveOnly` is the usual shape before an action: one region, refs only.

An unfiltered call is unchanged, byte for byte.

---

## Returns

The VM Service handler returns a JSON envelope `{ "snapshot": "<yaml>", "groupId": "<id>" }`. The CLI unwraps the `snapshot` field and writes the raw YAML to stdout; when the field is missing the entire JSON object is dumped instead.

**Success envelope (illustrative):**

```yaml
- text "Welcome back"
- textbox "Email" [ref=e1]
  typeable: true
- button "Sign in" [ref=e2]
```

Each line is `- <role> "<label>"`, with `: "<value>"` after the label when the node has a value and the `[ref=eN]` token on interactive nodes; plain text nodes print as `- text "..."` and carry no ref. Children are indented two spaces under their parent. The `typeable: true` sub-line marks the single surviving `textbox` node after the nested-field collapse described above; it is the node `tapir:type` resolves.

A ref line may end with ` [offscreen]` and/or ` [occluded]` after `[ref=eN]`:

```yaml
- button "Archive" [ref=e9] [offscreen]
- button "Save" [ref=e4] [occluded]
```

`[offscreen]` means the widget lies outside the viewport (scroll it into view with `tapir:scroll --intoView`). `[occluded]` means a hit test at its centre reaches a widget painted above it, such as a dialog or an overlay (dismiss that first). A healthy screen prints neither, so the output is unchanged. An offscreen node is never probed for occlusion, and a node with no area carries neither marker.

A merged node (a `MergeSemantics` boundary) whose centre is not on its own control gets one more indented sub-line, `tapOwner: {"x":656.0,"y":536.0,"w":120.0,"h":40.0}`: the control's rect in logical pixels. A tap on that ref goes to that control (see [`tapir:tap`](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md)) unless the object says `"retargets":false` (several candidates, or the control is covered or off screen), and `"centreHandled":true` means the centre has a tap handler of its own that `--no-retarget` would tap. The line is absent on every other node (#60).

When `--includeEnrichers` is set, each entry gains indented lines contributed by the registered enrichers (see [Enricher fragments](#enricher-fragments)).

### The diff baseline

An unfiltered `tapir:snap` records its text as the baseline that `--snapshot=diff` on an action verb compares against: the action then returns only the lines it changed. A snap with `--grep`, `--within`, `--depth`, `--interactiveOnly` or `--includeEnrichers` is a partial view and never replaces the baseline, and a hot restart clears it (the next diff then returns the full text). Take a plain `tapir:snap` first when you plan to use `diff`.

### Render errors

When the `FlutterError.onError` capture buffer holds non-fatal render or build errors (for example a `ParentDataWidget` misuse such as `Expanded` placed outside a `Flex`, or a layout overflow), the response includes a `renderErrors` block:

```json
{
  "snapshot": "<yaml>",
  "groupId": "snapshot-1700000000000",
  "renderErrors": {
    "count": 2,
    "recent": [
      { "type": "FlutterError", "message": "Incorrect use of ParentDataWidget." },
      { "type": "FlutterError", "message": "A RenderFlex overflowed by 32 pixels." }
    ],
    "hint": "Run tapir:exceptions (CLI) or tapir_exceptions (MCP) for full messages + stack traces."
  }
}
```

Fields:

| Field | Type | Description |
|-------|------|-------------|
| `count` | int | Total number of captured render/build errors. May exceed `recent.length`. |
| `recent` | array (max 3) | Most recent entries; each has `type` (string) and `message` (first line only). |
| `hint` | string | Fixed advisory pointing to `tapir:exceptions` (CLI) / `tapir_exceptions` (MCP) for full detail. |

The `renderErrors` block is **omitted entirely** when no errors are in the buffer. A clean screen produces the standard two-key envelope (`snapshot` + `groupId`).

**CLI banner:** when `renderErrors` is present, `tapir:snap` prints a render-error banner to **stderr** (stdout stays the pure snapshot text, so tooling that captures only stdout is unaffected):

```
⚠ 2 render error(s) captured on this screen (run tapir:exceptions for full detail):
  - FlutterError: Incorrect use of ParentDataWidget.
  - FlutterError: A RenderFlex overflowed by 32 pixels.
```

### Frame production

When the app is not producing frames, semantics labels are never rebuilt: the snapshot comes back with its buttons and none of its `- text` nodes, and a screen that renders perfectly reads as completely empty. Tapir first tries to wake a hidden or minimised app, and a snapshot taken after waking carries `"framesForced": true`. When it cannot (the `TAPIR_FORCE_FRAMES=false` opt-out, a `detached` lifecycle, a wake that produced no frame, or any hidden web tab) the response carries a `warnings` block and `tapir:snap` prints a banner to stderr. On web:

```
⚠ The app is not producing frames (lifecycle: hidden), so this result may be stale. A
  backgrounded browser tab is the usual cause: bring the page to front and retry.
```

On desktop the banner names a hidden, minimised or occluded window or an asleep display instead.

On a web session started with `--cdp-port`, the CLI acts on the web warning itself: it sends CDP `Page.bringToFront` once and calls `ext.tapir.snap` again, so a snapshot of a backgrounded tab usually comes back healthy. A CDP failure leaves the first result and its exit code. Without a `cdpPort` nothing changes.

Do not read an empty tree as an empty screen without checking for this block first. See [Frame production](https://anilcancakir.com/tapir/docs/reference/frame-production.md).

**Error envelope:**

The VM Service handler propagates errors as `ServiceExtensionResponse.error(extensionError, message)`. The CLI surfaces the exception via `DowelContext.callExtension` and exits with a non-zero status. Typical failure modes:

- No running app at the recorded URI (the dowel dispatcher reports the dial failure before `tapir:snap` runs).
- `TapirPlugin.install()` missing from `lib/main.dart` (run `tapir:install`).

---

## Enricher fragments

When `--includeEnrichers` is true, every `TapirSnapshotEnricher` appended to the `TapirPlugin.enrichers` live list contributes indented lines under each ref. The two first-party enrichers:

- **MagicTapirIntegration** ships the Magic enrichers (see [Plugins: Magic integration](https://anilcancakir.com/tapir/docs/plugins/magic-integration.md) for the fields).
- **`wind_kit`** surfaces a six-field `wind:` block (breakpoint, brightness, platform, states, bgColor, textColor) through the neutral `wind_kit_diagnostics_contracts.WindDebugRegistry` bridge rather than via an enricher, once the app calls `Wind.installDebugResolver()`, so the data appears under each W-prefixed widget ref without any enricher registration.

Each enricher is synchronous and stateless; the `Element` reference is never retained across calls.

### Overflow annotation

The `overflow: true` sub-line is emitted by the snapshot dispatcher itself (not via an enricher) when the resolved `RenderObject.toStringShort()` contains the Flutter debug suffix ` OVERFLOWING`. It appears for any interactive node whose nearest render ancestor is currently violating its constraints, regardless of whether enrichers are enabled. Example output:

```yaml
- button "Submit" [ref=e5]
  overflow: true
```

### Typeable annotation and textbox collapse

A text field commonly produces two nested `textbox` Semantics nodes: an outer wrapper (e.g. a wind `WInput`'s `Semantics(textField:true)`) and the `RenderEditable` leaf, which always owns its own `textField` node and which `MergeSemantics` cannot absorb. Both nodes used to mint a ref; typing on the inner leaf threw `-32000`. The snapshot walk now suppresses the inner node when its render object is a render-tree descendant of the outer `textbox` node's render object, leaving one ref for the surviving node and appending `typeable: true` beneath it:

```yaml
- textbox "Email" [ref=e2]
  typeable: true
```

The collapse is by render-object containment only, never label/value equality, so two sibling fields sharing a label remain two distinct refs. The `typeable: true` node is the one `tapir:type` resolves to the inner `EditableText`.

### Merged controls

A control wrapped in `MergeSemantics` (a magic_starter `MSSwitch` row, a wind `WAnchor` around a hover `WDiv`) is listed once. Flutter keeps each absorbed descendant in the tree as its own node flagged `isMergedIntoParent`, so the walk used to print a `button "X"` line followed by a nested duplicate. A merged node now prints no line and mints no ref; the walk still descends through it, and the boundary line already carries the merged label, flags and actions, which is what the platform exposes. Refs after a removed duplicate shift down by one each, so a script that hard-coded ref numbers re-snaps.

---

## Examples

### 1. Minimal snapshot of the current screen

```bash
dart run tapir tapir:snap
```

Expected output (illustrative; truncated):

```yaml
- text "Monitors"
- button "New monitor" [ref=e1]
- button "Settings" [ref=e2]
```

### 2. Snapshot with depth cap

```bash
dart run tapir tapir:snap --depth=4
```

Caps the walk at four levels of nesting. Useful for very dense screens (long lists, complex forms) where the full tree is noisy.

### 3. Snapshot with enrichers turned on

```bash
dart run tapir tapir:snap --includeEnrichers
```

Expected output (illustrative):

```yaml
- button "New monitor" [ref=e1]
  wind:
    breakpoint: lg
    brightness: light
  magicRoute: /monitors
```

---

## Related Documentation

- [tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md): consume an `eN` token to synthesise a tap.
- [tapir:find](https://anilcancakir.com/tapir/docs/commands/tapir-find.md): mint a long-lived `qN` handle that survives rebuilds.
- [tapir:observe](https://anilcancakir.com/tapir/docs/commands/tapir-observe.md): structured candidate list when the agent needs more than the raw Semantics tree.
- [Plugins: Enricher authoring](https://anilcancakir.com/tapir/docs/plugins/enricher-authoring.md): how to ship a custom enricher that contributes additional fragments.

---

# tapir:find

Mint a re-resolvable `q<N>` handle backed by one or more predicates (text, semanticsLabel, key).

The command mirrors Playwright's Locator semantics: every action call against a `qN` handle re-walks the live Semantics tree on each invocation, so the handle survives intermediate widget rebuilds without going stale.

`qN` and `eN` token spaces are disjoint. A handle minted by `tapir:find` is always `qN`; a handle harvested from `tapir:snap` is always `eN`. The dispatcher distinguishes by prefix, but action commands accept either shape via `--ref=`.

- [Synopsis](#synopsis)
- [Arguments](#arguments)
- [Returns](#returns)
- [Re-resolution semantics](#re-resolution-semantics)
- [Examples](#examples)
- [e-ref staleness and when to prefer q-handles](#ref-staleness)
- [Avoiding `--semanticsLabel` over-match](#semantics-label-over-match)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:find [--text=<value>]
                                    [--contains=<substring>]
                                    [--semanticsLabel=<value>]
                                    [--key=<value>]
                                    [--within=<eN>]
```

`tapir:find` requires a running Flutter session (`CommandBoot.connected`). It dials the VM Service URI, calls `ext.tapir.find` with the supplied predicates, and prints the minted handle envelope as pretty-printed JSON.

At least one of the four predicate options must be non-empty (`--within` is a scope, not a predicate); an empty params map returns exit code `1` with a CLI-side error before the VM Service call.

---

## Arguments

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--text` | string | unset | Exact match against an accessibility label first, then against the `Text.data` of a rendered `Text` as a fallback. Most common predicate; mirrors Playwright's `getByText` with exact-match semantics. |
| `--contains` | string | unset | Substring match against the visible text label or Semantics label (case-sensitive). Use when the label is dynamic (counters, timestamps, plurals) and exact `--text` is too brittle. |
| `--semanticsLabel` | string | unset | Exact match against the widget's accessibility label (the explicit `Semantics(label: ...)` value set by the widget tree). Use when the visible text and the a11y label diverge. |
| `--key` | string | unset | Match the widget's `ValueKey` identifier (the `Key('signin-button')` form). Most precise; survives label and copy changes. |
| `--within` | string (`e<N>`) | unset (whole tree) | Evaluate the predicates inside one subtree. The scope becomes part of the minted `q<N>` handle, so it survives into every re-resolve; once the scope stops resolving the handle reports `matched: false` with a diagnostic naming it. Take the ref from a `tapir:snap` output: a ref minted by `tapir:wait` carries no semantics node, so it cannot bound a `--semanticsLabel` lookup and that combination is refused with a diagnostic rather than widened to the whole tree. |

The predicates compose AND: a `tapir:find --text=Sign --key=signin-button` call returns the widget that matches both. Use a single predicate when the agent only needs one axis.

The CLI guards an empty params map (`Provide at least one of --text / --contains / --semanticsLabel / --key.`) so the VM Service handler never sees a zero-predicate call.

---

## Returns

`tapir:find` returns an integer exit code via `Future<int>`:

| Exit code | Meaning |
|-----------|---------|
| `0` | The call completed. A match mints a handle and emits the JSON envelope below; no match emits `{"ref": null, "matched": false}` (check `matched` before using `ref`). |
| `1` | No predicate supplied. The CLI guard fires before the VM Service call. |
| non-zero | VM Service handler returned `ServiceExtensionResponse.error`, or the call could not reach the app. |

**Success envelope (illustrative):**

Single match:

```json
{
  "ref": "q1",
  "matched": true,
  "matchCount": 1
}
```

Multi-match (ambiguous predicate):

```json
{
  "ref": "q1",
  "matched": true,
  "matchCount": 2,
  "diagnostic": "label 'Password' matched 2 nodes; refine with --key, --text, or --contains"
}
```

`matchCount > 1` means the predicate is ambiguous: the handle still resolves to the FIRST match (backward-compatible), but the agent should narrow with an additional predicate before acting. Common disambiguation strategies:

- Add `--key=<widget-key>` when the widget carries a `ValueKey`.
- Add `--text=<visible-label>` when the accessibility label and the visible text differ.
- Use `--contains=<unique-substring>` when only part of the label is unique.

**Error envelope:**

The VM Service handler propagates errors as `ServiceExtensionResponse.error(extensionError, message)`. The CLI surfaces them via `DowelContext.callExtension` and exits non-zero.

---

## Re-resolution semantics

A `qN` handle stores the predicate map, not the matched widget. Every action call (`tapir:tap --ref=q1`, `tapir:type --ref=q1`, etc.) re-executes the query against the live Semantics tree. Three consequences:

1. **Widget rebuilds don't invalidate the handle.** A `ListView` swap, a navigation transition, or a state-driven rebuild all leave the handle valid as long as the predicates still match something.
2. **The query is re-run on every action.** Cheap (a Semantics walk on each call), but emergent if the predicate is broad: prefer `--key` over `--text` for hot paths.
3. **`tapir:find` itself is idempotent in the registry.** Calling it twice with the same predicate map returns the same `qN`; the registry is content-addressed.

`eN` handles minted by `tapir:snap` work the opposite way: they freeze the matched widget at snap time and go stale on the next rebuild. Use `eN` for one-shot reads, `qN` for any sequence that spans more than one frame.

---

## Examples

### 1. Mint a handle by visible text

```bash
dart run tapir tapir:find --text="Sign in"
```

Expected output (illustrative):

```json
{
  "ref": "q1",
  "matched": true,
  "matchCount": 1
}
```

Reuse `q1` across subsequent action calls:

```bash
dart run tapir tapir:tap --ref=q1
```

### 2. Mint a handle by accessibility label

```bash
dart run tapir tapir:find --semanticsLabel="Submit form"
```

Use when the rendered button text is an icon and the only stable predicate is the a11y label.

### 3. Mint a handle by widget key (most precise)

```bash
dart run tapir tapir:find --key="signin-submit"
```

Survives copy changes and a11y-label changes. Pair with a widget-side `Key('signin-submit')` declaration.

### 4. Mint a handle by substring (dynamic label)

```bash
dart run tapir tapir:find --contains="pushed the button"
```

Useful when the visible label is dynamic, e.g. `"You have pushed the button 5 times:"` (counter changes per tap). `--text` would only match the exact string at the moment of capture; `--contains` survives the counter advancing.

### 5. Compose two predicates to disambiguate

```bash
dart run tapir tapir:find --text="Save" --key="monitor-form-save"
```

The two predicates AND together; useful when the screen has multiple "Save" buttons but only one with the canonical key.

---

## e-ref staleness and when to prefer q-handles

`e<N>` tokens minted by `tapir:snap` are frozen to the Semantics node that was
live at snap time. They become defunct the moment the node leaves the tree, which
happens on any route push, list rebuild, or conditional widget swap. The
`RefRegistry` that backs `e<N>` tokens does NOT re-resolve; calling an action
with a stale `e<N>` returns a `defunct (element no longer mounted)` failure.

`q<N>` handles minted by `tapir:find` store the predicate set instead of the
node, and re-walk the live tree on every action call. They survive navigations,
hot-reloads, and full widget rebuilds as long as the predicate still matches
something in the tree.

**When to reach for `tapir:find` / `q<N>` instead of using the `e<N>` from a
snap:**

- The page might rebuild between snap and action (e.g. Settings pages with
  dynamic sections, lists driven by async data).
- The agent will retry an action (gate failure, transient loading state).
- The flow spans more than one navigation hop; an `e<N>` from the previous
  screen is always stale after the route change.
- The agent holds a ref across a hot-reload.

The `RefRegistry` is intentionally frozen for `e<N>` (it is a FIFO token store,
not a live observer). There is no mechanism to refresh a stale `e<N>` in place;
the design intent is that `tapir:snap` re-mints the ref after every page change.
For rebuild-prone pages, prefer `tapir:find` / `tapir:observe` from the start.

---

## Avoiding `--semanticsLabel` over-match

`--semanticsLabel` performs an exact case-sensitive match against
`SemanticsNode.label` and returns the FIRST node in tree order. When two or
more nodes carry the same label (e.g. two `TextField` widgets both labelled
`Password` on a sign-up form, or a list of repeated row controls), the handle
resolves to the first node in tree order, which may not be the intended target.

The `matchCount` field in the response tells the agent how many nodes matched.
A `diagnostic` key appears when `matchCount > 1`, e.g.:

```
label 'Password' matched 2 nodes; refine with --key, --text, or --contains
```

**Disambiguation strategies (most to least precise):**

1. Add `--key=<widget-key>` when the widget carries a `ValueKey`. This is the
   most precise predicate and survives label changes.
2. Combine `--semanticsLabel=Password --text=Confirm` when the second node has
   distinct visible text (some widgets expose both a label and a text value).
3. Use `--contains=<unique-substring>` when only part of the label is unique
   across the matching nodes.
4. Use `tapir:observe` with a narrow `intent` and inspect the returned candidate
   list; each candidate includes role, bounds, and enricher fields that let the
   agent identify the correct target before minting the handle.

**Interactive nodes win a mixed collision.** When a label spans one interactive
node (a button, switch, or text field exposing `SemanticsAction.tap`) and one or
more inert nodes (a `Text` heading or a settings label that repeats the control's
copy), the handle resolves to the first interactive node rather than the first
node in tree order. A visible label naming an adjacent control, or a heading
repeating a button's text, otherwise sits first in tree order and the tap would
land on the inert label. When every match is interactive or every match is inert,
the handle falls back to the first node in tree order. `matchCount` and
`diagnostic` still report the full collision either way, so an agent that needs a
specific one of several interactive matches should still refine the predicate.

Each `qN` gesture then dispatches at the resolved node's own on-screen rect (the
`RenderBox` bounds of the widget that contributes the node), so off-centre
controls (a sidebar item, a submit button below the fold) receive the tap at
their real position rather than the viewport centre.

---

## Related Documentation

- [tapir:snap](https://anilcancakir.com/tapir/docs/commands/tapir-snap.md): produce `eN` refs for one-shot reads.
- [tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md): consume the `qN` ref to synthesise a tap.
- [tapir:observe](https://anilcancakir.com/tapir/docs/commands/tapir-observe.md): structured candidate list of every interactive widget; useful when the agent doesn't know which predicate to query.

---

# tapir:observe

Return a structured candidate list of every interactive widget on screen.

The command mirrors the Stagehand observe-once-act-many pattern: the agent observes once, then issues many `tapir:tap` / `tapir:type` / `tapir:drag` calls against the minted `qN` refs without re-observing between actions.

No LLM is invoked server-side. The handler walks the live Semantics tree, mints a re-resolvable `qN` handle for each interactive widget, and returns the candidate list as JSON. The agent reads the list and decides which refs to act on. This is what differentiates `tapir:observe` from a model-side `tapir:snap`: it returns a flat, role-filterable list optimised for LLM consumption rather than the full tree.

A control wrapped in `MergeSemantics` is listed once, as its boundary node: the descendants it absorbs are never sent to the platform and get no candidate and no `qN` handle.

The CLI surface is mostly for debugging; the MCP descriptor is the primary surface for agent integrations.

- [Synopsis](#synopsis)
- [Arguments](#arguments)
- [Returns](#returns)
- [Observe-once-act-many](#observe-once-act-many)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:observe [--intent=<hint>]
                                       [--roles=<csv>]
                                       [--limit=<n>]
                                       [--includeEnrichers=<true|false|full>]
```

`tapir:observe` requires a running Flutter session (`CommandBoot.connected`). It dials the VM Service URI, calls `ext.tapir.observe`, and prints the JSON candidate list to stdout.

---

## Arguments

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `intent` | string | unset | Free-form caller hint describing what the agent is looking for. Accepted for caller-side logging only; the handler does not use it for ranking or filtering and the response does not carry it. |
| `roles` | csv string | unset (every role) | Comma-separated role filter (e.g. `button,textbox,checkbox`). Omit for every role. Useful when the agent already knows it only cares about, say, form fields. |
| `limit` | int (string) | `50` | Maximum number of candidates to return. The handler walks the tree in order and stops once it has N. |
| `includeEnrichers` | enum string | `true` | One of `true` (default; `magicFormField`, `magicRoute`, `magicGateResult` and the `wind` fields `breakpoint` and `states`), `false` (no enricher fields), `full` (every enricher field, including every `wind` sub-field). Use `full` when the agent needs the complete wind block; use `false` for the smallest payload. |

All four options pass through to the VM Service handler as string values (no client-side parsing). Empty strings are dropped so the handler sees absent rather than empty when the caller omits an option.

---

## Returns

The VM Service handler returns a JSON envelope; the CLI dumps it to stdout via `jsonEncode`.

**Success envelope (illustrative; `includeEnrichers=true`, single candidate shown):**

```json
{
  "candidates": [
    {
      "ref": "q1",
      "role": "button",
      "label": "Sign in",
      "value": null,
      "bounds": {"x": 120, "y": 400, "w": 240, "h": 48},
      "isEnabled": true,
      "isVisible": true,
      "inViewport": true,
      "occluded": false,
      "magicRoute": "/login",
      "wind": {"breakpoint": "md", "states": "hover"}
    }
  ],
  "count": 1
}
```

Every candidate ships with:

- A re-resolvable `qN` handle (Playwright Locator semantics: every action call re-walks the tree).
- The Semantics `role` (button, textbox, checkbox, link, etc.).
- The Semantics `label` (visible text or explicit a11y label) and its `value`, `null` when empty.
- The widget `bounds` as `{x, y, w, h}`.
- `isEnabled`, `isVisible` (non-empty bounds that overlap the viewport), `inViewport` (`false` when the bounds lie outside the view) and `occluded` (`true` when a hit test at the bounds' centre reaches a widget painted above the candidate instead of the candidate itself; only probed for a visible candidate, so `false` for one that is not).
- `tapOwner`, `{x, y, w, h}`, only on a merged candidate (a `MergeSemantics` boundary) whose bounds' centre is not on its own control: the control's rect, which a `tapir:tap` on the candidate goes to unless `--no-retarget` is passed (#60); `centreHandled: true` means the centre has a tap handler of its own. Absent on every other candidate.
- The enricher fields (`magicFormField`, `magicRoute`, `magicGateResult`, `wind`) as top-level keys when `includeEnrichers` is `true` or `full` and an enricher produced them.

**Error envelope:**

The VM Service handler propagates errors as `ServiceExtensionResponse.error(extensionError, message)`. Common causes: no running app at the recorded URI, `TapirPlugin.install()` never called.

---

## Observe-once-act-many

The Stagehand pattern that gives `tapir:observe` its name:

1. **Observe once.** A single `tapir:observe` call enumerates the interactive surface of the current screen, mints `qN` handles, and returns them in one JSON payload.
2. **Act many.** The agent issues a sequence of `tapir:tap --ref=qN`, `tapir:type --ref=qN`, `tapir:set_checkbox --ref=qN`, etc. against the minted refs WITHOUT re-observing between actions. Each action re-resolves the `qN` handle against the live tree, so the refs survive intermediate rebuilds.

Candidates sharing one label stay distinct through that re-resolution. Each handle carries its position among the nodes that label matched, which lets a list of rows offering the same action be worked row by row while the list is unchanged; a handle reports stale only when fewer same-label nodes remain than its position. `tapir:find` is deliberately different, because there the predicate is one you chose: it answers the first match and reports the total so you can refine it or scope it with `--within`.

The index is a position and not an identity, so it survives neither a row leaving nor a row arriving above it. A row inserted above the list between the observe call and the action (a pull-to-refresh, a lazily built header, a banner carrying the same label) shifts every held handle down by one, and a row removed above it shifts them up by one, silently, because nothing re-checks the node it lands on. Playwright's `nth(i)` behaves the same way. Re-observe after anything that can add or remove a row with that label; only a handle whose position no longer exists is reported stale.

The "no server-side LLM" property is the second half of the pattern: Stagehand-the-product runs an LLM server-side to rank candidates by intent. `tapir:observe` returns the raw candidate list and lets the agent's own LLM rank, so no model context is consumed on the server, and the response is deterministic.

Re-observe only when:

- The agent navigated to a new screen (the handles minted on the previous screen become stale matches).
- The candidate set itself changes (e.g. a modal opens, a list grows or shrinks, a tab switches).
- Same-label rows are reordered (a sort, a filter, a drag to reorder): the held position then selects a different row without any candidate being added or removed.

For incremental state changes on the same screen (clicking a button that disables another button, typing into a field that reveals a new form section), re-resolution on every action call is sufficient; no second `tapir:observe` is needed.

---

## Examples

### 1. Enumerate every interactive widget on the current screen

```bash
dart run tapir tapir:observe
```

Returns up to 50 candidates with the default subset of enricher fields. Useful as the first call after a navigation to discover what is on screen.

### 2. Filter to a single role

```bash
dart run tapir tapir:observe --roles=button --limit=10
```

Limits the response to up to 10 button candidates. Useful when the agent already knows the next action is a tap.

### 3. Observe followed by act-many

```bash
dart run tapir tapir:observe --roles=textbox,button > /tmp/observe.json
# agent reads /tmp/observe.json, decides to type into q1 then tap q2
dart run tapir tapir:type --ref=q1 --text="user@example.com"
dart run tapir tapir:tap --ref=q2
```

No re-observe between the two actions; both `qN` handles re-resolve against the live tree on each call.

---

## Related Documentation

- [tapir:snap](https://anilcancakir.com/tapir/docs/commands/tapir-snap.md): the raw Semantics-tree YAML; richer than `tapir:observe` but with `eN` refs that go stale on rebuild.
- [tapir:find](https://anilcancakir.com/tapir/docs/commands/tapir-find.md): mint a single `qN` handle from a known predicate; pair with `tapir:observe` when the agent already knows what to look for.
- [tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md), `tapir:type`, `tapir:drag`: the action commands that consume the `qN` refs minted by `tapir:observe`.

---

# tapir:tap

Synthesise a tap at the widget identified by a snapshot ref token.

`tapir:tap` is the primary action command: every interactive flow in an agent-driven test starts with a `tapir:snap` (to obtain `eN` refs) followed by one or more `tapir:tap --ref=<eN>` calls. The handler routes through the actionability gate (defunct, enabled, zero rect, off-viewport, stable, receives events) before the pointer event leaves the VM. A gate failure throws `TapirActionabilityException` and surfaces as a structured error; the agent re-snaps or re-finds rather than silently retrying.

- [Synopsis](#synopsis)
- [Arguments](#arguments)
- [Returns](#returns)
- [Actionability gate](#actionability-gate)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:tap --ref=<eN|qN>
                                   [--includeSnapshot]
                                   [--snapshot=full|diff|none]
                                   [--[no-]checkStable]
                                   [--[no-]checkReceivesEvents]
                                   [--[no-]retarget]
                                   [--until=<text>]
                                   [--untilTimeoutMs=<n>]
```

`tapir:tap` requires a running Flutter session (`CommandBoot.connected`). It dials the VM Service URI, calls `ext.tapir.tap`, and prints either a one-line success or the post-tap JSON depending on `--includeSnapshot` / `--until`.

The pointer is dispatched at the target's LIVE centre: the handler re-resolves the element's current bounding rect immediately after the actionability gate passes (falling back to the cached snapshot rect only for slivers / detached render objects), so a tap still lands on a button whose host rebuilt it into a shifted slot between `tapir:snap` and `tapir:tap`.

---

## Arguments

| Option | Type | Default | Required | Description |
|--------|------|---------|----------|-------------|
| `--ref` | string | (none) | yes (`mandatory: true`) | Snapshot ref token (e.g. `e1` from a prior `tapir:snap`, or `q1` from a prior `tapir:find`). Empty values trigger a CLI-side error with exit code `1` before the VM Service call is made. |
| `--includeSnapshot` | flag | `false` | no | Embed the post-tap snapshot YAML in the response. Useful when the tap is expected to trigger a navigation or modal and the next agent step needs the fresh tree. |
| `--snapshot` | `full`, `diff` or `none` | (none) | no | Print the post-tap snapshot after the one-line summary and override `--includeSnapshot`. `full` is the whole tree; `diff` is only the lines the tap changed since your last unfiltered snapshot (a `tapir:snap` or an earlier action), as `- old` then `+ new` per changed row, `+ ` for an added row, `- ` for a removed one, and a `(K of N lines changed)` footer; `none` prints nothing. With no baseline yet, `diff` returns the full text. Over MCP this is the `snapshot` enum on `tapir_tap`. |
| `--checkStable` | flag | `true` | no | Run the Stable (2-frame rect-unchanged) actionability gate. Disable when targeting an animating widget that intentionally rebuilds across frames. |
| `--checkReceivesEvents` | flag | `true` | no | Run the Receives-Events (front-most hit-test) actionability gate. Disable when targeting a widget that is intentionally occluded by an overlay you also want to interact with. |
| `--retarget` | flag | `true` | no | Send a tap on a merged boundary to its one labelled control. `--no-retarget` taps the boundary centre (see below). |
| `--until` | string | (none) | no | After the tap settles, poll the live element tree (same loop as `tapir:wait`) for a `Text` whose data equals this value, up to the `--untilTimeoutMs` timeout (default 3000ms), and add an `untilMatched` boolean to the response reporting whether it appeared. Use to confirm a navigation / state change in one call instead of a separate `tapir:wait`. Off by default, which keeps the response shape unchanged. Setting `--until` always prints the JSON envelope (so `untilMatched` is visible) regardless of `--includeSnapshot`. |
| `--untilTimeoutMs` | int | `3000` | no | Timeout in milliseconds for the `--until` poll. Ignored when `--until` is not set. |

The two `check*` flags default to `true`. Disable them with the inverted form (`--no-checkStable`, `--no-checkReceivesEvents`) when the target genuinely should not be subject to that precondition.

---

## Returns

`tapir:tap` returns an integer exit code via `Future<int>`:

| Exit code | Meaning |
|-----------|---------|
| `0` | Tap synthesised. The handler emits either `Tapped <ref>` (default) or the full JSON envelope when `--includeSnapshot` is set. |
| `1` | `--ref` was missing or empty (CLI-side guard fires before the VM Service call). |
| non-zero | VM Service handler returned `ServiceExtensionResponse.error`. Common causes: ref not found in the registry, actionability gate failure, no running app at the recorded URI. |

**Success envelope (default, `--includeSnapshot` off):**

```
✓ Tapped e2
```

When the `effect` block reports no change, the one-line form says so rather than
claiming a plain success:

```
✓ Tapped e2 (no observable change)
```

**Success envelope (`--includeSnapshot` on):**

```json
{
  "snapshot": "- text \"Welcome\"\n- button \"Continue\" [ref=e2]\n...",
  "ref": "e2"
}
```

**The `effect` block, on every response:**

```json
{
  "ref": "e2",
  "effect": { "kind": "treeChanged", "changed": true }
}
```

`changed` is `true` when the target's route or its own semantics subtree differed after the tap, `false` when nothing observable changed. The signal is deliberately scoped to the TARGET rather than the whole tree, so unrelated background churn does not read as "something happened", and a counter button whose own label increments does.

`changed: false` means nothing changed within that measured scope (the target's own semantics subtree and the route). It is not proof that the handler did not fire: a handler that updates state elsewhere on the screen, or one that has no semantic effect, also reads `false`. Check the intended result with `tapir:snap` before retrying, because a tap is not safe to repeat blindly.

**Stale `eN` refs.** When the widget behind an `eN` ref was rebuilt since the snapshot, the tap relocates it by the label and index the snapshot bound to the ref, provided the live tree has the same number of nodes with that label. The response then lists the ref: `"reresolved": ["e2"]`. With a different count the ref fails as `defunct (element no longer mounted)` and the agent re-snaps. The bound query has no role, so a node of another role with the same label in the same position could be matched.

**A merge boundary taps its own control (#60).** A `MergeSemantics` boundary (a player, a row or a card that merges a label and a button) taps at its own centre, which can belong to another handler (a full-frame stage that pauses on any tap) while the gate still reports `confirmed`. When exactly one labelled control owns the merged label (a `Semantics` whose label is part of it, with an `onTap` or `button`) and a hit test at its centre reaches it, the pointer goes there and the response carries `"retargeted": {"from": {"x", "y"}, "to": {"x", "y"}, "ownerRect": {"left", "top", "width", "height"}}`; the summary says `Tapped e7 on its control at (x, y), not the merged centre (x, y)`. When the centre had a tap handler of its own (a stage or a row that opens) the response adds `"centreHandled": true` inside `retargeted` and the summary names `--no-retarget`: pass `--no-retarget` to tap that handler instead of the control.

When that is not safe (several labelled candidates, or the control is covered by something else or lies outside the viewport) the tap stays at the centre and the response carries `"tapPointOutsideOwner": {"ownerRect": {...}, "point": {"x", "y"}}`, with one warning line on stderr naming both. Treat it as "this tap may have hit something else": check the result with `tapir:snap`, or target the control's own ref. The gate is unchanged. `tapir:snap` and `tapir:observe` show the control's rect before any tap (`tapOwner`). Only `tap` retargets; `hover`, `dblclick`, `right_click`, `triple_click` and `drag` still use the centre.

**Hidden window.** A hidden or minimised desktop app is woken before the tap and the response carries `"framesForced": true`; a tap against a window that cannot be woken carries a `warnings` block instead. On a web session started with `--cdp-port`, the CLI sends CDP `Page.bringToFront` once when the answer carries a web `warnings` block (or the call fails and the tab reports `hidden`). A tap is never repeated, because its gesture may already have fired: a stderr notice tells you to run `tapir:snap` to see what it did. See [Frame production](https://anilcancakir.com/tapir/docs/reference/frame-production.md).

**Error envelope (actionability gate failure):**

The message format is `Widget ref=<ref> is not actionable: <reason>` where `<reason>` is one of `defunct (...)`, `not enabled`, `zero rect`, `off-viewport (rect=..., viewport=...)`, `not stable (rect changed by Xpx)`, or `obscured by other widget (top=...)`. The agent branches by substring-matching on `<reason>`; the full vocabulary is documented under [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md#failure-reason-substrings).

---

## Actionability gate

The actionability gate runs six preconditions in order: defunct (Step 0, preflight: render-object still attached), enabled (Tristate.isFalse fails), zero-rect (zero width or height), off-viewport (auto-`showOnScreen` first when a Scrollable ancestor exists), stable (2-frame rect drift ≤ 0.5px; opt out via `--no-checkStable`), and receives-events (hit-test path includes the target or descendant; opt out via `--no-checkReceivesEvents`). The full reference lives at [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md).

Two of the six run only while their CLI flags are enabled (both default to on):

- `checkStable`: the rect is unchanged across two consecutive frames.
- `checkReceivesEvents`: the hit-test at the rect centre resolves to the target widget (that is, no overlay is intercepting the tap).

See [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md) for the full ordering rationale and how new preconditions can be appended without breaking pinned agent prompts.

---

## Examples

### 1. Tap a button by its snapshot ref

```bash
dart run tapir tapir:snap > /tmp/snap.yaml
# locate the button's eN in /tmp/snap.yaml
dart run tapir tapir:tap --ref=e2
```

Expected output (illustrative):

```
✓ Tapped e2
```

### 2. Tap and capture the post-tap tree in one round trip

```bash
dart run tapir tapir:tap --ref=e2 --includeSnapshot
```

Expected output (illustrative; abbreviated):

```json
{"snapshot":"- text \"Detail page\"\n...","ref":"e2"}
```

### 3. Tap an intentionally-animating widget

```bash
dart run tapir tapir:tap --ref=e5 --no-checkStable
```

Skips the 2-frame stable check for an animating loader / shimmer / spinner that the agent legitimately wants to interact with.

### 4. Read whether the tap had an observable effect

```bash
dart run tapir tapir:tap --ref=e2 --includeSnapshot
```

Expected output (illustrative):

```json
{"ref":"e2","effect":{"kind":"treeChanged","changed":true},"snapshot":"..."}
```

No flag is needed: the block is on every response. Use it as a post-condition assertion in agent-driven flows, and read it before concluding the app is broken.

### 5. Tap and wait for the expected text to appear

```bash
dart run tapir tapir:tap --ref=e2 --until="Welcome back"
```

Expected output (illustrative):

```json
{"ref":"e2","untilMatched":true}
```

After the tap, the handler polls the element tree for a `Text("Welcome back")` up to 3000ms. `untilMatched:false` means the text never appeared within the window (the tap did not produce the expected navigation / state change). This folds a `tapir:wait --text=...` into the tap call so the agent confirms the outcome in one round trip.

---

## Related Documentation

- [tapir:snap](https://anilcancakir.com/tapir/docs/commands/tapir-snap.md): produce the `eN` refs that `tapir:tap` consumes.
- [tapir:find](https://anilcancakir.com/tapir/docs/commands/tapir-find.md): mint a re-resolvable `qN` handle that survives rebuilds; pass it as `--ref=q1`.
- [tapir:observe](https://anilcancakir.com/tapir/docs/commands/tapir-observe.md): structured candidate list when the agent needs more than the raw Semantics tree.
- [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md): full ordering and message format the agent branches on.

---

# tapir:fill

Focus, clear, type, and settle a text field in a single call.

`tapir:fill` promotes the manual focus + clear + type + settle + stale-retry dance into one first-class command, so an agent no longer re-discovers the sequence (and its frame-await + retry subtleties) on every form.

Internally `tapir:fill` composes the existing gated `ext.tapir.focus`, `ext.tapir.clear`, and `ext.tapir.type` handlers verbatim, so it inherits the full 6-step actionability gate, IME focus, `onChanged` / form-validator firing (via `userUpdateTextEditingValue`), and post-action snapshot semantics. It re-resolves the ref before each attempt and retries the whole sequence once if the ref goes stale mid-fill.

- [Synopsis](#synopsis)
- [Arguments](#arguments)
- [Returns](#returns)
- [Which field was written](#which-field-was-written)
- [Stale-retry](#stale-retry)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:fill --ref=<eN|qN> --text=<value>
                                    [--includeSnapshot]
                                    [--snapshot=full|diff|none]
                                    [--[no-]checkStable]
                                    [--[no-]checkReceivesEvents]
```

`tapir:fill` requires a running Flutter session (`CommandBoot.connected`). It dials the VM Service URI, calls `ext.tapir.fill`, and prints either a one-line success (`Filled <ref>`) or the full JSON envelope when `--includeSnapshot` is set.

---

## Arguments

| Option | Type | Default | Required | Description |
|--------|------|---------|----------|-------------|
| `--ref` | string | (none) | yes (`mandatory: true`) | Text-field ref token (`e1` from a prior `tapir:snap`, or `q1` from a prior `tapir:find`). Empty values trigger a CLI-side error with exit code `1` before the VM Service call. |
| `--text` | string | (none) | yes (`mandatory: true`) | Value to set. Replaces existing content. Pass an empty string to clear the field. |
| `--includeSnapshot` | flag | `false` | no | Embed the post-fill snapshot YAML in the response. |
| `--snapshot` | `full`, `diff` or `none` | (none) | no | Print the post-fill snapshot after the one-line summary and override `--includeSnapshot`. `diff` prints only the lines the fill changed since your last unfiltered snapshot (a `tapir:snap` or an earlier action), as `- old` then `+ new` per changed row, with a `(K of N lines changed)` footer; with no baseline yet it prints the full text. Over MCP this is the `snapshot` enum on `tapir_fill`. |
| `--checkStable` | flag | `true` | no | Run the Stable (2-frame rect-unchanged) actionability gate during the type step. |
| `--checkReceivesEvents` | flag | `true` | no | Run the Receives-Events (front-most hit-test) actionability gate during the type step. |

---

## Returns

| Exit code | Meaning |
|-----------|---------|
| `0` | Field filled. Emits `Filled <ref>` (default) or the full JSON envelope when `--includeSnapshot` or `--json` is set. |
| `1` | `--ref` or `--text` was missing (CLI-side guard fires before the VM Service call); OR, in the one-line mode, `effect.verified` came back `false`. |
| non-zero | VM Service handler returned an error: ref not found, actionability gate failure, no editable under the ref, or a stale handle that did not recover on retry. |

**A fill that did not stick.** The response carries `effect.verified`, read back from the live controller after the two-frame settle, so a formatter or echo that reverts the write a frame later reports `verified: false` too. A green tick only means the text was dispatched: an input formatter that trimmed or rejected it leaves the field holding something else. In the one-line mode that case prints an error naming what the field holds and exits `1`:

```
Fill not verified: e7 holds "12", not the text that was typed ("12abc")
```

With `--includeSnapshot` or `--json` the JSON envelope is printed and the exit code stays `0`; read `effect.verified` and `effect.value` yourself.

**Success envelope (`--includeSnapshot` on):**

```json
{
  "ref": "e7",
  "text": "alice@example.com",
  "filled": true,
  "snapshot": "- textbox \"Email\" [ref=e7]\n  typeable: true\n..."
}
```

---

## Which field was written

`tapir:fill` resolves the target field once and uses it for focus, clear and type, so the three steps cannot land in different fields. The response says which one in `effect.target`:

```json
"effect": {
  "kind": "text", "verified": true, "value": "alice@example.com",
  "target": { "matchKind": "overlap", "label": "Email", "rect": { "x": 20, "y": 200, "width": 335, "height": 56 } }
}
```

`matchKind` is `overlap` (the field overlapping the ref's rect the most: the ref is the field), `nearest` (nothing overlaps, so the field nearest the ref's centre was written) or `element` (the ref had no rect, so the first editable under its element was used). Label and static-text handles keep the `nearest` fallback, since a label above its field is how you address that field. On `nearest` the CLI prints a warning naming the field and its rect, so a fill into a neighbouring field is visible.

A ref whose node is an interactive control other than a text field is refused instead of falling back to the nearest field (a dropdown, checkbox or button ref used to wipe and rewrite whichever field sat closest). The error reads `ref e9 is a button, not a text field`, with the role being `button`, `checkbox`, `radio`, `switch`, `slider` or `link`. Target the field itself, or use `tapir:tap`, `tapir:select_option` or `tapir:set_checkbox`. The same rules apply to `tapir:type` and `tapir:clear`.

---

## Stale-retry

`tapir:fill` re-resolves the ref via the registry before each attempt. When a `q<N>` handle's stored predicates transiently miss (the field is rebuilding mid-fill), the resolver reports a stale handle; `tapir:fill` re-runs the whole resolve + focus + clear + type sequence once so the second pass walks the now-settled tree. A second stale outcome surfaces a typed `stale` error envelope so the agent re-snaps or re-finds rather than looping. Prefer a `q<N>` handle (from `tapir:find`) for fields that may rebuild between snapshot and fill; the retry then re-resolves cleanly.

---

## Examples

### 1. Fill an email field in one call

```bash
dart run tapir tapir:snap > /tmp/snap.yaml
# locate the email field's eN in /tmp/snap.yaml
dart run tapir tapir:fill --ref=e7 --text="alice@example.com"
```

```
✓ Filled e7
```

### 2. Clear a field

```bash
dart run tapir tapir:fill --ref=e7 --text=""
```

### 3. Fill a re-resolvable handle that survives rebuilds

```bash
dart run tapir tapir:find --key="email-input"   # -> q1
dart run tapir tapir:fill --ref=q1 --text="alice@example.com" --includeSnapshot
```

---

## Related Documentation

- [tapir:snap](https://anilcancakir.com/tapir/docs/commands/tapir-snap.md): produce the `eN` refs that `tapir:fill` consumes; text fields collapse to a single `typeable: true` node.
- [tapir:find](https://anilcancakir.com/tapir/docs/commands/tapir-find.md): mint a re-resolvable `qN` handle that survives rebuilds; pass it as `--ref=q1`.
- [tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md): focus a field by tapping; `tapir:fill` does the focus for you.
- [Reference: Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md): the gate the composed type step runs.

---

# tapir:screenshot

Capture a screenshot of the running Flutter app to a file.

On web targets where dowel was started with `--cdp-port`, the command routes through Chrome DevTools Protocol `Page.captureScreenshot` for a full-viewport capture (bypassing the in-isolate `ext.tapir.screenshot` extension, which hangs under CanvasKit+DWDS, issue #13). On native targets the VM Service handler walks the render tree to find the `RepaintBoundary` that `TapirPlugin.install()` wrapped around the app root, calls `toImage`, and returns a base64-encoded PNG or JPEG. The CLI decodes the payload and writes the bytes to the path supplied by `--output`.

JPEG is the default for size: a typical Flutter web screen renders in ~30 KB at quality 70. Switch to PNG when the agent needs lossless pixels for a diff comparison.

> **Scope:** `tapir:screenshot` captures the whole viewport, or one widget with `--ref` (and `--rect`). The CDP fallback applies to the CLI command only; the `tapir_screenshot` MCP tool dispatches `ext.tapir.screenshot` in-isolate and can still time out on web, so prefer the CLI for web screenshots.

- [Synopsis](#synopsis)
- [Arguments](#arguments)
- [Returns](#returns)
- [Format and quality](#format-and-quality)
- [CDP path vs. in-isolate path](#cdp-vs-extension)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:screenshot --output=<path>
                                          [--format=jpeg|png]
                                          [--quality=<1-100>]
                                          [--ref=<eN|qN>]
                                          [--rect=<x,y,w,h>]
```

`tapir:screenshot` requires a running Flutter session (`CommandBoot.connected`). It dials the VM Service URI. When `cdpPort` is set in state (a web target), the command uses CDP `Page.captureScreenshot`; otherwise it calls `ext.tapir.screenshot`, decodes the base64 payload, and writes the resulting bytes to the supplied output path.

---

## Arguments

| Option | Abbr | Type | Default | Required | Description |
|--------|------|------|---------|----------|-------------|
| `--output` | `-o` | string (path) | (none) | yes (`mandatory: true`) | Output file path. Resolved relative to the CWD. The directory must already exist. |
| `--format` | none | enum | inferred from `--output`, else `jpeg` | no | One of `jpeg`, `png`. Constrained by `allowed: ['jpeg', 'png']` so any other value errors out at parse time. See [Format and quality](#format-and-quality) for the inference. |
| `--quality` | none | int (string-parsed) | `70` | no | JPEG quality, range 1-100. Ignored for PNG. Falls back to `70` when the value fails `int.tryParse`. |
| `--ref` | none | string | (none) | no | Capture only this widget. An `e<N>` token from `tapir:snap` or a `q<N>` handle from `tapir:find`. Omit for the whole viewport. |
| `--rect` | none | string `x,y,w,h` | (none) | no | Sub-rect in logical pixels, relative to the ref's top-left. Requires `--ref`. |

The `--output` guard fires before the VM Service call; an empty or missing path returns exit code `1` with `Missing --output=<path>.`. `--rect` without `--ref` returns `1` as well, rather than quietly capturing the whole frame: a sub-rect is meaningless without the widget it is relative to, and an image that looks right but answers a different question is the failure this flag exists to remove.

---

## Returns

`tapir:screenshot` returns an integer exit code via `Future<int>`:

| Exit code | Meaning |
|-----------|---------|
| `0` | Screenshot captured and written. The command prints `Wrote <N> bytes (<K> KB, <format>) to <path>` where `<N>` is the size of the decoded image (useful for spotting empty buffers without inspecting the file). |
| `1` | `--output` was missing or empty, or `--rect` was given without `--ref` (CLI-side guards); OR the VM Service handler returned a response without a `base64` field. |

**Success line (CLI side):**

```
✓ Wrote 30912 bytes (30.2 KB, jpeg) to /tmp/dashboard.jpeg
```

**VM Service envelope (handler side):**

```json
{ "base64": "<base64-encoded image bytes>" }
```

The CLI calls `base64Decode(base64Str)` and writes the resulting bytes to `output`. No additional metadata (width, height, mime) is returned today; the agent infers shape from the file on disk if needed.

---

## Format and quality

When `--format` is not given, the format follows the `--output` extension: `.png` captures PNG, `.jpg` and `.jpeg` capture JPEG, so a `.png` file never holds JPEG bytes. Any other extension falls back to `jpeg`. An explicit `--format` always wins; when it disagrees with the extension (`--output=a.png --format=jpeg`) the command writes the file as asked and warns on stderr that the file will hold the other format's bytes.

- **jpeg** (default): on native targets the VM Service handler encodes via the `image` package's JPEG encoder at the supplied quality; on web (CDP path) the `format` + `quality` params are forwarded directly to `Page.captureScreenshot`. Quality 70 is a Playwright-aligned default; bump to 90 for visual-regression diffs, drop to 40 for quick sanity checks.
- **png**: lossless, larger files (typically 5x JPEG at quality 70). The `--quality` value is ignored.

On a hidden or minimised desktop window tapir wakes the app before the in-isolate capture (the response carries `framesForced: true`), so the image is a fresh frame rather than the last cached one. The CDP path on web is unaffected by the lifecycle. See [Frame production](https://anilcancakir.com/tapir/docs/reference/frame-production.md).

The handler never resizes the screenshot; the captured image matches the running viewport's pixel dimensions (logical size times DPR). To capture at a controlled viewport, run `tapir:resize` or `tapir:device` first.

---

## CDP path vs. in-isolate path

| Condition | Path taken |
|---|---|
| No `cdpPort` in state (native target) | `ext.tapir.screenshot` (in-isolate) |
| `cdpPort` set (web target) | CDP `Page.captureScreenshot` |

The CDP path sends `Page.enable` first (required by Chrome before `Page.captureScreenshot`), then `Page.captureScreenshot` with `fromSurface: true`. The resulting dimensions reflect the `Emulation.setDeviceMetricsOverride` still in force, which is only one whose DevTools session is still open (`tapir:resize --hold`); Chrome drops it when the session that sent it detaches.

**`--ref` works on both paths, by different routes.** In-isolate, `ext.tapir.screenshot` rasterises the ref's own render-object region directly. Over CDP there is no notion of a Flutter ref, so the command first asks the extension for the region in geometry mode, which resolves `--ref` / `--rect` and returns the rect without rasterising (the rasterise is exactly what hangs on this target), then passes it to `Page.captureScreenshot` as a `clip`. Flutter logical pixels and CDP CSS pixels are the same unit, so the rect crosses over unscaled.

One extra round-trip, and one definition of what a ref covers rather than two. When the ref no longer resolves the command exits `1` instead of falling back to a full-frame capture.

---

## Examples

### 1. Capture the current screen as JPEG

```bash
dart run tapir tapir:screenshot --output=/tmp/screen.jpeg
```

Expected output (illustrative):

```
✓ Wrote 30912 bytes (30.2 KB, jpeg) to /tmp/screen.jpeg
```

### 2. Capture losslessly for a visual diff

```bash
dart run tapir tapir:screenshot --output=/tmp/screen.png --format=png
```

Useful when the agent compares against a baseline PNG via `image_diff` or `pixelmatch`.

### 3. Capture at high quality JPEG

```bash
dart run tapir tapir:screenshot --output=/tmp/hifi.jpeg --quality=92
```

### 4. Capture after a controlled resize

```bash
# The override lives only as long as the session that sent it: hold it.
dart run tapir tapir:resize --width=1440 --height=900 --hold &
dart run tapir tapir:screenshot --output=/tmp/desktop.jpeg
```

### 5. Capture one component instead of the whole screen

```bash
dart run tapir tapir:snap | grep 'PricingCard'
# - region "PricingCard" [ref=e42] ...
dart run tapir tapir:screenshot --output=/tmp/card.png --format=png --ref=e42
```

Reach for this whenever the question is about one component. A full-screen capture of a tall page costs far more tokens than the region under review, and it buries the thing you are actually checking. It also removes the resize dance: without `--ref`, seeing a component below the fold means growing the viewport to something no device has, capturing, and putting the height back.

### 6. Capture part of a component

```bash
# The top-left 200x60 of the card, in logical pixels relative to its own origin.
dart run tapir tapir:screenshot --output=/tmp/card-header.png --ref=e42 --rect=0,0,200,60
```

---

## Related Documentation

- [tapir:snap](https://anilcancakir.com/tapir/docs/commands/tapir-snap.md): the structured-text counterpart; agents typically pair `tapir:snap` and `tapir:screenshot` to read both the Semantics tree and the pixels in a single round.
- [tapir:hot_reload_and_snap](https://anilcancakir.com/tapir/docs/commands/index.md#hot-reload-and-snap): captures snapshot + screenshot + recent exceptions in one round trip.
- [tapir:resize](https://anilcancakir.com/tapir/docs/commands/index.md#cdp) and [tapir:device](https://anilcancakir.com/tapir/docs/commands/index.md#cdp): control the viewport that `tapir:screenshot` captures from on web targets.

---

# tapir:reset_overlays

Return the app to a known clean screen by dismissing every modal, pressing Escape, and tapping a Cancel/Dismiss affordance as a fallback.

`tapir:reset_overlays` promotes the manual overlay-reset dance (dismiss + Escape + Cancel-tap) into one idempotent command, so an agent can reliably clear stuck dialogs, bottom sheets, dropdown menus, and barrier modals between flows without composing the steps by hand.

- [Synopsis](#synopsis)
- [Layers](#layers)
- [Returns](#returns)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:reset_overlays
```

`tapir:reset_overlays` requires a running Flutter session (`CommandBoot.connected`). It takes no arguments, calls `ext.tapir.reset_overlays`, and prints the JSON result. It is idempotent: calling it when nothing is open is a safe no-op.

---

## Layers

Three escalating layers run in order, each a no-op when the prior already cleared the overlays:

1. **Dismiss modals**: pops every `PopupRoute` (dialogs, bottom sheets, popups) across every `NavigatorState`, reusing the same `dismissAllModals` path as `tapir:modal`. The page navigation stack is never touched.
2. **Escape key**: delivers an `Escape` key down + up through the binding's `onKeyData` (the path real key data takes, so the focus tree hears it), dismissing overlays driven by the dismiss shortcut that are NOT `PopupRoute`s (custom `OverlayEntry` panels, dropdown menus closed via `Shortcuts`).
3. **Cancel/Dismiss tap**: only attempted when an overlay still appears present. Finds the first tappable Semantics node whose label matches `Cancel`, `Dismiss`, `Close`, `OK`, or `Done` (case-insensitive) and synthesises a tap at its centre, for modal barriers that require an explicit affordance to close.

---

## Returns

| Exit code | Meaning |
|-----------|---------|
| `0` | Reset attempted. Emits the JSON result. |
| non-zero | VM Service handler returned an error (no running app at the recorded URI, unexpected failure). |

**Success envelope:**

```json
{
  "popped": 2,
  "escaped": true,
  "dismissTapped": false
}
```

- `popped`: number of `PopupRoute`s dismissed by layer 1.
- `escaped`: whether the Escape key press was dispatched.
- `dismissTapped`: whether layer 3 tapped a Cancel/Dismiss affordance.

On a clean tree all three indicate no work was done (`popped: 0`, `dismissTapped: false`), confirming idempotency.

---

## Examples

### 1. Reset overlays between test flows

```bash
dart run tapir tapir:reset_overlays
```

```json
{"popped":1,"escaped":true,"dismissTapped":false}
```

### 2. Speculative reset before navigating

```bash
dart run tapir tapir:reset_overlays
dart run tapir tapir:navigate --route=/dashboard
```

Safe to call even when nothing is open; the no-op path returns `popped: 0`.

---

## Related Documentation

- [tapir:modal](https://anilcancakir.com/tapir/docs/commands/index.md#navigation): the underlying dismiss-modals path (the `tapir_dismiss_modals` MCP tool); `tapir:reset_overlays` adds Escape + Cancel-tap fallback on top.
- [tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md): tap a specific Cancel button by ref when you want precise control.
- [tapir:snap](https://anilcancakir.com/tapir/docs/commands/tapir-snap.md): re-snapshot after a reset; refs from before the reset are stale.

---

# tapir:perf_begin

Open a performance measurement session around an interaction you are about to drive.

`tapir:perf_begin` zeroes the frame buffer and the wind and magic counters and records the liveness baseline that `tapir:perf_end` judges the run against. In `attribution` mode (the default) it also switches Flutter's build profiling on; in `timing` mode it touches no profiling flag at all. Nothing is measured until you call it, and the instrumentation costs real time, so keep every session tight: begin, drive one interaction, end.

- [Synopsis](#synopsis)
- [Modes](#modes)
- [What it turns on](#what-it-turns-on)
- [Returns](#returns)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:perf_begin [--mode=attribution|timing] [--phases] [--json]
```

`tapir:perf_begin` requires a running Flutter session (`CommandBoot.connected`) and calls `ext.tapir.perf_begin`.

| Flag | Default | Meaning |
|------|---------|---------|
| `--mode` | `attribution` | `attribution` profiles builds for blocks, self time and counters. `timing` touches no profiling flag and reports frame timings only. |
| `--phases` | `false` | Also profile layout and paint, not just builds. The span volume multiplies, so reach for it when builds alone did not explain the cost. Rejected with `--mode=timing`. |
| `--json` | `false` | Print the raw envelope instead of the one-line summary. |

---

## Modes

The profiling flags that make attribution possible inflate every duration they wrap; Flutter's own docs call the overhead significant relative to the work measured. So one session cannot both attribute and time honestly:

- **`attribution`** answers "what did this interaction spend its time on": blocks ranked by self time, counts per painted frame, wind and magic counters, insights. Rank by its milliseconds; do not quote them.
- **`timing`** answers "how long did the frames take": no flag is touched, the report carries frame timings only, and its milliseconds are the ones to compare between a before and an after.

## What it turns on

In `timing` mode only step 4 runs; every flag is left where it was.

1. `FlutterTimeline.debugCollectionEnabled` first. Both `startSync` and `finishSync` check that flag, so enabling the build flags ahead of it would push a finish with no matching start.
2. `debugProfileBuildsEnabled` and `debugProfileBuildsEnabledUserWidgets`, from `package:flutter/widgets.dart`.
3. With `--phases`, `debugProfileLayoutsEnabled` and `debugProfilePaintsEnabled`, from `package:flutter/rendering.dart`. Two libraries, one session.
4. The session-begin hook the host wired, called with the session's mode: it zeroes wind's counters, clears the crumbs frame buffer, and turns wind's counting on in `attribution` mode only (counting sits on wind's hottest path and would inflate the milliseconds `timing` mode exists to report). Without the hook (no `magic_devtools` in the app) those sections come back empty and the frame summary reports zero frames.

Each flag's prior value is saved in the session. `tapir:perf_end` restores those values rather than forcing `false`, so a host that had build profiling on for its own reasons gets it back.

---

## Returns

| Exit code | Meaning |
|-----------|---------|
| `0` | Session open. |
| non-zero | VM Service handler returned an error (no running app at the recorded URI). |

**Success envelope:**

```json
{
  "sessionToken": "perf-1",
  "mode": "attribution",
  "phases": true,
  "livenessBaseline": 412,
  "restartedPreviousSession": false
}
```

- `sessionToken` names the session in the matching `tapir:perf_end` payload and is the `--token` `tapir:perf_insight` accepts.
- `mode` echoes the mode the session opened in. An unknown mode, or `--phases` with `--mode=timing`, is rejected before anything is touched.
- `livenessBaseline` is the frame-liveness counter as it read at begin. `tapir:perf_end` refuses to report when it has not moved past this.
- `restartedPreviousSession` is `true` when a session was already open. A begin restarts rather than fails, so a `perf_end` that never landed (a crash, a dropped connection) does not strand the profiling flags on; the restart restores the previous session's flags before saving the current ones.

---

## Examples

### 1. Build attribution for one scroll

```bash
dart run tapir tapir:perf_begin
# drive the interaction (scroll, tap, navigate)
dart run tapir tapir:perf_end --json
```

### 2. Builds did not explain it, so add the phases

```bash
dart run tapir tapir:perf_begin --phases --json
```

```json
{"sessionToken":"perf-2","mode":"attribution","phases":true,"livenessBaseline":412,"restartedPreviousSession":false}
```

### 3. Time the same interaction without the profiling tax

```bash
dart run tapir tapir:perf_begin --mode=timing
# drive the same interaction
dart run tapir tapir:perf_end --json | jq '.summary.frames'
```

---

## Related Documentation

- [tapir:perf_end](https://anilcancakir.com/tapir/docs/commands/tapir-perf-end.md): closes the session, reports ranked insights, restores every flag.
- [tapir:perf_insight](https://anilcancakir.com/tapir/docs/commands/tapir-perf-insight.md): the rows behind one insight.
- [Frame production](https://anilcancakir.com/tapir/docs/reference/frame-production.md): why a backgrounded tab measures nothing, and the refusal that says so.
- [tapir:snap](https://anilcancakir.com/tapir/docs/commands/tapir-snap.md): confirm the surface you mean to measure is actually on screen first.

---

# tapir:perf_end

Close the measurement session opened by `tapir:perf_begin` and read a bounded report of frames, blocks, counters and insights.

The report holds frame percentiles against a stated budget, blocks ranked by self time and by count per painted frame, wind and magic counters, and ranked insights you can drill into with `tapir:perf_insight`. The command also restores every profiling flag the session changed, so a session you forget to close is the one that taxes every later frame.

- [Synopsis](#synopsis)
- [Returns](#returns)
- [Insights](#insights)
- [The refusal](#the-refusal)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:perf_end [--json]
```

`tapir:perf_end` requires a running Flutter session (`CommandBoot.connected`) and calls `ext.tapir.perf_end`. It takes no arguments beyond `--json`. Without a prior `tapir:perf_begin` it returns a typed error: the session carries the flag values to restore and the liveness baseline the report is judged against, and neither can be reconstructed afterwards.

`ext.tapir.perf_end` itself also accepts `full: 'true'`, which the command does not pass. It lifts every cut: the block rankings, counter breakdowns, route transitions and insights carry every row, and `omitted` reads all zeros. That form is for a runner that writes the report to a file; the bounded default is the one to read.

---

## Returns

| Exit code | Meaning |
|-----------|---------|
| `0` | Report returned. |
| `1` | The run was REFUSED (see below), or the handler returned an error. |

**Success envelope** (bounded to about 6 KB; the rows behind each insight stay behind `tapir:perf_insight`):

```json
{
  "sessionToken": "perf-1",
  "refused": false,
  "mode": "attribution",
  "env": {"platform": "macOS", "isWeb": true, "buildMode": "debug", "renderer": "canvaskit", "semanticsEnabled": true, "phases": false},
  "coverage": {"framesDrawn": 45, "framesSummarized": 45, "framesOutsideSession": 2, "complete": true, "missing": []},
  "summary": {
    "durationMs": 2310.4,
    "budgetMs": 16.7,
    "frames": {
      "count": 45, "painted": 45, "dropped": 0,
      "overBudget": 3, "overBudgetBuild": 3, "overBudgetRaster": 0,
      "buildMs": {"p50": 3.1, "p90": 8.1, "p99": 31.2, "worst": 31.2},
      "rasterMs": {"p50": 1.2, "p90": 1.9, "p99": 2.4, "worst": 2.4}
    },
    "blocksBySelf": [{"name": "MonitorRow", "selfMs": 21.4, "frames": 12}],
    "blocksByCount": [{"name": "WText", "count": 540, "perFrame": 12.0}],
    "routeTransitions": [{"route": "/monitors", "ms": 118.2}]
  },
  "counters": {
    "columns": ["name", "count", "perFrame"],
    "wind": {"cacheHits": {"count": 812, "perFrame": 18.04}, "cacheSize": 64, "widgetBuilds": [["WDiv", 402, 8.93]]},
    "magic": {"controllerNotifies": [["MonitorController", 12, 0.27]]}
  },
  "insights": [
    {
      "id": "I1",
      "severity": "warn",
      "title": "3 of 45 frames over the 16.7ms budget",
      "evidence": {"metric": "framesOverBudget", "value": 3, "perFrame": 0.07, "threshold": {"budgetMs": 16.7, "errorShare": 0.1}},
      "estimatedSavingsMs": 29.4,
      "nextStep": "Build-bound: drill in for the worst frames and their self-time blocks."
    }
  ],
  "omitted": {"blocksBySelf": 212, "blocksByCount": 212, "routeTransitions": 0, "wind.widgetBuilds": 9, "insights": 0}
}
```

- `env` says where the numbers came from, read in the app: `buildMode` from `kProfileMode` / `kDebugMode`, and `semanticsEnabled`, which is `true` whenever tapir is installed because tapir holds a semantics handle for the whole process. `renderer` is what the `rendererReader` pointer answers: `canvaskit` or `skwasm` on web, `unknown` elsewhere until a host assigns one (a `tapir:perf_run` run fills it from the launch log).
- `coverage` says whether the summary describes every frame the engine drew. `framesDrawn` comes from the liveness counter, which a post-frame callback increments once per frame; `framesSummarized` counts the records Flutter's `onReportTimings` delivered, and Flutter batches those. The summary describes the session window only: a frame drawn before `perf_begin` whose timings arrived late, and the idle frame `perf_end` draws to flush the tail, are read but left out, and `framesOutsideSession` counts them (a frame is placed by its `vsyncStartUs`; a record without one is kept). A large `framesOutsideSession` next to few summarized frames on a non-web target means `vsyncStartUs` and the session clock disagree there. When `complete` is `false` the report describes a SUBSET and the coverage insight says so: an empty ranking then means "not reported", not "nothing was slow". `missing` names sources that were never read: `wind` (no wind perf resolver, so `counters.wind` is `null`, which is a different finding from zeros), `blocks`, `blockSelfTime`. Read this before the numbers.
- `summary.frames`: `painted` is the frames Flutter reported, `dropped` the frames missing from the `frameNumber` sequence (how a dropped scene shows on web), `count` their sum. A frame is over budget when its slower thread took longer than `budgetMs`.
- `blocksBySelf` ranks by EXCLUSIVE time. A parent's inclusive time contains its children's, so ranking by it blames the parent for the child's work. `frames` separates a block that cost 10ms once from one that cost 0.1ms in each of a hundred frames; those need opposite fixes. Both block lists keep the top 10; `omitted` counts the rest.
- `counters` are given raw and per painted frame. A breakdown keeps its top 3 as positional rows in `columns` order.
- In `timing` mode `counters` is `null` and `summary` carries `durationMs`, `budgetMs` and `frames` only.

Attribution milliseconds are inflated by the profiling that makes attribution possible. Rank by them; compare milliseconds only between `--mode=timing` sessions.

---

## Insights

At most six, sorted by severity (`error`, `warn`, `info`) then `estimatedSavingsMs`. Each carries `id`, `severity`, `title`, `evidence {metric, value, perFrame, threshold}` and `nextStep`; the threshold it was judged against is always in the evidence, so a verdict can be checked rather than trusted. Ids are assigned before the sort and the cut, so an insight counted in `omitted.insights` is still drillable.

| Metric | Fires when | Severity |
|---|---|---|
| `framesOverBudget` | a frame's slower thread exceeds 16.7ms | `error` past a 0.1 share of painted frames, else `warn` |
| `framesDropped` | the `frameNumber` sequence steps by 2 or more | `error` past a 0.1 share, else `warn` |
| `blockSelfMs` | one block owns at least 0.3 of all self time and at least 1ms per painted frame | `error` past 8.35ms per frame, else `warn` |
| `blockCountPerFrame` | one block runs at least 20 times per painted frame and 10 times the median block | `warn` |
| `framesUnreported` / `sourcesMissing` | coverage is incomplete, or a source was never read | `warn`, or `info` when only wind is missing |
| `contributorErrors` | a host-contributed rule threw or returned a malformed insight | `warn` |

The host adds its own rules through `perfInsightContributors` (magic_devtools fills it with wind and magic rules). A contributor that fails costs its own insights and never the report.

---

## The refusal

Check `refused` before anything else.

```json
{
  "sessionToken": "perf-1",
  "refused": true,
  "mode": "attribution",
  "coverage": {"framesDrawn": 0, "livenessBaseline": 412, "livenessFinal": 412, "complete": false},
  "reason": "The liveness counter advanced by 0 between perf_begin and perf_end ..."
}
```

When the liveness counter advanced by 1 or less, the engine rendered nothing worth measuring and every metric would be a zero or a single sample that reads as "fast". The response therefore carries no metrics at all, `tapir:perf_insight` has nothing to drill into, and the command exits `1` so a shell caller cannot chain on a report that does not exist.

The ordinary cause is an idle app, not a broken one. Flutter schedules a frame only when something is dirty, so a session that opens, sleeps and closes legitimately draws nothing: drive an interaction inside the session, and aim a scroll at something that actually scrolls. The second cause is a hidden or backgrounded page, which produces exactly one frame rather than zero, which is why the threshold is `1` and not `0`.

That counter is the authority here, not the `warnings` block that may sit on the same response: `SchedulerBinding.framesEnabled`, which the warning reads, was measured reporting `true` with lifecycle `resumed` on a Chrome page that was hidden and had produced one frame in two seconds. Bring the page to front (CDP `Page.bringToFront`) and run the session again.

---

## Examples

### 1. Read the insights after a scroll

```bash
dart run tapir tapir:perf_end --json | jq '.insights'
```

### 2. Human summary at a terminal

```bash
dart run tapir tapir:perf_end
```

```
✓ Performance session perf-1 closed (attribution): 45 painted frames, 3 over the 16.7ms budget, worst build 31.2ms. 2 insights; top [warn] I1: 3 of 45 frames over the 16.7ms budget. Drill in with tapir:perf_insight --id=I1, or pass --json for the report.
```

---

## Related Documentation

- [tapir:perf_begin](https://anilcancakir.com/tapir/docs/commands/tapir-perf-begin.md): opens the session, picks the mode, records the liveness baseline.
- [tapir:perf_insight](https://anilcancakir.com/tapir/docs/commands/tapir-perf-insight.md): the rows behind one insight.
- [Interactions and the perf trace](https://anilcancakir.com/tapir/docs/reference/perf-trace.md): what each gesture in the session opened, exported as Chrome Trace Event JSON.
- [Frame production](https://anilcancakir.com/tapir/docs/reference/frame-production.md): the backgrounded-tab failure mode the refusal exists for.

---

# tapir:perf_run

Run a perf scenario several times from a clean start and write one run file per scenario.

The file holds medians of counts per painted frame, a spread block, the insights of the median repeat, and every repeat's full report. It is what `tapir:perf_compare` reads.

- [Synopsis](#synopsis)
- [The scenario file](#the-scenario-file)
- [Fragments, parameters and variants](#fragments-parameters-and-variants)
- [What one run does](#what-one-run-does)
- [The run file](#the-run-file)
- [Refusals and exit codes](#refusals-and-exit-codes)
- [The semantics pass](#the-semantics-pass)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:perf_run <scenario.yaml> [--variant=<key>] [--label=<name>]
    [--out=<dir>] [--repeat=<n>] [--platform=chrome|android|ios] [--timing]
    [--against=<baseline.yaml>] [--semantics-pass] [--json]
```

`tapir:perf_run` requires a running session (`CommandBoot.connected`). On Chrome it also needs the CDP port `dowel start --cdp-port` records: every session is brought to front first, and viewport, resize and wheel go through DevTools.

| Flag | Default | Meaning |
|------|---------|---------|
| `<scenario.yaml>` / `--scenario` | required | The scenario file. |
| `--variant` | none | The [variant](#variants) to run. Required when the file declares `variants` (the error lists the keys), refused when it does not. It applies to `--against` too, so both files have to declare it. |
| `--label` | `run` | Names the run in the file name. `[a-z0-9_-]` only; anything else is rejected. |
| `--out` | `build/perf` | Directory the run files go to. |
| `--repeat` | the scenario's `repeat` | Repeats per series. |
| `--platform` | read from the session | `chrome`, `android` or `ios`. Read from the state file's device when omitted (`chrome`/`web-server`, `emulator-*`, a simulator UDID). |
| `--timing` | `false` | Also run timing-mode repeats, interleaved with the attribution ones. Their medians are the only milliseconds `tapir:perf_compare` gates on. |
| `--against` | none | A baseline scenario run inside the same rounds, the order alternating, written to its own file. Both files carry `interleavedWith`. |
| `--semantics-pass` | `false` | Also measure with tapir's semantics handle released. See [the semantics pass](#the-semantics-pass). |
| `--json` | `false` | Print the run file minus every `repeats[]` (insights cut to six), plus `path`. |

---

## The scenario file

```yaml
name: monitors-list-scroll-1440   # [a-z0-9_-]: becomes the file name
viewport: {width: 1440, height: 900}   # Chrome only; the device's own elsewhere
platforms: [chrome, android]      # default: chrome, android, ios
setup:                            # runs before EVERY repeat
  - hot_restart
  - navigate: /monitors
  - wait_for_text: Monitors       # or {text: Monitors, timeout_ms: 20000}
  - wait_for_network_idle
  - tap: {target: {text: perf-monitor-0000}}   # a gesture, unmeasured
steps:                            # the timed window
  - wheel: {target: {key: monitor-list}, dy: 1200}
    only: [chrome]
  - drag: {target: {text: Monitors}, dy: -600}
    only: [android, ios]
  - tap: {target: {role: button, name: Add monitor}}
  - wait: 400
repeat: 3
thresholds: {warn: 10, error: 25}  # percent, per metric
```

Steps: `tap`, `fill` (`text`), `type` (`text`), `press_key` (`key`), `scroll` (`dx`/`dy`), `wheel` (`dx`/`dy`, and `ticks`: how many events of that size to send one frame apart at the one resolved point, 1 to 200, default 1; a real wheel is many small ticks, and one large event jumps a list in a single frame), `drag` (`dx`/`dy` from the target's centre), `navigate` (a route), `resize` (`width`/`height`) and `wait` (ms). A step may carry `only: [...]`.

Setup takes `hot_restart`, `navigate`, `wait_for_text` and `wait_for_network_idle`, and also the gestures `tap`, `fill`, `type`, `press_key`, `wheel`, `drag` and `wait`, written and validated exactly as steps are (targets, `only`, the Chrome-only rule). They run before `perf_begin`, so the path to the measured screen is not measured: navigate to `/monitors`, tap the row `perf-monitor-0000`, then time only the tab switches, rather than baking a seeded id into `navigate: /monitors/<uuid>`. `only` is refused on the four setup verbs, which run everywhere.

A target is resolved on the live screen in every repeat, never written as a ref: an `e12` from one run is stale after the next navigate, and the file is rejected if it names one. A target only `wait` steps precede (on the platform the run is on) is resolved before `perf_begin`, a `wheel`'s hover point with it, so the lookup costs the window nothing. Every other target could be created or moved by an earlier step (the `English` option in the overlay a tap opens), so it is resolved inside the window, right before its step, and the run file records that cost. A target not there yet is looked up again every 100 ms for up to 3 s before the run fails with "matched nothing". Exactly one of:

| Target | Resolves through |
|---|---|
| `{text: ...}` | `ext.tapir.find --text`; with `index > 0`, the `index`-th of `ext.tapir.find_by_text` |
| `{label: ...}` | `ext.tapir.find --semanticsLabel`; no `index` (nothing can serve one: name the control as `{role, name, index}` instead) |
| `{role: ..., name: ...}` | the `index`-th `ext.tapir.observe` candidate with that role whose label is `name`: what `tapir:snap` prints as `- button "Add monitor"`. Roles are snap's: `button`, `textbox`, `checkbox`, `link`, `heading`, `image` |
| `{key: ...}` | `ext.tapir.find --key`; a key names one widget, so no `index` |

`wheel` is a CDP mouseWheel, because `tapir:scroll` moves the parent scrollable programmatically and some screens only respond to the wheel. `wheel` and `resize` are Chrome only, and the file is rejected when one could run elsewhere: on android and ios scroll with a `drag`. Every problem in the file is reported at once.

---

## Fragments, parameters and variants

A scenario file is loaded through `loadPerfScenarios` (`lib/src/perf/scenario_loader.dart`), which adds three things to the grammar above: setup fragments, `${...}` interpolation with secrets, and variants. `PerfScenario.parse` reads the same grammar from a string, except that it refuses an `include` (a string has no directory to resolve one against) and `variants` (they yield several scenarios).

### Fragments

A setup entry `- include: <path>` flattens a fragment file into `setup` in place. The path is relative to the file that holds the entry.

```yaml
# scenarios/monitors-list.yaml
setup:
  - hot_restart
  - include: fragments/login.yaml
    with: {email: "${env.PERF_EMAIL}", password: "${env.PERF_PASSWORD}"}
    when: {text: Sign in, unless_text: Monitors, timeout_ms: 60000}
  - navigate: /monitors
```

```yaml
# scenarios/fragments/login.yaml
params:
  email: {}                         # required: no default
  password: {secret: true}
  submit: {default: Sign in}
when: {text: Sign in}               # used when the include names no `when`
steps:                              # the setup grammar, nested includes too
  - fill: {target: {label: Email}, text: "${email}"}
  - fill: {target: {label: Password}, text: "${password}"}
  - tap: {target: {role: button, name: "${submit}"}}
```

A fragment takes `params`, `when` and `steps` and nothing else. Every param is required unless it has a `default`; a `with:` key the fragment does not declare, a missing required param, an include cycle (a includes b includes a) and includes nested deeper than 8 are each a problem. An include is a setup entry only: the measured `steps` are written out, so the file shows everything the window times. A problem inside a fragment names it and the entry, `fragments/login.yaml steps[1].fill.text`, and so does every flattened entry at run time.

`when: {text, unless_text, timeout_ms}` guards the whole fragment; the include's own `when` replaces the fragment's. The runner polls the screen for up to `timeout_ms` (default 60000): `text` on screen runs the fragment, `unless_text` on screen skips it (and wins when both are there). On timeout the fragment is skipped when there is no `unless_text`, and the run fails when there is one, since the screen showed neither state.

At run time the guard is a poll of `ext.tapir.find --text` every 250 ms, `unless_text` first, then `text`, up to `timeout_ms`. Each guard is decided once per pass over the setup (so once per repeat in `tapir:perf_run`), at the first of its steps that runs on the platform, and the decision covers every step the include flattened. A guard nested in another is decided only after the outer one decided to run, so a skipped outer fragment never polls for its inner one. The timeout failure names both texts and the include (`list-scroll setup[1] (when): neither "Sign in" nor "Monitors" showed within 60000 ms, ...`) and ends with the same `Diagnostics:` line as any setup failure.

The run file's `scenario.setup` echoes each guard once, as `when`, on the first step it governs, which marks where a guarded group begins (the steps its include flattened follow it, in order; the echo does not mark where the group ends): `{"tap": {"target": {"text": "Sign in"}}, "when": {"text": "Sign in", "unless_text": "Monitors", "timeout_ms": 60000}}`. A guard entered on the same step as one nested in it is that one's `parent`; a step written as a bare verb becomes `{"hot_restart": null, "when": {...}}`. Unguarded steps are written as before. A `when` never holds a secret: the loader refuses one there.

### Interpolation

Every scalar value in a scenario or fragment file (never a key) is interpolated once, in its own file:

| Written | Reads |
|---|---|
| `${name}` | the fragment's param `name` |
| `${env.NAME}` | the environment variable `NAME` |
| `$$` | one literal `$` |

A `with:` value is resolved in the including file and passed on as it is, never scanned again: `Pa$$w0rd` arrives as `Pa$w0rd` however many includes it goes through, and an environment value `a${b}` arrives as `a${b}`. A `default` reads the environment only. An undefined name is a problem that names the file and the path.

### Secrets

A value any part of which came from `${env.*}` or from a param declared `secret: true` is a secret, and stays one through every `with:`. It may only be the `text` of a `fill` or `type`; anywhere else (a route, a `wait_for_text`, a target, a `when`) the file is refused with "a secret may only be typed". A non-empty secret shorter than 4 characters is refused too, with a problem naming the variable (`${env.PIN} is 2 characters`) or the param, never the value: every output is masked for every secret wherever its text appears, so a secret `1` or `80` would mask that number in every log line and every run file. An empty `${env.*}` value is no secret and masks nothing. The run file writes the text of a secret step as `***`, and a problem never prints a secret, raw or JSON-encoded. Once the files have loaded, `tapir:perf_run` masks every secret, raw or JSON-encoded, in everything it prints (errors, diagnostics, the success lines and the `--json` envelope) and in every string of the run files it writes, such as a `semanticsPassReason` that quotes a failed fill. The run files and the `--json` envelope are masked as JSON trees (string values only) and the envelope is printed once, unwrapped: a text pass over encoded JSON could rewrite a number or a key a secret matches (a secret `1234` inside `81234567`) into invalid JSON. An exception message the diagnostics quote is masked before it is cut to 200 characters, so a secret the cut would split leaves no prefix behind.

### Variants

`variants` turns one file into one scenario per key, named `<name>-<key>`, so twin files that differ in the viewport become one:

```yaml
name: monitors-list-scroll
platforms: [chrome]
viewport: {width: 1440, height: 900}
steps:
  - wheel: {target: {key: monitor-list}, dy: 1200}
variants:
  1440: {}
  390:
    viewport: {width: 390, height: 844}
    platforms: [chrome, android, ios]
    steps:
      - drag: {target: {text: Monitors}, dy: -600}
```

A variant may replace `viewport`, `platforms`, `repeat` and `steps`; each key it names replaces the base's whole value (a variant's `steps` replaces the whole list). A key is read as text (YAML reads `1440` as a number) and must use `[a-z0-9_-]`. Each resulting scenario is validated on its own, so a step's `only:` is checked against that variant's `platforms`, and a problem in one names it (`monitors-list-scroll-390: variants.390.steps[0]...`).

`tapir:perf_run` runs one variant per call: `--variant=390` runs `monitors-list-scroll-390` and writes `<out>/monitors-list-scroll-390-<label>.json`, whose top-level `variant` says which key it was. A file with variants run without `--variant`, a key it does not declare, and `--variant` on a file without variants each exit 1 before the app is touched.

---

## What one run does

Each repeat is one unit: the scenario's setup, `Page.bringToFront` on Chrome, the targets that can be resolved early, `perf_begin`, the steps, a 300 ms settle (Flutter delivers frame timings in batches of about 100 ms), then `perf_end` with `full=true`. Setup runs before every repeat so each starts from the same state: the controllers are singletons, and a search term left by one repeat would filter every later one.

A setup `navigate` has to land and stay. First the app has to be routable: the runner reads `ext.tapir.get_routes` every 100 ms, for up to 10 s, until its `uri` names a mounted Router. `ext.tapir.boot_id` answers as soon as `TapirPlugin.install()` has run, and a host that installs tapir before its own boot (magic_devtools' documented order) is still booting or showing a loading screen then; a navigate sent before the Router exists answers `navigated: false` even when the route lands a moment later. No Router within 10 s fails the run, and so does a `get_routes` with no `uri` at all, which means the app runs an older tapir than the CLI: relaunch it.

An answer of `navigated: false` is then held against the Router for up to 3 s: `ext.tapir.navigate` reads the Router two frames after dispatching, and a Router that has only just mounted is still applying its first location then (measured after a web hot restart: `false` as the Router mounted, `true` 300 ms later). A route whose path is reached exactly in that time counts (query ignored; a page under it does not, since a web hot restart keeps the URL and an app still on `/monitors/7` would otherwise pass for a dropped navigate to `/monitors`), the payload the diagnostics quote carries `landedLate: true`, and the unit's entry in `repeats[]` carries `setupLandedLate: true`. A route that never lands (the router dropped it) or lands elsewhere (a redirect) fails the run with the payload. The route is never dispatched twice: a second push would stack it.

Once it has landed, the runner reads `get_routes`'s `uri`, waits for network idle, and reads it again; a route whose path moved in between (a first fetch answering 401 redirects to the login screen) fails the run naming both. The two reads compare paths, so a page that normalises its query after the first fetch (`/monitors` to `/monitors?page=1`) has not moved.

Every setup failure other than a restart's ends with a `Diagnostics:` line: the Router's `uri` as `ext.tapir.get_routes` answers it (`route none (no Router mounted)` when there is none, plus the page name when the Navigator's top page has one), the last setup navigate's payload, and the three newest `ext.tapir.exceptions` entries, each message's first line masked for the secrets and then cut to 200 characters. A diagnostic call that fails is named in its place.

`hot_restart` is a hot restart on a debug build. A profile build cannot hot restart, so there it is a full relaunch through `dowel restart`, carrying the session's flags; `env.restartMode` says which (`none` when the setup has no restart). Either way the runner reads `ext.tapir.boot_id` first and waits, up to 90 s after a hot restart, until it answers with a different id, which `TapirPlugin.install()` mints on every run of `main()` and registers last. Not a new isolate: on Flutter web DWDS keeps isolate `"1"` across a hot restart, and on the VM the old isolate answers until the new one replaces it. The errors the app answers while it restarts (DWDS's -32603 for an extension not registered yet) are waited out, and the last one is named if the 90 s run out. An app that does not answer `ext.tapir.boot_id` at all runs an older tapir: relaunch it.

With `--timing`, `--against` or both, each round runs every unit once and the next round reverses the order, so drift in the app (a warming cache, a growing heap) lands on both sides alike.

Actions are called with `includeSnapshot: false`: a snapshot per step would build the semantics tree inside the window and cost frames the scenario did not ask for.

---

## The run file

`<out>/<scenario>-<label>.json`:

```json
{
  "scenario": {"name": "monitors-list-scroll-1440", "...": "the parsed scenario"},
  "label": "before",
  "variant": "1440",
  "env": {"platform": "macOS", "isWeb": true, "buildMode": "debug",
          "semanticsEnabled": true, "target": "chrome", "device": "chrome",
          "emulator": false, "restartMode": "hot_restart",
          "host": {"os": "macos", "uname": "Darwin 25.0.0 arm64",
                   "cpu": "Apple M3 Pro", "cores": 12},
          "renderer": "unknown"},
  "summary": {
    "repeats": 3, "refused": 0,
    "frames": {"count": 42, "painted": 42, "dropped": 0, "overBudget": 1},
    "perFrame": {"blocks.MonitorRow": 2.2, "wind.wDivBuilds": 31.4},
    "ms": {"buildMs.p50": 4.1, "buildMs.p90": 8.3, "rasterMs.p50": 3.0},
    "spread": {"perFrame": {"blocks.MonitorRow": {"min": 2.0, "max": 3.0, "rangePct": 45.5}},
               "ms": {"...": {}}},
    "timing": {"repeats": 3, "refused": 0, "ms": {"...": 0}, "spread": {}}
  },
  "insights": [{"id": "I1", "severity": "warn", "title": "...", "...": "..."}],
  "repeats": [{"series": "attribution", "index": 0, "...": "the full perf_end report",
               "resolves": [{"step": 0, "verb": "tap", "phase": "beforeBegin", "resolveMs": 12.4},
                            {"step": 2, "verb": "tap", "phase": "inWindow", "resolveMs": 38.1}]}]
}
```

- `perFrame` flattens every count to a name: `blocks.<widget>`, `<wind|magic>.<counter>`, `<wind|magic>.<counter>.<row>`. Gauges such as `wind.cacheSize` are left out. A metric a repeat lacks counts as zero there.
- `ms` (attribution) is indicative: build profiling inflates every duration. Compare `summary.timing.ms` instead.
- `insights` come from the repeat whose total per-frame count is the median.
- `variant` is the `--variant` the run used, present only when it used one.
- `repeats[].resolves` lists each targeted step's lookup: `beforeBegin` outside the window, `inWindow` inside it, where `resolveMs` (retries included) is time the session measured. The semantics pass resolves nothing, so its repeats carry an empty list.
- `env.host` comes from the host: `uname` and the CPU. `env.renderer` is the app's own answer (`canvaskit` or `skwasm` on web, through `rendererReader`); only when the app answers `unknown` does the runner fall back to the Impeller backend line of the dowel run log (`impeller-vulkan`), else `unknown`.

---

## Refusals and exit codes

A refused repeat (the engine drew one frame or none, see `tapir:perf_end`) is kept in `repeats[]` with `refused: true` and left out of every median; `summary.refused` counts them.

| Exit code | Meaning |
|-----------|---------|
| `0` | At least one attribution repeat was measured. |
| `1` | A bad input (scenario, label, repeat, platform), a setup or step that could not run (the session is still closed, so the profiling flags are restored), or every attribution repeat refused. The file is still written in the last case. |

---

## The semantics pass

tapir keeps a semantics handle for the whole process, so every tapir-driven frame also builds the semantics tree. `--semantics-pass` measures the app without it, as a separate `semanticsOff` series:

1. The first attribution round records where each `tap`, `drag` and `wheel` dispatched (`reportPoint`).
2. Each semantics repeat runs the setup, opens the session, calls `ext.tapir.semantics_hold action=release`, replays the steps by those coordinates (`ext.tapir.tap {x, y}`, `ext.tapir.drag {x, y, toX, toY}`, CDP for the wheel), closes the session with `perf_end`, and only then calls `action=acquire`. The acquire's frame rebuilds the whole tree, so it stays out of the window, and the report's `env.semanticsEnabled` describes the window rather than the re-acquired handle. The handle is never released outside that window, and the acquire runs even when a step or `perf_end` fails.

The file gains `semanticsPass: "measured"` and `semanticsOff: {summary, repeats}`. `fill`, `type` and `scroll` act through a resolved widget, so a scenario with one of them records `semanticsPass: "unsupported"` with a `semanticsPassReason` instead of failing the run; so does a replay that fails. See [the semantics hold](https://anilcancakir.com/tapir/docs/reference/semantics-hold.md).

A release does not always turn the tree off. The framework builds it while any handle is held, and the platform holds its own while `platformDispatcher.semanticsEnabled` is true. When the release answers `semanticsEnabled: true` the pass stops there: it closes that window, re-acquires, records `semanticsPass: "unsupported"` and writes no `semanticsOff` series, since what it would measure is the attribution series again. The `semanticsPassReason` names the platform and what holds semantics on:

| Where | What holds it | `semanticsPassReason` |
|---|---|---|
| chrome | The web engine turns semantics on at the first semantics tree a real app sends (tapir's first snapshot sends one) and never turns it off. | `on chrome, releasing tapir's semantics handle left semantics on: the platform holds it: Flutter web's engine ...` |
| android, ios | An accessibility service (TalkBack, VoiceOver, another assistive service). | `on android, ... an accessibility service ... is on; turn it off and rerun.` |
| any | A `SemanticsHandle` the app or a package took with `ensureSemantics`. | `on <platform>, ... another semantics handle in the app holds it ...` |

On chrome, then, the pass reports `unsupported` for any app tapir has snapshotted; measure the semantics-off figure on a native target.

---

## Related Documentation

- [tapir:perf_compare](https://anilcancakir.com/tapir/docs/commands/tapir-perf-compare.md): judge one run file against another.
- [tapir:perf_end](https://anilcancakir.com/tapir/docs/commands/tapir-perf-end.md): the report each repeat is.
- [tapir:perf_trace](https://anilcancakir.com/tapir/docs/commands/tapir-perf-trace.md): export a session's timeline.

---

# tapir:perf_trace

Write the last closed perf session as a Chrome Trace JSON file and print only its path.

The file opens as is in [ui.perfetto.dev](https://ui.perfetto.dev) and `chrome://tracing`.

- [Synopsis](#synopsis)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:perf_trace --out=<file> [--token=<perf-1>]
```

`tapir:perf_trace` requires a running session (`CommandBoot.connected`) and calls `ext.tapir.perf_trace`. The trace runs to thousands of events, which is why it goes to a file: the path is all an agent needs to hand on.

| Flag | Default | Meaning |
|------|---------|---------|
| `--out` | required | The file to write. Parent directories are created. |
| `--token` | none | The session's `sessionToken`. Only the most recent closed session is kept; a token naming any other is refused. |

The file carries `traceEvents`, `displayTimeUnit` and `otherData` (the session token, its window and the event counts). What goes into it, and why the frames must be exported before the next `perf_begin`, is on [the perf trace page](https://anilcancakir.com/tapir/docs/reference/perf-trace.md).

| Exit code | Meaning |
|-----------|---------|
| `0` | Written; stdout is the absolute path. |
| `1` | `--out` missing. |
| non-zero | The extension refused: no closed session, a stale token, or a session still open. |

## Related Documentation

- [tapir:perf_run](https://anilcancakir.com/tapir/docs/commands/tapir-perf-run.md), [tapir:perf_end](https://anilcancakir.com/tapir/docs/commands/tapir-perf-end.md).

---

# tapir:perf_insight

Drill into one insight of the report `tapir:perf_end` last produced: its title, a summary in prose, the raw rows behind it, the estimated savings and the next step.

The report stays small because these rows live here; ask for the one insight you are acting on.

- [Synopsis](#synopsis)
- [Returns](#returns)
- [Errors](#errors)
- [Examples](#examples)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:perf_insight --id=<I1> [--token=<perf-1>] [--json]
```

`tapir:perf_insight` requires a running Flutter session (`CommandBoot.connected`) and calls `ext.tapir.perf_insight`.

| Flag | Default | Meaning |
|------|---------|---------|
| `--id` | required | Insight id from the `insights[]` list `tapir:perf_end` returned. Ids are assigned before the report cuts its list, so one counted in `omitted.insights` is drillable too. |
| `--token` | none | The report's `sessionToken`. Only the most recent closed session is kept; a token naming any other is refused, which guards against reading a newer session than the report you hold. |
| `--json` | `false` | Print the raw envelope, `detail` included, instead of the human summary. |

---

## Returns

| Exit code | Meaning |
|-----------|---------|
| `0` | Drill-down returned. |
| `1` | `--id` missing. |
| non-zero | The handler returned an error (see below). |

```json
{
  "sessionToken": "perf-1",
  "id": "I1",
  "severity": "warn",
  "title": "3 of 45 frames over the 16.7ms budget",
  "summary": "3 of 45 painted frames took longer than 16.7ms on their slower thread (3 over on build, 0 on raster). Their time past the budget totals 29.4ms, the most a fix to these frames alone could win back.",
  "detail": {
    "overBudgetBuild": 3,
    "overBudgetRaster": 0,
    "worstFrames": [
      {"frameNumber": 212, "buildMs": 31.2, "rasterMs": 2.1, "blocks": [{"name": "MonitorRow", "selfMs": 9.8, "count": 12}]}
    ]
  },
  "estimatedSavingsMs": 29.4,
  "nextStep": "Build-bound: drill in for the worst frames and their self-time blocks."
}
```

`detail` depends on the rule:

| Metric | `detail` |
|---|---|
| `framesOverBudget` | `overBudgetBuild`, `overBudgetRaster`, and up to 10 `worstFrames`, each with its top 5 blocks by self time |
| `framesDropped` | up to 20 `gaps` as `{after, next, missing}`, plus `gapsOmitted` |
| `blockSelfMs` | the `block` (self and inclusive ms, count, frames, share), `totalSelfMs`, and the 10 frames where it cost most |
| `blockCountPerFrame` | the `block`, `medianPerFrame`, and the 10 frames where it ran most |
| `framesUnreported` / `sourcesMissing` | the coverage map |
| `contributorErrors` | which contributor failed and how |

`estimatedSavingsMs` is `null` where no saving can be stated. Where it is stated it is an upper bound: the time past the budget, or a block's whole self time.

---

## Errors

Each names what to read instead:

- No `--id`: an `invalidParams` error asking for an id from `insights[]`.
- No session has closed yet: run `tapir:perf_begin`, drive, `tapir:perf_end`.
- A stale `--token`: the error names the session that IS held.
- The last session was refused: it has no insights; rerun it with an interaction driven inside.
- An id the session never issued: the error points at the `insights[]` list of `tapir:perf_end`.

---

## Examples

### 1. Open the top insight the summary line named

```bash
dart run tapir tapir:perf_end
dart run tapir tapir:perf_insight --id=I1
```

### 2. The worst frames as JSON

```bash
dart run tapir tapir:perf_insight --id=I1 --token=perf-1 --json | jq '.detail.worstFrames'
```

---

## Related Documentation

- [tapir:perf_end](https://anilcancakir.com/tapir/docs/commands/tapir-perf-end.md): the report whose ids this reads, and the rules behind each insight.
- [tapir:perf_begin](https://anilcancakir.com/tapir/docs/commands/tapir-perf-begin.md): attribution versus timing mode.

---

# tapir:perf_compare

Judge one `tapir:perf_run` file against another: a verdict per metric and one overall, on counts per painted frame first and timing-mode milliseconds second.

- [Synopsis](#synopsis)
- [What is compared](#what-is-compared)
- [Returns](#returns)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:perf_compare <a.json> <b.json> [--json]
```

`tapir:perf_compare` reads two files and needs no running app (`CommandBoot.none`). `a` is the baseline, `b` the candidate; `--a` and `--b` name them too, which is how the MCP tool passes them.

---

## What is compared

- **Counts per painted frame**, from `summary.perFrame`, are the gate. Raw counts are never compared: a run that drew 10% fewer frames reports 10% fewer of every count, which reads as an improvement and is not one. The painted-frame counts are shown as info.
- **Milliseconds**, only from `summary.timing.ms`, the medians of the `--timing` repeats. Attribution milliseconds are inflated by build profiling and never gated; without a timing pass on both sides the result says so in `timing.note`.
- **Emulator raster milliseconds** (`env.emulator`) are listed with severity `info` and never gated: an emulator's raster thread is the host GPU's, not a device's.

Every metric is one where higher is worse. Per metric:

| Change (B against A) | Verdict |
|---|---|
| inside either run's own repeat-to-repeat range (`summary.spread`) | `unchanged`: the repeats produce that much by themselves |
| at or above `error` percent | `regressed`, severity `error` |
| at or above `warn` percent | `regressed`, severity `warn` |
| at or below minus `warn` percent | `improved` |
| a metric A never recorded | `regressed`, severity `warn`, no percentage |
| otherwise | `unchanged` |

Thresholds default to warn 10% and error 25%, and come from B's scenario `thresholds` (else A's). The overall verdict is `regressed` when any gated row regressed, else `improved` when any improved, else `unchanged`.

---

## Returns

The default output is a compact table: the verdict and thresholds, the painted frames of each side, then the changed rows, worst first (the first 20; `--json` has all).

```json
{
  "verdict": "regressed",
  "thresholds": {"warn": 10, "error": 25},
  "frames": {"painted": {"a": 100, "b": 90}},
  "rows": [
    {"metric": "blocks.MonitorRow", "a": 2.0, "b": 2.6, "deltaPct": 30.0,
     "verdict": "regressed", "severity": "error"},
    {"metric": "timing.rasterMs.p50", "a": 3.0, "b": 9.0, "deltaPct": 200.0,
     "verdict": "regressed", "severity": "info"}
  ],
  "unchanged": 41,
  "timing": {"gated": true}
}
```

| Exit code | Meaning |
|-----------|---------|
| `0` | No error-level regression (a warn is reported, not failed). |
| `1` | An error-level regression, a missing argument or file, or a run with no measured repeat (every one refused). |

---

## Related Documentation

- [tapir:perf_run](https://anilcancakir.com/tapir/docs/commands/tapir-perf-run.md): the files this reads.

---

# tapir:perf_campaign

Run every scenario of a perf campaign on one platform, each from a cold start of the app, and summarise which passed.

One command replaces the shell harness that used to boot services, start the app, log in and loop over `tapir:perf_run`: the app declares that work in a campaign YAML, and tapir runs it.

- [Synopsis](#synopsis)
- [The campaign file](#the-campaign-file)
- [What one campaign does](#what-one-campaign-does)
- [Files and output](#files-and-output)
- [Secrets](#secrets)
- [Exit codes](#exit-codes)
- [Related Documentation](#related-documentation)

## Synopsis

```
dart run tapir tapir:perf_campaign <campaign.yaml> --platform=chrome|android|ios
    [--label=<name>] [--out=<dir>] [--only=<substring>] [--device=<id>]
    [--cdp-port=<port>] [--timing] [--semantics-pass] [--json]
```

`tapir:perf_campaign` needs no running app (`CommandBoot.none`): it starts and stops the app itself through dowel's `start` and `stop`, run in-process. It is CLI only; there is no MCP tool for it.

Rebuild a stale dispatcher before invoking it: the command runs inside the compiled dispatcher, whose staleness stamp keys only on `pubspec.lock` and the SDK, so a tapir change reached through a path override never reaches it. Run `rm -f .dowel/build.stamp` first.

| Flag | Default | Meaning |
|------|---------|---------|
| `<campaign.yaml>` / `--campaign` | required | The campaign file. |
| `--platform` | required | `chrome`, `android` or `ios`. Only scenarios whose `platforms` list it run. |
| `--label` | `run` | Names the run in every file name. `[a-z0-9_-]` only. |
| `--out` | `build/perf` | Directory the run files and `.err` files go to. |
| `--only` | none | Runs only the scenarios whose name (the run file stem, `<name>-<variant>` for a variant) contains this substring. |
| `--device` | see below | Chrome: `chrome`. Android: the emulator running `android.avd`, else the first `emulator-*` serial `adb devices` lists as ready. iOS: required, the id of a USB-connected device. |
| `--cdp-port` | `9222` | The Chrome DevTools port `dowel start --cdp-port` opens. Chrome only. Checked before anything runs: a value that is not an integer from 1 to 65535 exits 1. |
| `--timing` | `false` | Passed to every `tapir:perf_run`. |
| `--semantics-pass` | `false` | Passed to every `tapir:perf_run`. |
| `--json` | `false` | Print only the envelope described in [files and output](#files-and-output). |

---

## The campaign file

```yaml
scenarios:                        # relative to this file; `*` in the file name only
  - scenarios/*.yaml
hooks:                            # shell strings, run verbatim, never interpolated
  before_campaign: ./tool/perf/services.sh up
  before_scenario: ./tool/perf/services.sh reset
  after_campaign: ./tool/perf/services.sh down
android:
  avd: my_pixel_api35             # matched by name, launched when not running
  reverse: [8001, 8080]           # adb reverse tcp:P tcp:P each
  grant: [android.permission.POST_NOTIFICATIONS]
after_start:                      # the scenario `setup` grammar, includes and all
  - include: fragments/login.yaml
    with: {email: "${env.PERF_EMAIL}", password: "${env.PERF_PASSWORD}"}
    when: {text: Sign in, unless_text: Monitors}
retries: 1                        # extra attempts per scenario, default 1
```

- `scenarios` expands a `*` in the file name against its directory, sorted; a `*` in a directory or `**` is refused. A file with `variants` becomes one scenario per variant. Two scenarios with one name are refused, since each name is a run file.
- `hooks` run through `/bin/sh -c` in the directory the command was invoked from. `${` in a hook is refused: read a variable in the shell as `$NAME`. Each hook gets the inherited environment minus the credentials the campaign itself consumes (see [secrets](#secrets)), plus `TAPIR_PERF_PLATFORM`, `TAPIR_PERF_LABEL` and `TAPIR_PERF_OUT`; `before_scenario` also gets `TAPIR_PERF_SCENARIO`, the scenario name, and `after_campaign` gets `TAPIR_PERF_STATUS`, `ok` or `failed`.
- `android` is read only with `--platform=android`. Nothing in it has a default: the AVD, the ports and the permissions are the app's. Each `grant` entry must be letters, digits, `_` and `.` only (`android.grant[i]` names one that is not): `adb shell pm grant` hands it to the device's `sh`, which would read anything else as syntax.
- `after_start` runs once per cold start, before `tapir:perf_run` and so before the scenario's own `setup`. It uses the setup grammar of [tapir:perf_run](https://anilcancakir.com/tapir/docs/commands/tapir-perf-run.md#fragments-parameters-and-variants), fragments, `when` guards and secrets included.

The whole file is validated before anything runs, and every problem is listed at once, each scenario file's prefixed with the file.

---

## What one campaign does

1. **Filter.** The scenarios whose `platforms` list `--platform` and whose name contains `--only`. When none is left the command prints `No scenario matched --only=<x> on <platform>.` (or `No scenario lists <platform>.`) and exits 1 before any hook or process runs. `--platform=ios` without `--device`, an unsafe `--label` and a `--cdp-port` that is not a port are refused here too.
2. **`hooks.before_campaign`.** A non-zero exit stops the campaign. The hook is done when its shell exits: a server it starts in the background should redirect all three streams (`(exec nohup server) >log 2>&1 </dev/null &`), since output still arriving 5 s after the exit is cut and the `.err` says so.
3. **`flutter pub get`.** An edit to `pubspec_overrides.yaml` does not reach `.dart_tool/package_config.json` on its own.
4. **Android preparation** (`--platform=android`). adb is `$ANDROID_HOME/platform-tools/adb` when it exists, else `adb` on `PATH`: flutter drives the SDK's adb, and a second adb of another version restarts the shared server whenever either runs. With `android.avd` (and no `--device`): the serial is the ready `emulator-*` whose `adb emu avd name` is that AVD, so another emulator already running is never the one measured; when none runs it, `flutter emulators --launch <avd>` and the same match every 2 s until it appears (up to 180 s). Then `getprop sys.boot_completed` every 2 s until it reads `1` (up to 180 s). Without `android.avd` the serial is `--device` or the first ready `emulator-*`. Then `adb -s <serial> reverse tcp:P tcp:P` per `android.reverse`. With `android.grant`: `flutter build apk --profile`, `adb install -r` of the profile APK and `pm grant <applicationId> <permission>` each, the `applicationId` read from `android/app/build.gradle(.kts)`. That `applicationId` must be letters, digits, `_` and `.` only, for the same device-shell reason as the grants: one that is not (a Gradle expression such as `"com.example.${flavor}"`, which tapir does not resolve) stops the campaign before the device is touched, with a message saying the Gradle value could not be used. A permission prompt on first launch sits on top of the task and swallows every later launch intent, so the grant comes before the first start. Any step that exits non-zero stops the campaign, and so does one that cannot start at all (`flutter` or `adb` not found, or not executable): the command prints `<executable> could not start: <reason>` and exits 1.
5. **Each scenario**, up to `retries + 1` attempts:
   1. `hooks.before_scenario`. A non-zero exit, or a shell that cannot start, stops the campaign at this scenario.
   2. The session is read (dowel's stop deletes it), dowel `stop` runs, and the command waits until the old app's pid is gone and the ports dowel start refuses to start on can be bound, polling every 250 ms for up to 30 s: the web port and the CDP port of a browser session, and nothing on a device. The VM Service port is not waited for: on Android `adb forward` keeps it listening after the app is gone, for as long as the adb server lives, and flutter starts over it regardless. dowel's stop signals and returns, and its start fails at once on a port still held.
   3. dowel `start`: `--device`, `--cdp-port` on Chrome, `--profile-static` on a device (a profile build).
   4. `ext.tapir.boot_id` is polled every 500 ms, for up to 180 s, until it answers: the VM Service is up before `main()` has installed tapir.
   5. `after_start`, once the app has mounted a Router (`boot_id` answers before it has one, and a login screen needs it). The Router is read every 100 ms for as long as the largest `timeout_ms` among `after_start`'s `when` guards (60 s, the guard default, when it has none), never less than the 10 s `tapir:perf_run` waits: a login guard written to wait out a slow cold start does not lose to a router wait that gave up first.
   6. `tapir:perf_run <scenario> --variant --label --out --platform [--timing] [--semantics-pass]`, in-process on the same connection. Once it exits 0 the command reads the run file it wrote and masks it again for the campaign's secrets (see [secrets](#secrets)).

   Every scenario runs from its own cold start: on Chrome, DWDS answers `ext.tapir.*` with `0/1 responses` timeouts that compound over a long session, and a retry in the same session does not clear them. Whatever an attempt throws, or a non-zero exit from stop, start or perf_run, fails that attempt; the next attempt, and the next scenario, still run.
6. **The end.** The app is stopped once the last scenario is done, whatever happened. A stop that exits non-zero makes the campaign exit 1 even when every scenario passed, and says `dowel stop exited <n> after the campaign; the app may still be running.`
7. **`hooks.after_campaign`.** Runs once, after that stop, however the campaign ended: every scenario passed, some failed, `before_scenario` stopped it, or the preparation did, a failed `before_campaign` included, since a hook that failed halfway may have started half of what this one tears down. It does not run when the command refused its input or selected nothing (step 1), since nothing was started then. `TAPIR_PERF_STATUS` is `ok` when every selected scenario passed and the final stop succeeded, else `failed`. A non-zero exit, or a shell that cannot start, makes the campaign exit 1 and is reported after the scenario results, never instead of them; its output is appended to `campaign-<label>.err`.

---

## Files and output

- `<out>/<scenario>-<label>.json`: the run file `tapir:perf_run` writes, masked again for the campaign's secrets.
- `<out>/<scenario>-<label>.err`: written when an attempt fails, one section per failed attempt: the failure, the stack trace of anything that is not a perf-run failure, what stop, start and perf_run printed, and, when the attempt failed while starting, a copy of the session's `flutter-dev.log`. A scenario that passes on its first attempt has none; a stale one from an earlier run is deleted when the scenario starts.
- `<out>/campaign-<label>.err`: the output of a hook, `flutter pub get` or Android step that stopped the campaign, then that of a failed `after_campaign`.

An `.err` that cannot be written (an `--out` under a file, a full disk) is reported as `tapir:perf_campaign could not write <path>: <reason>.` and the campaign goes on: the scenarios after it still run and the app is still stopped.

One line per scenario, as each finishes:

```
  monitors-list-scroll-1440  ok
  monitors-list-scroll-390   ok (attempt 2, see /abs/build/perf/monitors-list-scroll-390-base.err)
  monitor-detail-390         FAILED (see /abs/build/perf/monitor-detail-390-base.err)
```

A scenario that passed only on a later attempt says which attempt, and names the `.err` holding the attempts that failed before it.

With `--json` the lines are replaced by one envelope, printed however the campaign ended, a stop before the first scenario included:

```json
{"results": [
  {"scenario": "monitors-list-scroll-1440", "status": "ok", "attempts": 1,
   "runFile": "/abs/build/perf/monitors-list-scroll-1440-base.json", "errFile": null},
  {"scenario": "monitor-detail-390", "status": "failed", "attempts": 2,
   "runFile": null, "errFile": "/abs/build/perf/monitor-detail-390-base.err"},
  {"scenario": "monitor-detail-1440", "status": "not_run", "attempts": 0,
   "runFile": null, "errFile": null}
],
 "stopped": "hooks.before_scenario exited 2 before monitor-detail-390",
 "errors": ["dowel stop exited 1 after the campaign; the app may still be running."]}
```

- `results` lists every selected scenario. `not_run` is one the campaign stopped before: every scenario when a hook, `flutter pub get` or an Android step stopped it, the ones after it when `before_scenario` did.
- `stopped` is present when the campaign stopped, with the sentence it printed (and the `campaign-<label>.err` it wrote, when the failed step printed anything).
- `errors` is present when something failed after the scenarios: the final dowel stop, `hooks.after_campaign`.
- `errFile` is also set on an `ok` scenario whose first attempt failed.

---

## Secrets

A value read through `${env.*}` or a `secret: true` param, in `after_start` or any scenario, is a secret (see [tapir:perf_run](https://anilcancakir.com/tapir/docs/commands/tapir-perf-run.md#secrets)). The campaign masks every secret, raw and JSON-encoded, as `***` in every line it prints, every `.err` it writes (hook output and the copied `flutter-dev.log` included), every run file and the `--json` envelope.

- **Run files.** `tapir:perf_run` masks its run file for its own scenario's secrets only, so an `after_start` credential an app exception quotes (in `semanticsPassReason`, say) would pass through it. After each passing attempt the campaign reads the run file back, masks every string in it for all of its secrets and writes it again: still valid JSON, with the same keys and numbers.
- **Diagnostics.** A setup or `after_start` failure quotes the app's newest exceptions, each message cut to 200 characters. The message is masked before it is cut, so a secret the cut would split leaves no prefix behind.
- **The `--json` envelope** is masked as a tree (string values only) and printed once, unwrapped. A text pass over the encoded envelope could rewrite a key or a number a secret happens to match: a secret `attempts` would turn `"attempts":2` into `"***":2`. No secret is put on a command line: hooks, adb and flutter get only their literal arguments, and a hook reads what it needs from the environment it inherits.
- **The environment.** Every variable the campaign reads through `${env.NAME}`, in `after_start` or any scenario, is kept out of the processes it starts: hooks and every preparation process (`flutter pub get`, adb, `flutter emulators`, `flutter build apk`) get the invoking environment minus those variables, and nothing else is inherited on top. The filter is by name, never by value, so `CI=1` survives a secret that happens to read `1`. A hook that backgrounds a server therefore cannot leave the password running with it; a hook that needs a variable the campaign does not read still gets it. The exceptions are dowel `start` and `stop`, which run in-process and have no way to set the environment of what they spawn: `flutter run` and the app build it drives, the Chrome a CDP start launches, and stop's `adb shell am force-stop` on Android inherit the dispatcher's environment whole, and so does a `tapir:perf_run` relaunch, which chains the two. An adb of another version than the SDK's restarting the shared adb server from there keeps the variable for as long as that server lives.
- **Short secrets.** A secret shorter than 4 characters is refused when the campaign loads, naming the variable or the param: its mask would hit every number and word that holds it.

---

## Exit codes

| Exit code | Meaning |
|-----------|---------|
| `0` | Every selected scenario passed. |
| `1` | A bad input or campaign file, nothing selected, a hook, `flutter pub get` or Android step that failed or could not start, an `applicationId` that could not be used, any scenario that failed every attempt, a dowel stop after the campaign that exited non-zero, or a `hooks.after_campaign` that failed or could not start. |

---

## Related Documentation

- [tapir:perf_run](https://anilcancakir.com/tapir/docs/commands/tapir-perf-run.md): the scenario file, fragments and the run file.
- [tapir:perf_compare](https://anilcancakir.com/tapir/docs/commands/tapir-perf-compare.md): judge one campaign's run files against another's.

---

# Tapir MCP Overview

Tapir adds its MCP tools to the MCP server hosted by `dowel`, so an AI client sees one catalogue of dowel and tapir tools.

`tapir` does not ship its own MCP server. `TapirDowelProvider`, a
[`dowel`](https://anilcancakir.com/dowel/docs/mcp/overview) `DowelServiceProvider`,
contributes the `tapir_*` tool descriptors. When the provider is registered (`plugin:install
tapir` adds it to the generated `lib/app/_plugins.g.dart` barrel, and a hand-written dispatcher
lists it in `baseProviders`), the substrate MCP server picks the tapir tools up at
`initialize` time and lists them next to its own substrate tools.

- [Substrate MCP server, tapir tool descriptors](#substrate-and-descriptors)
- [The tapir tools](#tool-catalog)
- [Dispatch surfaces: `ext.tapir.*` vs. `dowel:tapir:*`](#dispatch-surfaces)
- [Lifecycle: state file, lazy reconnect, snap-act loop](#lifecycle)
- [Related Documentation](#related-documentation)

## Substrate MCP server, tapir tool descriptors

```bash
dart run tapir mcp:install   # writes the MCP client entry into .mcp.json
dart run tapir mcp:serve     # the stdio server the client launches (or ./bin/dowel mcp:serve)
```

`dart run tapir mcp:serve` speaks stdio JSON-RPC, reads the project's dowel session file
(`~/.dowel/sessions/<hash>/state.json`) to find the running Flutter app's VM Service URI, and
collects every registered provider's `mcpTools()` list at boot (the `tapir` wrapper forces
`collectMcpTools: true`, so every `tapir_*` tool surfaces without a scaffolded `./bin/dowel`).
The substrate server registers each `McpToolDescriptor` as a regular MCP tool and dispatches
calls through the descriptor's declared `extensionMethod`. No additional server process is
launched for tapir; one MCP endpoint, one server, plugin-extensible.

This means every `.mcp.json` snippet that wires the substrate MCP server already gives the
AI client access to the tapir tools. There is no separate `tapir:mcp` binary to add, no
second `cwd` to configure. See [setup.md](https://anilcancakir.com/tapir/docs/mcp/setup.md) for the per-client install matrix.

---

## The tapir tools

`TapirDowelProvider.mcpTools()` returns the descriptors below. The list is sorted
alphabetically; each link jumps to the per-tool entry in [tool-reference.md](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md).

| Tool | Purpose |
|:---|:---|
| [`tapir_blur`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_blur) | Clear keyboard focus from whatever currently holds it. |
| [`tapir_clear`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_clear) | Empty the `TextEditingController` of a resolved text field. |
| [`tapir_close_app`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_close_app) | Request a graceful shutdown via `SystemNavigator.pop()`. |
| [`tapir_console`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_console) | Read recent log entries: tapir's `debugPrint` capture, plus crumbs when it is wired. |
| [`tapir_dblclick`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_dblclick) | Double-click a widget by ref. |
| [`tapir_device_profile`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_device_profile) | Emulate a named device profile via CDP. |
| [`tapir_dismiss_modals`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_dismiss_modals) | Pop every modal route above the first persistent route. |
| [`tapir_drag`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_drag) | Drag from one widget to another by ref. |
| [`tapir_evaluate`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_evaluate) | Evaluate a Dart expression in the running isolate. |
| [`tapir_exceptions`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_exceptions) | Read recent exceptions: tapir's `FlutterError` capture, plus crumbs when it is wired. |
| [`tapir_fill`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_fill) | Focus + clear + type + settle a text field in one call (stale-retry). |
| [`tapir_find`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_find) | Mint a re-resolvable `q<N>` handle by text / label / key. |
| [`tapir_focus`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_focus) | Request keyboard focus on a widget by ref. |
| [`tapir_get_routes`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_get_routes) | Report the mounted Router's location, the top page name and a title hint. |
| [`tapir_hot_reload_and_snap`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_hot_reload_and_snap) | Hot reload, snap, screenshot, exceptions in one round-trip. |
| [`tapir_hover`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_hover) | Hover a mouse cursor over a widget by ref. |
| [`tapir_navigate`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_navigate) | Navigate to a route path. |
| [`tapir_navigate_back`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_navigate_back) | Pop the top route off the navigator stack. |
| [`tapir_observe`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_observe) | Structured candidate list of interactive widgets (Stagehand pattern). |
| [`tapir_perf_begin`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_perf_begin) | Open a performance measurement session around an interaction. |
| [`tapir_perf_compare`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_perf_compare) | Judge one `tapir_perf_run` file against another. |
| [`tapir_perf_end`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_perf_end) | Close the session and read a bounded report with ranked insights. |
| [`tapir_perf_insight`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_perf_insight) | Drill into one insight of the last report. |
| [`tapir_perf_run`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_perf_run) | Run a perf scenario several times from a clean start and write the medians to a file. |
| [`tapir_perf_trace`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_perf_trace) | Write the last closed session as a Chrome Trace JSON file. |
| [`tapir_press_key`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_press_key) | Press a hardware key with optional modifiers. |
| [`tapir_reset_overlays`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_reset_overlays) | Reset overlays: dismiss modals + Escape + Cancel-tap fallback (idempotent). |
| [`tapir_resize_viewport`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_resize_viewport) | Resize the web viewport via CDP. |
| [`tapir_right_click`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_right_click) | Fire a right (secondary mouse) click. |
| [`tapir_run`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_run) | Run several tapir verbs in one call. |
| [`tapir_screenshot`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_screenshot) | Capture a screenshot of the running app. |
| [`tapir_scroll`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_scroll) | Scroll a Scrollable widget by ref. |
| [`tapir_select_option`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_select_option) | Select an option in a DropdownButton. |
| [`tapir_set_checkbox`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_set_checkbox) | Read the checked state from Semantics and tap only when it differs. |
| [`tapir_snap`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_snap) | Capture a YAML Semantics snapshot with `e<N>` refs. |
| [`tapir_tap`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_tap) | Tap a widget by ref. |
| [`tapir_triple_click`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_triple_click) | Fire three primary clicks (~100ms apart). |
| [`tapir_type`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_type) | Type text into a TextField by ref. |
| [`tapir_wait_for`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_wait_for) | Wait until a UI condition is satisfied. |
| [`tapir_wait_for_network_idle`](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md#tapir_wait_for_network_idle) | Wait for zero in-flight HTTP requests. |

Every tool follows the `tapir_<verb>` shape, and the provider test pins the tool names.
Renames break agent prompts and pinned consumer scripts.

---

## Dispatch surfaces: `ext.tapir.*` vs. `dowel:tapir:*`

The substrate MCP server inspects each descriptor's `extensionMethod` field to choose a
dispatch path. Tapir uses two:

- **`ext.tapir.*`.** The default path, used by every action and inspection tool except the
  ones below. The MCP server calls
  `VmServiceClient.callServiceExtension(method, args)` against the running Flutter app's VM
  Service. The handler runs inside the app isolate and returns a `ServiceExtensionResponse`.
- **`dowel:tapir:*`.** Dispatched in-process by the MCP server via the dowel
  registry, executing the matching CLI command: `tapir_hot_reload_and_snap`
  (`tapir:hot_reload_and_snap`), `tapir_resize_viewport` (`tapir:resize`),
  `tapir_device_profile` (`tapir:device`), `tapir_perf_run` (`tapir:perf_run`),
  `tapir_perf_compare` (`tapir:perf_compare`), `tapir_perf_trace` (`tapir:perf_trace`) and
  `tapir_run` (`tapir:run`). `tapir_hot_reload_and_snap` reloads the app and then reads it back, which
  from inside the target isolate would deadlock. It reloads by writing `r` to the `flutter run`
  stdin FIFO and tail-polling the log for the reload marker, so it needs a session started by
  `dart run tapir start` (plain `flutter run` has no FIFO). And
  `tapir_resize_viewport` / `tapir_device_profile` drive Chrome DevTools Protocol on the
  host's Chromium subprocess. The substrate routes them through the CLI command instead so
  the orchestration runs outside the target isolate.

Both paths return MCP `CallToolResult` content; the agent sees no difference at the JSON-RPC
layer. The split exists purely so the same tool catalogue can mix in-isolate VM Service calls
and out-of-isolate CLI drivers without a second binary.

---

## Lifecycle: state file, lazy reconnect, snap-act loop

Tapir inherits the substrate's lifecycle. The MCP server stays online even when no Flutter
app is running: the session file may be absent at `initialize` time, and the server
still registers every tool descriptor. The first `tools/call` against a `tapir_*` tool
triggers a lazy reconnect: the MCP server reads the session file, opens a WebSocket to the VM
Service URI, and dispatches the call. Subsequent calls reuse the cached connection.

The canonical agent loop:

```
tapir_snap          ->  capture Semantics tree, read refs
tapir_find / read   ->  identify the target widget
tapir_tap / type /  ->  drive an action against the ref
  scroll / drag
tapir_wait_for /    ->  bridge async UI transitions
  wait_for_network_idle
tapir_snap          ->  observe the new state, loop
```

The `e<N>` refs from `tapir_snap` are frozen at snap time; re-snap after any navigation,
modal open/close, or significant rebuild. `q<N>` refs from `tapir_find` re-resolve on every
action call so they survive rebuilds as long as the predicates still match.

---

## Related Documentation

- [setup.md](https://anilcancakir.com/tapir/docs/mcp/setup.md): per-client install matrix (Claude Code, Cursor, Windsurf, VS Code,
  etc.) plus the reconnect ritual after editing `.mcp.json` or `.dowel/mcp.json`.
- [tool-reference.md](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md): per-tool input schema, return shape, and example
  JSON-RPC payload for every tapir tool.
- [Substrate MCP overview](https://anilcancakir.com/dowel/docs/mcp/overview): the underlying
  dowel MCP server that hosts the tapir tools.

---

# Tapir MCP Setup

Setting up the tapir MCP tools means writing the `.mcp.json` entry of the `dowel` MCP server and registering `TapirDowelProvider`.

The tapir tools ride on the substrate MCP server shipped inside
[`dowel`](https://anilcancakir.com/dowel/docs/mcp/setup). Install the substrate, register
`TapirDowelProvider`, and every `tapir_*` tool surfaces automatically.

```bash
dart run tapir mcp:install
```

- [Prerequisites](#prerequisites)
- [Automated install (recommended)](#automated-install-recommended)
- [Canonical `.mcp.json` entry](#canonical-mcpjson-entry)
- [Fallback invocations](#fallback-invocations)
- [Per-client install](#per-client-install)
- [Reconnect ritual](#reconnect-ritual)
- [Troubleshooting](#troubleshooting)
- [Related Documentation](#related-documentation)

## Prerequisites

Before wiring any client config:

1. The consumer's `pubspec.yaml` depends on `dowel` and `tapir`.
2. The consumer's `bin/dispatcher.dart` (the generated scaffold from `dart run tapir install`)
   picks `TapirDowelProvider` up from the `lib/app/_plugins.g.dart` barrel, which
   `dart run tapir plugin:install tapir` fills and `dart run tapir plugins:refresh`
   regenerates. `dart run tapir tapir:install` runs both for you.
3. `dart run tapir list` shows the tapir commands (`tapir:snap`, `tapir:tap`,
   etc.). When they are missing, the provider is not registered.

The MCP server stays online with zero apps running. Plugin tool calls lazy-reconnect to the
VM Service URI recorded in the project's dowel session file
(`~/.dowel/sessions/<hash>/state.json`) on first call.

## Automated install (recommended)

`dowel` ships a built-in MCP installer that writes the canonical `.mcp.json`
entry for you. Once tapir is in `pubspec.yaml` and the provider is registered, the same
single command wires Claude Code, Cursor, Windsurf, and any other client that
reads `.mcp.json` at the project root:

```bash
dart run tapir mcp:install
```

The installer is idempotent: pre-existing entries are preserved and the `dowel` key is
replaced in-place on re-run. Override the target path per client:

```bash
# Cursor (per-project)
dart run tapir mcp:install --path .cursor/mcp.json
```

To remove the entry later:

```bash
dart run tapir mcp:uninstall
```

## Canonical `.mcp.json` entry

When writing the file by hand (or wiring a client whose path is not yet covered by
`mcp:install --path`):

```json
{
  "mcpServers": {
    "dowel": {
      "command": "dart",
      "args": ["run", "tapir", "mcp:serve"],
      "cwd": "."
    }
  }
}
```

The `cwd` field must point at the project root (the directory that contains the consumer's
`pubspec.yaml`). `dart run tapir mcp:serve` starts the substrate's MCP server with
`TapirDowelProvider` already registered, so the tapir descriptors ride on it.

## Fallback invocations

`mcp:install` picks the `.mcp.json` command/args payload based on the consumer's scaffold state. Three precedence levels, highest first:

1. **`./bin/dowel mcp:serve`**: when the fastcli scaffold is present and the platform is POSIX. Fastest startup (a pre-compiled binary). This is the default after `dart run tapir tapir:install`.

   ```json
   { "command": "./bin/dowel", "args": ["mcp:serve"], "cwd": "." }
   ```

2. **`dart run tapir mcp:serve`**: when fastcli is absent (Windows or scaffold skipped). Auto-selected: the tapir wrapper injects `--invocation=tapir` before forwarding `mcp:install` to the substrate, so the correct payload is written without any manual intervention. About 3s startup per call. This path surfaces every `tapir_*` tool without a scaffold, because the wrapper forces `collectMcpTools: true` when dispatching `mcp:serve`.

   ```json
   { "command": "dart", "args": ["run", "tapir", "mcp:serve"], "cwd": "." }
   ```

3. **`dart run :dispatcher mcp:serve`**: fallback when `mcp:install` runs without a plugin invocation hint (for example `dart run dowel mcp:install`, which skips the tapir wrapper). Prefer level 2 for tapir consumers; this form boots without tapir plugin tools unless the generated dispatcher already registers the provider.

Trade-off: the fastcli path (level 1) requires the `./bin/dowel` AOT binary to be pre-compiled and present on the file system, but offers the fastest MCP server startup. The `dart run` path (level 2) works everywhere Dart is on PATH with no pre-compilation, at the cost of about 3s cold-start per agent session.

## Per-client install

| Client | Config path | After edit |
|:---|:---|:---|
| Claude Code | `.mcp.json` (project) or `~/.claude.json` (user) | `/mcp reconnect dowel` |
| Cursor | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (user) | Auto-reload |
| VS Code | `code --add-mcp '{"name":"dowel","type":"stdio","command":"dart","args":["run","tapir","mcp:serve"]}'` | Reload window |
| Continue | `.continue/config.json` `mcpServers` block | Restart Continue panel |
| Windsurf | Windsurf MCP settings panel | Reload Cascade panel |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows) | Fully quit + relaunch (close-window != quit) |

For Claude Code via CLI:

```bash
claude mcp add dowel -- dart run tapir mcp:serve
# or project-scoped:
claude mcp add --scope project dowel -- dart run tapir mcp:serve
```

## Reconnect ritual

Claude Code, Continue, and Windsurf do NOT auto-reconnect when `.mcp.json` or
`.dowel/mcp.json` (the visibility filter) changes. After every edit:

- **Claude Code:** run `/mcp reconnect dowel` in the chat. The slash command
  re-initialises only the named server; other MCP entries stay connected.
- **VS Code / Continue:** reload the editor window or restart the panel.
- **Windsurf:** reload the Cascade panel.
- **Cursor:** picks up changes on its own; no manual action needed.

The substrate MCP server stays online during a reconnect; the client simply re-runs
`initialize` and reads the refreshed tool catalogue.

## Troubleshooting

**The server is online but no app is running.** This is normal. The substrate MCP server
starts without requiring the session file. Every `tapir_*` tool call returns an
actionable error (`No Flutter app detected`) until you run `dart run tapir start`. Once the
session file exists the next tool call lazy-reconnects.

**`tapir_*` tools missing from the catalogue.** The provider is not registered with the
executable `.mcp.json` starts. Check that executable, not the wrapper: when `.mcp.json`
starts `./bin/dowel`, run `./bin/dowel list`, because `dart run tapir list` registers
`TapirDowelProvider` itself and shows the `tapir:*` block even when the scaffolded
`./bin/dowel` lacks the provider (for example after a failed Phase 2 of `tapir:install`).
When the block is missing, run `dart run tapir plugin:install tapir`, then
`./bin/dowel list` again. `dart run tapir plugins:refresh` regenerates the
`lib/app/_plugins.g.dart` auto-discovery barrel. When `.mcp.json` starts
`dart run tapir mcp:serve`, `dart run tapir list` is the right check.

**Lazy-reconnect on first `tools/call` is slow (~1s).** Expected; the substrate opens a
WebSocket to the VM Service URI on demand. Subsequent calls reuse the cached connection.

**Tool visibility filter.** Hide a tool surface without uninstalling: edit
`.dowel/mcp.json` to add the tool name under `tools.deny`. Deny always wins over allow.
Run the reconnect ritual after editing.

## Related Documentation

- [overview.md](https://anilcancakir.com/tapir/docs/mcp/overview.md): tool catalogue, dispatch surfaces (`ext.tapir.*` vs.
  `dowel:tapir:*`), lifecycle.
- [tool-reference.md](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md): per-tool input schema and example payloads.
- [Substrate MCP setup](https://anilcancakir.com/dowel/docs/mcp/setup): the full per-client
  install matrix for the underlying server.

---

# Tapir MCP Tool Reference

The input schema, return shape and an example payload for every `tapir_*` MCP tool that `TapirDowelProvider` contributes.

Most tools dispatch through an `ext.tapir.*` VM Service extension. Seven (`tapir_hot_reload_and_snap`,
`tapir_resize_viewport`, `tapir_device_profile`, `tapir_perf_run`, `tapir_perf_compare`,
`tapir_perf_trace`, `tapir_run`) route through the `dowel:tapir:*` substrate path to a CLI command,
because their orchestration cannot run inside the target isolate.

Sections are ordered alphabetically. Every section names the dispatch surface
(`extensionMethod`) at the top so the consumer knows which path the server takes. All
example payloads show the `params.arguments` object inside the `tools/call` JSON-RPC
request; the substrate MCP server wraps the response as `CallToolResult` text content.

- [Universal response fields: `framesForced`, `warnings`, `reresolved`](#universal-response-fields-framesforced-warnings-reresolved)
- [Universal response field: `effect`](#universal-response-field-effect)
- [tapir_blur](#tapir_blur)
- [tapir_clear](#tapir_clear)
- [tapir_close_app](#tapir_close_app)
- [tapir_console](#tapir_console)
- [tapir_dblclick](#tapir_dblclick)
- [tapir_device_profile](#tapir_device_profile)
- [tapir_dismiss_modals](#tapir_dismiss_modals)
- [tapir_drag](#tapir_drag)
- [tapir_evaluate](#tapir_evaluate)
- [tapir_exceptions](#tapir_exceptions)
- [tapir_fill](#tapir_fill)
- [tapir_find](#tapir_find)
- [tapir_focus](#tapir_focus)
- [tapir_get_routes](#tapir_get_routes)
- [tapir_hot_reload_and_snap](#tapir_hot_reload_and_snap)
- [tapir_hover](#tapir_hover)
- [tapir_navigate](#tapir_navigate)
- [tapir_navigate_back](#tapir_navigate_back)
- [tapir_observe](#tapir_observe)
- [tapir_perf_begin](#tapir_perf_begin)
- [tapir_perf_end](#tapir_perf_end)
- [tapir_perf_compare](#tapir_perf_compare)
- [tapir_perf_insight](#tapir_perf_insight)
- [tapir_perf_run](#tapir_perf_run)
- [tapir_perf_trace](#tapir_perf_trace)
- [tapir_press_key](#tapir_press_key)
- [tapir_reset_overlays](#tapir_reset_overlays)
- [tapir_resize_viewport](#tapir_resize_viewport)
- [tapir_right_click](#tapir_right_click)
- [tapir_run](#tapir_run)
- [tapir_screenshot](#tapir_screenshot)
- [tapir_scroll](#tapir_scroll)
- [tapir_select_option](#tapir_select_option)
- [tapir_set_checkbox](#tapir_set_checkbox)
- [tapir_snap](#tapir_snap)
- [tapir_tap](#tapir_tap)
- [tapir_triple_click](#tapir_triple_click)
- [tapir_type](#tapir_type)
- [tapir_wait_for](#tapir_wait_for)
- [tapir_wait_for_network_idle](#tapir_wait_for_network_idle)
- [Related Documentation](#related-documentation)

A minimal session: read the screen, then act on a ref from the snapshot.

```json
{ "name": "tapir_snap", "arguments": { "interactiveOnly": true } }
{ "name": "tapir_tap", "arguments": { "ref": "e5" } }
```

## Universal response fields: `framesForced`, `warnings`, `reresolved`

A hidden or minimised desktop window and a backgrounded browser tab stop the app producing
frames, and a snapshot then reads as empty while an action reports a success that could not
have landed. Tapir wakes a hidden or paused app at the entry of every `ext.tapir.*` verb
except the perf verbs, `boot_id`, `close_app`, `console`, `exceptions`, `semantics_hold`
and `evaluate`, and a response that had to wake it carries `"framesForced": true`. The app's
lifecycle observers see `resumed` while that happens;
`--dart-define=TAPIR_FORCE_FRAMES=false` turns it off. A browser tab is the exception: Chrome
withholds animation frames from a hidden tab, so tapir does not attempt the wake on web and
the `warnings` block stays. The CLI (not the MCP tool) covers that case itself when the
session has a `cdpPort`: see [Frame production](https://anilcancakir.com/tapir/docs/reference/frame-production.md).

When tapir could not force frames (the opt-out, a `detached` lifecycle, or a wake that produced
no frame) the success payload
gains a `warnings` block instead:

```json
{
  "warnings": {
    "framesEnabled": false,
    "lifecycleState": "hidden",
    "platform": "web",
    "hint": "... Bring the page to front (CDP Page.bringToFront) and retry ..."
  }
}
```

`platform` is `web` or the desktop `TargetPlatform` name, and `hint` names the usual cause
for it: a backgrounded browser tab on web, a hidden, minimised or occluded window or an
asleep display on desktop. The block is omitted entirely on a healthy engine, so its
presence is the signal. See [Frame production](https://anilcancakir.com/tapir/docs/reference/frame-production.md) for the
full picture and the fallback.

A call that relocated a stale `e<N>` ref to the control that replaced it adds
`"reresolved": ["e5"]`. See [`tapir_tap`](#tapir_tap).

## Universal response field: `effect`

Every side-effect verb reports what the widget HOLDS afterwards, not what it was asked to
do. A tapir action confirms that it DISPATCHED; the `effect` block is what confirms the
widget received.

| Verb | `kind` | Fields |
|:---|:---|:---|
| `tapir_tap` | `treeChanged` | `changed` |
| `tapir_type`, `tapir_clear`, `tapir_fill` | `text` | `verified`, `value` (read back off the live controller after the settle), `target` (`matchKind`, `label`, `rect`: which field was written) |
| `tapir_scroll` | `scrollOffset` | `changed`, `before`, `after` |
| `tapir_select_option` | `selected` | `verified`, `value` (what the dropdown holds after the settle) |
| `tapir_set_checkbox` | `checked` | `verified`, `before`, `after` |

```json
{ "ref": "e5", "effect": { "kind": "text", "verified": false, "value": "" } }
```

That example is the real case it exists for: a fill against a number field reported the
text it had been handed while the widget kept nothing, and the resulting defect-shaped
story survived two rewrites of the widget before anyone read the field back.

## tapir_blur

Dispatch: `ext.tapir.blur`

Clear keyboard focus from whatever currently holds it (Playwright
`locator.blur()` / `document.activeElement.blur()` parity).

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `includeSnapshot` | boolean | no | Embed the post-blur snapshot in the response. Default `false`. |

### Returns

Success: `{ blurred: true, hadFocus: bool }`. `hadFocus` is `false` when no node held focus
at call time (still treated as success, idempotent).

Error: returned via MCP `isError: true` when the focus-tree walk fails internally.

### Example call

```json
{ "name": "tapir_blur", "arguments": { "includeSnapshot": false } }
```

Response:

```json
{ "blurred": true, "hadFocus": true }
```

---

## tapir_clear

Dispatch: `ext.tapir.clear`

Empty the `TextEditingController` backing the resolved text field (Playwright
`locator.clear()` parity).

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | yes | Widget ref of a `TextField` / `TextFormField` / `EditableText` (e.g. `"e5"`). |
| `includeSnapshot` | boolean | no | Embed the post-clear snapshot. Default `false`. |

### Returns

Success: `{ ref: "e<N>", text: "", effect }`, where `effect` is the `text` block that reads
the field back after the settle.

Error: `TapirActionabilityException` (when the gate fails) or `TapirStaleHandleException`
(when the ref is unknown / stale) surfaced as the wire error string `"Widget ref=<ref> is
not actionable: <reason>"`.

### Example call

```json
{ "name": "tapir_clear", "arguments": { "ref": "e5" } }
```

Response:

```json
{ "ref": "e5", "text": "" }
```

---

## tapir_close_app

Dispatch: `ext.tapir.close_app`

Request a graceful shutdown of the running Flutter app via `SystemNavigator.pop()`. On
mobile + desktop this terminates the app; on web the call only asks the browser to close
the tab, and browsers may ignore that request.

### Input schema

No parameters.

### Returns

Success: `{ closed: true }`, returned before the platform close fires. Where the app does
close, the VM Service URI is gone and the next `tapir_*` tool returns a
VM-Service-unreachable error. Where it does not (a web tab the browser kept open), the app
and its VM Service stay up and later calls still work, so confirm with a call rather than
assuming the app is gone.

### Example call

```json
{ "name": "tapir_close_app", "arguments": {} }
```

---

## tapir_console

Dispatch: `ext.tapir.console`

Read recent log entries from the running app. Without crumbs it returns the entries
captured from `debugPrint` (level `INFO`, logger `debugPrint`); direct `developer.log()`
calls appear only when crumbs is wired.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `limit` | integer | no | Maximum number of entries to return. Default `50`. |
| `minLevel` | string | no | Minimum severity level (`INFO`, `WARNING`, `ERROR`). Omit for all levels. |

### Returns

Success: `{ logs: [ { level, message, time, logger }, ... ], count }`. The entries
captured from `debugPrint` come first, newest first, and the crumbs entries (when crumbs
is wired) follow in the order crumbs returns them; the two lists are not merged by time. A
repeat of the same level, message and logger is dropped, the `debugPrint` copy winning, and
the `limit` clip then cuts from the end, so a crumbs entry newer than a buffered one can sit
below it or fall outside `limit`. `count` is the length of `logs` after the clip.

Error: never; missing crumbs is treated as the empty-logs success path.

### Example call

```json
{ "name": "tapir_console", "arguments": { "limit": 10, "minLevel": "ERROR" } }
```

---

## tapir_dblclick

Dispatch: `ext.tapir.dblclick`

Double-click a widget by ref. Synthesises two pointer Down+50ms+Up sequences at the
widget's centre with ~100ms between them (Playwright double-click model). Triggers
`GestureDetector.onDoubleTap`.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | yes | Widget ref from a prior `tapir_snap`. Shape `e<N>` or `q<N>`. |
| `snapshot` | string | no | `full`, `diff` or `none`. Overrides `includeSnapshot`. |
| `includeSnapshot` | boolean | no | Embed post-action snapshot. Default `true`. |
| `checkStable` | boolean | no | Run the Stable actionability gate. Default `true`. |
| `checkReceivesEvents` | boolean | no | Run the Receives-Events actionability gate. Default `true`. |

### Returns

Success: `{ ref: "e<N>" }`. The actionability gate runs once before the first tap; the
post-action snapshot is captured after the second tap completes.

Error: `"Widget ref=<ref> is not actionable: <reason>"` (gate failure) or stale-handle
error when the ref is unknown.

### Example call

```json
{ "name": "tapir_dblclick", "arguments": { "ref": "e7" } }
```

---

## tapir_device_profile

Dispatch: `dowel:tapir:device`

Emulate a named device profile (viewport + DPR + touch + user agent) via Chrome DevTools
Protocol. Requires the substrate to have been started with `--cdp-port`. The emulated
viewport, DPR, touch and user agent last only as long as the CDP session the call opens,
which closes when it returns; only the Chrome window size it sets stays. For a viewport
that lasts, run the CLI `tapir:resize --hold` in the background.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `preset` | string | no | One of `iphone-x`, `iphone-13`, `iphone-15-pro`, `pixel-5`, `pixel-8`, `ipad-pro-12.9`, `desktop-1440`, `desktop-1920`. Omit when using `list` or `reset`. |
| `list` | boolean | no | List all available presets. When `true`, `preset` + `reset` are ignored. Default `false`. |
| `reset` | boolean | no | Clear all viewport overrides (metrics + touch + user agent). Default `false`. |

### Returns

Success (`preset`): `{ applied: "<preset-name>", viewport: { width, height, dpr, mobile,
touch } }`. Success (`list`): `{ presets: [ { name, width, height, dpr, mobile }, ... ] }`.
Success (`reset`): `{ reset: true }`.

Error: unknown preset name (the response suggests running with `list: true`); `cdpPort`
not configured.

### Example call

```json
{ "name": "tapir_device_profile", "arguments": { "preset": "iphone-x" } }
```

---

## tapir_dismiss_modals

Dispatch: `ext.tapir.dismiss_modals`

Pop every modal route (dialog, bottom sheet, popup) currently above the first persistent
route. Idempotent.

### Input schema

No parameters.

### Returns

Success: `{ popped: <int> }`: the number of modals that were popped. `0` when no modals
were open.

Error: never; safe to call speculatively.

### Example call

```json
{ "name": "tapir_dismiss_modals", "arguments": {} }
```

---

## tapir_drag

Dispatch: `ext.tapir.drag`

Drag from one widget to another by ref tokens. Synthesises pointer Down + 5x intermediate
Move events + Up sequence from `startRef`'s centre to `endRef`'s centre.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `startRef` | string | yes | Source widget ref (`e<N>`). |
| `endRef` | string | yes | Target widget ref (`e<N>`). |
| `snapshot` | string | no | `full`, `diff` or `none`. Overrides `includeSnapshot`. |
| `includeSnapshot` | boolean | no | Embed post-action snapshot. Default `true`. |
| `checkStable` | boolean | no | Run the Stable actionability gate. Default `true`. |
| `checkReceivesEvents` | boolean | no | Run the Receives-Events actionability gate. Default `true`. |

### Returns

Success: `{ startRef, endRef }`. Both refs are echoed for caller bookkeeping.

Error: actionability gate failure on either ref, or stale-handle on either.

### Example call

```json
{ "name": "tapir_drag", "arguments": { "startRef": "e12", "endRef": "e18" } }
```

---

## tapir_evaluate

Dispatch: `ext.tapir.evaluate`

Evaluate a Dart expression in the running app. Over MCP, dowel's server answers this tool
itself with the VM Service `evaluate` RPC in the app's root library, so anything imported
by `lib/main.dart` is in scope (`dowel_tinker` evaluates the same way). The expression is
wrapped in `(() async => ...)()` when it contains `await`, and the VM evaluates that
without waiting, so the result is a reference to the wrapper's `Future`, not its completed
value. The `ext.tapir.evaluate` extension is a debug-only sentinel that never evaluates
by itself.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `expression` | string | yes | Single Dart expression. No statements, no trailing semicolon. |

### Returns

Success: `{ expression, result: "<stringified expression value>" }`.

Error: a runtime exception, a compile error and a stale isolate (after a hot restart) come
back as MCP error results; the app keeps running.

### Example call

```json
{ "name": "tapir_evaluate", "arguments": { "expression": "Auth.user?.email" } }
```

Response:

```json
{ "result": "user@example.com" }
```

---

## tapir_exceptions

Dispatch: `ext.tapir.exceptions`

Read recent exceptions recorded by the running app, including non-fatal `FlutterError`s.
Returns the merged union of two sources: the in-package non-fatal `FlutterError.onError`
capture buffer (installed by `TapirPlugin.install()`) and the crumbs exception watcher
(when `crumbs` is present). Entries are deduped by
`(type, message, stackHead)`, sorted newest-first, and clipped to `limit`. RenderFlex
overflow errors appear with `type: "overflow"`. Missing-crumbs graceful: the in-package
buffer ensures non-fatal errors are visible even without crumbs.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `limit` | integer | no | Maximum number of entries to return. Default `20`. |
| `since` | string | no | ISO8601 timestamp. When set, only exceptions whose `time` is strictly after this value are returned. Omit to return the full cumulative list. Unparseable values are silently ignored. |
| `clear` | boolean | no | Empty the in-package capture buffer after returning the current entries. The buffer is cumulative, so clear between routes to get a real delta. A wired crumbs keeps its own store. |

### Returns

Success: `{ exceptions: [ { type, message, stackHead, library, fatal, time }, ... ],
count: <int> }`. `stackHead` is the first 3 lines of the stack trace. `fatal` is always
`false` for in-package captured entries.

### Example call

```json
{ "name": "tapir_exceptions", "arguments": { "limit": 5, "since": "2024-01-01T10:00:00.000Z" } }
```

---

## tapir_fill

Dispatch: `ext.tapir.fill`

Fill a text field by ref in one call: focus, clear, type, settle. Composes the gated
`ext.tapir.focus`, `ext.tapir.clear`, and `ext.tapir.type` handlers (so the actionability
gate, IME focus, and `onChanged`/validator firing all run) and retries the whole sequence
once when the ref goes stale mid-fill. Replaces the manual focus + clear + type dance.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | yes | Text-field ref token (`e<N>` or `q<N>`) from a prior `tapir_snap` / `tapir_find`. |
| `text` | string | yes | Value to set. Replaces existing content. Pass `""` to clear. |
| `includeSnapshot` | boolean | no | Embed the post-fill snapshot (default `true`). |
| `checkStable` | boolean | no | Run the Stable actionability gate. Default `true`. |
| `checkReceivesEvents` | boolean | no | Run the Receives-Events actionability gate. Default `true`. |
| `snapshot` | string | no | `full`, `diff` or `none`. Overrides `includeSnapshot`. `diff` returns only the snapshot lines the fill changed since your last unfiltered snapshot (see [`tapir_tap`](#tapir_tap)). |

### Returns

Success: `{ ref, text, filled: true, effect }` plus an optional `snapshot` (YAML). The
`effect` block is `{kind: "text", verified, value, target}`: `value` is read after the
two-frame settle, so a formatter or echo that reverts the write reports `verified: false`,
and `target` is `{matchKind: "overlap"|"nearest"|"element", label, rect}`, which field was
written. A label or static-text handle keeps the `nearest` fallback; read `target` when
`matchKind` is `nearest`. A ref whose node is an interactive non-text control (button,
checkbox, radio, switch, slider, link) is refused with `ref eN is a <role>, not a text
field`. On a permanently stale handle (after the single retry) the response is a typed
`stale` error envelope.

### Example call

```json
{ "name": "tapir_fill", "arguments": { "ref": "e7", "text": "alice@example.com" } }
```

---

## tapir_find

Dispatch: `ext.tapir.find`

Find a widget by semantic query (text / semanticsLabel / key) and return a re-resolvable
`q<N>` handle. Unlike snapshot-frozen `e<N>` refs, `q<N>` re-executes the tree walk on
every subsequent action call, so the handle survives widget rebuilds as long as the
predicates still match.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `text` | string | no | Exact match against accessibility label first, then `Text.data`. |
| `contains` | string | no | Substring match against accessibility label first, then `Text.data` (case-sensitive). Use when the visible label is dynamic (counters, timestamps, plurals). |
| `semanticsLabel` | string | no | Exact match against `SemanticsNode.label` only (no Text fallback). |
| `key` | string | no | Match against a widget `Key`. For `ValueKey`, pass the inner value's `toString()`. |
| `within` | string | no | Evaluate the predicates inside one subtree: the `e<N>` ref of the region to search. The scope becomes part of the minted `q<N>` handle, so it survives every re-resolve; once the scope stops resolving the handle reports `matched: false` with a diagnostic naming it. |

At least one of the first four must be supplied; `within` alone is refused. The predicates
are not intersected: the resolver uses the first one that is set, in the order `key`,
`semanticsLabel`, `text`, `contains`, and ignores the rest. The one exception is a `text`
passed with `key`, which must also appear in a `Text` below the keyed widget. `within`
bounds whichever predicate applies. When `semanticsLabel` or `text` meets several nodes with
the same label, the first interactive one wins, and the first in tree order only when none
is.

### Returns

Success on first match: `{ ref: "q<N>", matched: true }`. No match: `{ ref: null, matched:
false }`.

Error: surfaced only when a follow-up action call finds zero live matches against the
handle (`"stale handle"`); the agent must re-find or re-snap, never silently retry.

### Example call

```json
{ "name": "tapir_find", "arguments": { "text": "Submit" } }
```

---

## tapir_focus

Dispatch: `ext.tapir.focus`

Request keyboard focus on the widget identified by `ref` (Playwright `locator.focus()`
parity). Walks to the nearest `Focus` ancestor and calls `requestFocus()`.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | yes | Widget ref (e.g. `"e5"`). |
| `includeSnapshot` | boolean | no | Embed the post-focus snapshot. Default `false`. |

### Returns

Success: `{ ref: "<ref>", focused: true }`.

### Example call

```json
{ "name": "tapir_focus", "arguments": { "ref": "e5" } }
```

---

## tapir_get_routes

Dispatch: `ext.tapir.get_routes`

Report where the running app is: the mounted Router's location, the top page's name and a
title hint. Read it to confirm a `tapir_navigate` landed or to see where a redirect took the
app; it does not list the declared routes.

### Input schema

No parameters.

### Returns

Success: `{ location, title, uri }`.

| Field | Meaning |
|:---|:---|
| `uri` | The first mounted `Router`'s location, the value `tapir_navigate` verifies against. `null` while no Router is mounted, as on a loading screen right after a restart. |
| `location` | The root Navigator's top page name. A Router-based app (go_router, MagicRouter) names no page, so it reads `""` on every screen there; read `uri`. |
| `title` | A location hint from the platform's default route name; `""` when there is none. |

### Example call

```json
{ "name": "tapir_get_routes", "arguments": {} }
```

Response:

```json
{ "location": "", "title": "", "uri": "/monitors?page=2" }
```

---

## tapir_hot_reload_and_snap

Dispatch: `dowel:tapir:hot_reload_and_snap`

Hot reload the running Flutter app, then capture a snapshot, screenshot, and recent
exceptions in one round-trip. Routes through the CLI command because an in-isolate handler
cannot reload itself.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `screenshot` | boolean | no | Capture a screenshot after the reload. Default `true`. |

### Returns

Success: `{ reloaded: true, durationMs: <int>, snapshot: "<yaml>", screenshot: "<base64
or screenshotError>", recentExceptions: [...] }`.

Compile error: `{ reloaded: false, durationMs: <int>, error: "<compile message>",
recentExceptions: [...] }`. `snapshot` + `screenshot` are omitted on compile error, and the
call is returned as an error result, so a client never reads a compile failure as success.

### Example call

```json
{ "name": "tapir_hot_reload_and_snap", "arguments": { "screenshot": false } }
```

---

## tapir_hover

Dispatch: `ext.tapir.hover`

Hover a mouse cursor over a widget by ref. Mouse-only (no touch equivalent). Synthesises a
`PointerHoverEvent` of `PointerDeviceKind.mouse` at the widget's centre.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | yes | Widget ref (`e<N>`). |
| `snapshot` | string | no | `full`, `diff` or `none`. Overrides `includeSnapshot`. |
| `includeSnapshot` | boolean | no | Embed post-action snapshot. Default `true`. |
| `checkStable` | boolean | no | Run the Stable actionability gate. Default `true`. |
| `checkReceivesEvents` | boolean | no | Run the Receives-Events actionability gate. Default `true`. |

### Returns

Success: `{ ref: "<ref>" }`. No-op on touch-only devices.

Error: actionability gate failure, or stale-handle.

### Example call

```json
{ "name": "tapir_hover", "arguments": { "ref": "e8" } }
```

---

## tapir_navigate

Dispatch: `ext.tapir.navigate`

Navigate the running Flutter app to a route path. Resolves through `MagicRoute.to(...)`
when Magic is installed, falling back to `Navigator.of(root).pushNamed(...)`.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `route` | string | yes | Route path. Must start with `/`. Example: `/monitors/123`. |
| `includeSnapshot` | boolean | no | Embed the post-navigation snapshot. Default `true`. |
| `snapshot` | string | no | `full`, `diff` or `none`. Overrides `includeSnapshot`. After a navigation `diff` mostly shows a whole new screen; it pays off when the route only changes a part of it. |

### Returns

Success: `{ navigated, route: "<path>", exactPath, reason?, snapshot?, snapshotMode? }`. `navigated` is
read off the first mounted Router two frames after the dispatch: `true` when its path is
the route's or a page under it (a navigate to `/monitors` that shows `/monitors/7`, a
default child), `false` with a `reason` when the router dropped or redirected it.
`exactPath` is `true` only when the path is the route's own, query aside, and `false`
beside `navigated: false`; branch on it when the named screen itself matters. ALWAYS
re-snap after; refs from a prior snapshot are invalidated.

### Example call

```json
{ "name": "tapir_navigate", "arguments": { "route": "/login" } }
```

---

## tapir_navigate_back

Dispatch: `ext.tapir.navigate_back`

Pop the top route off the active navigator stack. Equivalent to pressing the system Back
button. No-op when no Navigator has a page to leave.

The Navigator popped is the outermost one that can pop. A page pushed on the root Navigator
covers whatever a shell shows, so it is left first; a page stacked inside a shell (a
go_router `ShellRoute` builds its own nested Navigator, and MagicRouter's `.stacked()` pushes
onto it) is left once the root has nothing to pop. The root Navigator of such an app holds
the shell alone, so popping it would do nothing. A Navigator the user cannot see is skipped:
a go_router `StatefulShellRoute` keeps every branch alive and hides the inactive ones under
`Offstage` and a disabled `TickerMode`, so a page stacked on a hidden branch is never the one
left (a subtree under `Offstage(offstage: true)`, `TickerMode(enabled: false)` or
`Visibility(visible: false)` is not walked).

### Input schema

| Parameter | Type | Default | Meaning |
|:---|:---|:---|:---|
| `includeSnapshot` | boolean | `true` | Embed the post-pop snapshot in the response. |
| `snapshot` | string | (none) | `full`, `diff` or `none`. Overrides `includeSnapshot`. |

### Returns

Success: `{ navigatedBack, popped, snapshot? }`. `navigatedBack` equals `popped`. `popped`
is `false` when no Navigator had a page to leave (the bottom of every stack, the root route),
so the call did nothing; read
`tapir_get_routes` `uri`, or the snapshot, to see where the app is.

### Example call

```json
{ "name": "tapir_navigate_back", "arguments": {} }
```

---

## tapir_observe

Dispatch: `ext.tapir.observe`

Return a structured candidate list of every interactive widget on screen. Implements
Stagehand's observe-once-act-many pattern (no server-side LLM). Each candidate carries a
re-resolvable `q<N>` ref, and labelled candidates sharing one label stay distinct: the handle
carries its position among the nodes that label matched, so a list of rows offering the same
action can be worked row by row only while the list is unchanged: the position is an index,
not an identity, and nothing compares the current count with the one seen at observe time,
so after a same-label row is added or removed above a held handle it selects a neighbour and
the action still reports success. Observe again after any action that adds or removes a row
with that label. An unlabelled candidate carries no position: its handle
matches its value text, so it can land on another control with the same text, and one with no
value is stale at once; use a snapshot ref or a `key` for those. A control wrapped in `MergeSemantics` is listed once, as its
boundary node; the descendants it absorbs get no candidate.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `intent` | string | no | Free-form caller hint (e.g. `"login form"`). Echoed in audit logs, NOT used server-side. |
| `roles` | string | no | Comma-separated role filter (`button,textbox,link,checkbox,heading,image`). Omit for every role. |
| `limit` | integer | no | Maximum number of candidates. Default `50`. |
| `includeEnrichers` | string | no | `"true"` (default subset), `"false"` (none), or `"full"` (every field). |

### Returns

Success: `{ candidates: [ { ref, role, label, value, bounds, isEnabled, isVisible,
inViewport, occluded, enrichers: { ... } }, ... ] }`. `inViewport` is `false` when the
bounds lie outside the view; `occluded` is `true` when a hit test at the bounds' centre
reaches a widget painted above the candidate instead of the candidate itself (`false` for
a candidate that is not visible, since it has no centre worth probing). `isVisible` keeps
its meaning: non-empty bounds that overlap the viewport. A merged candidate whose bounds'
centre is not on its own control also carries `tapOwner: {x, y, w, h}` (the control's rect,
which a `tapir_tap` goes to); every other candidate omits it. The enricher subset projects
`magicFormField`, `magicRoute`, `magicGateResult`, `wind.breakpoint`, `wind.states` by
default.

### Example call

```json
{ "name": "tapir_observe", "arguments": { "intent": "login form", "roles": "textbox,button", "limit": 20 } }
```

---

## tapir_perf_begin

Dispatch: `ext.tapir.perf_begin`

Open a performance measurement session around an interaction you are about to
drive. Zeroes the frame buffer and the wind and magic counters and records the
liveness baseline `tapir_perf_end` judges the run against. In `attribution` mode
it also switches `FlutterTimeline` collection and Flutter's build profiling on;
that instrumentation costs real time, so keep the session tight: begin, drive
one interaction, end.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `mode` | string | no | `attribution` (default): blocks by self time, counts per painted frame, wind and magic counters, insights. `timing`: no profiling flag is touched and the report carries frame timings only. |
| `phases` | boolean | no | Also profile layout and paint, not just builds. Default `false`; the span volume multiplies. Rejected with `mode: "timing"`. |

### Returns

Success: `{ sessionToken: "perf-1", mode: "attribution", phases: bool,
livenessBaseline: <int>, restartedPreviousSession: bool }`.

An unknown `mode`, or `phases` with `timing`, is an `invalidParams` error and
opens nothing. A begin on an already-open session RESTARTS it rather than
failing, restoring the previous session's flags before saving the current ones,
so a `perf_end` that never landed cannot strand the profiling flags on.

Attribution milliseconds are inflated by the profiling. Rank by them; compare
milliseconds only between `timing` sessions.

### Example call

```json
{ "name": "tapir_perf_begin", "arguments": { "mode": "timing" } }
```

---

## tapir_perf_end

Dispatch: `ext.tapir.perf_end`

Close the session and read a bounded report (about 6 KB at most) with ranked
insights. Restores every profiling flag to the value it had BEFORE the session,
not to `false`.

### Input schema

No parameters. Requires a prior `tapir_perf_begin`; without one the call returns
a typed error rather than an empty report.

### Returns

Success: `{ sessionToken, refused: false, mode, env, coverage, summary,
counters, insights, omitted }`. Every duration is in milliseconds; every count
is given raw and per painted frame.

- `env`: `{platform, isWeb, buildMode, renderer, semanticsEnabled, phases}`,
  read in the app. `buildMode` comes from `kProfileMode` / `kDebugMode`;
  `renderer` is `canvaskit` or `skwasm` on web and `unknown` elsewhere unless a
  host assigns `rendererReader`; `semanticsEnabled` is `true` whenever tapir is
  installed, because tapir holds a semantics handle for the whole process.
- `coverage`: `{framesDrawn, framesSummarized, framesOutsideSession, complete,
  missing}`. `framesDrawn` is the liveness counter's advance;
  `framesSummarized` counts the frame records Flutter delivered inside the
  session window, which it batches, so a session can close before the last
  arrive; `framesOutsideSession` counts the delivered records left out because
  they lie outside the window (drawn before `perf_begin`, or the flush frame). `missing` names sources never read: `wind` (no perf
  resolver, so `counters.wind` is `null`, not zeros), `blocks` (profiling was
  on and no frame carried a block map), `blockSelfTime` (blocks without
  `selfMicros`). Read it before the numbers.
- `summary`: `{durationMs, budgetMs: 16.7, frames, blocksBySelf,
  blocksByCount, routeTransitions}`. `frames` is `{count, painted, dropped,
  overBudget, overBudgetBuild, overBudgetRaster, buildMs, rasterMs}`, the last
  two as `{p50, p90, p99, worst}`; `dropped` comes from `frameNumber` gaps and
  `count` is `painted + dropped`. `blocksBySelf` is `[{name, selfMs, frames}]`
  ranked by EXCLUSIVE time (a parent's inclusive time contains its children's,
  so ranking by it blames the parent); `blocksByCount` is `[{name, count,
  perFrame}]`. Both keep the top 10. `timing` mode carries `durationMs`,
  `budgetMs` and `frames` only.
- `counters`: `{columns: ["name", "count", "perFrame"], wind, magic}`, `null`
  in `timing` mode. A scalar counter is `{count, perFrame}` (`cacheSize` is a
  gauge and stays bare); a breakdown (`widgetBuilds`, `controllerNotifies`,
  ...) is its top 3 as positional rows in `columns` order.
- `insights`: at most 6, sorted by severity then `estimatedSavingsMs`, each
  `{id, severity, title, evidence: {metric, value, perFrame, threshold},
  estimatedSavingsMs?, nextStep}`. Ids (`I1`, `I2`, ...) are assigned before
  the sort and the cut. Built-in rules, with the thresholds each states in its
  evidence: `framesOverBudget` (slower thread past 16.7ms; `error` past a 0.1
  share), `framesDropped` (a `frameNumber` step of 2 or more; `error` past a
  0.1 share), `blockSelfMs` (one block owning at least 0.3 of all self time and
  1ms per painted frame; `error` past 8.35ms per frame), `blockCountPerFrame`
  (at least 20 runs per painted frame and 10 times the median block),
  `framesUnreported` / `sourcesMissing` (coverage). The host may add rules
  through `perfInsightContributors`; a contributor that throws becomes a
  `warn` insight named `contributorErrors`.
- `omitted`: how many entries each ranked list cut, keyed by list
  (`blocksBySelf`, `blocksByCount`, `routeTransitions`, `insights`,
  `wind.widgetBuilds`, `magic.controllerNotifies`, ...).

Refusal: `{ sessionToken, refused: true, mode, coverage: {framesDrawn,
livenessBaseline, livenessFinal, complete: false}, reason }`.

Check `refused` FIRST. When the liveness counter advanced by 1 or less, the
engine rendered nothing, the response carries NO metrics at all, and the reason
says so. A zero report would have read as "fast"; that is the reading a live
probe produced three times against a tab that was merely behind another window.
The liveness counter is the authority rather than the `warnings` block on the
same response, because `SchedulerBinding.framesEnabled` was measured reporting
`true` on a hidden page.

### Example call

```json
{ "name": "tapir_perf_end", "arguments": {} }
```

---

## tapir_perf_compare

Dispatch: `dowel:tapir:perf_compare` (runs the CLI command in the MCP server's
process; reads two files, needs no app)

Judge run `b` against run `a`, both `tapir_perf_run` files. Gates on counts per
painted frame, never raw counts; milliseconds only from timing-mode medians;
emulator raster ms are info. A change inside either run's repeat-to-repeat
range is `unchanged`. Thresholds: warn +10%, error +25%, or the scenario's.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `a` | string | yes | Baseline run file. |
| `b` | string | yes | Candidate run file. |
| `json` | boolean | no | Return the JSON result instead of the table. |

### Returns

`{ verdict, thresholds, frames: {painted: {a, b}}, rows: [{metric, a, b,
deltaPct, verdict, severity}], unchanged, timing: {gated, note?} }`. `rows`
lists what changed plus info rows, worst first. The call fails on an
error-level regression, or when a run has no measured repeat.

### Example call

```json
{ "name": "tapir_perf_compare", "arguments": { "a": "build/perf/list-before.json", "b": "build/perf/list-after.json", "json": true } }
```

---

## tapir_perf_insight

Dispatch: `ext.tapir.perf_insight`

Drill into one insight of the report `tapir_perf_end` last returned. Only the
most recent closed session is kept.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `id` | string | yes | Insight id (`I<n>`) from `insights[]`. One counted in `omitted.insights` is drillable too. |
| `token` | string | no | The report's `sessionToken`; a token naming any other session is refused. |

### Returns

Success: `{ sessionToken, id, severity, title, summary, detail,
estimatedSavingsMs, nextStep }`. `detail` holds the rows behind the insight:
`worstFrames` (each `{frameNumber, buildMs, rasterMs, blocks: [{name, selfMs,
count}]}`) for the budget rule, `gaps` (`{after, next, missing}`) for dropped
frames, the block and the frames where it weighed most for the block rules,
and the coverage map for a coverage insight.

Errors, each naming what to read instead: no `id` (`invalidParams`), no closed
session, a stale token, a refused session, and an id the session never issued,
which points at `perf_end`'s `insights[]`.

### Example call

```json
{ "name": "tapir_perf_insight", "arguments": { "id": "I1", "token": "perf-3" } }
```

---

## tapir_perf_run

Dispatch: `dowel:tapir:perf_run` (runs the CLI command in the MCP server's
process: it restarts the app, drives Chrome DevTools and writes files)

Run a scenario YAML several times from a clean start: setup (its hot restart,
or a relaunch on a profile build), `perf_begin`, the steps with targets
resolved on the live screen, `perf_end` with `full=true`. Writes
`<out>/<scenario>-<label>.json`.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `scenario` | string | yes | Scenario YAML path. |
| `variant` | string | no | The `variants` key to run: required when the file declares `variants`, refused when it does not; applies to `against` too. |
| `label` | string | no | `[a-z0-9_-]`, default `run`. |
| `out` | string | no | Output directory, default `build/perf`. |
| `repeat` | integer | no | Repeats per series; overrides the scenario's. |
| `platform` | string | no | `chrome`, `android` or `ios`; read from the session when omitted. |
| `timing` | boolean | no | Interleaved timing-mode repeats, the ms `tapir_perf_compare` gates on. |
| `against` | string | no | Baseline scenario run in the same rounds, one file each. |
| `semantics-pass` | boolean | no | Also measure with the semantics tree released (`semanticsOff`). |
| `json` | boolean | no | Return the run file minus `repeats[]`, plus `path`. |

### Returns

The run file: `scenario`, `label`, `env` (the app's own plus `target`,
`device`, `emulator`, `restartMode`, `host`, `renderer`), `summary`
(`repeats`, `refused`, median `frames`, `perFrame`, `ms`, `spread`, and
`timing` with `--timing`), `insights` of the median repeat, `repeats[]`, and
with the semantics pass `semanticsPass` plus `semanticsOff` or
`semanticsPassReason`. `semanticsPass` is `unsupported` when a release leaves
semantics on, which on chrome is every app tapir has snapshotted (the web
engine keeps semantics on once it has received a tree); the reason names the
platform and what holds it. A refused repeat is recorded and left out of the
medians; the call fails when every repeat refused. See
[tapir:perf_run](https://anilcancakir.com/tapir/docs/commands/tapir-perf-run.md).

### Example call

```json
{ "name": "tapir_perf_run", "arguments": { "scenario": "tool/perf/scenarios/list.yaml", "variant": "1440", "label": "before", "timing": true, "json": true } }
```

---

## tapir_perf_trace

Dispatch: `dowel:tapir:perf_trace` (runs the CLI command in the MCP server's
process, so the trace goes to a file and only the path comes back)

Write the last closed session's `ext.tapir.perf_trace` export as a Chrome Trace
JSON file. Export before the next `tapir_perf_begin`, which clears the frames
the trace reads.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `out` | string | yes | File to write. |
| `token` | string | no | The session's `sessionToken`; a stale one is refused. |

### Returns

The absolute path of the written file.

### Example call

```json
{ "name": "tapir_perf_trace", "arguments": { "out": "build/perf/list.trace.json" } }
```

---

## tapir_press_key

Dispatch: `ext.tapir.press_key`

Press a hardware key (optionally with modifiers). Delivers `KeyDownEvent` +
`KeyUpEvent` through the binding's `onKeyData`, the path real key data takes, so
`Focus.onKeyEvent`, `Shortcuts` and `CallbackShortcuts` hear the key as they
would a real press. A single letter or digit presses the key that carries
that character; text entry still goes through `tapir_type`.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `key` | string | yes | Logical key label (e.g. `Enter`, `Escape`, `Tab`, `ArrowDown`), or one letter or digit (`S`, `7`). |
| `snapshot` | string | no | `full`, `diff` or `none`. Overrides `includeSnapshot`. |
| `includeSnapshot` | boolean | no | Embed the post-key snapshot. Default `true`. |
| `modifiers` | array<string> | no | Subset of `control` (or `ctrl`), `shift`, `alt`, `meta`, in any case. Each is held down before the key and released after it, even when delivery throws, so exact-match shortcuts such as Shift+Tab or Ctrl+S fire. An unknown name is an error before anything is pressed. On the CLI this is a comma list (`--modifiers=control,shift`). |

### Returns

Success: `{ ok: true, key: "<label>" }`, plus the post-key snapshot unless `snapshot` is
`none` or `includeSnapshot` is `false`.

### Example call

```json
{ "name": "tapir_press_key", "arguments": { "key": "S", "modifiers": ["control"] } }
```

---

## tapir_reset_overlays

Dispatch: `ext.tapir.reset_overlays`

Reset the app to a clean screen via three escalating, idempotent layers: (1) pop every
`PopupRoute` (dialogs, bottom sheets, popups) without touching the page stack; (2) an
`Escape` key press for overlays driven by the dismiss shortcut; (3) a
Cancel/Dismiss/Close/OK/Done labelled tap for modal barriers that need an explicit
affordance. Each layer is a no-op when the prior already cleared the overlays, so the call
is safe to issue speculatively between flows.

### Input schema

No parameters.

### Returns

Success: `{ popped: <int>, escaped: <bool>, dismissTapped: <bool> }`. On a clean tree all
three indicate no work was done, confirming idempotency.

### Example call

```json
{ "name": "tapir_reset_overlays", "arguments": {} }
```

---

## tapir_resize_viewport

Dispatch: `dowel:tapir:resize`

Resize the running Flutter web app viewport via Chrome DevTools Protocol. Requires
dowel to have been started with `--cdp-port`. Chrome drops the override when the
DevTools session that sent it detaches, so through this tool it ends when the call
returns; the CLI's `--hold` flag (`tapir:resize --hold`, run in the background) keeps
the session open and is the way to drive the app at the new size.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `width` | integer | no | Viewport width in CSS pixels (e.g. `375` for mobile, `1440` for desktop). Required unless `reset`: the command refuses a resize without it. |
| `height` | integer | no | Viewport height in CSS pixels. Required unless `reset`. |
| `dpr` | number | no | Device pixel ratio (default `1.0`). Use `2.0` for Retina, `3.0` for iPhone Pro. Must be > 0. |
| `mobile` | boolean | no | Enable mobile device profile. Default `false`. |
| `touch` | boolean | no | Enable touch event synthesis (browser fires touch events instead of mouse). Default `false`. |
| `reset` | boolean | no | Clear all viewport overrides (metrics + touch + user agent). When `true`, all other params are ignored. Default `false`. |

### Returns

Success: the command's text output, `Viewport override sent: 375x812 @ 3.0x (mobile=true
touch=true).` followed by a note that the override ends with the call. With `reset: true`:
`Viewport reset to defaults.`

Errors (the call is reported with `isError`): `CDP not enabled` when the session has no
`cdpPort`; `A resize needs a positive --width and --height ... or --reset` when neither a size
nor `reset` is given. An argument the schema does not list, such as the old
`deviceScaleFactor`, is refused before the command runs.

### Example call

```json
{ "name": "tapir_resize_viewport", "arguments": { "width": 375, "height": 812, "dpr": 3.0, "mobile": true, "touch": true } }
```

---

## tapir_right_click

Dispatch: `ext.tapir.right_click`

Fire a right (secondary mouse) click (Playwright `locator.click({ button: "right" })`
parity). Injects `PointerDownEvent` + 50ms hold + `PointerUpEvent` (mouse kind,
`kSecondaryButton`).

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | yes | Widget ref (`e<N>`). |
| `includeSnapshot` | boolean | no | Embed post-action snapshot. Default `true`. |
| `checkStable` | boolean | no | Run the Stable actionability gate. Default `true`. |
| `checkReceivesEvents` | boolean | no | Run the Receives-Events actionability gate. Default `true`. |
| `snapshot` | string | no | `full`, `diff` or `none`. Overrides `includeSnapshot`. |

### Returns

Success: `{ ref: "<ref>" }`.

Error: actionability gate failure, or stale-handle.

### Example call

```json
{ "name": "tapir_right_click", "arguments": { "ref": "e5" } }
```

---

## tapir_run

Dispatch: `dowel:tapir:run` (substrate-routed)

Run several tapir verbs against the running app in one call. Each step is a CLI verb line
without the `tapir:` prefix, tokenised like a shell (quotes and backslash escapes), and takes
the same options as the standalone command. Saves a round trip per step when the next refs
are already known. See [tapir:run](https://anilcancakir.com/tapir/docs/commands/tapir-run.md) for the step grammar.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `steps` | array<string> | yes | Verb lines, run in order (e.g. `"tap --ref=e5"`). |
| `continue` | boolean | no | Keep running after a failing step (default `false`). |

### Returns

Text: one line per step (`[1/3] tap --ref=e5 ok: <first output line, cut to 120
characters>`), then the last step's full output. The batch stops at the first failing step
and returns `step N failed (exit C): <step>` with that step's output; with `continue: true`
it runs every step and reports the first failure. A step cannot be another `tapir_run`, nor a
verb that does not run on the connected app (resize, device, install, doctor, perf_campaign,
perf_compare). A step that ends the app (`close_app`, `perf_run`) must come last. Use `--text`,
`--key` or `q<N>` handles between steps that change the screen: `e<N>` refs belong to one
snapshot.

### Example call

```json
{ "name": "tapir_run", "arguments": { "steps": ["tap --ref=e5", "fill --ref=q1 --text=\"a b\"", "snap --grep Total"] } }
```

---

## tapir_screenshot

Dispatch: `ext.tapir.screenshot` (in-isolate, all targets). The CDP `Page.captureScreenshot` web fallback is implemented in the CLI command `tapir:screenshot --output=<path>`, NOT in this MCP tool.

Capture a screenshot of the running Flutter app as a base64-encoded image. This MCP tool
always dispatches the in-isolate `ext.tapir.screenshot` extension.

**Web limitation:** the in-isolate path can hang under CanvasKit+DWDS (the `toImage()`
future never completes). For reliable web screenshots, use the CLI command
`tapir:screenshot --output=<path>`: when dowel was started with `--cdp-port`, the CLI
falls back to CDP `Page.captureScreenshot`, honouring `--ref` / `--rect` there too. That
fallback is CLI-only and does not apply to this MCP tool.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `format` | string | no | `jpeg` or `png`. Default `jpeg`. |
| `quality` | integer | no | JPEG quality 0-100 (higher is better). Default `70`. Ignored when format is `png`. |
| `ref` | string | no | Capture only this widget: an `e<N>` from `tapir_snap` or a `q<N>` from `tapir_find`. Omit for the whole viewport. |
| `rect` | string | no | Sub-rect `"x,y,w,h"` in logical pixels, relative to the ref's top-left. Requires `ref`. |

Reach for `ref` whenever the question is about one component. A full-screen capture of a
tall page costs far more tokens than the region under review and buries the thing you are
checking, and it forces the resize dance for anything below the fold.

`rect` alone is a hard error rather than a silent full-frame capture: a sub-rect is
meaningless without the widget it is relative to.

### Returns

Success: `{ format: "<jpeg|png>", base64: "<base64>", width: <int>, height: <int> }`.

A hidden or minimised desktop window is woken before the capture, so the image is a fresh
frame and not the last cached one; the response then carries `framesForced: true`. The CLI
infers `format` from the `--output` extension; this tool takes `format` as given.

Without `ref` the capture is the app-root viewport (the `RepaintBoundary` the host wraps
the app in under `!kReleaseMode`). With `ref` it is the widget's own render-object region,
rasterised out of its nearest repaint-boundary ancestor.

The extension has a third mode, `geometry: "true"`, that returns
`{ rect: {x, y, width, height}, devicePixelRatio: <double> }` and skips rasterising
altogether. It exists so the CLI can build a CDP clip on web, where rasterising is the
step that hangs, and it is not part of this tool's schema: an MCP call that sends
`geometry` is refused with `Additional property "geometry" is not allowed`. Agents want
the pixels instead.

### Example call

```json
{ "name": "tapir_screenshot", "arguments": { "ref": "e42", "format": "png" } }
```

---

## tapir_scroll

Dispatch: `ext.tapir.scroll`

Drive a `Scrollable` widget by ref. The extension walks up to the nearest `Scrollable`
ancestor of the widget identified by `ref`.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | no | Widget ref (`e<N>`) inside the target Scrollable. Without it the first Scrollable found is scrolled. |
| `direction` | string | no | `up`, `down`, `left`, `right`. Default `down`. |
| `pixels` | number | no | Logical pixels to scroll. Default `300`. |
| `dx` | number | no | Horizontal delta in logical pixels (positive = right). Overrides `direction` / `pixels`. |
| `dy` | number | no | Vertical delta in logical pixels (positive = down). Overrides `direction` / `pixels`. |
| `intoView` | boolean | no | Bring `ref` itself into view (`Scrollable.ensureVisible`) instead of scrolling by a delta. |
| `snapshot` | string | no | `full`, `diff` or `none`. Overrides `includeSnapshot`. |
| `includeSnapshot` | boolean | no | Embed the post-scroll snapshot. Default `true`. |

### Returns

Success: `{ scrolled, finalOffset, effect, snapshot? }`. `scrolled` is `true` only when the
scroll offset moved; with `intoView` and no `Scrollable` around the ref, or a list already at
its edge, it is `false` and `effect.changed` is `false` (a delta scroll with no laid-out
`Scrollable` at all returns a not-found error). A delta is clamped to the scroll extents. Re-snap after; off-screen widgets gain refs only
once Flutter builds them.

### Example call

```json
{ "name": "tapir_scroll", "arguments": { "ref": "e12", "direction": "down", "pixels": 500 } }
```

---

## tapir_select_option

Dispatch: `ext.tapir.select_option`

Select an option in a `DropdownButton` by ref + value. The handler finds the first
`DropdownButton` at or below the ref's element and calls its `onChanged` with `value`
directly: nothing is opened or tapped and the actionability gate does not run. `value` is
passed as a string, so the tool suits a dropdown whose value type is `String`.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | yes | Ref (`e<N>`) of the select element. |
| `value` | string | yes | Value handed to `onChanged`. |

### Returns

Success: `{ selected: true, value, effect }`. `value` is the value you passed; `effect` is
the `selected` block (`verified`, `value`) that reports what the dropdown holds after the
settle, so a parent that refuses the change reads `verified: false`. Re-snap after;
downstream widgets may re-render.

Error: no selectable widget found (a `not found` error with candidate refs).

### Example call

```json
{ "name": "tapir_select_option", "arguments": { "ref": "e7", "value": "GET" } }
```

---

## tapir_set_checkbox

Dispatch: `ext.tapir.set_checkbox`

Read the checked or toggled state of a checkbox, switch or radio by ref and tap it only
when it differs from `value`. The state is read from the first of these that applies, so
a control from any library works (Flutter material, `material_ui`, `wind_kit` or a
hand-built `Semantics(checked: ...)`):

1. The ref's own node carries a checked or toggled flag: that flag is the state. A merging
   tile folds the flags of the controls inside it into its own node, and they cannot be told
   apart, so such a ref is read as one control and is never refused as ambiguous.
2. The ref's own node carries no flag and exactly one descendant node does: that descendant.
3. The ref was minted without a node (a `find_by_text` entry) and its render object owns
   none: the nearest node above it, from that node's own flag only; an ancestor's subtree
   holds siblings and is never searched. (A render object that owns a node makes it the
   ref's own node, read as in cases 1 and 2.)

It is refused when no state is found in any of these places, and when the ref's own node
carries no flag and several descendant nodes do (pass the ref of one of them). A missing
state is never assumed unchecked. A mixed checkbox is always tapped once and reports
`previousValue: null`. When the state already equals `value` the call does not tap and
returns `toggled: false`.

The tap goes to the control whose state was read: a state read off a descendant (case 2) is
tapped at that descendant's centre, and in the other cases at the ref's own centre.
`set_checkbox` does not pass the actionability
gate, so it does not scroll the control into view: a control marked `[offscreen]` or
covered is missed and reported as `effect.verified: false`. Bring it on screen first
with `tapir_scroll` on the containing list (its ref or the ref of a visible row), then
call it. Do not `tapir_tap` the control to reveal it: the tap activates the control, so its
value can change before `set_checkbox` reads it, and a value that already matched is
toggled twice. The `tapir:set_checkbox` CLI exits 1 on `verified: false`, except with
`--json` or `--includeSnapshot`, which print the response and exit 0.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | yes | Ref (`e<N>`) of the checkbox, switch or radio, or of a node around or above one. |
| `value` | string | yes | `"true"` or `"false"` (target checked state). |

### Returns

Success: `{ ref, previousValue, value, toggled, effect }`. `previousValue` is `null` for a
mixed checkbox. `toggled` is `false` when the state already matched. `effect` is the
`checked` block (`verified`, `before`, `after`) read back after the tap, so a parent that
refuses the change reads `verified: false`.

### Example call

```json
{ "name": "tapir_set_checkbox", "arguments": { "ref": "e4", "value": "true" } }
```

---

## tapir_snap

Dispatch: `ext.tapir.snap`

Capture a YAML snapshot of the running Flutter app's Semantics tree with stable
`[ref=eN]` tokens. Call this FIRST, then pass the returned ref tokens to subsequent
action calls.

Interactive nodes inside a currently-overflowing render ancestor carry an additive
`overflow: true` sub-line (live `RenderFlex.toStringShort()` check). This is a
current-state signal; call `tapir_exceptions` for the full non-fatal error history.

Text fields collapse to a single ref. A field that produces two nested `textbox`
Semantics nodes (an outer wrapper plus the `RenderEditable` leaf that always owns its
own node) emits one ref for the outer node, tagged with an additive `typeable: true`
sub-line; the inner duplicate is suppressed when its render object is a render-tree
descendant of the outer node's render object. Collapse is by render-object containment
only, so two sibling fields sharing a label stay two distinct refs. Target the node
carrying `typeable: true` when calling `tapir_type`.

A control wrapped in `MergeSemantics` (a magic_starter `MSSwitch` row, a wind `WAnchor`)
is listed once. Flutter keeps each absorbed descendant in the tree as its own node
flagged `isMergedIntoParent`; the walk prints no line and mints no ref for it, and
still descends through it. The boundary line already carries the merged label, flags
and actions, which is what the platform exposes.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `depth` | integer | no | Max tree-traversal depth from the root. Omit for full tree. |
| `within` | string | no | Scope the walk to one subtree: the `e<N>` ref of the region to read. `q<N>` handles are not addressable here. An unknown ref is an error, not a silent widening. |
| `interactiveOnly` | boolean | no | Emit only nodes carrying a ref; drop the plain `- text` lines. Default `false`. |
| `includeEnrichers` | boolean | no | Add the Magic and Wind enricher lines under each ref. Default `false`. |
| `grep` | string | no | Emit only nodes whose label or value matches this regular expression, plus the ancestors leading to them. A pattern that is not a valid regex (an unbalanced `(` in a label, say) is matched as a literal substring and the response carries `grepLiteral: true`. |

A full tree is the wrong default answer to most questions. It costs context on any real
screen, and on a shell whose sidebar repeats the labels of the pages it opens it is also
the misleading answer: the unscoped lookup resolves the nav item. `within` +
`interactiveOnly` is the usual shape before an action.

### Returns

Success: `{ "snapshot": "<yaml>", "groupId": "<id>" }`. The `snapshot` value is a YAML
document where each node is annotated with a `[ref=e<N>]` token, its role, label, actions,
bounds, optional `overflow: true` and `typeable: true` sub-lines, and any enricher-contributed
indented lines.

A ref line may end with ` [offscreen]` (the widget lies outside the viewport) and/or
` [occluded]` (a hit test at its centre reaches something painted above it), after
`[ref=e<N>]`. Both are absent on a healthy screen. An offscreen node is never probed for
occlusion, and a node with no area carries neither marker.

A merged node whose centre is not on its own control also gets an indented
`tapOwner: {"x":..,"y":..,"w":..,"h":..}` sub-line (the control's rect); a `tapir_tap` on that
ref goes to the control.

When non-fatal render or build `FlutterError`s are in the capture buffer (for example a
`ParentDataWidget` misuse or a layout overflow), a `renderErrors` block is added to the
response:

```json
{
  "snapshot": "...",
  "groupId": "snapshot-1700000000000",
  "renderErrors": {
    "count": 1,
    "recent": [ { "type": "FlutterError", "message": "Incorrect use of ParentDataWidget." } ],
    "hint": "Run tapir:exceptions for full messages + stack traces."
  }
}
```

`renderErrors` is omitted entirely when the screen is clean. `recent` contains at most 3
entries, each with `type` (string) and `message` (first line of the error). `count` reflects
the full buffer depth, which may exceed 3. Use `tapir_exceptions` to retrieve full messages and
stack traces.

### Example call

```json
{ "name": "tapir_snap", "arguments": { "depth": 8 } }
```

---

## tapir_tap

Dispatch: `ext.tapir.tap`

Tap a widget by ref. Synthesises a pointer Down + 50ms hold + Up sequence at the widget's
LIVE centre. Triggers `GestureDetector.onTap`, `InkWell.onTap`, button `onPressed`. For
`TextField` widgets the tap also requests keyboard focus.

The pointer dispatches at the target's live rect, re-resolved immediately after the
actionability gate passes (it falls back to the cached snapshot rect only for slivers /
detached render objects). A button whose host rebuilt it into a shifted slot between
`tapir_snap` and `tapir_tap` is still hit correctly.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | yes | Widget ref (`e<N>`). |
| `snapshot` | string | no | Post-tap snapshot: `full` (the default), `diff` or `none`. `diff` returns only the lines the tap changed since your last unfiltered snapshot (a `tapir_snap` or an earlier action): a changed row is `- <old line>` then `+ <new line>`, an added row `+ `, a removed row `- `, then a `(K of N lines changed)` footer, and the payload adds `snapshotMode: "diff"`. With no baseline yet the full text comes back. A filtered `tapir_snap` (`grep`, `within`, `depth`, `interactiveOnly`) never records the baseline, and a hot restart clears it. |
| `includeSnapshot` | boolean | no | Embed post-action snapshot. Default `true`. |
| `checkStable` | boolean | no | Run the Stable actionability gate. Default `true`. |
| `checkReceivesEvents` | boolean | no | Run the Receives-Events actionability gate. Default `true`. |
| `retarget` | boolean | no | Default `true`: a tap on a merged boundary goes to its one labelled control. `false` taps the boundary centre. |
| `until` | string | no | After the tap settles, poll the live element tree for a `Text` equal to this value (up to `untilTimeoutMs`) and add an `untilMatched` boolean. Confirms a navigation / state change in one call. Default off, which keeps the response shape unchanged. |
| `untilTimeoutMs` | integer | no | Poll ceiling for `until`, in milliseconds. Default `3000`. |

### Returns

Success: `{ ref: "<ref>", effect: {kind: "treeChanged", changed: bool} }`. The `effect`
block is always present: `changed` is true when the target's own route or semantics
subtree differed after the tap, false when nothing observable happened. With `until` set
the response also carries `untilMatched: true|false` (true when the expected text appeared
within the window).

**A merge boundary taps its own control.** A tap at the centre of a `MergeSemantics`
boundary can land on another handler (a full-frame stage) while the gate still says
confirmed. When exactly one labelled control owns the merged label and a hit test
at its centre reaches it inside the viewport, the pointer goes there and the response adds
`retargeted: {from: {x, y}, to: {x, y}, ownerRect: {left, top, width, height}, centreHandled?}`
(`centreHandled: true` when the centre has a tap handler of its own). Pass `retarget: false` to
tap the centre instead. When retargeting is not safe (several candidates, or the control is
covered or off screen) the tap stays at the centre and the response adds
`tapPointOutsideOwner: {ownerRect, point}`. The gate is unchanged. `tapir_snap` and
`tapir_observe` show the control's rect ahead of time as `tapOwner` (with `retargets: false`
when a tap cannot go there). Only `tapir_tap` retargets.

Error: actionability gate failure (`"not enabled"` / `"zero rect"` / `"off-viewport"`) or
stale-handle.

**Stale `e<N>` refs.** When the element behind an `e<N>` ref has left the tree, the
action relocates it through the label-and-index query the snapshot bound to the ref, and
trusts the result only if the live tree has the same number of nodes with that label as at
snapshot time and the hit sits on the route the ref was minted on. A relocation adds
`reresolved: ["e5"]` to the response. With a different count, or on another route, the ref
fails as before with `defunct (element no longer mounted)`; re-snap. Known limit: the bound
query has no role, so a node of another role with the same label in the same position on
the same route could match.

### Example call

```json
{ "name": "tapir_tap", "arguments": { "ref": "e5" } }
```

---

## tapir_triple_click

Dispatch: `ext.tapir.triple_click`

Fire three primary clicks (~100ms apart) at the widget identified by `ref` (Playwright
`locator.click({ clickCount: 3 })` parity). In Material text fields this selects an entire
paragraph.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | yes | Widget ref (`e<N>`). |
| `includeSnapshot` | boolean | no | Embed post-action snapshot. Default `true`. |
| `checkStable` | boolean | no | Run the Stable actionability gate. Default `true`. |
| `checkReceivesEvents` | boolean | no | Run the Receives-Events actionability gate. Default `true`. |
| `snapshot` | string | no | `full`, `diff` or `none`. Overrides `includeSnapshot`. |

### Returns

Success: `{ ref: "<ref>" }`. The actionability gate runs once before the first tap.

### Example call

```json
{ "name": "tapir_triple_click", "arguments": { "ref": "e5" } }
```

---

## tapir_type

Dispatch: `ext.tapir.type`

Type text into a `TextField` widget by ref. Fires `userUpdateTextEditingValue` so
`onChanged` callbacks fire and form validators run. Replaces existing text (does not
append).

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `ref` | string | yes | TextField widget ref (`e<N>`). |
| `text` | string | yes | Text to enter. Pass empty string to clear. |
| `snapshot` | string | no | `full`, `diff` or `none`. Overrides `includeSnapshot`. |
| `includeSnapshot` | boolean | no | Embed post-action snapshot. Default `true`. |
| `checkStable` | boolean | no | Run the Stable actionability gate. Default `true`. |
| `checkReceivesEvents` | boolean | no | Run the Receives-Events actionability gate. Default `true`. |

### Returns

Success: `{ text, effect }`, with no `ref`; `text` is the text you passed and `effect` is the
`text` block that reports what the field holds after the settle. Multi-line text uses `\n`
line breaks. A `checks` report (what the actionability gate could not establish) and the
post-action snapshot ride along when they apply.

### Example call

```json
{ "name": "tapir_type", "arguments": { "ref": "e9", "text": "hello@example.com" } }
```

---

## tapir_wait_for

Dispatch: `ext.tapir.wait_for`

Wait until a UI condition is satisfied or the timeout expires. Polls at 200ms; returns as
soon as the condition flips.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `text` | string | no | Wait until a `Text` with this exact data exists. |
| `textGone` | string | no | Wait until no such `Text` exists. |
| `expression` | string | no | Matched as text, exactly like `text`; it is not evaluated as Dart (use `tapir_evaluate` for that). |
| `timeoutMs` | integer | no | Wait timeout in milliseconds. Default `5000`. |

Pass one of `text`, `textGone`, `expression`; the handler errors when none is passed.

### Returns

Match: `{ matched: true, elapsedMs: <int> }`.

Timeout: a normal result, `{ matched: false, reason: "timeout" }`, not an MCP error, so check
`matched` before continuing (the CLI, `tapir:wait`, exits 1 in that case). With none of the
three keys the call errors; with several it uses the first of `text`, `textGone`, `expression`.

### Example call

```json
{ "name": "tapir_wait_for", "arguments": { "text": "Welcome", "timeoutMs": 3000 } }
```

---

## tapir_wait_for_network_idle

Dispatch: `ext.tapir.wait_for_network_idle`

Wait until the running app reports zero in-flight HTTP requests for a contiguous `idleMs`
window. Playwright `waitForLoadState` network-idle semantics. Missing-crumbs graceful:
returns idle immediately when crumbs is not set up.

### Input schema

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `timeoutMs` | integer | no | Maximum total wait time. Default `5000`. |
| `idleMs` | integer | no | Contiguous-zero window before declaring idle. Default `500`. |
| `pollIntervalMs` | integer | no | Poll cadence in milliseconds. Minimum `100`; default `200`. |

### Returns

Success: `{ matched: true, idleAchievedMs: <int> }`.

Error on timeout: structured error envelope `{ type: "timeout", message: "max in-flight
count observed: <int>" }`.

### Example call

```json
{ "name": "tapir_wait_for_network_idle", "arguments": { "timeoutMs": 8000, "idleMs": 750 } }
```

---

## Related Documentation

- [overview.md](https://anilcancakir.com/tapir/docs/mcp/overview.md): the tool catalogue, dispatch surfaces and lifecycle.
- [setup.md](https://anilcancakir.com/tapir/docs/mcp/setup.md): the per-client install matrix and the reconnect ritual.
- [actionability-gate.md](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md): the checks behind every "not actionable" error.
- [perf-trace.md](https://anilcancakir.com/tapir/docs/reference/perf-trace.md): the Chrome Trace export behind `tapir_perf_trace`.

---

# Authoring a snapshot enricher

`TapirSnapshotEnricher` is the extension point that lets a package or a host app append custom YAML lines under each ref of a `tapir:snap` output.

Enrichers run when the snapshot is taken with `includeEnrichers` on. The Magic integration
ships enrichers out of the box, and anyone can register one. This
guide walks through the typedef, the four-clause contract, the registration surface, and a
short worked example.

- [The typedef](#the-typedef)
- [The four-clause contract](#the-four-clause-contract)
- [Registration](#registration)
- [Worked example: Riverpod provider value enricher](#worked-example-riverpod-provider-value-enricher)
- [Testing your enricher](#testing-your-enricher)
- [Related Documentation](#related-documentation)

## The typedef

```dart
typedef TapirSnapshotEnricher =
    String? Function(Element element, RefRegistry refs);
```

An enricher is a plain top-level function (or any compatible callable)
that receives a Flutter `Element` plus the snapshot's `RefRegistry` and
returns either a YAML fragment to append under the ref, or `null` to skip
that element.

**The typedef is frozen.** The signature `String? Function(Element element,
RefRegistry refs)` does not change without a coordinated bump across `tapir` and
`magic_devtools` (which ships the Magic enrichers via `MagicTapirIntegration`). Treat it
as a load-bearing cross-repo contract.

## The four-clause contract

Every enricher implementation MUST honour these clauses:

1. **Synchronous.** No `Future` return. The snapshot extension iterates
   the enricher chain on a single render-tree pass; an async enricher
   would deadlock the dispatcher.
2. **Stateless WRT call ordering.** The dispatcher iterates
   `TapirPlugin.enrichers` in insertion order; later-registered enrichers
   see the same `Element` as earlier ones. An enricher must not mutate
   shared state in a way that affects siblings later in the chain.
3. **Keep output keys distinct.** When two enrichers emit overlapping
   YAML keys for the same ref, the snapshot writes both fragments; neither
   wins, and a reader cannot rely on registration order as precedence.
4. **Null means skip.** Return `null` when the element is not relevant
   (no matching widget type, no ancestor context, no data available).
   The dispatcher silently drops null returns.

A fifth rule applies to every enricher implementation in practice:
**never retain the `Element` across calls.** The enricher receives the
element by reference; capturing it in a closure, a static field, or any
external collection produces a leak and can silently widen the actionability
gate's view of the live tree on the next snap.

## Registration

Enrichers register against the `TapirPlugin.enrichers` list, mutated in
place. The list is read live on every snapshot call, so mid-session
registrations are picked up immediately.

```dart
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:tapir/tapir.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  if (!kReleaseMode) {
    TapirPlugin.install();
    TapirPlugin.enrichers.add(myCustomEnricher);
  }
  runApp(app);
}
```

When you ship a reusable integration (rather than a one-off in `main`),
follow the `MagicTapirIntegration` pattern: a private constructor, an
`install()` static that guards against duplicate adds with a static bool,
and a `resetForTesting()` static that removes the enricher and clears the
guard. `wind_kit` takes a different path (the neutral `WindDebugRegistry`
bridge, read by tapir at snap time without an enricher); pick the enricher
pattern when your data is per-element and the bridge pattern when your
data is a global registry the consumer installs once.

## Worked example: Riverpod provider value enricher

Surface the current value of a `StateProvider<int>` (e.g. a session
counter) next to every snapshot ref. The enricher reads the provider once
per snap from a host-supplied `ProviderContainer`, formats the value, and
emits a `riverpodCounter:` line.

```dart
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:tapir/tapir.dart';

/// Host-owned counter provider. Real apps would define this elsewhere.
final counterProvider = StateProvider<int>((ref) => 0);

class RiverpodTapirIntegration {
  RiverpodTapirIntegration._();

  static bool _installed = false;
  static ProviderContainer? _container;

  /// Wire the enricher. Pass the host's [ProviderContainer] so the
  /// enricher can read provider values synchronously at snap time.
  static void install(ProviderContainer container) {
    if (_installed) return;
    _installed = true;
    _container = container;
    TapirPlugin.enrichers.add(riverpodCounterEnricher);
  }

  @visibleForTesting
  static void resetForTesting() {
    TapirPlugin.enrichers.remove(riverpodCounterEnricher);
    _container = null;
    _installed = false;
  }
}

/// Emits `riverpodCounter: <value>` for every element when a container
/// is wired. Element-independent (the value is global), but kept as a
/// per-element enricher so the YAML emitter consistently surfaces it
/// next to each ref. Returns null when no container has been installed.
String? riverpodCounterEnricher(Element element, RefRegistry refs) {
  final container = RiverpodTapirIntegration._container;
  if (container == null) return null;
  final int value = container.read(counterProvider);
  return 'riverpodCounter: $value';
}
```

A few details worth noting:

- The enricher reads from a module-static `_container` rather than
  capturing the container in a closure. This is the canonical pattern
  when an enricher needs side-channel state; it keeps the typedef
  intact and lets `resetForTesting()` cleanly drop the reference.
- `container.read(counterProvider)` is the synchronous Riverpod read.
  A `.watch` would not compile here (the enricher is not a widget) and
  would also violate clause 1 of the contract.
- The `element` parameter is unused. That is fine; per-element
  enrichers may emit element-independent annotations. The dispatcher
  still walks the element tree, which keeps the line attached to the
  correct ref in the YAML output.

## Testing your enricher

Drive the enricher directly from a widget test:

```dart
testWidgets('riverpodCounterEnricher surfaces the current value',
    (tester) async {
  final container = ProviderContainer();
  addTearDown(container.dispose);
  RiverpodTapirIntegration.install(container);
  addTearDown(RiverpodTapirIntegration.resetForTesting);

  await tester.pumpWidget(const SizedBox.shrink());
  final element = tester.element(find.byType(SizedBox));

  expect(riverpodCounterEnricher(element, RefRegistry.instance),
      'riverpodCounter: 0');

  container.read(counterProvider.notifier).state = 42;
  expect(riverpodCounterEnricher(element, RefRegistry.instance),
      'riverpodCounter: 42');
});
```

For tests that exercise the enricher inside the full snapshot pipeline,
trigger a real `tapir:snap` via the VM Service extension (see the tapir
extension tests under `test/src/extensions/` for the pattern).

## Related Documentation

- [magic-integration.md](https://anilcancakir.com/tapir/docs/plugins/magic-integration.md): the multi-enricher reference (form
  fields, controllers, gates, middleware, auth, broadcast state, and crumbs ring buffers).
- [wind-integration.md](https://anilcancakir.com/tapir/docs/plugins/wind-integration.md): the bridge pattern for global state, which
  surfaces breakpoint, brightness, platform and pseudo-class states without an enricher.

---

# Magic integration

`MagicTapirIntegration` is the glue layer that registers Magic-aware snapshot enrichers with `tapir`.

It sits between the `magic` Flutter framework (Laravel-inspired primitives like `MagicForm`,
`MagicRouter`, `Gate`, `Auth`, `Echo`) and the `tapir` snapshot pipeline. It registers a fixed
set of `TapirSnapshotEnricher` callbacks against `TapirPlugin.enrichers`, so a `tapir:snap`
(or `tapir_snap` MCP) taken with `includeEnrichers` carries Magic-aware annotations
alongside the standard Semantics tree.

`MagicTapirIntegration` ships in the **`magic_devtools`** package, not in magic
core. Add it as a dev_dependency (it is debug-only; release builds tree-shake
the `!kReleaseMode` branch that calls `install()`):

```yaml
dev_dependencies:
  magic_devtools: ^<version>
```

This document covers the behavioural enrichers most likely to drive an
agent's reasoning loop. The others (`magicFormEnricher`, `magicNavigationEnricher`,
`magicControllerFlagsEnricher`, `magicRouteParamsEnricher`,
`magicEchoConnectionEnricher`, `magicGateResultsAllEnricher`,
`magicRecentHttpEnricher`, `magicRecentLogsEnricher`,
`magicRecentExceptionsEnricher`) surface form fields, the active route,
controller flags, route parameters, broadcast connection state, recent
gate results, and the crumbs HTTP / log / exception ring buffers; read
the dartdoc on `MagicTapirIntegration` for those.

- [When to call install](#when-to-call-install)
- [The core enrichers](#the-core-enrichers)
- [Example snapshot output](#example-snapshot-output)
- [Test-only reset](#test-only-reset)
- [Frozen contract](#frozen-contract)
- [Related Documentation](#related-documentation)

## When to call install

`MagicTapirIntegration.install()` must run **after** `Magic.init()` has
booted the container (the enrichers read from `Magic.controllers`,
`MagicRouter.instance`, `Gate.manager`, and `Auth.user()`, all of which
require the service providers to be live). It must also run **after**
`TapirPlugin.install()`, because the `TapirPlugin.enrichers` list is the
target the integration mutates.

The canonical debug-only host integration (`MagicTapirIntegration` comes from
the `magic_devtools` dev_dependency):

```dart
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:magic/magic.dart';
import 'package:magic_devtools/tapir.dart'; // from the magic_devtools dev_dependency
import 'package:tapir/tapir.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  if (!kReleaseMode) TapirPlugin.install();
  await Magic.init();
  if (!kReleaseMode) MagicTapirIntegration.install();
  runApp(const MagicApplication());
}
```

`package:magic_devtools/tapir.dart` exists only in a `magic_devtools` release built on
tapir; an older release has no tapir integration yet, and the import above does not
compile against it. Upgrade `magic_devtools` first. `dart run tapir tapir:install` writes
these lines only when the resolved `magic_devtools` ships `tapir.dart`; otherwise it skips
them and warns, and `tapir:doctor` says what to upgrade.

`install()` is idempotent; calling it twice in the same isolate is a no-op
after the first call, matching `TapirPlugin.install()` semantics. Release
builds tree-shake both `!kReleaseMode` branches. Installing tapir before `Magic.init()` keeps
the driver live while Magic boots.

## The core enrichers

### magicControllerEnricher

Emits `magicControllerState: <ControllerClass>.<rxStatus>` for the first
`MagicStateMixin`-bearing controller registered via `Magic.put`. The status
is the enum name of the controller's `rxStatus.type` (`success`, `loading`,
`error`, or `empty`). Returns null when no `MagicStateMixin` controller is
registered, so a guest-only or pre-controller view collapses cleanly.

### magicFormErrorsEnricher

Emits `magicFormErrors: <field>="<text>",...` for elements under a
`MagicForm` whose controller carries server-side `ValidatesRequests` errors
that match the form's own field set. Cross-form leak is guarded by
intersecting the controller's `validationErrors.keys` with the form's
`fieldNames`; messages longer than 80 characters are truncated to a
77-character prefix followed by `...`. Returns null when the controller
has no errors, no `ValidatesRequests` mixin, or no errors matching the
form's fields.

### magicGateResultEnricher

Emits `magicGateResult: <ability>.<allowed|denied>` for the most recently
cached `GateResult` in `Gate.manager`. The cache is populated transparently
by every `Gate.allows` / `Gate.denies` call, so an agent reading the
snapshot can confirm which authorization check ran last and what it
returned. Returns null when no check has run since the last
`Gate.manager.flush()`.

### magicMiddlewareEnricher

Emits `magicMiddleware: <name1,name2>` for the active route's resolved
middlewares. Reads `MagicRouter.instance.currentRoute.middlewares` and
labels each entry by class `toString()` for `MagicMiddleware` instances or
by the raw string for kernel-aliased middlewares. Returns null when no
route is active or the route has zero middlewares.

### magicAuthUserEnricher

Emits `magicAuthUser: <id>[:<displayName>]` for the authenticated user
surfaced by `Auth.user()`. Falls back to `magicAuthUser: <id>` (no trailing
colon) when `display_name` is null, missing, or empty. Returns null when
the session is a guest.

## Example snapshot output

A typical snapshot fragment for a `MonitorListView` rendered inside a
`MagicForm` with one validation error and a recently checked `monitors.view`
ability:

```yaml
- ref: e3
  role: button
  label: "Create Monitor"
  bounds: 16,128,160,40
  magicRoute: /monitors
  magicControllerState: MonitorController.success
  magicGateResult: monitors.create.allowed
  magicMiddleware: EnsureAuthenticated,VerifyTeamMembership
  magicAuthUser: 4f9a-2b1c:Anilcan Cakir
- ref: e4
  role: textField
  label: "Name"
  bounds: 16,200,328,48
  magicFormField: name
  magicFormErrors: name="The name field is required."
```

The enrichers populate the lines under each ref in the order
they were registered. The dispatcher iterates `TapirPlugin.enrichers` in
insertion order and writes every non-null fragment under the ref. Nothing
deduplicates keys: if two enrichers emit the same key, the snapshot carries
both lines, so keep enricher keys distinct.

## Test-only reset

`MagicTapirIntegration.resetForTesting()` removes every enricher from
`TapirPlugin.enrichers`, cancels the internal Echo connection-state
subscription, and clears the idempotency guard. Call it in `tearDown` so
consecutive widget tests start with a clean enricher chain.

## Frozen contract

Every Magic enricher honours the `TapirSnapshotEnricher` typedef contract:
synchronous, stateless, never retains the `Element` across calls, returns
null when the element is not relevant. The typedef is frozen; see
[enricher-authoring.md](https://anilcancakir.com/tapir/docs/plugins/enricher-authoring.md) for the full typedef and authoring guide.

## Related Documentation

- [enricher-authoring.md](https://anilcancakir.com/tapir/docs/plugins/enricher-authoring.md): the typedef, the four-clause contract and how to write your own enricher.
- [wind-integration.md](https://anilcancakir.com/tapir/docs/plugins/wind-integration.md): the `wind:` block that tapir emits ahead of these enrichers.

---

# Wind integration

Tapir reads the state of `wind_kit` widgets through a neutral diagnostics bridge, so a host only calls `Wind.installDebugResolver()`.

`wind_kit` publishes runtime diagnostics through `wind_kit_diagnostics_contracts.WindDebugRegistry`,
a package both `wind_kit` and `tapir` depend on without depending on each other. Tapir reads
`WindDebugRegistry.current?.resolve(element)` inside `ext_snapshot.dart` and `ext_observe.dart`
ahead of the enricher loop, so no tapir-side install call is required for wind metadata to
appear. The `wind:` block shows under the ref of every W-prefixed widget that has a `className`,
in a snapshot taken with `includeEnrichers` on (`tapir:snap --includeEnrichers`, or the
`includeEnrichers` flag of `tapir_snap` and `tapir_observe`). `tapir_observe` projects the block:
its default and `"true"` modes return only `breakpoint` and `states`, and `className`, `brightness`,
`platform` and the colours need `includeEnrichers: "full"`.

- [Host integration](#host-integration)
- [The core fields](#the-core-fields)
- [Example snapshot output](#example-snapshot-output)
- [Test-only reset](#test-only-reset)
- [Cross-package coupling](#cross-package-coupling)
- [Related Documentation](#related-documentation)

## Host integration

Call `Wind.installDebugResolver()` (exported by `package:wind_kit/wind_kit.dart`) inside the host's
`!kReleaseMode` branch, after `TapirPlugin.install()`. No additional tapir-side registration is
required; tapir reads the resolver through the neutral contracts bridge at snap time.

```dart
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:tapir/tapir.dart';
import 'package:wind_kit/wind_kit.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  if (!kReleaseMode) {
    TapirPlugin.install();
    Wind.installDebugResolver();
  }
  runApp(app);
}
```

Both calls are idempotent. Release builds tree-shake the entire `!kReleaseMode` branch on dart2js (web) and
dart2native (mobile and desktop AOT).

## The core fields

Tapir emits a `wind:` YAML block under each W-widget ref by resolving the element through
`WindDebugRegistry.current?.resolve(element)` before the enricher loop runs. `className`,
`breakpoint`, `brightness`, `platform` and `states` are always present; `bgColor` and `textColor`
appear only when the resolved `WindStyle` carries a non-null `decoration.color` / `color`. A
W-widget with no `className` (an interaction-only widget such as `WAnchor`) gets no block.

| Field | Source | Notes |
|:------|:-------|:------|
| `className` | the widget's `className` | The raw utility string. |
| `breakpoint` | `WindContext.activeBreakpoint` | The widest `screens` entry the width reaches: `sm`, `md`, `lg`, `xl`, `2xl` by default, `base` below the first. |
| `brightness` | `WindContext.theme.brightness` | `light` or `dark`. |
| `platform` | `WindContext.platform` | `web`, `ios`, `android`, `macos`, `windows`, `linux`, or `unknown`. |
| `states` | `WindContext.activeStates` | Pseudo-class states active on the element (e.g. `[hover]`, `[hover, focus]`). |
| `bgColor` | `style.decoration?.color` | `#` plus 6-char RGB hex (opacity dropped, uppercase). |
| `textColor` | `style.color` | `#` plus 6-char RGB hex (opacity dropped, uppercase). |

## Example snapshot output

A `WButton` rendered on web at the `md` breakpoint with a hover state active:

```yaml
- ref: e7
  role: button
  label: "Sign In"
  bounds: 240,360,160,40
  wind:
    className: px-4 py-3 bg-blue-500 text-white hover:bg-blue-600
    breakpoint: md
    brightness: light
    platform: web
    states: [hover]
    bgColor: #3B82F6
    textColor: #FFFFFF
```

## Test-only reset

There is no tapir-side reset for wind state: the old `WindTapirIntegration` class no longer
exists. Tests reset the bridge with `WindDebugRegistry.resetForTesting()` from
`wind_kit_diagnostics_contracts`. Production code never calls any reset method.

## Cross-package coupling

`wind_kit_diagnostics_contracts` is a hosted dependency of both `tapir` and `wind_kit`; neither
depends on the other. A change to the contracts package is a coordinated bump across the
packages that read it.

## Related Documentation

- [enricher-authoring.md](https://anilcancakir.com/tapir/docs/plugins/enricher-authoring.md): the `TapirSnapshotEnricher` contract, for data that is per element rather than a global registry.
- [magic-integration.md](https://anilcancakir.com/tapir/docs/plugins/magic-integration.md): the Magic enrichers that run after the wind block.

---

# Actionability gate

The actionability gate is the precondition check tapir runs before it dispatches a pointer or key event at a widget.

- [Overview](#overview)
- [Precondition chain](#precondition-chain)
- [Live-rect dispatch (post-gate, pre-dispatch)](#live-rect-dispatch-post-gate-pre-dispatch)
- [What the gate could not prove](#what-the-gate-could-not-prove)
- [Failure reason substrings](#failure-reason-substrings)
- [Opt-out flags](#opt-out-flags)
- [Intentional gate skips](#intentional-gate-skips)
- [Cross-package implications](#cross-package-implications)
- [Related Documentation](#related-documentation)

## Overview

A refused gesture reads like this:

```
Widget ref=e5 is not actionable: not enabled
```

The pointer verbs (`tap`, `hover`, `drag`, `dblclick`, `right_click`, `triple_click`) and the
text verbs (`type`, `fill`) run the gate BEFORE synthesising the pointer or key
event. `clear`, `focus`, `scroll`, `press_key`, `select_option` and `set_checkbox` skip it. It lives in `lib/src/utils/actionability_gate.dart` and is invoked
through `ensureActionable(entry, ref: ...)`. The gate guards an agent against
firing a gesture against a widget that cannot accept it: disabled, collapsed,
off-screen, animating, or covered by another widget.

A failed gate throws a typed `TapirActionabilityException` whose `message` is
re-emitted by the VM-Service handler as
`ServiceExtensionResponse.error(extensionError, exception.message)`. Agents
parse the failure-reason substring to decide whether to re-snap, re-find,
scroll, wait, or abort.

## Precondition chain

The gate evaluates its preconditions in a fixed order (a defunct preflight, then five ordered checks). **The order is
FROZEN**: agents branch on the failure-reason
substring, so adding, removing, or reordering checks is a breaking change.

0. **Defunct (preflight)**; the entry's `Element` may have been deactivated by parent
   rebuild, route pop, or list-item recycle since the snapshot minted the ref.
   `findRenderObject()` returns null, or the framework throws on the inactive element.
   This guard runs before the five ordered checks below. Failure reasons:
   `defunct (element no longer attached to a render object)` or
   `defunct (element no longer mounted)`. The agent's recovery is to re-snap.
1. **Enabled**; the entry's `SemanticsNode` is non-null AND its
   `flagsCollection.isEnabled` is `Tristate.isFalse`. `Tristate.none` (no
   enabled flag set, e.g. plain `Text`) and `Tristate.isTrue` both pass. The
   gate only fails when the framework has explicitly marked the widget
   disabled. Synthetic entries without a captured `SemanticsNode` (for example,
   `find_by_text` results) pass through this check untouched.
2. **Zero-area rect**; the entry's `rect.width == 0 || rect.height == 0`. A
   zero-area rect cannot receive a pointer event at `rect.center` and almost
   always indicates the widget has been collapsed or detached between snapshot
   and action.
3. **Off-viewport**; the entry's rect does not intersect the active
   `FlutterView`'s visible logical viewport (recomputed every call from
   `WidgetsBinding.instance.platformDispatcher.views.firstOrNull` so window
   resizes between actions are honoured). Visible means the view minus its
   `viewInsets`: the app keeps laying out under a soft keyboard, but a
   pointer there never reaches it. When the rect's centre lies outside the
   visible viewport the gate first attempts `RenderObject.showOnScreen` to
   bring the element into view, then re-checks; it fails only when
   scroll-into-view cannot place the target inside the viewport. Skipped
   gracefully when no `FlutterView` is attached (headless test harnesses,
   multi-view race).
4. **Stable**; the entry's bounding box, sampled from the
   live `RenderBox` before and after one frame, has not drifted by more than
   0.5 logical pixels on any side. Animated widgets (sliding sheets,
   expanding tiles, page transitions) fail this gate so the agent waits for
   the animation to settle before retrying. Both samples are live, so a
   layout change that finished before the gate ran (the soft keyboard
   opening, the step 3 auto-scroll) does not trip this check. Opt out via
   `checkStable: false`.
5. **Receives events**; a hit-test at `rect.center` on the
   active view confirms the entry's render object (or a descendant) appears
   in the hit-test path. If the topmost target is anything else, an overlay,
   modal scrim, or stacked widget is swallowing the pointer. The thrown reason
   carries the obscurer's `runtimeType`. A graceful degradation accepts the
   action when the hit-test path contains only a root `RenderView` /
   `_ReusableRenderView` (Flutter Web's debug compositor sometimes pipes
   hit-tests through a snapshot view that does not mirror the live element
   subtree). Opt out via `checkReceivesEvents: false`.

## Live-rect dispatch (post-gate, pre-dispatch)

After the gate passes and BEFORE the pointer is synthesised, every pointer verb
(`tap`, `hover`, `drag` start + end endpoints, `dblclick`, `right_click`,
`triple_click`) re-resolves the target's CURRENT bounding rect via
`dispatchRectOf(entry)` and dispatches at that live centre, falling back to the
cached `entry.rect.center` only when the live rect is `null` (a sliver, a
detached / unsized render object, or a synthetic test entry). `dispatchRectOf`
reuses the same `_liveRectOf(entry.element)` helper the stable check (step 4)
measures, guarded by the `renderObject.attached` precondition Flutter's
`localToGlobal` asserts.

One exception: `tap` can retarget a merged semantics boundary. When exactly one
labelled control owns the merged label and a hit test at its centre reaches it,
the pointer goes to that control instead of the live centre (the response carries
`retargeted`). It is the default; `retarget: false` (`--no-retarget` on the CLI)
taps the live centre. `hover`, `dblclick`, `right_click`, `triple_click` and `drag`
always use the live centre. See [tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md).

This is purely additive to the FROZEN gate: it runs after the gate passes and
before dispatch, so it touches neither the evaluation order nor any
failure-reason substring. It fixes the false-success class where a host rebuilt
the target into a shifted slot between snapshot and action: the `Element` /
`RenderObject` identity (and thus `SemanticsNode.id`) is retained across a
same-type-and-key rebuild, so the live rect is valid and the pointer lands on
the moved target instead of its stale gate-time position. A residual TOCTOU
window remains between the live-rect re-resolve and the dispatch itself (the
smallest achievable without a frame lock); the `effect` block on every
`ext.tapir.tap` response reports whether the tap produced an observable effect,
so the residual window is visible rather than silent.

## What the gate could not prove

The gate throws on a precondition it can DISPROVE. Step 5 has a third
outcome it cannot: the hit-test sometimes fails to answer at all. On Flutter
Web's debug build that is routine, because DWDS pipes hit-tests through a
snapshot view that does not mirror the live element subtree, so the path
comes back carrying only the root render view.

Breaking every valid tap on that artefact would be the worse failure, so the
gate proceeds. It used to proceed silently, and a clean pass was then
indistinguishable from a confirmed one: that is how a fill printed a green
tick four times onto a row covered by a pinned footer, with nothing in any
response to say the check had not run.

The response carries a `checks` block whenever step 5 did not confirm. The
gated verbs that emit it are `tap`, `hover`, `drag`, `dblclick`,
`right_click`, `triple_click` and `type`; `fill` runs the gate through its
type step but copies only `effect` into its own response:

```json
{
  "ref": "e7",
  "checks": {
    "receivesEvents": "indeterminate",
    "why": "hit-test returned only the root render view",
    "overlapCandidates": ["RenderPhysicalShape@0,712,390x88"],
    "hint": "The gate could not confirm the target receives the event, so this action may have landed on something else. Read the `effect` block before trusting it."
  }
}
```

| `receivesEvents` | Meaning |
|:---|:---|
| absent | Confirmed. The hit-test reached the target or a descendant. |
| `indeterminate` | The hit-test could not answer. The action was dispatched anyway. |
| `skipped` | The caller passed `checkReceivesEvents: false`. |

`overlapCandidates` is a rect scan run only on the indeterminate path: render
objects that overlap the target and paint after it, capped at five. It is
advisory, not a verdict. An overlap is not proof of occlusion, since a
transparent layer overlaps and swallows nothing, which is exactly why the
hit-test exists and why these are candidates.

The block is absent on the healthy path, so its presence is the signal.

## Failure reason substrings

The thrown message has the shape
`Widget ref=$ref is not actionable: $reason`. Agents perform substring matches
against `$reason` to branch their recovery. **The substring list is FROZEN**:

| Reason substring | Trips when | Suggested agent recovery |
|:-----------------|:-----------|:-------------------------|
| `defunct (...)` | `findRenderObject()` returns null OR Element is in `_ElementLifecycle.defunct` lifecycle state | Re-snap; the widget was deactivated. |
| `not enabled` | `flagsCollection.isEnabled == Tristate.isFalse` | Re-snap; the widget may enable later. |
| `zero rect` | `rect.width == 0 \|\| rect.height == 0` | Re-snap or re-find; layout has shifted. |
| `off-viewport` | rect does not overlap the visible viewport (view minus `viewInsets`) even after `showOnScreen` + one frame | `tapir_scroll` with `intoView: true`, then retry. |
| `not stable` | live rect drifted > 0.5 logical pixels on any side across one frame | `tapir_wait_for_network_idle` or settle delay. |
| `obscured by` | hit-test at `rect.center` resolves to a non-descendant render object first | Dismiss the obscurer (modal, scrim, overlay). |

The off-viewport reason carries the rect and viewport
(`off-viewport (rect=..., viewport=...)`); the not-stable reason carries the
maximum side delta (`not stable (rect changed by X.Xpx)`); the obscured reason
carries the obscurer's runtime type (`obscured by other widget (top=...)`).
Match on the leading substring shown above, not the trailing detail.

## Opt-out flags

`ensureActionable` exposes two opt-out parameters; both default to `true` to
match Playwright's actionability semantics:

```dart
Future<ActionabilityReport> ensureActionable(
  RefEntry entry, {
  required String ref,
  bool checkStable = true,
  bool checkReceivesEvents = true,
});
```

| Flag | Disables | When to opt out |
|:-----|:---------|:----------------|
| `checkStable: false` | the stable precondition (4) | widget tests that fabricate synthetic `RefEntry` rects which do not match the live render-object geometry. |
| `checkReceivesEvents: false` | the receives-events precondition (5) | the same widget-test scenarios, plus environments where the platform compositor swallows hit-tests. |

The pointer verbs, `type` and `fill` expose the same two flags as `checkStable` and
`checkReceivesEvents` inputs (see [tool-reference.md](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md)); both default to `true`.

## Intentional gate skips

Some action handlers do NOT route through the actionability gate. These skips
are deliberate and listed here so contributors do not add the gate "for symmetry":

- **`scroll`**; operates on the parent `Scrollable` rather than the ref
  target. Gating the ref would refuse scrolls against widgets that are
  off-viewport, which is exactly the scenario `tapir_scroll` is meant to fix.
- **`select_option`**; calls the dropdown's `onChanged` callback directly
  instead of tapping, so no pointer event leaves the VM and there is nothing
  for the gate to check.
- **`press_key`**; targets the currently focused widget, not a ref. The gate
  contract requires a `RefEntry`; the focused widget may not have a token.

## Cross-package implications

The gated actions share a common error shape. `TapirActionabilityException`
is caught by the VM-Service handler and re-emitted via
`ServiceExtensionResponse.error(extensionError, wrapErrorDetail(...))`. The wire
error detail is a JSON string with a `message` field (the flat message, reason
included) and an `envelope` field (a machine-readable `type`, `widget_path` and
`suggestions`). Substring matching on the reason still works because the reason
sits verbatim inside `message`; consuming agents (Claude Code, Cursor,
Windsurf via the MCP tool surface) branch on it.

The contract guarantee is:

- The reason substrings are frozen and listed above.
- The evaluation order is frozen so substring branching stays deterministic.
- The exception is always typed; the wire format is always the JSON string described above.
- Agents re-snap or re-find on failure. The gate never silently retries; the
  cost of a silent retry on an animating or obscured widget is a flaky test
  the agent cannot diagnose.

A change to any of these guarantees requires a coordinated bump across
`tapir` (this package), `magic` (whose `MagicTapirIntegration` adds
enrichers to the snapshots that mint the refs the gate guards) and `wind_kit`
(whose diagnostics reach the same snapshots through
`wind_kit_diagnostics_contracts`). Treat the gate's public contract as
load-bearing across the ecosystem.

## Related Documentation

- [tool-reference.md](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md): the `checkStable` and `checkReceivesEvents` inputs and the `effect` block of every gated verb.
- [frame-production.md](https://anilcancakir.com/tapir/docs/reference/frame-production.md): why a hidden window or tab produces no frames for the stable check to sample.
- [magic-integration.md](https://anilcancakir.com/tapir/docs/plugins/magic-integration.md): the Magic enrichers that annotate the refs the gate guards.

---

# Frame production

Every tapir read and action depends on the app producing frames, and this page covers when that stops, what tapir does about it, and the fallback.

When frame production stops, reads and actions go wrong at once, and neither looks like a tooling problem.

- [When frame production stops](#when-frame-production-stops)
- [What breaks, and why it reads as a product defect](#what-breaks-and-why-it-reads-as-a-product-defect)
- [What tapir does](#what-tapir-does)
- [The fallback](#the-fallback)
- [Related Documentation](#related-documentation)

## When frame production stops

Flutter turns frame production off for some lifecycle states:

| `AppLifecycleState` | Frames |
|:---|:---|
| `resumed`, `inactive` | on |
| `hidden`, `paused`, `detached` | off |

On Flutter web, Chrome reports `document.visibilityState: "hidden"` as soon as the tab is backgrounded or its window falls behind another, and the engine maps that to `AppLifecycleState.hidden`. Starting the app detached is enough to land there without touching anything.

On desktop the same state follows the window: hidden, minimised or fully occluded (macOS reports `hidden` after an occlusion event). Another app in front of a visible window is `inactive`, which still produces frames.

## What breaks, and why it reads as a product defect

Two separate symptoms, one cause:

- **A snapshot loses its text.** Semantics labels are rebuilt during a frame. With no frames, `tapir:snap` returns the buttons and none of the `- text` nodes, so a screen that renders perfectly reads as completely empty. This has been mistaken for "the dashboard is permanently stuck on loading skeletons"; the screen was fine and a screenshot proved it.
- **An action reports success and changes nothing.** A gesture is dispatched into the widget tree, but the frame that would apply it never runs. The handler returns a clean payload for a tap that could not possibly land. On a hidden macOS window a tap answered "no observable change" and a screenshot returned the last cached frame.

## What tapir does

### Frame forcing

Tapir wakes the engine itself. At the entry of every `ext.tapir.*` verb, when `SchedulerBinding.framesEnabled` is false and the lifecycle is `hidden` or `paused`, `ensureFramesProduced()` delivers `AppLifecycleState.inactive` through the `flutter/lifecycle` channel, the message the engine itself sends, and schedules a forced frame; once a frame has run it delivers `resumed`. (`inactive` first, because Flutter drops a message equal to the current state, which would hide a real engine `resumed` arriving during the wait.) `detached` and a null lifecycle are never forced: the first means the engine is going away, the second that it has not reported a state yet.

The wake counts only when a frame actually runs within `kFrameSyncTimeout` after it. If none does, tapir delivers the previous lifecycle again and the call proceeds as if it had not tried, so the `warnings` block below stays. That check stops a wake that did nothing (an asleep display) from being reported as forced. On web the wake is not attempted: see [Web](#web).

A response whose call had to force carries `framesForced: true`, so you know the app was occluded even though the result is fresh:

```json
{ "ref": "e7", "effect": { "kind": "treeChanged", "changed": true }, "framesForced": true }
```

The force is re-applied on every call, not once, because the OS flips the lifecycle back to `hidden` on its next occlusion event.

Verbs that must observe the engine as it is skip it: `perf_begin`, `perf_end`, `perf_insight`, `perf_trace`, `boot_id`, `close_app`, `console`, `exceptions`, `semantics_hold` and `evaluate`.

**Side effect.** The app's own lifecycle observers see `resumed` while its window is still hidden. An app that pauses work or tears down a socket on `hidden` will not have done so by the time tapir acts.

The same applies to routes: reading a ref's route (for `e<N>` relocation) uses `ModalRoute.of`, which makes each labelled element depend on its route's modal scope. A snapshot can therefore rebuild an element, and run its `didChangeDependencies`, when its route's status changes (a push or pop over it). Flutter offers no public way to read the route without that dependency.

**Opt-out.** Build the app with `--dart-define=TAPIR_FORCE_FRAMES=false` (`kTapirForceFrames`) to leave a hidden app frameless. Every response then carries the `warnings` block below.

### macOS

Verified live with the window hidden (`osascript -e 'tell application "System Events" to set visible of process "<App>" to false'`): `tapir:tap`, `tapir:snap`, `tapir:screenshot` and `tapir:navigate` all work once the lifecycle is forced. Before forcing, taps reported "no observable change", snapshots went stale and screenshots returned the last cached frame.

One caveat remains: an asleep display can still starve frames. `caffeinate -u -t 3` wakes the display; that it fixes tapir's case has not been verified here.

### Web

A hidden Chrome tab has its `requestAnimationFrame` callbacks withheld by the browser, so no lifecycle message can make a frame run there; tapir does not attempt the wake on web, which would cost every verb a 200 ms wait and four lifecycle callbacks in the app for nothing. Verified live with a second tab in front: a tap answered `effect.changed: false` with the `warnings` block (`platform: web`, `lifecycleState: hidden`) and no `framesForced`; after the app tab was activated through CDP the same tap applied. On web the fix stays [`Page.bringToFront`](#the-fallback).

### Bounded settling

Handlers settle a gesture or an edit by awaiting one or two frames. Those awaits go through `awaitFrameOrTimeout` / `awaitFramesOrTimeout` and fall through after `kFrameSyncTimeout` (200ms per frame) rather than blocking on `WidgetsBinding.instance.endOfFrame`, which never completes while frames are off. Without the bound a `tapir:tap` against a hidden page sat for 45s+ with no output and no error until the caller's own timeout killed it.

A healthy engine is unaffected: a real frame lands in ~16ms and always wins the race.

### The `warnings` block

When tapir could not force frames (the opt-out above, a `detached` lifecycle, or a wake that produced no frame, or any hidden web tab) every `ext.tapir.*` success payload gains a `warnings` key while frame production is off:

```json
{
  "snapshot": "...",
  "groupId": "snapshot-1700000000000",
  "warnings": {
    "framesEnabled": false,
    "lifecycleState": "hidden",
    "platform": "web",
    "hint": "The engine is not producing frames, so the semantics tree is not being rebuilt and dispatched gestures cannot take effect. A backgrounded browser tab is the usual cause. Bring the page to front (CDP Page.bringToFront) and retry before trusting this result."
  }
}
```

| Field | Type | Description |
|:------|:-----|:------------|
| `framesEnabled` | bool | Always `false` when the block is present. |
| `lifecycleState` | string \| null | The `AppLifecycleState` behind it (`hidden`, `paused`, `detached`), or null before the first lifecycle message. |
| `platform` | string | `web`, or the `TargetPlatform` name (`macOS`, `windows`, `linux`, `iOS`, ...). |
| `hint` | string | Advisory for that platform. Web names a backgrounded tab and CDP `Page.bringToFront`; desktop names a hidden, minimised or occluded window or an asleep display and says to bring the window to front. |

The block is **omitted entirely** on a healthy engine, so its presence is itself the signal and a clean run carries no extra bytes.

**CLI banner.** Commands that summarise rather than print the raw envelope (`tapir:snap` prints only the tree, `tapir:tap` prints `✓ Tapped e7`) would drop the block, so they print a banner to **stderr** instead. stdout stays the payload. On web:

```
⚠ The app is not producing frames (lifecycle: hidden), so this result may be stale. A
  backgrounded browser tab is the usual cause: bring the page to front and retry.
```

On desktop the second sentence reads "The window is hidden, minimised or occluded, or the display is asleep: bring the window to front and retry."

## The fallback

Forcing covers a hidden desktop window. It cannot cover a hidden browser tab, the opt-out, `detached` or an asleep display: bring the target to front yourself.

On web, over CDP:

```sh
# The app must have been started with a CDP port for this to be reachable.
./bin/dowel start --device=chrome --cdp-port=9333
```

```json
{ "method": "Page.bringToFront" }
```

One call flips the page back to `visible` and focused: the text nodes return, and a tap that hung answers immediately. When tapir behaves strangely on web, read `document.hidden` before concluding anything about the app.

On desktop, activate the window (macOS: `osascript -e 'tell application "<App>" to activate'`) and retry.

Two blank-screen causes look identical and are not, so read the console entry count before deciding which one you have. A mounted tree with missing text is a hidden page: `Page.bringToFront` fixes it on web, forcing on desktop. Zero glass panes, zero canvases and **zero console lines** is a dead bootstrap instead, which no amount of bringing-to-front repairs; restart the run.

## Related Documentation

- [Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md): the preconditions each gesture passes before dispatch.
- [Driving real apps: gotchas for agents](https://anilcancakir.com/tapir/docs/getting-started/driving-real-apps-gotchas.md): the other blank-screen and stale-result traps.
- [Tool reference](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md): the `framesForced` and `warnings` response fields on every verb.

---

# Interactions and the perf trace

Inside a perf session every gesture tapir dispatches opens an interaction, and `ext.tapir.perf_trace` exports them with the session's frames as Chrome Trace Event JSON.

An **interaction** is a handle that says which verb caused the work that follows. The export
carries the closed session's interactions, frames and the host's timeline rows, and opens as is
in [ui.perfetto.dev](https://ui.perfetto.dev) and `chrome://tracing`.

- [Interactions](#interactions)
- [Reaching an interaction from app code](#reaching-an-interaction-from-app-code)
- [ext.tapir.perf_trace](#ext-tapir-perf-trace)
- [Host timeline rows](#host-timeline-rows)
- [Related Documentation](#related-documentation)

## Interactions

The verbs that dispatch into the app open one: `tap`, `dblclick`, `triple_click`, `right_click`, `hover`, `drag`, `type`, `clear`, `fill`, `press_key`, `focus`, `blur`, `scroll`, `select_option`, `set_checkbox`, `navigate`, `navigate_back`, `dismiss_modals` and `reset_overlays`. Only while a session is open: outside one a verb runs exactly as before, with no handle, no zone and no timer. A gesture that fails the actionability gate dispatched nothing and opens nothing, with one exception: `fill` opens its interaction first and gates each of its steps inside it.

A `PerfInteraction` carries:

| Field | Meaning |
|:---|:---|
| `id` | `i<N>`, unique for the isolate's lifetime. |
| `verb` | The `ext.tapir.*` verb without its prefix. |
| `target` | The ref, route or key the verb acted on; `null` for `blur`, `navigate_back`, `dismiss_modals`, `reset_overlays`. |
| `startUs` | `FlutterTimeline.now` at dispatch. |
| `closedAtUs` | `FlutterTimeline.now` at settle; `null` while open. |

An interaction **closes at settle**: once no frame has been scheduled for 300 ms, after 5 s whatever the app does (an infinite animation never goes quiet), or when the session closes. A verb dispatched inside another joins it rather than opening its own: `fill` runs `focus`, `clear` and `type`, and to the app that is one gesture.

Interactions may overlap: an agent can tap again before the last tap settles.

---

## Reaching an interaction from app code

Two routes, because Dart zones reach some of a gesture's consequences and not others.

**The zone.** tapir dispatches the gesture inside `runZoned(zoneValues: {#tapir_interaction: handle})`. Gesture callbacks run synchronously inside that dispatch, and Timers, microtasks, Futures and stream subscriptions created there keep the zone they were created in, so an `onTap` that starts a request hands it the interaction:

```dart
final Object? value = Zone.current[#tapir_interaction];
final PerfInteraction? interaction =
    value is PerfInteraction && value.closedAtUs == null ? value : null;
```

`#tapir_interaction` is a public symbol and equal across libraries, so a package reads it without importing tapir; `PerfInteraction.zoneKey` names the same symbol.

**Treat a closed handle as absent.** A Timer or a subscription keeps its zone forever: a Reverb socket opened during a login tap would otherwise attribute every later message to that tap. The close is what bounds the attribution.

**The active slot.** Frames, builds, `initState` and post-frame callbacks run in the binding's frame zone, not in the zone that marked a widget dirty, so a refetch fired from `initState` after a tap navigated never sees the zone value. That work joins by time through `activeInteraction()`, which returns the newest interaction still open (or `null` outside a session), and marks the join `linkedBy: 'frame'`. Work that read its own zone marks `linkedBy: 'zone'`.

---

## ext.tapir.perf_trace

| Param | Meaning |
|:---|:---|
| `token` | Optional. The session's `sessionToken`; when given it must name the most recent closed session, the only one kept. |

```json
{
  "sessionToken": "perf-1",
  "traceEvents": [
    {"ph": "M", "name": "process_name", "pid": 1, "args": {"name": "tapir perf-1"}},
    {"ph": "M", "name": "thread_name", "pid": 1, "tid": 1, "args": {"name": "interactions"}},
    {"ph": "X", "cat": "interaction", "name": "tap", "ts": 812345, "dur": 412000, "pid": 1, "tid": 1,
     "args": {"id": "i1", "target": "e3"}},
    {"ph": "X", "cat": "frame", "name": "Frame 212", "ts": 813001, "dur": 16200, "pid": 1, "tid": 2,
     "args": {"frameNumber": 212, "buildMs": 9.1, "rasterMs": 2.2, "interactionId": "i1", "linkedBy": "frame"}},
    {"ph": "b", "cat": "http", "name": "GET /monitors", "id": "r1", "ts": 812500, "pid": 1, "tid": 3,
     "args": {"interactionId": "i1", "linkedBy": "zone"}},
    {"ph": "e", "cat": "http", "name": "GET /monitors", "id": "r1", "ts": 1012500, "pid": 1, "tid": 3}
  ],
  "displayTimeUnit": "ms",
  "otherData": {"sessionToken": "perf-1", "startUs": 800000, "endUs": 2900000,
                "interactions": 1, "frames": 45, "framesOutsideWindow": 2,
                "rows": 12, "skippedRows": 0}
}
```

- **Interactions** are `X` slices on the `interactions` track, from `startUs` to `closedAtUs`; one still open when the session closed ends at the session's end.
- **Frames** are `X` slices on the `frames` track, placed at `vsyncStartUs` for `totalSpanMicros`. A frame record without `vsyncStartUs` cannot be placed and is left out; one placed outside the session window (drawn before `perf_begin`, or the idle flush frame after it) is left out and counted in `otherData.framesOutsideWindow`. The window is cut by the rule `perf_end` uses, so the two artefacts agree on the frames: when frames carry a timestamp and none lands in the window, the engine's vsync clock and the session's clock disagree, every frame is kept where its own clock puts it (so it may sit apart from the interactions and rows), `framesOutsideWindow` reads 0 and `otherData.sessionClockMismatch` is `true`, as `perf_end`'s `coverage.sessionClockMismatch` is.
- **Host spans with an `id`** become async `b`/`e` pairs keyed by that id, with `cat` set to the track: the shape for work that overlaps other work on its track, such as two requests in flight. Spans without an id become `X` slices, instants `i` events, counters `C` events.
- `X` slices must nest on their track for Perfetto to draw them. Two can straddle in ordinary use (a tap before the last one settled, a frame whose build starts while the previous one rasterises), so a slice that would straddle another moves to an overflow lane, `interactions (2)`, rather than being trimmed. Durations stay true.
- Only what STARTED inside the session window is exported; the window runs from `perf_begin` to `perf_end`.

The frames and the host rows are read when you call `perf_trace`, not when the session closed. Export before the next `perf_begin`, whose host hook clears those buffers: while a session is open `perf_trace` answers an error rather than a trace that silently lost its frames. It also answers an error before any session closed, for a token that is not the one held, and when a host reader throws.

---

## Host timeline rows

The host (magic_devtools) fills the `perfTimelineReader` pointer. One row per map:

```text
{kind: 'span'|'instant'|'counter', track: String, name: String,
 startUs: int, endUs: int?, id: String?, interactionId: String?,
 linkedBy: String?, value: num?, args: Map?}
```

Times are `FlutterTimeline.now` microseconds, the clock tapir stamps interactions and the session window with. A span with no `endUs` is still running and ends at the session's end. Return the whole buffer; tapir keeps the rows inside the window. A row missing `kind`, `track`, `name` or an int `startUs`, a kind outside the three above, or a counter without a numeric `value` is skipped and counted in `otherData.skippedRows`, never a failed export.

---

## Related Documentation

- [tapir:perf_begin](https://anilcancakir.com/tapir/docs/commands/tapir-perf-begin.md): opens the session interactions are recorded in.
- [tapir:perf_end](https://anilcancakir.com/tapir/docs/commands/tapir-perf-end.md): closes it; the trace exports that session.
- [tapir:perf_trace](https://anilcancakir.com/tapir/docs/commands/tapir-perf-trace.md): writes this export to a file and prints its path.
- [Perfetto: other formats](https://perfetto.dev/docs/getting-started/other-formats): the Chrome JSON rules the trace follows.

---

# The semantics hold

`ext.tapir.semantics_hold` releases tapir's semantics handle for one timed window, so `tapir:perf_run --semantics-pass` can measure the app without the semantics tree.

`TapirPlugin.install()` takes a semantics handle for the whole process, because every snapshot, `q<N>` handle and actionability check reads the semantics tree. The cost is that every frame of a tapir-driven app also builds that tree, which an app without tapir (and without a screen reader) does not.

- [ext.tapir.semantics_hold](#exttapirsemantics_hold)
- [Driving while the tree is released](#driving-while-the-tree-is-released)
- [Related Documentation](#related-documentation)

## ext.tapir.semantics_hold

| Param | Meaning |
|:---|:---|
| `action=release` | Drops tapir's handle. Refused unless a perf session is open, so the tree can only go away inside a timed window. |
| `action=acquire` | Takes the handle again, then awaits one frame (bounded, 200 ms) so the tree exists again when it answers. |

```json
{"action": "release", "released": true, "semanticsEnabled": false, "heldByPlatform": false}
{"action": "acquire", "acquired": true, "semanticsEnabled": true, "treeReady": true}
```

`semanticsEnabled` stays `true` after a release when something else holds a handle: the tree only goes away when the last handle does. `heldByPlatform` is `platformDispatcher.semanticsEnabled`, true when the platform holds a handle of its own. On Flutter web that is every real app once it has sent a semantics tree: the engine turns semantics on at the first update and nothing turns it off, so a release there answers `semanticsEnabled: true, heldByPlatform: true`. On a native device it is true while an accessibility service runs. `heldByPlatform: false` with `semanticsEnabled: true` is another `SemanticsHandle` in the app (or the test harness). `TapirPlugin.semanticsReleased` reads the state in-app.

The caller owns the pairing: acquire after `perf_end`, so the acquire's full tree rebuild is not a frame of the session, and acquire even when a step or `perf_end` failed. `perf_end` also re-takes a handle left released, as a safety net for a caller that died in between. `tapir:perf_run` does all of it.

---

## Driving while the tree is released

Anything that resolves a target reads the tree, so while it is released nothing may: `ext.tapir.find`, a `q<N>` action and a snapshot would all see no nodes, and a transient handle taken to look would rebuild the tree inside the window being measured. Resolve first, with the tree on, then dispatch by coordinates:

| Extension | Records the point (tree on) | Dispatches by coordinates |
|:---|:---|:---|
| `ext.tapir.tap` | `reportPoint: true` adds `point: {x, y}` | `{x, y}` with no `ref` |
| `ext.tapir.drag` | `reportPoint: true` adds `from` and `to`; `startRef` plus `dx`/`dy` drags by an offset | `{x, y, toX, toY}` with no ref |
| `ext.tapir.hover` | `reportPoint: true` adds `point` | (a wheel then goes through CDP) |

A coordinate dispatch has no element, so none of the actionability gate's checks can run. Its response always carries:

```json
"checks": {"gate": "skipped", "semantics": "released", "why": "..."}
```

`semantics` is `held` or `released`; the enabled check is the one that reads the tree. Nothing about a coordinate dispatch proves what it landed on: it is a replay of a point that was valid when the tree was on, for a screen that is expected to be in the same state.

---

## Related Documentation

- [tapir:perf_run](https://anilcancakir.com/tapir/docs/commands/tapir-perf-run.md#the-semantics-pass): the command that drives the pass.
- [Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md): the checks a coordinate dispatch skips.