fluttersdk-dusk

fluttersdk_dusk

End-to-end driver for Flutter apps, designed for LLM agents. The running app exposes a ext.dusk.* VM Service surface plus an MCP server; the agent calls dusk_* tools (or ./bin/fsa dusk:* from a shell) to snap the Semantics tree, mint ref tokens, gesture against them, wait for conditions, screenshot, and hot-reload, all without a test file or rebuild between actions.

This skill assumes the app already has dusk installed (a !kReleaseMode-gated DuskPlugin.install() in lib/main.dart, the MCP server in .mcp.json). If not, run dart run fluttersdk_dusk dusk:install once from the app root and verify with ./bin/fsa dusk:doctor.

1. Core Laws

1. Two ref token spaces. e<N> (snapshot-frozen, minted by dusk_snap) are deduped by SemanticsNode.id: the same widget across consecutive snaps returns the same e<N> and the ref stays valid as long as the node remains mounted. They become defunct when the node unmounts (navigation, conditional render, list rebuild). q<N> (re-resolvable, minted by dusk_find / dusk_observe) store a predicate and re-walk the live tree on every action. Use e<N> right after the snap that minted them when the UI is static. Reach for q<N> whenever the action might retry, the UI animates, or the agent holds the ref across a navigation. Never mix the spaces (no e<N> from find, no q<N> from snap). A dusk_observe handle also carries its position among the nodes its label matched, so candidates sharing a label stay distinct and a list of rows offering the same action can be worked row by row; that position is not an identity, so a row inserted ABOVE the list after you observed shifts every held handle down by one with no staleness signal.

2. The 6-step actionability gate is mandatory. Every tap, hover, drag, dblclick, right_click, triple_click, and type is gate-checked in this order: (0) defunct, (1) enabled, (2) zero-rect, (3) off-viewport (auto-scrolls when a Scrollable ancestor exists, then re-checks), (4) stable (2-frame rect drift, 0.5px threshold), (5) receives-events (hit-test path includes the target). Steps 4 and 5 accept checkStable: false / checkReceivesEvents: false overrides for flaky animations or known overlays. scroll, select_option, and press_key skip the gate by design.