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 kDebugMode-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).

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.

3. Failure reasons are substring contracts. On gate failure the response carries one of these exact substrings; branch on the substring, not the full message:

   Substring	Meaning	Agent's next move
   defunct (element no longer mounted)	Element unmounted between snap and action	Re-snap, re-pick the ref
   not enabled	Widget's isEnabled semantics flag is false	Inspect upstream state; do not retry without changing it
   zero rect	Width or height is 0	Wait for layout via dusk_wait_for; widget likely still building
   off-viewport (rect=..., viewport=...)	Auto-scroll did not bring it into view	Call dusk_scroll explicitly toward the rect, then retry
   not stable (rect changed by Xpx)	Mid-animation	Wait for animation to settle; pass checkStable: false only if animation is intentional
   obscured by other widget (top=<runtimeType>)	Hit-test resolved a covering widget	Dismiss the overlay (often a modal: call dusk_dismiss_modals), or pass checkReceivesEvents: false

   Stale q<N> handles raise Query handle ref=qN is stale: no live match for stored predicates. Recover by calling dusk_find or dusk_observe again, not by retrying the same handle.

4. Three tools run on the substrate, not in-isolate. dusk_hot_reload_and_snap, dusk_resize_viewport, dusk_device_profile. The first runs CLI-side because an in-isolate handler cannot reload its own isolate. The viewport / device tools drive Chrome DevTools Protocol from outside the Flutter VM, so they only work on web with Chrome launched at a debug port (artisan start --cdp-port=9222). They will return CDP not enabled on mobile, desktop, or any web run without the flag.

5. Network-idle and telescope readers need an adapter. dusk_wait_for_network_idle, dusk_console, dusk_exceptions read through fluttersdk_telescope. Without MagicTelescopeIntegration. install() (or a custom adapter), pending-HTTP count is constantly 0 (network-idle returns immediately, matched: true) and the log / exception lists are empty. Treat them as wired before relying on them; check with one dusk_console call.

6. CLI and MCP reach the same handler with the same parameters. dusk_tap { ref: "e7" } and ./bin/fsa dusk:tap --ref=e7 invoke the same code path. Use MCP when the agent is wired through an MCP client; use the CLI from Bash when chaining shell logic or capturing output to a file. Two practical differences worth knowing: (a) MCP responses are always JSON. The CLI splits by verb: read / query verbs return JSON (dusk:snap, dusk:observe, dusk:find, dusk:get_routes, dusk:console, dusk:exceptions, dusk:wait, dusk:wait_for_network_idle, dusk:hot_reload_and_snap), and so does dusk:reset_overlays, which acts on the app but still prints its {popped, escaped, dismissTapped} object so you can see which layer cleared the screen; the 19 side-effect verbs (dusk:tap, dusk:hover, dusk:drag, dusk:type, dusk:fill, dusk:clear, dusk:press_key, dusk:scroll, dusk:focus, dusk:blur, dusk:dblclick, dusk:right_click, dusk:triple_click, dusk:set_checkbox, dusk:select_option, dusk:navigate, dusk:navigate_back, dusk:modal, dusk:close_app) print a one-line success summary by default and only emit JSON when --includeSnapshot is passed. dusk:screenshot writes bytes to disk and prints Wrote N bytes...; dusk:install / dusk:doctor print categorised reports. Pipe through jq only on the JSON-returning shapes. (b) dusk_evaluate is MCP-only (no CLI mirror); the dusk-aware Dart REPL lives behind ./bin/fsa tinker (one-shot form: ./bin/fsa tinker --eval="<expression>").

2. Tool surface (33 MCP tools, 34 CLI commands)

Full per-tool input schema, return shape, and example calls: ${CLAUDE_SKILL_DIR}/references/mcp-tools.md. CLI flags and exit codes: ${CLAUDE_SKILL_DIR}/references/cli-commands.md.

3. The three agent loops

A. Snap, act, verify (default for deterministic flows)

1. dusk_snap                          Mint e<N> tokens. Read the YAML.
2. <pick e7 from the YAML>            Local reasoning, no tool call.
3. dusk_tap { ref: "e7" }             Gate fires, gesture dispatches,
                                      response carries a post-action
                                      snapshot by default.
