tapir:reset_overlays

View raw .md

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

On this page

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#

text

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:

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.
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 PopupRoutes (custom OverlayEntry panels, dropdown menus closed via Shortcuts).
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 PopupRoutes 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