fluttersdk_dusk 0.0.11

Flutter E2E driver for LLM agents and CI. 34 CLI commands and 33 MCP tools drive a running app over VM Service extensions; no flutter_test harness needed.

Changelog

All notable changes to this project will be documented in this file.

This project follows Semantic Versioning 2.0.0. Entries follow the Keep a Changelog shape.

---

0.0.11 - 2026-08-20

Fixed

• A --within scope ref that no longer lived was walked anyway, and answered. Registry membership is not liveness: nothing calls disposeGroup in production, so a token outlives the widget it was minted from, and both a detached SemanticsNode and a defunct Element still answer their visit methods. dusk:snap --within=<stale ref> therefore returned an EMPTY tree, which an agent reads as "this region is empty" rather than "your ref is stale", and dusk:find --within=<stale ref> returned a match from the screen that had already been replaced. Both now check SemanticsNode.attached and Element.mounted and report the ref as no longer resolving. Touches lib/src/extensions/ext_snapshot.dart, lib/src/extensions/ext_find.dart.

• ext.dusk.select_option echoed the value it was handed back to the caller. {selected: true, value: <requested>} is the request, not the result, which is the exact pattern the effect block was introduced to kill and the one verb it had not reached. A dropdown whose parent refuses the change kept its old value and still reported a clean success. It now re-reads the control after the frame and returns effect: {kind: 'selected', verified, value}, resolving the ref again rather than reusing a BuildContext from before the await. Touches lib/src/extensions/ext_scroll.dart, lib/src/utils/effect_report.dart.

Documentation

• The CDP clip docblock described the opposite of what the code does. It claimed scale: 1 "keeps the output at the page's own device pixel ratio"; it keeps it at CSS resolution. Measured against this package's example under dusk:device --preset=ipad-pro-12.9 (1024x1366 @ 2.0x): full frame 1024x1266, clipped 992x32, both CSS. No code change: an unclipped Page.captureScreenshot returns CSS resolution too, so the two paths agree and a caller switching between them gets one scale. The measurement is recorded in the docblock so the next reader does not re-derive it.

0.0.10 - 2026-08-20

Added

• The actionability gate now reports what it could NOT prove, instead of passing silently. Step 5 hit-tests the target's centre and throws when something else is on top, but it can also fail to ANSWER: 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. The gate proceeds in that case (breaking every valid tap on the artifact is the worse failure) and used to do so silently, so a clean pass was indistinguishable from a confirmed one. That is how dusk:fill printed a green tick four times onto a row covered by a pinned footer, with nothing in any response saying the check had not run.

  ensureActionable now returns an ActionabilityReport (confirmed / indeterminate / skipped), and the response carries a checks block whenever step 5 did not confirm, with a why and, on the indeterminate path, overlapCandidates: a rect scan naming render objects that overlap the target and paint after it, capped at five. Advisory rather than a verdict, since an overlap is not proof of occlusion. The block is absent on the healthy path. The six-step order and every failure-reason substring are unchanged. Covered by test/src/utils/actionability_report_test.dart and a payload case in test/src/extensions/ext_pointer_test.dart.

