dusk:snap

Capture the Semantics tree of the running Flutter app as YAML, tagging every interactive node with a [ref=eN] token. dusk:snap is the foundational read command: every action command (dusk:tap, dusk:type, dusk:drag, etc.) consumes one of its eN refs to locate the target widget.

The eN namespace is snapshot-frozen: every fresh dusk:snap clears the registry and mints new tokens. For long-lived handles that survive rebuilds, use dusk:find (which mints qN tokens) or dusk:observe.

Table of contents

• Synopsis
• Arguments
• Returns
• Enricher fragments
• Examples
• See also

Synopsis

dart run fluttersdk_dusk dusk:snap [--depth=] [--includeEnrichers]

dusk:snap requires a running Flutter session (CommandBoot.connected). It dials the VM Service URI recorded in ~/.artisan/state.json, calls ext.dusk.snap, and prints the snapshot YAML to stdout.

Arguments

The flag is parsed via (ctx.input.option('includeEnrichers') as bool?) ?? false and serialised as a string into the VM Service params map.

Returns

The VM Service handler returns a JSON envelope { "snapshot": "" }. 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):

[ref=e1] role=button label="Sign in" rect=(120,400,120,48) actions=[tap]
[ref=e2] role=textbox label="Email" rect=(20,200,335,56) actions=[tap, focus, type]
[ref=e3] role=text label="Welcome back" rect=(20,80,335,32)

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

Error envelope:

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

• No running app at the recorded URI (the artisan dispatcher reports the dial failure before dusk:snap runs).
• DuskPlugin.install() not wired in lib/main.dart (run dusk:install).

Enricher fragments

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

• MagicDuskIntegration ships seven enrichers covering forms, routes, controllers, models, http, cache, and the policy gate.
• Wind alpha-10 surfaces a six-field wind: block (breakpoint, brightness, platform, states, bgColor, textColor) through the neutral fluttersdk_wind_diagnostics_contracts.WindDebugRegistry bridge rather than via an enricher, 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.

Examples

1. Minimal snapshot of the current screen

dart run fluttersdk_dusk dusk:snap

Expected output (illustrative; truncated):

[ref=e1] role=text label="Monitors" rect=(20,80,200,32)
[ref=e2] role=button label="New monitor" rect=(20,140,335,48) actions=[tap]
[ref=e3] role=button label="Settings" rect=(355,140,40,48) actions=[tap]

2. Snapshot with depth cap

dart run fluttersdk_dusk dusk: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

dart run fluttersdk_dusk dusk:snap --includeEnrichers

Expected output (illustrative):

[ref=e2] role=button label="New monitor" rect=(20,140,335,48) actions=[tap]
  magicRoute: /monitors
  windClassName: bg-primary-600 dark:bg-primary-500 text-white

See also

• dusk:tap: consume an eN token to synthesise a tap.
• dusk:find: mint a long-lived qN handle that survives rebuilds.
• dusk:observe: structured candidate list when the agent needs more than the raw Semantics tree.
• Plugins: Enricher authoring: how to ship a custom enricher that contributes additional fragments.