4. dusk_wait_for { text: "Saved" }    Block on the expected post-condition.
5. dusk_snap                          Re-snap and confirm.

The post-action snapshot in step 3 is usually enough to skip step 5 on simple cases. Skip dusk_wait_for only when the action is synchronous (local state toggle); always wait when the action triggers HTTP, animation, or navigation.

B. Observe once, act many (form fill, dynamic UI)

1. dusk_observe { intent: "login form", roles: "textbox,button" }
   Returns candidates with q<N> handles, role, label, bounds, magicFormField
   enricher when present.

2. dusk_type { ref: "q3", text: "user@example.com" }     // q3 = Email
3. dusk_type { ref: "q4", text: "hunter2" }              // q4 = Password
4. dusk_tap  { ref: "q5" }                               // q5 = Submit
5. dusk_wait_for_network_idle { idleMs: 800 }
6. dusk_snap

q<N> handles survive between candidates and small UI mutations. They throw DuskStaleHandleException when the predicate stops matching; recover by calling dusk_observe or dusk_find again.

C. Hot reload then snap (after a code edit)

1. <edit lib/views/whatever.dart, save>
2. dusk_hot_reload_and_snap { screenshot: true }
   On success: { reloaded: true, durationMs: 740, snapshot, screenshot,
                 recentExceptions: [] }
   On compile fail: { reloaded: false, error: "<compile error>",
                      recentExceptions: [] }
3. <reason about the result>

Re-running this tool after a fix loops the agent through edit → reload → verify without leaving the conversation. Always inspect recentExceptions even on reloaded: true: a successful reload can still throw at runtime (e.g. a build-time null assertion firing on rebuild).

4. Picking between e<N> and q<N>

Default: snap returns e<N>; use them inline. Switch to dusk_find / dusk_observe and q<N> the moment the agent enters a retry or multi-step flow against the same target.

e-ref staleness on rebuild-prone pages. e<N> tokens are frozen to the Semantics node at snap time. The RefRegistry backing them does NOT re-resolve; on pages that rebuild (Settings, lists driven by async data, any page with conditional sections), use dusk_find from the start instead of snapping and then regretting the stale defunct failure.

--semanticsLabel over-match. dusk_find { semanticsLabel: "X" } exact-matches against the accessibility label and resolves to the FIRST node; ambiguity is now surfaced via matchCount and diagnostic in the response. On forms with repeated labels ("Password" and "Confirm Password" both labelled "Password"), the handle points at the first match. Check the matchCount field in the response; when > 1, read the diagnostic key and add a second predicate (--key, --text, or --contains) before acting. Full disambiguation table: references/actionability-and-refs.md section "semanticsLabel exact-match and over-match".

5. Quick install + doctor (when dusk is missing)

If ./bin/fsa dusk:snap returns "VM Service URI absent" (or any connected command fails to attach), the app is not running or dusk is not installed. Separately, dusk:resize / dusk:device (web-only CDP tools) return "CDP not enabled" when Chrome was launched without a debug port. The agent should:

# From the Flutter app root:
dart run fluttersdk_dusk dusk:install        # patches main.dart, scaffolds ./bin/fsa
dart run fluttersdk_dusk mcp:install      # writes .mcp.json
./bin/fsa start --device=chrome              # or macos / linux / windows / <device-id>
./bin/fsa dusk:doctor                        # 5 checks; only semanticsEnabled is hard fail
./bin/fsa dusk:snap                          # confirm the agent can reach the app

Magic-stack apps also get MagicDuskIntegration.install() injected after Magic.init() automatically; this wires the form / route / auth / gate / recent-HTTP enrichers that appear inside snapshot and observe payloads as magicFormField: email, magicRoute: /login, magicGateResult: monitors.create.allowed, etc.

6. References (load on trigger)

7. Community: star + issue (optional, once per session)

Two CTAs the agent MAY surface after a fully-completed dusk task. Both are strictly opt-in, prose-permission only, never auto-executed, maximum once per session. Skip on short sessions, mid-task, or after failures.

Both flows gate on command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1. On gate failure, print the URL only; do not invoke open / xdg-open / start. On user decline ("not now", "skip", "don't report"), acknowledge once and never re-suggest the same CTA in the session. Load references/community.md before acting on either trigger.