• dusk:exceptions --clear empties the capture buffer after returning the current entries. The buffer is cumulative by design (it is the app's error history, which is what the command is for), so one real fault at boot rides along on every later read and a per-route sweep reports it against every route. A 12-of-12 "overflow on every screen" finding once turned out to be a single 4.8px transient, and an instrument with a permanent false positive stops being consulted. Clearing after the read rather than before gives a caller everything so far plus a clean slate, which is the primitive a before/after sweep needs. Only dusk's in-package buffer is affected; a wired telescope owns its own store. New: clearCapturedExceptions() in lib/src/dusk_error_capture.dart (the existing reset was test-only and also uninstalled the hook). Covered by three cases in test/src/extensions/ext_exceptions_test.dart.

• --json on every dusk:* verb prints the raw envelope. The CLI used to split by verb: read commands printed JSON, the side-effect verbs printed a one-line summary, and a caller driving from a shell had to know which shape each verb produced. Worse, the summarising verbs dropped fields that mattered, and one of them (dusk:wait) dropped the only field it had. The flag makes output shape a caller's choice; the default is unchanged, so a human at a terminal still gets the summary. Where a summary can hide a verdict it now names it: ✓ Tapped e7 (no observable change). New: lib/src/commands/json_output.dart, applied to 20 commands.

• dusk:snap gained --within, --interactiveOnly and --grep; dusk:find gained --within. 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 one: an exact-label lookup resolves the nav item, so the caller measures the sidebar and concludes two pages differ. The workaround in the field was an x-coordinate threshold for "the content region", which is wrong at every other width and meaningless on a phone where there is no sidebar.

  --within takes an e<N> ref and walks that subtree; an unknown or node-less ref is an error rather than a silent widening. --interactiveOnly drops the plain - text lines. --grep keeps matching nodes plus the ancestors leading to them, because the ancestors carry the refs an agent acts on and a matching text line has none of its own. The three compose, and an unfiltered call is byte-identical to before.

  On find, the scope becomes part of the minted q<N> handle (DuskQuery.withinRef) rather than a one-off resolution argument: a handle re-executes on every action, and a scoped locator that forgot its scope on the next re-resolve would look correct right up until the shell rebuilt. Playwright's scoped locators behave the same way, including the part where a handle stops resolving once its scope is gone; dusk reports that as matched: false with a diagnostic naming the ref. Touches lib/src/extensions/ext_snapshot.dart, lib/src/extensions/ext_find.dart, lib/src/ref_registry.dart, both commands and both MCP descriptors; covered by test/src/extensions/ext_snapshot_filter_test.dart and test/src/extensions/ext_find_within_test.dart.

• dusk:doctor gained two checks for the failures that present as "dusk is broken" and are not. Session ownership compares state.json's projectRoot against the working directory: ~/.artisan/state.json is a single global slot, so a sibling project's artisan start silently takes it and every dusk:* call from here drives that app instead, succeeding each time. The measured case had a worktree in another repository rewrite it mid-session, and two commands produced a screenshot of an entirely different product before anyone noticed. CDP session health probes the recorded cdpPort for three failures that share one symptom, a capture that never changes: the port refuses (a killed run left its dev server holding the web port while its Chrome is gone), it serves no page on this run's webPort (an orphan browser still up with the old build), or the matching page is hidden (frame production off). Both are WARN and both skip cleanly when the relevant state is absent. Touches lib/src/commands/dusk_doctor_command.dart; covered by eight cases in test/src/commands/dusk_doctor_command_test.dart.

• CdpClient.connect accepts matchUrlSubstring to pick the page tab that belongs to this run. It selected the first type: "page" tab unconditionally, which is not reliably the app under test: an orphan Chrome from a killed run answers on its own debug port with the old build still loaded. The parameter defaults to null, so existing callers are unchanged; dusk:doctor passes this run's web port. Touches lib/src/cdp/cdp_client.dart.

• Five verbs now return an effect block reporting what the widget HOLDS, not what it was asked to do. A dusk action confirms that it DISPATCHED; nothing in the response confirmed the widget received, and that gap has produced defect-shaped stories more than once. ext.dusk.fill printed a green tick four times onto a field covered by a pinned footer. A fill against an InputType.number field reported the text it had been handed while the widget kept nothing, and the resulting "the sheet holds a stale copy" theory survived two rewrites of a widget that had been correct the whole time. The block is always present on those five, because the agents who most need it are the ones who do not know to ask. The verbs left out have nothing cheap to read back; select_option is the exception worth a follow-up, since it still echoes its own value parameter:

  Verb	kind	Fields
  tap	treeChanged	changed (target-scoped route + semantics-subtree signal)
  type, clear, fill	text	verified, value read back off the live TextEditingController
  scroll	scrollOffset	changed, before, after
  set_checkbox	checked	verified, before, after re-read from the widget

  Two handlers were reporting the request rather than the result and now read back: ext.dusk.type echoed its own text parameter, and ext.dusk.set_checkbox returned value: <requested> for a control that may have ignored the tap. typeIntoElement returns the post-write value for this. New: lib/src/utils/effect_report.dart. Covered by test/src/extensions/ext_text_input_effect_test.dart (including a digits-only field that rejects the write, the reproducible stand-in for the number-field case) plus cases in the scroll, checkbox, fill and pointer suites.

• dusk:screenshot and dusk_screenshot now expose ref and rect, so an agent can capture one component instead of the whole screen. ext.dusk.screenshot has supported all three modes (viewport, ref, ref + sub-rect) since it shipped, and the skill documented them, but neither surface an agent actually reaches declared the parameters: the CLI's configure had only --output / --format / --quality, the MCP inputSchema had only format / quality, and its description sent the reader to dusk_snap for "region screenshots", which mints a ref that nothing would accept. The capability was reachable only by calling the VM Service extension by hand. Agents worked around it by capturing the full frame and cropping in Python, or by growing the viewport to a size no device has and putting it back afterwards. rect still requires ref and is a hard error alone, rather than a silent full-frame capture.

  On web the CLI captures through CDP because the in-isolate rasterise hangs under CanvasKit + DWDS, and CDP has no notion of a Flutter ref. Rather than duplicate the geometry, ext.dusk.screenshot gained a geometry: 'true' mode that resolves the same ref + rect and returns {rect: {x, y, width, height}, devicePixelRatio} without rasterising; the CLI turns that into a Page.captureScreenshot clip (Flutter logical pixels and CDP CSS pixels are the same unit, so it crosses over unscaled). A ref that no longer resolves exits 1 rather than falling back to a full-frame capture, because an image that looks right and answers a different question is the failure this flag exists to remove. Touches lib/src/extensions/ext_screenshot.dart, lib/src/commands/dusk_screenshot_command.dart, lib/src/dusk_artisan_provider.dart; covered by test/src/extensions/ext_screenshot_test.dart and test/src/commands/dusk_screenshot_command_test.dart. New page: doc/reference/frame-production.md sibling doc/commands/dusk-screenshot.md examples 5 and 6.

• Every ext.dusk.* success payload now carries a warnings block while the app has stopped producing frames, and the CLI prints a matching stderr banner. With frames off, semantics labels are never rebuilt and dispatched gestures cannot take effect, so two different readings go wrong at once and neither looks like a harness problem: dusk:snap returns a screen with its buttons and none of its - text nodes (a rendering dashboard reads as "permanently stuck on loading skeletons", which nearly shipped as a defect), and an action reports a clean dispatch that could not possibly have landed. The block carries framesEnabled: false, the lifecycleState behind it, and a hint naming Page.bringToFront as the fix. It is omitted entirely on a healthy engine, so its presence is the signal and a clean run carries no extra bytes. The banner exists because the commands that summarise rather than print the envelope (dusk:snap prints only the tree, dusk:tap prints ✓ Tapped e7) would otherwise drop the one field that says the result is untrustworthy. New: lib/src/utils/dusk_response.dart (duskResult, the single seam all 34 handler success paths now return through), frameProductionWarning() in lib/src/utils/frame_sync.dart, lib/src/commands/frame_warning_output.dart, doc/reference/frame-production.md. Covered by test/src/utils/dusk_response_test.dart plus banner cases in the snap and tap command tests.

Removed

• ext.dusk.tap's opt-in verify flag and its top-level changed field. The signal it produced is now the always-on effect block above, so the flag was a second way to ask for something the response already carries. dusk:tap --verify and the verify MCP property are gone; read effect.changed instead of changed. Migration is a one-line rename for anything that branched on it. dusk:tap's one-line output also gained a (no observable change) suffix, because the default path prints ✓ Tapped e7 and would otherwise drop the one field worth reading.

Fixed

• The gate's checks block reached tap and none of the other seven verbs that run the gate. ensureActionable returns an ActionabilityReport, and only the tap handler stamped it; hover, drag, dblclick, right_click, triple_click and type discarded the return value, which means fill did too. ARCHITECTURE.md and doc/reference/actionability-gate.md both present it as a gate-level guarantee, and the anecdote that motivated it is a fill onto a row covered by a pinned footer, so the one verb it was written for was the one that could not report it. All eight now route through a shared stampChecks.

• dusk:wait_for_network_idle reported success and exited 0 when the network never went idle, the same defect dusk:wait had, in the sibling command, fixed in the same release. See the dusk:wait entry below.

• dusk:scroll's effect block measured a different scrollable than the one it drove. The before-offset came from Scrollable.maybeOf(target), which is the ANCESTOR, while the delta branch resolves through a three-stage ladder that also accepts the target BEING a scrollable or containing one. Passing a ListView's own ref, which is what dusk:find --key=my-list returns, therefore reported before: null beside a real after and called it changed: true: exactly the "ref is not a scrollable" case the block was added to catch. The offset is now read from the scrollable each branch actually resolved.

• dusk_screenshot advertised a q<N> handle it could not resolve. Both the CLI help and the MCP inputSchema say ref takes "an e<N> token from dusk_snap or a q<N> handle from dusk_find", but the resolver called RefRegistry.lookup, which never sees the q space. A query handle failed with "not found in RefRegistry. Call ext.dusk.snapshot first", pointing the agent at the wrong recovery. It now routes through resolveRefForAction like every other verb.

• dusk:doctor warned that a session belonged to another project when the caller stood in a subdirectory of it, and crashed outright when the recorded CDP port had been taken over by a non-CDP service. The ownership row compared paths exactly while artisan's own sessionOwnershipError compares is-within, so the two tools disagreed about the same state file; and the CDP probe decoded JSON outside the guard that catches the port being dead, turning one of the three cases the check exists to name into a crash of the whole run. The warning text also still described ~/.artisan/state.json as a single global slot, which stops being true with per-project sessions.

• dusk:doctor carried a third copy of artisan's path-ownership rule, and the copy disagreed with the original. The doctor compared state.json's projectRoot to the working directory for EQUALITY while sessionOwnershipError compares is-within, so standing in a package subdirectory made the doctor report the session as another project's while every artisan command drove it without complaint. Two tools disagreeing about one state file is worse than either answer alone.

  It now calls sessionOwnershipError as the predicate and keeps its own dusk-specific wording for the warning. That is what the dependency bump to fluttersdk_artisan ^0.0.10 is for: the function does not exist in 0.0.9, so the older constraint would let a consumer resolve a version this package no longer compiles against. Touches lib/src/commands/dusk_doctor_command.dart, pubspec.yaml.

• dusk:find --within scoped only one of its five predicate legs and silently searched the whole tree for the other four. _findElementByKey, _findElementByTextData, _findElementByTextContains and _findSemanticsNodeByLabelContains each took the scope as a from parameter and then walked from the root anyway, so --key / --contains (and --text whenever it fell through to the element leg) resolved against the entire screen while reporting a scoped answer. Only --semanticsLabel honoured it, which is why a live drive of the feature looked correct. An unused named parameter is not an analyzer diagnostic, so nothing caught it. All four walks now start at the scope.

  A second hole sat behind it: a scope entry carrying no SemanticsNode left the semantics walks unbounded rather than refusing. ext.dusk.find_by_text mints exactly that shape (RefRegistry.register without a node), so a ref taken from a dusk:wait result reached the widening path. A label lookup, which has no element-tree fallback, now returns matched: false with a diagnostic naming the recovery; --text and --contains fall through to the element leg, which the scope does bound. Touches lib/src/extensions/ext_find.dart; covered by four cases in test/src/extensions/ext_find_within_test.dart.

• The gate reported obscured by other widget (top=_ReusableRenderView), naming the render view as the thing covering the widget it hosts. The graceful-degradation branch tested path.length == 1 && isRootRenderView(path.first), but path runs deepest-first, so the root view being topmost already means nothing in the widget layer claimed the point. A path of view plus gesture-handler therefore missed the branch and threw. The condition is now isRootRenderView(path.first), which is what it was a proxy for. Touches lib/src/utils/actionability_gate.dart.

• dusk:wait reported success and exited 0 when the condition never matched. ext.dusk.wait_for returns a SUCCESS envelope carrying matched: false on timeout rather than an error, and the command printed ✓ Condition matched without reading it. So the one command whose entire job is asserting a post-condition passed on exactly the case it exists to catch, and any shell chain gated on its exit code proved nothing. It now prints what happened and exits 1 when matched is false. dusk:wait_for_network_idle had the identical defect and the identical fix: its handler also answers a timeout with {matched: false}, and the command printed Network idle and returned 0 regardless. It is the one a CI script is most likely to chain on. Touches lib/src/commands/dusk_wait_command.dart and lib/src/commands/dusk_wait_for_network_idle_command.dart; covered by both command test files.

• Every action extension hung forever when the app stopped producing frames, which is what a backgrounded browser tab does. Twenty-seven await WidgetsBinding.instance.endOfFrame calls across ext_pointer, ext_text_input, ext_navigation, ext_fill, ext_focus, ext_scroll and ext_checkbox settled a gesture or an edit by awaiting the binding directly. endOfFrame only schedules a frame while SchedulerBinding.framesEnabled is true, and Flutter Web turns frame production off once Chrome reports document.visibilityState: "hidden", so the future never completed: dusk:tap sat for 45s+ with no output and no error until the caller's shell timeout killed it, which reads as a wedged app rather than a backgrounded window. All twenty-seven now route through awaitFrameOrTimeout / awaitFramesOrTimeout (lib/src/utils/frame_sync.dart), which falls through after kFrameSyncTimeout (200ms per frame). A healthy engine is unaffected: a real frame lands in ~16ms and still wins. The actionability gate's own private copy of this helper was removed in favour of the shared one, leaving one bound for the whole package. Covered by test/src/utils/frame_sync_test.dart and a frame-starvation case in test/src/extensions/ext_pointer_test.dart.

• CdpClient.defaultHttpGet and ChromeFinder.defaultHttpGet closed the HttpClient while the response body was still streaming. Both returned response.transform(utf8.decoder).join() without awaiting it inside a try/finally whose finally calls client.close(), so the close raced the body drain and a truncated or failed read was possible on a slow /json response. The same shape was in the integration smoke helper. Touches lib/src/cdp/cdp_client.dart, lib/src/cdp/chrome_finder.dart, test/integration/cdp_smoke_test.dart.

Docs

• The registry dispatch fires on a published release now, not on every push that touches the skill. Under the push trigger fluttersdk/ai climbed to v1.3.75, and most of those releases re-published identical skill content: a docs commit and a release commit each cost the registry a version. The registry version now tracks published dusk releases instead of counting commits. workflow_dispatch stays as the manual escape hatch when a skill fix has to reach users before the next release. (.github/workflows/dispatch-to-registry.yml)
• dusk_fill and dusk_reset_overlays were invisible to the skill. Both shipped in 0.0.7, and neither appeared anywhere in skills/fluttersdk-dusk/: not in references/mcp-tools.md (whose header still promised "31 tools" against a real 33), not in references/cli-commands.md, not in the SKILL.md family table, not in the CLI output-shape law. An agent loading the skill therefore re-discovered the manual focus + clear + type + wait sequence that dusk_fill exists to replace, and had no answer at all for an overlay that is not a PopupRoute, since dusk_dismiss_modals only pops those. Both now carry a full entry: input schema, return shape, when to reach for them over the older tool, and the CLI form. (skills/fluttersdk-dusk/SKILL.md, skills/fluttersdk-dusk/references/mcp-tools.md, skills/fluttersdk-dusk/references/cli-commands.md)
• Three counts corrected with them: the MCP tool total (31 to 33), the in-isolate ext.dusk.* split (28 to 30 extension tools, 3 substrate), and the CLI side-effect verb list (18 to 19, dusk:fill). dusk:reset_overlays went into the JSON-returning list instead, because unlike the other side-effect verbs it always emits JSON. (skills/fluttersdk-dusk/SKILL.md, skills/fluttersdk-dusk/references/mcp-tools.md)
• Documented one asymmetry a Bash caller trips on: includeSnapshot defaults to true on the dusk_fill MCP tool and to false on dusk:fill. (skills/fluttersdk-dusk/references/cli-commands.md, skills/fluttersdk-dusk/references/mcp-tools.md)

0.0.9 - 2026-07-29

Added

• ext.dusk.find now surfaces a matchCount field and an ambiguity diagnostic in its success response when --semanticsLabel or --text matches more than one Semantics node. Previously the handler silently returned the first match, so --semanticsLabel "Password" over-matched the email field on forms where both <TextField semanticsLabel="Password"/> nodes shared the same label. The response now includes matchCount: N on every match; when N > 1 a diagnostic key carries a human-readable hint (label 'X' matched N nodes; refine with --key, --text, or --contains). Single-match and no-match behaviour is unchanged (backward-compatible). Touches lib/src/extensions/ext_find.dart; covered by test/src/extensions/ext_find_test.dart.

• ext.dusk.snap now surfaces captured non-fatal render/build FlutterErrors in a renderErrors block, and dusk:snap prints a ⚠ N render error(s) banner to stderr while stdout stays the pure snapshot. A widget that throws at build time (a ParentDataWidget misuse such as flex-1/Expanded placed under a Semantics/WAnchor instead of directly inside a Flex, or an overflow) can render partially and stay invisible in the semantics snapshot, so an action against it silently no-ops with no signal to the agent. The snapshot payload now carries renderErrors: {count, recent: [{type, message}], hint} (populated from the existing FlutterError.onError capture buffer, omitted entirely when clean), so a broken screen is impossible to miss without separately calling ext.dusk.exceptions. Touches lib/src/extensions/ext_snapshot.dart, lib/src/commands/dusk_snap_command.dart; covered by test/src/extensions/ext_snapshot_render_errors_test.dart.

Changed

• ext.dusk.navigate now tries the consumer navigate adapter (DuskPlugin.navigateAdapter, e.g. MagicRoute.to) BEFORE Navigator.pushNamed. On a Router-only stack (go_router / auto_route) Navigator.onGenerateRoute is null, so Navigator.pushNamed raised an asynchronous "no corresponding route" FlutterError on every navigate. Because the failure was async, the handler's try/catch could not suppress it, and it landed in the FlutterError buffer, now doubly visible via the new renderErrors snapshot block as a false positive. Adapter-first dispatch routes through the app's own router public API (the correct path for these apps) and skips the throwing Navigator.pushNamed entirely; it remains the fallback for apps with no registered adapter. Touches lib/src/extensions/ext_navigation.dart.

Fixed

• dusk:doctor check 3 (snapshot enrichers) now emits INFO when no enrichers are registered, instead of WARN. Enrichers are opt-in; zero is a valid state, not a problem. The WARN reading alongside "integration wired" (check 5) created false contradiction. Touches lib/src/commands/dusk_doctor_command.dart; test case updated in test/src/commands/dusk_doctor_command_test.dart.

• q<N> (find / observe) taps now dispatch at the target's own rect instead of the viewport centre. _entryFromSemanticsNode anchored the RefEntry at the root element, so dispatchRectOf returned _liveRectOf(root) (the whole viewport) and every find/observe gesture fired at screen centre. A centred target coincidentally worked; off-centre controls (a submit button, a checkbox, a sidebar item) were missed silently. The entry now resolves the element whose RenderBox contributes the node (via debugSemantics identity, matching ext_observe), so the gesture lands on the addressed widget. Touches lib/src/extensions/ext_find.dart; covered by test/src/extensions/ext_find_test.dart.

• find-by-label now prefers the first INTERACTIVE match when a label collides with inert text. A visible Text naming an adjacent control (a settings label beside a switch that shares its semanticLabel) or a heading repeating a button's text (a "Sign In" heading over the submit button) sits first in tree order, so the handle resolved to the inert node and the tap landed on the label. find now resolves to the first node exposing SemanticsAction.tap (button / switch / text field) when the label spans an interactive and a non-interactive node, falling back to the first match otherwise. matchCount / diagnostic still report the collision. Touches lib/src/extensions/ext_find.dart; covered by test/src/extensions/ext_find_test.dart.

• dusk:type now targets the editable inside the ref's own Semantics rect, not the first EditableText in the tree. The handler resolved the field to type into by walking to the first editable under the isolate, so on a form with several inputs a type against q3 (Password) could land in the first field (Email). It now maps the ref's SemanticsNode to its global rect (localToGlobal) and selects the editable whose render box OVERLAPS that rect by the largest area (falling back to the nearest-center editable when none overlaps), so the value goes into the addressed field. The same rect-based selection also backs dusk:clear. Touches lib/src/extensions/ext_text_input.dart; covered by test/src/extensions/ext_text_input_test.dart.

---

0.0.8 - 2026-06-17

Changed

• dusk:install now injects import 'package:magic_devtools/dusk.dart'; and gates on the magic_devtools dependency instead of the removed package:magic/dusk_integration.dart. The MagicDuskIntegration class was extracted from the magic core into the new magic_devtools package; the injected class name (MagicDuskIntegration.install()) is unchanged. Consumers that follow magic's install.yaml (which adds magic_devtools to dev_dependencies before running dusk:install) get the integration wired automatically; magic-only consumers without magic_devtools in pubspec.yaml are unaffected. Coordinated with the magic_devtools extraction.

Fixed

• dusk:install no longer injects import 'package:magic_devtools/dusk.dart'; or MagicDuskIntegration.install() into a vanilla Flutter app that has magic_devtools in its pubspec but no await Magic.init( call in lib/main.dart. Previously, the magic_devtools wiring block ran whenever the pubspec listed the dependency, regardless of whether a Magic.init anchor existed. This left an unused import in the consumer's file, causing dart analyze to fail. The gate is now hasMagicInit && _hasMagicDevtoolsDep(), matching the block's own intent documented in the comment above it. The existing try/catch around injectAfterMagicInit is retained as a defensive fallback.

Documentation

• Docs, skill, and example synced to the magic_devtools extraction: doc/plugins/magic-integration.md updated to note that MagicDuskIntegration now ships in magic_devtools (add as a dev_dependency) and shows the required import 'package:magic_devtools/dusk.dart';. skills/fluttersdk-dusk/references/cli-commands.md updated to reflect the magic_devtools gate and magic_devtools/dusk.dart import. ARCHITECTURE.md frozen-contracts item updated from magic to magic_devtools. Version pins bumped to ^0.0.8 throughout (pubspec.yaml, example/pubspec.yaml, doc/getting-started/installation.md, skills/fluttersdk-dusk/SKILL.md).

---

0.0.7 - 2026-06-17

Added

• dusk:console now surfaces debugPrint output even without fluttersdk_telescope. DuskPlugin.install() now chains a debugPrint override that records every call into a bounded in-package ring buffer (cap 50, newest-first). ext.dusk.console merges this buffer with the existing telescope recentLogsReader output using the same merge+dedup pattern as ext.dusk.exceptions, so debugPrint(...) / print(...) calls appear in dusk:console results regardless of whether telescope is installed. The telescope reader indirection is preserved: when telescope is wired it augments with Logger.root.onRecord entries and any other watchers it ships. Direct dart:developer log() calls that bypass debugPrint are not captured by the in-package path; they require telescope's LogWatcher. Capture scope is documented in doc/commands/index.md under "Console and exceptions".

• Opt-in verify flag on dusk:tap / dusk_tap / ext.dusk.tap. When verify: true, the tap handler captures a cheap TARGET-scoped signal before and after the pointer (the nearest enclosing route name plus a hash of the target element's own semantics subtree: label, value, enabled/checked flags) and adds a changed: true|false field to the response reporting whether the tap produced an observable effect on the target. The signal is deliberately target-scoped, not a global route/whole-tree hash, so a counter button whose own label increments reports changed: true while unrelated background churn elsewhere in the tree does not. Default off (verify: false) keeps the response shape byte-identical to before: no changed key. The dusk:tap CLI gains a --verify flag and the dusk_tap MCP descriptor gains a verify boolean property (a parameter addition to the existing dusk:tap / dusk_tap, not a new command or tool).

• Optional since filter on dusk:exceptions / dusk_exceptions / ext.dusk.exceptions. Pass since: "<iso8601>" (e.g. 2024-01-01T10:00:00.000Z) to receive only exceptions whose time is strictly after that timestamp. Agents can record the current time before an action, then call dusk:exceptions --since=<time> afterwards to see only new exceptions raised by that action, eliminating false positives from cumulative history. Default behavior (no since) is unchanged: the full cumulative list is returned. Unparseable since values are silently treated as absent. The dusk:exceptions CLI gains a --since flag and the dusk_exceptions MCP descriptor gains a since string property (a parameter addition to the existing dusk:exceptions / dusk_exceptions, not a new command or tool).

• dusk:fill / dusk_fill / ext.dusk.fill — one-call text-field fill. Resolves a text-field ref (e<N> / q<N>), then focuses, clears, types, and settles in a single round-trip, replacing the manual focus + clear + type + settle dance every agent re-discovers. Composes the existing GATED ext.dusk.focus, ext.dusk.clear, and ext.dusk.type handlers verbatim (so the 6-check actionability gate, IME focus, onChanged/validator firing, and post-action snapshot semantics are reused, never re-implemented). Retries the whole resolve + focus + clear + type sequence ONCE when the ref goes stale mid-fill (a transiently-missing q<N> re-walks the now-settled tree on the second pass); a second stale outcome surfaces a typed stale envelope so the agent re-snaps or re-finds. Returns {ref, text, filled: true} plus an optional post-fill snapshot. This is a NEW command (CLI 32 -> 34) and a NEW MCP tool (31 -> 33) backed by a NEW ext.dusk.fill extension (28 -> 30).

• dusk:reset_overlays / dusk_reset_overlays / ext.dusk.reset_overlays — one-call overlay reset. Returns the app to a known clean screen via three escalating, idempotent layers: (1) pop every PopupRoute (reusing dismissAllModals, never touching the page stack); (2) an Escape key press for overlays driven by the dismiss shortcut that are not PopupRoutes; (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 command is safe to call speculatively between flows. Returns {popped: N, escaped: bool, dismissTapped: bool}. This is a NEW command (CLI 32 -> 34) and a NEW MCP tool (31 -> 33) backed by a NEW ext.dusk.reset_overlays extension (28 -> 30).

• until confirmation on dusk:tap / dusk_tap / ext.dusk.tap. When until: "<text>" is set, after the tap settles the handler polls the live element tree (reusing the dusk:wait_for poll loop) for a Text whose data equals the expected string, up to untilTimeoutMs (default 3000), and adds an untilMatched: true|false field reporting whether it appeared. Confirms a navigation / state change produced the expected text in one call, replacing a separate dusk_wait_for round-trip. Default off (no until) keeps the response shape unchanged. The dusk:tap CLI gains a --until flag and the dusk_tap MCP descriptor gains until / untilTimeoutMs properties (a param addition, not a new tool).

• "Driving real apps: gotchas for agents" doc page (doc/getting-started/driving-real-apps-gotchas.md). Captures the hard-won lessons from a long real-app E2E session, each now partly or fully addressed by D1-D7: refs go stale on rebuild (re-snap, or prefer a q<N> from dusk:find); text fields may snapshot nested (use dusk:fill, or note the typeable: true marker on the collapsed outer node); dusk:console captures debugPrint in-package now and is enriched by telescope; dusk:exceptions is cumulative (use --since); restart preserves the CDP port; overlays may need dusk:reset_overlays. Linked from llms.txt.

Fixed

• dusk:dismiss_modals now dismisses modals on ALL NavigatorState instances, not just the first. The previous implementation walked the element tree with a first-match guard and popped PopupRoute entries one-at-a-time with an endOfFrame await between each pop. showDialog defaults to useRootNavigator: true (root navigator) and showModalBottomSheet defaults to useRootNavigator: false (nearest navigator); when these are different navigators, the first-match walk left one modal open. The fix collects every NavigatorState in a full DFS walk, then calls popUntil((r) => r is! PopupRoute) on each navigator innermost-first, counting every PopupRoute dismissed. The popped return value is the additive sum across all navigators. The per-pop endOfFrame await is removed, which also unblocks unit tests that previously hung the flutter_test fake-clock harness when real modal routes were open.

Changed

• Pointer verbs now dispatch at the element's LIVE rect, not the cached snapshot rect. Every pointer verb (tap, hover, drag start + end endpoints, dblclick, right_click, triple_click) re-resolves the target's current bounding rect via the new dispatchRectOf(entry) helper immediately after the actionability gate passes and dispatches at that live center, falling back to the cached entry.rect.center only when the live rect is null (sliver / detached / synthetic). A host that rebuilt the target into a shifted slot between snapshot and action retains the same Element / RenderObject identity, so the live rect is valid. This fixes the false-success class where dusk:tap reported success while onTap never fired because the pointer landed on the target's stale gate-time position. The helper is purely additive to the FROZEN actionability gate: it runs after the gate passes and before dispatch, touching neither the gate order nor any failure-reason substring.
• dusk:snap collapses nested textbox nodes and marks the survivor typeable: true. A wind WInput wraps as Semantics(textField:true) > MergeSemantics > TextField; because RenderEditable unconditionally owns its own textField Semantics node (flutter#26336) and MergeSemantics cannot absorb it (flutter#160281), the tree carried TWO nested textbox nodes and minted two eN refs. Agents naturally targeted the inner leaf, where dusk:type threw -32000. The snapshot walk now suppresses any textbox node whose render object is a render-tree DESCENDANT of an enclosing textbox node's render object, emitting a single ref for the outer typeable node so existing scripts keep resolving. The surviving textbox line gains an additive typeable: true sub-line. Collapse is by render-object CONTAINMENT only, never label/value equality, so two sibling fields sharing a label stay two distinct refs. The textbox role string is unchanged; eN minting stays snapshot-only. The source-side fix lives in wind (W1); this is the defensive dusk-side collapse.
• Bumped fluttersdk_artisan to ^0.0.8. Picks up the substrate restart fix that preserves --cdp-port across the stop/start cycle (so dusk:resize / dusk:device keep working after fsa restart) and the published-config import-path fix in the plugin installer.

---

0.0.6 - 2026-06-09

Added

• dusk:screenshot web CDP fallback via Page.captureScreenshot. When ~/.artisan/state.json carries a cdpPort (a web target), the CLI command sends Page.enable + Page.captureScreenshot (format, quality, fromSurface: true) over the Chrome DevTools Protocol and writes the decoded bytes directly, bypassing the in-isolate ext.dusk.screenshot extension that hangs under CanvasKit+DWDS (issue #13). Native targets (no cdpPort) keep using ext.dusk.screenshot. The command captures the full app frame. This CDP fallback is CLI-only; the dusk_screenshot MCP tool still dispatches ext.dusk.screenshot in-isolate, so web agents should use the CLI for screenshots. Region (ref/rect) capture remains deferred.
• Non-fatal FlutterError capture surfaced by dusk:exceptions. DuskPlugin.install() now chains a FlutterError.onError handler that records every non-fatal error (including RenderFlex overflow, tagged type: "overflow") into a bounded in-package ring buffer (cap 50, dedup by message + stackHead, newest-first). ext.dusk.exceptions merges this buffer with the existing telescope reader output, so overflow and other non-fatal rendering errors appear in dusk:exceptions results even when fluttersdk_telescope is absent (issue #14).
• Per-ref overflow: annotation in dusk:snap output. Interactive nodes inside a currently-overflowing render ancestor now carry an additive overflow: true sub-line in the snapshot YAML. The check is a live renderObject.toStringShort().contains(' OVERFLOWING') call (the Flutter debug-mode convention from RenderFlex.toStringShort); no retained state, no Expando. Non-overflowing layouts produce no annotation. The annotation silently drops if a future Flutter version renames the suffix; dusk:exceptions remains the authoritative overflow signal.

Changed

• fluttersdk_artisan constraint bumped from ^0.0.6 to ^0.0.7 (Dart pre-1.0 caret rule: ^0.0.7 resolves to >=0.0.7 <0.0.8). Consumers now pull in artisan 0.0.7 which hardens start --cdp-port with busy-port fast-fail and Chrome/FIFO/profile cleanup (issue #25). All dusk-consumed artisan surfaces (CommandBoot, ArtisanCommand, ArtisanContext.callExtension, McpToolDescriptor, registerExtensionIdempotent, StateFile.read/write) are signature-identical to 0.0.6; the bump is non-breaking.

---

0.0.5 - 2026-05-28

Changed

• fluttersdk_artisan constraint bumped from ^0.0.5 to ^0.0.6 (Dart pre-1.0 caret rule: ^0.0.6 resolves to >=0.0.6 <0.0.7). Consumers now pull in artisan 0.0.6 which ships the substrate mcp:install --invocation=<exec> flag this release depends on for the fallback behavior below.
• mcp:install fallback when bin/fsa is absent now writes dart run fluttersdk_dusk mcp:serve. The dusk wrapper auto-injects --invocation=fluttersdk_dusk when forwarding mcp:install to the substrate, so the substrate's .mcp.json writer picks the plugin-aware payload instead of the legacy dart run :dispatcher mcp:serve fallback. No change in behavior when fastcli is present; the ./bin/fsa mcp:serve payload is unchanged.
• Renamed every dart run fluttersdk_artisan reference inside the dusk package to dart run fluttersdk_dusk (33 docs/code occurrences). The dusk wrapper proxies the full artisan command surface; the package-local invocation is now canonical inside dusk's own docs, error messages, dartdocs, and chained subprocess calls. Substrate package:fluttersdk_artisan/ Dart imports unchanged.

Fixed

• bin/fluttersdk_dusk.dart now forces collectMcpTools: true when dispatching mcp:serve, so dart run fluttersdk_dusk mcp:serve surfaces all 31 dusk_* MCP tools even without the fastcli scaffold. Previously returned 0 plugin tools (only the 10 substrate tools). Verified end-to-end on a fresh flutter create consumer with path-linked dusk + artisan 0.0.6 against a running Flutter app on Chrome (real counter increments visible via dusk:tap + subsequent dusk:snap).

---

0.0.4 - 2026-05-27

Added

• README.md ## AI Coding Assistants section + llms.txt ## AI & Tooling section + 📡 AI-first Distribution feature-table row. Aligns dusk's surface with the cross-package fluttersdk pattern (already shipped on fluttersdk_wind): the canonical fluttersdk-dusk skill at skills/fluttersdk-dusk/ is distributed through fluttersdk/ai to 8 agents (Claude Code, Cursor, OpenCode, Gemini CLI, VS Code Copilot, Codex CLI, Cline, Roo Code) via npx skills add fluttersdk/ai --skill fluttersdk-dusk. The hosted docs MCP at mcp.fluttersdk.com exposes a search-docs tool over Streamable HTTP for direct docs-corpus queries, with an npx @fluttersdk/mcp stdio bridge for clients without HTTP MCP transport. The README copy is explicit that this is independent of dusk's own runtime MCP (./bin/fsa mcp:serve): the docs MCP teaches the agent ABOUT dusk; the runtime MCP gives the agent eyes and hands on a running Flutter app.

Changed

• Hero logo (.github/dusk-logo.svg) realigned to fluttersdk_magic 1:1. The previous logo had drifted toward indigo (#3730A3, #4338CA, #6366F1, #818CF8) which is not in the magic palette the sibling packages share, and its custom wavy shimmer accents diverged from the family line work. The new SVG is a verbatim copy of magic-logo.svg: same 4-layer 3D chevron geometry, same three tilted orbit rings (rotated -12°, 25°, 60° around the same center), same rx / ry / stroke-width / stop-opacity tokens, same 7-color violet palette (#4C1D95 through #DDD6FE). The only change is the gradient ID prefix (m* -> d*, plus orbit-N -> d-orbit-N) so both logos can render on the same page without DOM-level ID collisions. Verification: diff <(grep colors dusk) <(grep colors magic) is empty (set-equal); the same diff over rotate() transforms, ellipse params, chevron paths, and stroke / opacity tokens is also empty.

Fixed

• README + CI workflow stale develop references. README.md hero logo URL, CI badge ?branch=, and contributor-section CI sentence pointed at the retired develop branch (404 after the GitHub Flow migration in 0.0.3). All three now point at master. .github/workflows/ci.yml push + pull_request triggers reduced from [main, master, develop] to [master] (single long-lived branch per the new flow; main was never used, develop is retired). Pub.dev's frozen 0.0.3 archive still carries the broken logo URL; this 0.0.4 docs-only release ships the fix to pub.dev.

---

0.0.3 - 2026-05-26

Added

• skills/fluttersdk-dusk/ Section 7 + references/community.md. Opt-in star and issue-report CTAs for the LLM-agent skill, bumped to skill version: 0.0.3. Section 7 carries the trigger matrix only (star = task verified end-to-end; issue = dusk-side bug, explicitly excluding all six Core Law 3 actionability substrings since those are app-state signals). Executable detail (preflight command -v gh && gh auth status, gh api --method PUT /user/starred/fluttersdk/dusk --silent, gh issue create -R fluttersdk/dusk --body-file - heredoc, dusk:doctor + dusk_console + dusk_exceptions diagnostic gather, prefill URL fallback under 6KB, spam brakes) lives in references/community.md so the always-loaded SKILL.md body stays compact. Both flows are prose-permission only, maximum once per session, never auto-executed; on gh absence the agent prints the URL but does not invoke open / xdg-open / start.

Changed

• Skill bundle decontaminated from consumer-specific identifiers. dusk_evaluate examples in references/mcp-tools.md, references/cli-commands.md, and references/workflows.md now use generic placeholders (MyService.instance.state, MyService.instance.state.toString()) instead of consumer-private symbols (Magic.find<MonitorController>(), Magic.find<MagicApplication>()). Route-discovery hint switched from grep -r 'MagicRoute.page' to portable grep -rEn 'GoRoute|MaterialPage|name:' lib/.

• Tinker REPL guidance unified on the concrete command ./bin/fsa tinker across the published skill bundle. Package-name attribution (magic_tinker, artisan_tinker) dropped from SKILL.md, references/mcp-tools.md, references/workflows.md, references/cli-commands.md since users only ever need the command they run. Code-side magic_tinker references in lib/src/dusk_artisan_provider.dart, lib/src/extensions/ext_evaluate.dart, ARCHITECTURE.md, and doc/mcp/tool-reference.md are unchanged and tracked for a separate follow-up.

• Three Copilot review findings on closed PR #5. references/mcp-tools.md IIFE closure now returns state.toString() so the placeholder API stays consistent with the surrounding MyService.instance.state examples. references/workflows.md route-discovery grep uses portable grep -rEn extended-regex syntax instead of the BSD-incompatible basic-regex \| alternation. skills/fluttersdk-dusk/SKILL.md stale REPL attribution rewritten.

• Two Copilot review findings on PR #6. skills/fluttersdk-dusk/SKILL.md CLI output description rewritten to match references/cli-commands.md truth: 9 read / query verbs emit JSON, the 18 side-effect verbs print a one-line success summary by default and only emit JSON when --includeSnapshot is passed. references/community.md star-flow note drops the spurious HTTP 304 reference; GitHub's PUT /user/starred/{owner}/{repo} is idempotent and returns 204 whether the star was new or already set.

Docs

• CLAUDE.md adopts GitHub Flow (Golden Rule 5 + Branching section). One long-lived branch (master); task branches cut from master, PR back into master; releases bump pubspec.yaml + promote [Unreleased] then tag (git tag X.Y.Z && git push origin X.Y.Z triggers publish.yml). Matches flutter/flutter, dart-lang/sdk, dart-lang/pub, and the modern OSS ecosystem (react, vscode, rust, node, kubernetes, go, angular). The repo's develop branch is retired after this release PR merges.

---

0.0.2 - 2026-05-24

Added

• skills/fluttersdk-dusk/ LLM-agent skill bundle. Ships an Anthropic-shape skill that teaches an LLM agent (Claude Code or any MCP client) how to drive a Flutter app where fluttersdk_dusk is installed. Mirrors the fluttersdk_telescope skill layout. Five files: SKILL.md (frontmatter + 6 core laws + 3 agent loops + tool families + install snippet), references/mcp-tools.md (per-tool input schema / return shape / when-to-use / pitfalls across all 31 dusk_* tools), references/cli-commands.md (CLI mirror via ./bin/fsa dusk:*, pipeline patterns, exit codes), references/actionability-and-refs.md (6-step gate detail + e<N> / q<N> ref recovery matrix), references/workflows.md (8 concrete agent playbooks: form fill, scroll-to-tap, modal flow, navigation verify, hot-reload-after-edit, pull-to-refresh, log tail, before/after diff). Frontmatter front-loads TRIGGER when: / DO NOT TRIGGER when: vocabulary so the model auto-loads the skill on any dusk_* MCP call, dusk:* CLI invocation, or E2E-driver task on a running Flutter app.

Docs

• README demo.gif placeholder removed. The <p align="center"><img src=".../screenshots/demo.gif"></p> block plus its TODO(v0.0.2-followup) recording-instructions comment are dropped until the actual asset ships. The hero logo, badges, and below-the-fold content are unchanged.
• example showroom em-dash sweep. example/lib/main.dart section headers and inline comments are normalised to commas / colons / parentheses, aligning the example with the global no-em-dash rule applied across the rest of the repo.

---

0.0.1 - 2026-05-23

Initial public release of fluttersdk_dusk. E2E driver for Flutter apps. Snapshot, tap, type, drag, scroll, screenshot, wait, find via VM Service extensions (ext.dusk.*). Framework-agnostic (vanilla Flutter friendly); Magic / Wind integrations ship inside those packages via DuskPlugin.enrichers extension point. Plugin of fluttersdk_artisan ^0.0.5 (hosted-only; no path overrides). Wind diagnostics flow through the neutral fluttersdk_wind_diagnostics_contracts bridge (WindDebugRegistry) rather than through the enricher list, so wind alpha-10 needs no dusk-side install wiring.

Added

• 32 CLI commands via DuskArtisanProvider.commands() (live count from ls lib/src/commands/*_command.dart): dusk:install, dusk:snap, dusk:tap, dusk:screenshot, dusk:type, dusk:scroll, dusk:wait, dusk:wait_for_network_idle, dusk:hover, dusk:drag, dusk:modal, dusk:doctor, dusk:navigate, dusk:navigate_back, dusk:get_routes, dusk:press_key, dusk:select_option, dusk:close_app, dusk:find, dusk:focus, dusk:blur, dusk:clear, dusk:right_click, dusk:dblclick, dusk:triple_click, dusk:set_checkbox, dusk:console, dusk:exceptions, dusk:observe, dusk:resize, dusk:device, dusk:hot_reload_and_snap. dusk:install is the one-shot bootstrap; the rest wrap a matching VM Service extension or substrate-routed action.
• 31 MCP tool descriptors via DuskArtisanProvider.mcpTools() (live count from grep "name: 'dusk_" lib/src/dusk_artisan_provider.dart | sort -u): dusk_blur, dusk_clear, dusk_close_app, dusk_console, dusk_dblclick, dusk_device_profile, dusk_dismiss_modals, dusk_drag, dusk_evaluate, dusk_exceptions, dusk_find, dusk_focus, dusk_get_routes, dusk_hot_reload_and_snap, dusk_hover, dusk_navigate, dusk_navigate_back, dusk_observe, dusk_press_key, dusk_resize_viewport, dusk_right_click, dusk_screenshot, dusk_scroll, dusk_select_option, dusk_set_checkbox, dusk_snap, dusk_tap, dusk_triple_click, dusk_type, dusk_wait_for, dusk_wait_for_network_idle. All McpToolDescriptor const instances with Claude Code canonical descriptions (imperative opener + context paragraph + Usage: bullets).
• 28 ext.dusk. VM Service extensions + 3 artisan:dusk: substrate-routed tools** (live count from grep "extensionMethod:" lib/src/dusk_artisan_provider.dart | sort -u). Direct ext.dusk.: snap, screenshot, tap, hover, drag, type, scroll, wait_for, wait_for_network_idle, dismiss_modals, press_key, select_option, navigate, navigate_back, get_routes, evaluate, close_app, find, focus, blur, clear, right_click, dblclick, triple_click, set_checkbox, console, exceptions, observe. Substrate-routed via artisan:dusk:*: resize, device, hot_reload_and_snap (in-isolate hot-reload deadlock avoidance). All ext.dusk. extensions register through registerExtensionIdempotent for hot-restart safety.
• DuskPlugin.install(); idempotent host-side install entry. Wraps the app widget root in a RepaintBoundary (no GlobalKey) so ext.dusk.screenshot can find it via render-tree walk. Hot-restart safe via static _installCount guard. Honors DUSK_DISABLE env var (1 / true / yes, case-insensitive) as kill switch.
• DuskSnapshotEnricher typedef; snapshot-enricher extension point. String? Function(Element, RefRegistry). Magic ships its enrichers via MagicDuskIntegration. Wind no longer ships an enricher as of wind alpha-10: wind state is read through the neutral fluttersdk_wind_diagnostics_contracts.WindDebugRegistry.current?.resolve(element) bridge inside ext_snapshot.dart and ext_observe.dart ahead of the enricher loop, so the 6 core wind fields (breakpoint, brightness, platform, states, bgColor, textColor) survive without an enricher registration. Contract: synchronous, stateless w.r.t. call ordering, may return null to skip, multi-line fragments split + indented under the ref entry by the dispatcher.
• fluttersdk_wind_diagnostics_contracts integration: new production dep fluttersdk_wind_diagnostics_contracts: ^1.0.0. ext.dusk.snap and ext.dusk.observe read wind state via WindDebugRegistry.current?.resolve(element) in addition to the existing enricher list dispatch; the wind: block (filtered by _kDefaultWindKeys in defaults mode) is emitted directly by dusk. Magic enricher contract UNCHANGED.
• RefRegistry; stable e<N> (snapshot-frozen) and q<N> (re-resolvable Playwright-Locator) token systems. e<N> refs are minted at dusk_snap time and consumed by every action tool; q<N> refs are minted by dusk:find and re-execute their stored predicates against the live tree on every action call (resilient to widget rebuild + route push).
• Actionability gate (lib/src/utils/actionability_gate.dart); tap / hover / drag / type resolve through a single gate that verifies the target's enabled flag (Tristate.isFalse fails; Tristate.none and Tristate.isTrue pass), zero-area rect, and viewport overlap BEFORE synthesising the pointer / key event. Failures surface ServiceExtensionResponse.error(extensionError, "Widget ref=$ref is not actionable: $reason") with $reason ∈ {"not enabled", "zero rect", "off-viewport (rect=..., viewport=...)"}. scroll, select_option, and press_key intentionally skip the gate (see Known gaps).
• dusk:install one-shot bootstrap; minimal install. Edits the consumer's lib/main.dart only (no bin/artisan.dart or lib/app/ scaffolding for vanilla Flutter apps). Detects Magic-stack apps via the await Magic.init( anchor and injects DuskPlugin.install() BEFORE Magic.init (then MagicDuskIntegration.install() AFTER), falling back to the runApp( anchor for vanilla Flutter apps. Wind alpha-10 needs no install-time wiring from dusk: the consumer calls Wind.installDebugResolver() directly, and dusk reads wind state through WindDebugRegistry at snap time. Vanilla consumers access dusk via dart run fluttersdk_dusk <cmd>. Idempotent; safe to re-run.
• Flutter-free CLI wrapper; bin/fluttersdk_dusk.dart + executables: fluttersdk_dusk pubspec entry. dart run fluttersdk_dusk <cmd> proxies the full artisan CLI surface and exposes the dusk commands without dragging dart:ui into pure-Dart contexts.
• install.yaml plugin manifest; V1 manifest at the package root makes plugin:install fluttersdk_dusk work end-to-end via the artisan PluginInstaller.
• lib/cli.dart codegen barrel; Flutter-free typedef alias FluttersdkDuskArtisanProvider. Consumed by consumer-side lib/app/_plugins.g.dart auto-discovery without pulling Flutter symbols into the pure-Dart artisan codegen path.
• dusk:find Playwright-Locator pattern; mints q<N> query handles backed by text / semanticsLabel / key predicates. Unlike e<N> refs (frozen at snap time), q-handles re-execute the Semantics + Element walk on every action call, so they survive widget rebuilds and route pushes as long as the predicates still match. Stale match returns an explicit stale-handle error; the agent re-finds, never silently retries.
• dusk:doctor; diagnostic command that checks ~/.artisan/state.json Chrome PID staleness, DUSK_DISABLE env-var value, registered enricher count, Semantics-tree-forced flag, and Magic-init wiring in one pass. Emits a categorised report (OK / WARN / ERROR per check); exit code 0 when every check passes.
• Chrome reaper (lib/src/utils/chrome_reaper.dart); graceful Chromium subprocess teardown between dusk:* runs so leftover headless tabs no longer accumulate. Detects orphans by VM Service URI, exits cleanly via SystemNavigator.pop first, falls back to SIGTERM.
• Example apps: example/ (vanilla Flutter, 7 scenario screens: home menu + buttons / inputs / scroll / modals / drawer / forms) for live e2e validation against the 31 MCP tools + 32 CLI commands.
• CDP driver (lib/src/cdp/): CdpClient, DevicePresets (8 curated device presets with explicit DPR values: iphone-x, iphone-13, iphone-15-pro, pixel-5, pixel-8, ipad-pro-12.9, desktop-1440, desktop-1920), ChromeFinder. Minimal in-house Chrome DevTools Protocol client (~110 LoC, dart:io WebSocket + dart:convert; no pub.dev deps).
• dusk:resize CLI (lib/src/commands/dusk_resize_command.dart): dart run fluttersdk_dusk dusk:resize --width=375 --height=812 [--dpr=3] [--mobile] [--touch]. Reads cdpPort from state.json, opens CdpClient, sends Emulation.setDeviceMetricsOverride (+ optional setTouchEmulationEnabled). --reset sends 3-call clear chain. Fails loudly when CDP not enabled.
• dusk:device CLI (lib/src/commands/dusk_device_command.dart): dart run fluttersdk_dusk dusk:device --preset=iphone-x. Applies the full emulation chain (metrics + conditional touch + UA) from the curated preset database. --list prints all 8 preset entries; --reset mirrors dusk:resize --reset.
• 2 CDP MCP tools (dusk_resize_viewport + dusk_device_profile): both dispatch via the existing artisan: substrate prefix (no mcp_server.dart changes).
• FakeCdpServer test harness (test/src/cdp/fake_cdp_server.dart): dart:io HttpServer + WebSocketTransformer.upgrade on an ephemeral loopback port. Configurable failure modes (failOnJsonVersion, dropWebSocket, delayResponseMs). Used by cdp_client_test.dart, dusk_resize_command_test.dart, dusk_device_command_test.dart.
• Integration smoke test (test/integration/cdp_smoke_test.dart): tagged @Skip so default flutter test skips it; run manually via flutter test test/integration --tags integration to validate dart-lang/webdev#2642 regression status.
• dusk:install magic-detect branch: now injects import 'package:magic/dusk_integration.dart'; instead of import 'package:magic/magic.dart';. Pairs with magic 1.0.0-alpha.15 which extracts the integration class into a dedicated sub-barrel.
• 6-step actionability gate (Wave 3): Step 0 defunct preflight + Stable + Receives-Events gates round out ensureActionable (now async). Total preconditions in evaluation order: defunct (preflight), enabled, zero-rect, off-viewport, stable (rect unchanged across 2 consecutive frames; Playwright auto-waiting), receives-events (hit-test confirms ref is the front-most pointer target). Opt-out via checkStable=false / checkReceivesEvents=false (both default true). Failure-reason substrings extended: "defunct", "not stable", "obscured by" join the existing agent branch surface.
• Snapshot-in-action-response (Wave 3, Playwright setIncludeSnapshot pattern): 8 action handlers (tap, hover, drag, type, press_key, scroll, navigate, navigate_back) accept includeSnapshot=true and append the post-action snapshot YAML to the success response. The agent no longer needs a mandatory follow-up dusk_snap call. duskSnapBuild widened from @visibleForTesting to public (legitimate production reuse). press_key handler endOfFrame omission fixed in passing.
• Structured error envelope + fuzzy-match suggestions (Wave 3): lib/src/utils/error_envelope.dart with DuskErrorEnvelope carrying type + widget_path + suggestions[]. 10 type values: timeout, not_found, obscured, disabled, stale, zero_rect, off_viewport, not_stable, missing_param, unexpected. 6 factories. Dual-write into errorDetail (JSON envelope alongside the free-form message) preserves backward compat for substring-matching agents. Levenshtein with prefix-bonus drives the suggestions list for not_found. RefRegistry.activeRefs() added to support candidate collection.
• ext.dusk.wait_for_network_idle (Wave 3): polls TelescopeStore.pendingHttpCount until the count hits zero for a configurable idleMs window. Params timeoutMs (5000), idleMs (500), pollIntervalMs (200). Function-pointer indirection (pendingHttpCountReader exported from dusk.dart) keeps dusk free of a hard telescope dependency; magic-side wires the real reader at install time. New CLI command dusk:wait_for_network_idle.
• 4 utility tools (Wave 3): dusk_console (telescope log reader, function-pointer indirection via recentLogsReader), dusk_exceptions (telescope exception reader via recentExceptionsReader), dusk_dblclick (two synthesised taps with 100ms inter-tap delay, shared 6-step actionability gate + snapshot embed), dusk_set_checkbox (idempotent Checkbox / Switch toggle via element walk; no-op when current value matches target).
• ext.dusk.observe (Wave 4): Stagehand-style observe-once-act-many pattern. Walks every active PipelineOwner semantics tree, filters interactive nodes (buttons / textfields / links / checkboxes / dropdowns via _roleFor / _isInteractive), mints a re-resolvable q<N> ref per candidate (Playwright Locator pattern; never e<N>), and returns a structured JSON list {candidates: [...], count: N}. Each candidate carries ref, role, label, value, bounds, isEnabled, isVisible, plus enricher-projected fields. Params: intent (caller hint, echoed only), limit (default 50), roles (comma-separated filter), includeEnrichers.
• dusk:hot_reload_and_snap (Wave 4): CLI-side orchestration via VmServiceClient.reloadSources (in-isolate handler cannot reload its own isolate; deadlock avoidance). Sequence: reload -> wait -> snap -> screenshot -> exceptions -> bundle. Success envelope {reloaded, durationMs, snapshot, screenshot, recentExceptions}; compile-error envelope skips snap/screenshot but still gathers exceptions. Screenshot failure surfaces as partial-result screenshotError rather than aborting the round-trip. MCP descriptor uses the artisan: substrate routing prefix (extensionMethod: 'artisan:dusk:hot_reload_and_snap').
• dusk:install is now self-sufficient (Wave 5 pre-publish). Phase 1 patches lib/main.dart (unchanged contract). Phase 2 chains dart run fluttersdk_dusk install (scaffolds bin/dispatcher.dart + ./bin/fsa AOT wrapper) followed by dart run fluttersdk_dusk plugin:install fluttersdk_dusk (registers DuskArtisanProvider; artisan 0.0.5 auto-purges the AOT bundle cache). Both Phase 2 sub-process calls are file-marker-guarded (bin/dispatcher.dart, .artisan/installed/fluttersdk_dusk.json) so re-runs are fast no-ops; failures swallow with a warning so Phase 1's lib/main.dart inject remains the guaranteed contract regardless of the consumer's dart PATH / sandbox state. Net effect: a fresh consumer needs only flutter pub add fluttersdk_dusk + dart run fluttersdk_dusk dusk:install to reach a working ./bin/fsa list + MCP tools/list surface.
• ext.dusk.find substring predicate + dusk:find --contains=<substring> CLI flag (Wave 5; pre-publish E2E pass). Existing --text=<exact> semantics unchanged; agents now have a brittle / dynamic-label fallback. DuskQuery.containsText field is the carrier; matching walks Semantics labels first, then Text.data, mirroring the text path.
• dusk:drag --fromRef=<eN> --toRef=<eN> flag aliases parallel to the --ref shape used by dusk:tap / dusk:hover (Wave 5). Legacy --startRef / --endRef flags retained for back-compat.
• dusk:scroll --direction=<up|down|left|right> --pixels=<N> convenience flags that translate to signed --dy / --dx (Wave 5). Explicit --dy / --dx still win when both forms supplied.
• Surface deltas (live counts): CLI commands: 32 (lib/src/commands/*_command.dart); MCP tool descriptors: 31 (dusk_artisan_provider.dart); VM Service extensions: 28 ext.dusk.* + 3 artisan:dusk:* substrate-routed.

Fixed (pre-publish macOS + web E2E pass, Wave 5)

• dusk_resize_viewport MCP arg parsing (GAP I): handler cast ctx.input.option('width') as String? which failed when MCP tools/call delivers {"width":390} as a native JSON int rather than a stringified arg. Resize command now defensively reads int / double / bool from either type via _readInt / _readDouble / _readBool helpers. CLI invocations still work unchanged (ArgParser-emitted strings).

Fixed

• ext.dusk.focus on TextField + EditableText (GAP C): handler walked UP from the snap-captured Semantics element looking for a Focus ancestor; for TextField the FocusNode sits BELOW the captured element (inside EditableText / FocusableActionDetector). Now falls back to a descendant walk that picks the first EditableText.focusNode or Focus.focusNode it finds. Reproducer: dusk:focus --ref=<textbox-eN> previously returned no Focus ancestor; now returns focused: true.
• ext.dusk.scroll with ref pointing at the Scrollable itself (GAP D): Scrollable.maybeOf(context) walks UP, so passing the ListView's own ref (e.g. from dusk:find --key=my-list) returned null. Handler now resolves in three stages: (1) target element IS a Scrollable, use its state; (2) Scrollable ancestor (legacy); (3) descendant Scrollable walk (when ref is a parent like a Scaffold wrapping a list).
• dusk:press_key --key= case-sensitivity (NIT 5): agents calling --key=TAB or --key=enter hit unknown key even though the supported set covered the intent. Lookup now does a case-insensitive fallback over _kKeyMap.keys when the direct hit misses; canonical PascalCase keys (Tab, Enter, ArrowUp) remain documented.
• dusk:screenshot success message now reports decoded byte count + KB + format, e.g. Wrote 239456 bytes (233.8 KB, jpeg) to ./shot.jpg (NIT 1). Previously the line referenced the base64 character count which misled agents parsing for byte size.
• dusk:screenshot missing-output error now suggests the canonical invocation dusk:screenshot --output=./shot.jpg --format=jpeg (NIT 8).
• README + installation.md document the full 3-step install flow: flutter pub add fluttersdk_dusk + dart run fluttersdk_dusk dusk:install + dart run fluttersdk_dusk install && dart run fluttersdk_dusk plugin:install fluttersdk_dusk (GAP B). Previously the plugin:install step was missing, leaving consumers with ./bin/fsa list showing 0 dusk:* commands. installation.md carries a new ## Register with artisan section explaining the fastcli scaffold + plugin registration.

Test coverage

• 678 tests passing (2026-05-23 pre-publish, flutter test --exclude-tags=integration --timeout=30s). Scope covers handler entry points (params + error paths + happy paths where reachable under flutter_test), 32 CLI commands (name / boot / description / configure / handle / missing-arg validation), DuskArtisanProvider.commands() / mcpTools() shape, DuskPlugin.install() idempotency + DUSK_DISABLE env-var kill switch, RefRegistry mint / lookup / disposeGroup / disposeAll / refsForGroup / registerQuery / lookupQuery, actionability gate (6-step: defunct / enabled / zero-rect / off-viewport / not-stable / obscured), encodeToJpeg PNG-to-JPEG roundtrip + quality boundaries (1, 100, error), modal-route classification, dispatcher contract, CDP client + device presets + resize/device commands, Wave 3 structured error envelopes, Wave 4 observe + hot-reload-and-snap, Wave 5 find-contains substring + descendant focus walk + Scrollable-own-ref scroll. Pre-publish E2E pass against a fresh vanilla Flutter consumer (/tmp/dusk_e2e) verified 27 of 32 CLI commands + MCP initialize + tools/list (41 tools = 31 dusk_* + 10 artisan_*) + tools/call dusk_snap (identical to CLI) + tools/call dusk_evaluate (actual evaluation via artisan 0.0.5 substrate routing).
• Coverage: dusk ~79% line coverage via flutter test --coverage. The remaining gap covers engine-dependent paths that hang the flutter_test fake-clock harness: handler endOfFrame waits, Future.delayed poll loops in wait_for, real toImage() rasterisation in screenshot success paths, and private _defaultProcessStartTime / _parsePsLstart doctor seam defaults. End-to-end coverage for those paths is captured by the example/ playground sweep.

Known gaps

• dusk:doctor runs in pure-Dart CLI context and cannot import package:flutter/rendering.dart without dragging dart:ui (breaks dart run invocation). Two checks defang gracefully as a result: semanticsEnabledProbe defaults to true (the only ERROR-class check, so doctor cannot ERROR from CLI) and enrichersProbe defaults to 0 (always WARNs on Check 3). The real probes belong to a future VM-Service-attached doctor invocation that calls into the running app.
• scroll, select_option, and press_key intentionally skip the actionability gate: scroll targets the parent scrollable not the ref, select_option dispatches through Material/Cupertino popup machinery that owns its own enabled check, and press_key targets the focused widget rather than a ref. Adding the gate to these three handlers is V1.x candidate work.
• RefRegistry._queries (q-handle store) is monotonically growing within a debug session; only RefRegistry.disposeAll() clears it. Worst-case memory bounded by debug-session lifetime; per-handle eviction is V1.x candidate work.

Risks Accepted

• dart-lang/webdev#2642 live regression: "Hot restart broken when running DWDS without Chrome Debug Port". Integration smoke test (test/integration/cdp_smoke_test.dart) surfaces this if active. Mitigation lives in the user's pinned Flutter SDK; plan does not block on regression resolution.
• Flutter SDK >= 3.30.0 required for --cdp-port (per flutter/flutter#170612). Lower versions get an actionable error from both artisan doctor (advisory) and artisan start --cdp-port (fail-fast).
• GAP E (drag synthesis vs Flutter Draggable): dusk:drag returns success but Flutter's DragTarget.onAcceptWithDetails does not fire on synthesised events in some configurations (Pointer Down + 5x Move + Up sequence may not match Draggable's gesture recognizer expectations on certain platforms / dwell times). Verified via E2E showroom (2026-05-23). Tracked for a 0.0.2 follow-up; agents needing drag should fall back to a pair of dusk:tap + manual scroll for now.
• GAP G (advisory): receives-events check + q-refs on widgets with deep render subtrees: when dusk:find --key=<name-field> resolves to a TextField (or any widget whose findRenderObject() returns a top-level RenderObject), the actionability gate's receives-events check sees a hit-test path topped by a deeper descendant (e.g. RenderEditable) and trips obscured by other widget. The _isDescendantOf walk does not catch this case consistently. Workarounds: (1) use the e<N> ref from a prior dusk:snap rather than a q<N> from --key; (2) pass --no-checkReceivesEvents on the action. Tracked for a 0.0.2 follow-up; deeper investigation needed in the gate's hit-test path traversal.
• GAP H (web): dusk:screenshot + dusk:close_app timeout on Chrome (DWDS): 10s timeout. macOS desktop works fine. The web path likely needs special handling for RepaintBoundary.toImage() under DWDS pixel pipeline + the platform-close semantics of SystemNavigator.pop() (which closes the tab, so the response can't return). Workaround for close: rely on ./bin/fsa stop SIGTERM (works). Workaround for screenshot on web: use the browser DevTools snapshot. Tracked for a 0.0.2 follow-up.

Backward compat

DuskSnapshotEnricher typedef, DuskPlugin.install / DuskPlugin.enrichers / DuskPlugin.registerNavigateAdapter, RefRegistry public methods (register, lookup, registerQuery, lookupQuery, disposeAll, resetForTesting), and every MCP tool name / ext.dusk.* extension name are part of the public 0.0.1 contract. Future releases keep these stable across the 0.x line; any change requires a coordinated bump with magic + wind.