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.

Unreleased #

0.0.18 - 2026-10-07 #

Fixed #

dusk:press_key / dusk_press_key reaches the focused widget. The key was handed to HardwareKeyboard.instance.handleKeyEvent, which updates the pressed-key state and calls the keyboard's global handlers and nothing else, so Focus.onKeyEvent, Shortcuts and CallbackShortcuts never heard it, whatever the tool description promised: three ArrowDown presses on an app whose focused FocusScope zaps channels on the arrows changed nothing. Both halves of the press now enter through the binding's onKeyData, the handler real key data reaches, marked synthesized so each is dispatched at once, which delivers to HardwareKeyboard and to the focus tree alike. Every key also carries its own physical key now, where every press used to report the Enter key's. dusk:reset_overlays pressed its Escape the same broken way and now goes through the same helper, so a Shortcuts-bound dismiss hears it. Two limits are documented on the helper: a real key whose raw message is still pending holds the press back until the next real key, and on an embedder that sends only raw key messages (none of Flutter's own) a press before the first real key fixes the transit mode to key data and real keys stop reaching the focus tree until a restart, so such an embedder must not be driven with it; reset_overlays stays best-effort there, catching the debug assert as well as a missing handler. (lib/src/utils/key_press.dart, lib/src/extensions/ext_text_input.dart, lib/src/extensions/ext_modal_router.dart)

Added #

dusk:press_key --key=<letter or digit>. A single ASCII letter or digit presses the key that carries it (G and g both press the G key with the character g), so a shortcut bound to a letter can be driven; text still goes through dusk:type, since a text field takes its text from the text input channel. Anything else outside the named keys is still refused. (lib/src/extensions/ext_text_input.dart, lib/src/commands/dusk_press_key_command.dart, lib/src/dusk_artisan_provider.dart, doc/mcp/tool-reference.md)

0.0.17 - 2026-09-29 #

Fixed #

dusk:perf_campaign keeps the credentials it reads out of the processes it starts. Hooks got the whole inherited environment spread under DUSK_PERF_*, and the preparation processes inherited it too, so a server hooks.before_campaign backgrounded kept the password the campaign reads through ${env.*} for as long as it lived. The loader now names every variable a ${env.NAME} read (PerfLoadResult.envNames, PerfSetupLoadResult.envNames, PerfCampaign.secretEnvNames), and hooks and preparation processes run with includeParentEnvironment: false on the invoking environment minus those names. The filter is by name, not by value: CI=1 survives a secret that reads 1. artisan start and stop run in-process with no environment seam, so the flutter run, the Chrome and the Android adb force-stop they spawn still inherit the dispatcher's environment; the campaign doc says so. (lib/src/perf/scenario.dart, lib/src/perf/scenario_loader.dart, lib/src/perf/campaign.dart, lib/src/commands/dusk_perf_campaign_command.dart, doc/commands/dusk-perf-campaign.md)
perf_run's restart wait names the app's last answer. Since the boot wait became pollDuskBoot, a read could start after the pause that spent the budget, with no time left, and its TimeoutException replaced the app's own last error in the failure; no read starts once the budget is spent now. The campaign also survives a stale .err it cannot delete (reported, like a write it cannot make) and a flutter-dev.log with malformed UTF-8 (decoded leniently), both of which escaped the per-scenario catch and skipped after_campaign and the envelope. (lib/src/perf/perf_run_driver.dart, lib/src/commands/dusk_perf_campaign_command.dart)
dusk:perf_campaign --json prints its envelope however the campaign ends. A stop in the preparation (a hook, flutter pub get, an Android step) returned before the envelope, so a --json caller read nothing; a before_scenario stop listed only the scenarios tried. The envelope now lists every selected scenario, those never tried as status: "not_run" with attempts: 0, carries the stop sentence as stopped, and names anything that failed after the scenarios in errors. An artisan stop that fails after the campaign now exits 1 (it kept exit 0), and an .err that cannot be written inside the per-scenario catch is reported through the output instead of escaping it and ending the campaign before the app stop. (lib/src/commands/dusk_perf_campaign_command.dart, doc/commands/dusk-perf-campaign.md)
dusk:perf_campaign's after_start waits for the Router as long as its guards wait. The Router wait before after_start gave up at perf_run's 10 s, so a cold start that mounted its login screen at 15 s failed before a when guard written for 60 s ever polled. PerfSetupRunner.awaitRouter takes an optional budget (perf_run keeps its 10 s, kPerfRouterBudget), and the campaign passes the largest timeout_ms among the after_start guards, the 60 s guard default when there is none, never less than 10 s. (lib/src/perf/perf_setup_runner.dart, lib/src/commands/dusk_perf_campaign_command.dart, doc/commands/dusk-perf-campaign.md)
A secret shorter than 4 characters is a load problem. Every output is masked for every secret wherever its text appears, so a secret 1 or 80 masked that number in every log line, run file and envelope. loadPerfScenarios and loadPerfSetup now refuse a non-empty ${env.*} value or secret: true param under 4 characters (kPerfMinSecretLength), naming the variable or the param and its length, never the value. (lib/src/perf/scenario.dart, lib/src/perf/scenario_loader.dart, doc/commands/dusk-perf-run.md)
ext.dusk.navigate_back leaves a hidden shell branch alone. It popped the first poppable Navigator in tree order, offstage ones included, so in a go_router StatefulShellRoute (every branch kept alive, the inactive ones under Offstage and a disabled TickerMode) a page stacked on a hidden branch was popped while the visible branch stayed, and the answer said popped: true. A subtree under Offstage(offstage: true), TickerMode(enabled: false) or Visibility(visible: false) is no longer walked. (lib/src/extensions/ext_navigation.dart)
A perf_run setup navigate lands on its own path, and a late landing is on the record. The late-landing poll accepted a path under the route, so a dropped navigate to /monitors while a web hot restart had left the app on /monitors/<id> passed as landed; it now needs the exact path, query ignored. A unit whose setup relied on a late landing carries setupLandedLate: true in its repeats[] entry. (lib/src/commands/dusk_perf_run_command.dart)
perf_run's post-idle route check compares paths. It compared whole URIs, so a page that normalises its query after the first fetch (/monitors to /monitors?page=1) failed setup as moved. (lib/src/commands/dusk_perf_run_command.dart)
perf_trace cuts its frames by perf_end's rule. Under a clock mismatch (frames carry a timestamp and none lands in the window) perf_end keeps every frame while the trace dropped them all, so the two artifacts disagreed silently. The trace now shares perf_end's window cut, keeps the frames, and says so with otherData.sessionClockMismatch: true. buildPerfReport forwards sessionClockMismatch the way analysePerf takes it. (lib/src/extensions/ext_perf.dart, lib/src/extensions/ext_perf_trace.dart, lib/src/utils/perf_insights.dart)
The CDP emulation tools say how long their override lasts. dusk_resize_viewport and dusk_device_profile promised a resize, and neither can pass hold: each call opens its own CDP session and closes it on return, and Chrome drops the Emulation.* override with it. Both descriptors, both CLI descriptions and dusk:device's output now say the override lasts only as long as the call's CDP session (only dusk:device's window size stays), and dusk:resize reports "override sent" rather than "Viewport set to", pointing at --hold. (lib/src/dusk_artisan_provider.dart, lib/src/commands/dusk_resize_command.dart, lib/src/commands/dusk_device_command.dart)
ext.dusk.navigate_back pops a page stacked inside a shell. It popped the first Navigator in the tree, which in a go_router app is the root one, and that holds the shell alone: for a detail page pushed inside a ShellRoute (MagicRouter layouts, .stacked()) the pop did nothing, the answer was still navigatedBack: true, and get_routes's uri kept naming the detail page because it was still mounted. It pops the outermost Navigator that can pop instead, so a page pushed on the root is left before a shell's. uri itself was not stale: it follows the Router's report within the frames the handler awaits. The answer gains an additive popped, false when no Navigator could pop, so a no-op no longer reads as a pop. (lib/src/extensions/ext_navigation.dart, lib/src/dusk_artisan_provider.dart, doc/mcp/tool-reference.md, skills/fluttersdk-dusk/references/mcp-tools.md)
The semantics pass re-acquires after perf_end, not inside the window. perf_run called ext.dusk.semantics_hold action=acquire before perf_end, so the acquire's frame, a rebuild of the whole semantics tree, was a frame of the session, and perf_end read env.semanticsEnabled after it: every semanticsOff repeat reported true. The session now closes first and the acquire follows, and it still runs when a step or perf_end throws. (lib/src/commands/dusk_perf_run_command.dart, lib/src/extensions/ext_semantics_hold.dart, doc/commands/dusk-perf-run.md, doc/reference/semantics-hold.md)
The semantics pass no longer reports a release that left semantics on as measured. On Flutter web the engine turns semantics on at the first semantics tree a real app sends and never turns it off, so once dusk had snapshotted the app, releasing dusk's handle left the tree on: a measured uptizm list scroll showed the SEMANTICS block on 58 of 60 semanticsOff frames, as many as the attribution series, under semanticsPass: "measured". The release answer gains heldByPlatform (platformDispatcher.semanticsEnabled), and a release that answers semanticsEnabled: true ends the pass: semanticsPass: "unsupported", no semanticsOff series, and a semanticsPassReason naming the platform and what holds semantics on (the web engine on chrome, an accessibility service on a device, or another SemanticsHandle). (lib/src/extensions/ext_semantics_hold.dart, lib/src/commands/dusk_perf_run_command.dart, lib/src/dusk_artisan_provider.dart, doc/commands/dusk-perf-run.md, doc/reference/semantics-hold.md, doc/mcp/tool-reference.md)
perf_run navigates once the app can route. ext.dusk.boot_id answers as soon as DuskPlugin.install() has run, which a host that installs dusk before its own boot (magic_devtools' documented order) reaches before runApp mounts its Router, so the first setup navigate after every hot restart answered navigated: false and every Chrome scenario that navigates failed at its first unit. A setup navigate now waits, up to 10 s, for get_routes to report a mounted Router, and holds a navigated: false against the Router for up to 3 s before failing: a Router that has only just mounted is still applying its first location when the navigate reads it (measured: false as it mounted, true 300 ms later). The route is never dispatched twice. (lib/src/commands/dusk_perf_run_command.dart, doc/commands/dusk-perf-run.md)
perf_run's post-idle route check can see a redirect. It compared get_routes's location before and after network idle, which a Router-based app answers as "" on both sides; it compares uri now, and the setup diagnostics quote it (route none (no Router mounted) when there is none). (lib/src/commands/dusk_perf_run_command.dart)
perf_end describes its own window. A list scroll on the Pixel 8 emulator drew 24 frames and the summary held 31: timings the engine had parked before perf_begin arrive after the buffer is cleared, and the idle frame perf_end draws to flush the tail is a frame of its own. Frames are now kept by vsyncStartUs inside the session window (a record without one is kept), the denominator stays the liveness advance read before the flush, and coverage.framesOutsideSession counts what was read and left out. vsyncStartUs against FlutterTimeline.now is unverified off the web; a disagreement shows as a large framesOutsideSession. (lib/src/extensions/ext_perf.dart, lib/src/utils/perf_insights.dart, doc/commands/dusk-perf-end.md)
perf_trace counts the frames it leaves out. A frame outside the session window was dropped silently; otherData.framesOutsideWindow now says how many. (lib/src/extensions/ext_perf_trace.dart, doc/reference/perf-trace.md)
ext.dusk.find_by_label finds labels in a running app. It walked rootPipelineOwner alone, so a view mounted under a child pipeline owner (the test harness, a multi-view app) matched nothing; it now walks every owner as observe and snap do. (lib/src/extensions/ext_wait_find.dart)
dusk:resize says what it can keep. Chrome drops Emulation.setDeviceMetricsOverride when the DevTools session that sent it detaches, whatever its parameters (measured against Chrome: 390 px inside the session, the page's own width right after), so the command set a viewport and exited, and the success line said it was set. A new --hold keeps the session open until Ctrl-C or until Chrome exits; without it the command now warns that the override ends with it. (lib/src/commands/dusk_resize_command.dart, doc/commands/index.md, doc/commands/dusk-screenshot.md)
perf_run setup failures say which screen the app was on. A wait_for_text that timed out, or a setup gesture that matched nothing, named only the text, so a navigate the router had dropped read the same as a slow page. Every setup failure but a restart's now ends with a Diagnostics: line: the route ext.dusk.get_routes answers, the last setup navigate's payload and the three newest ext.dusk.exceptions entries. A setup navigate answering navigated: false fails at once with its payload instead of being ignored, and after each one the runner waits for network idle and reads the route again, failing when the app has moved (an auth redirect after the first fetch). (lib/src/commands/dusk_perf_run_command.dart, doc/commands/dusk-perf-run.md)
perf_run waits up to 3 s for a target. A target the screen had not built yet failed the run as "matched nothing" on the first lookup; it is now looked up every 100 ms for up to 3 s (30 lookups at most) first. (lib/src/commands/dusk_perf_run_command.dart)
perf_run resolves outside the window what it can. Every target was resolved inside the measured window, so each lookup (and a wheel's hover) was session cost. A target only wait steps precede is now resolved before perf_begin, a wheel's hover point with it (PerfStepVerb.movesTargets); a target an earlier step can create or move, such as an option in the overlay a tap opens, still resolves just before its step. Each repeat in the run file gains resolves: [{step, verb, phase: beforeBegin|inWindow, resolveMs}], so the in-window cost is visible. (lib/src/commands/dusk_perf_run_command.dart, lib/src/perf/scenario.dart, doc/commands/dusk-perf-run.md)
The run file keeps the renderer the app reported. env.renderer was always overwritten with the run log scrape, which reads unknown on web, so the canvaskit or skwasm answer from rendererReader never reached the file. The app's answer now wins, and the scrape is used only when the app answers unknown. (lib/src/commands/dusk_perf_run_command.dart, doc/commands/dusk-perf-run.md)
perf_run setup waits survive a slow web restart. wait_for_text now waits in 5 s slices until its budget is spent: DWDS abandons any service extension call at 10 s, so one 15 s in-app wait failed as a -32603 whenever the app took longer than 10 s to show the text.
The actionability gate no longer refuses every ref once the soft keyboard has opened. The stable check measured the live rect against the rect the snapshot minted, so any reflow since the snapshot read as motion: on Android, the keyboard that fill itself opens failed the next fill and tap with not stable (rect changed by 21.0px) and kept failing until a re-snap, however still the page was. Both samples are now live, one frame apart, as the check was documented to do. The off-viewport check now measures against the view minus its viewInsets, and scrolls a target in when its center is outside that area: a submit button laid out under the keyboard used to pass as on-screen and then fail with obscured by other widget (top=_RenderInkFeatures), the Scaffold's own Material in the inset. With no Scrollable to bring it up, such a target is refused as off-viewport. Check order and reason substrings are unchanged. (lib/src/utils/actionability_gate.dart, doc/reference/actionability-gate.md)
A scenario wheel can scroll like a wheel. ticks: N sends N events of dx/dy, one frame apart, at the one point the step resolved. A single 1200 px event jumped the uptizm monitor list in one frame and the session measured five.
perf_end no longer loses the frames a session drew last. The web engine hands frame timings over only from inside a later frame, 100 ms after the previous hand-over, so the tail of a session stayed parked and a list scroll reported 1 of 5 frames. perf_end now waits past that interval and draws one idle frame (after the liveness verdict, so a hidden page still refuses) before it reads.

Added #

hooks.after_campaign: a campaign's teardown. before_campaign could start services and nothing stopped them (a server bound to 0.0.0.0 outlived every campaign). after_campaign runs once after the final app stop, however the campaign ended, a failed before_campaign included (it may have started half of what the teardown stops), and not when the command refused its input or selected nothing. It gets the hook environment plus DUSK_PERF_STATUS=ok|failed; a failure exits 1, is listed in the envelope's errors and appended to campaign-<label>.err, and never hides the scenario results. (lib/src/perf/campaign.dart, lib/src/commands/dusk_perf_campaign_command.dart, doc/commands/dusk-perf-campaign.md)
ext.dusk.navigate answers exactPath. Its verdict stays a prefix match, the documented intent (a navigate to /monitors that shows /monitors/7, a default child, navigated), and the payload now says whether the Router's path is the route's own, query aside: exactPath: true for the route itself, false for a page under it and beside navigated: false. Additive; dusk:perf_run's setup keeps its own exact check. (lib/src/extensions/ext_navigation.dart, lib/src/dusk_artisan_provider.dart, doc/mcp/tool-reference.md, skills/fluttersdk-dusk/)
The run file's setup echoes its when guards. PerfSetupStep.toJson wrote a guarded step as if it always ran, so nothing in a run file said a guard stood in front of it. Each guard is now echoed once, marking where its group begins, as when: {text, unless_text, timeout_ms}, on the first step it governs (PerfSetupStep.toJson(opens:), PerfSetupGuard.toJson); an enclosing guard entered on the same step is its parent, and a bare verb there becomes {verb: null, when}. Unguarded steps are unchanged, and dusk:perf_compare reads no setup. (lib/src/perf/scenario.dart, doc/commands/dusk-perf-run.md)
dusk:perf_campaign: a whole perf campaign in one command. dusk:perf_campaign <campaign.yaml> --platform=<chrome|android|ios> filters the campaign's scenarios by platform and --only (nothing selected exits 1 before any hook or process runs), runs hooks.before_campaign through /bin/sh -c with DUSK_PERF_PLATFORM, DUSK_PERF_LABEL and DUSK_PERF_OUT, flutter pub get, and on Android boots android.avd, waits for sys.boot_completed, adb reverses each port and installs and grants a profile APK. Each scenario then gets up to retries + 1 attempts, each from a cold start: hooks.before_scenario (plus DUSK_PERF_SCENARIO), artisan stop, a wait until the old pid is gone and its ports are free, artisan start, a poll of ext.dusk.boot_id, after_start once a Router is mounted, and dusk:perf_run in-process. A failed attempt, whatever it threw, is recorded in <out>/<scenario>-<label>.err (with flutter-dev.log when the start failed) and the campaign goes on; the app is stopped at the end; one line per scenario (or a --json envelope) and exit 1 when any failed. Every line, .err, run file and envelope is masked for the campaign's secrets: the run file perf_run wrote is masked again for the after_start ones, a diagnostic exception message is masked before it is cut to 200 characters, and the --json envelopes of both commands are tree-masked and printed once, so a numeric secret cannot break their JSON. A flutter, adb or hook shell that cannot start stops the campaign with <exe> could not start, a --cdp-port that is not a port exits 1 before anything runs, an android.grant entry or Gradle applicationId that is not [A-Za-z0-9_.]+ is refused before it reaches the device shell, and a scenario that passed on a retry prints ok (attempt N, see <err>). dusk_perf_run takes variant. CLI only, no MCP tool. (lib/src/commands/dusk_perf_campaign_command.dart, lib/src/dusk_artisan_provider.dart, doc/commands/dusk-perf-campaign.md)
dusk:perf_run loads fragments and variants, runs when guards and masks secrets. Both the scenario and --against load through loadPerfScenarios, so include, ${...} and variants work in a run. --variant=<key> picks one variant (required when the file declares variants, the error listing the keys; refused when it does not; applied to --against too), and the run file carries a top-level variant when one was picked. An include's when guard polls ext.dusk.find --text every 250 ms up to timeout_ms, unless_text first: text runs the group, unless_text skips it, a timeout skips it without unless_text and fails the run naming both texts with one. Every line the command prints and every string in the run files it writes is masked for the loaded secrets, raw and JSON-encoded (PerfRedactor, RedactingOutput). The setup and step execution moved into the public PerfSetupRunner (run, awaitRouter, diagnose) and PerfActions, which the campaign command reuses; existing scenarios run exactly as before. (lib/src/commands/dusk_perf_run_command.dart, lib/src/perf/perf_actions.dart, lib/src/perf/perf_setup_runner.dart, lib/src/perf/perf_redaction.dart, doc/commands/dusk-perf-run.md)
Scenario fragments, interpolation, secrets and variants. loadPerfScenarios(path, env:) loads a scenario file and answers (scenarios, secrets): a setup entry - include: <path> with with: and when: flattens a fragment (params, when, steps, nested up to 8 deep, cycles refused) into setup, each flattened entry keeping its origin (fragments/login.yaml steps[1]) and the when guard as a PerfSetupGuard; every scalar is interpolated once (${param}, ${env.NAME}, $$); a value from the environment or a secret: true param may only be the text of a fill or type, is marked PerfStep.secret, written as *** by toJson and masked in every parse problem; variants: {<key>: {viewport, platforms, repeat, steps}} yields <name>-<key> scenarios validated one by one. loadPerfSetup reads a bare entry list (a campaign's after_start:) the same way. PerfScenario.parse refuses include and variants, and reads $$ as $. (lib/src/perf/scenario.dart, lib/src/perf/scenario_loader.dart, doc/commands/dusk-perf-run.md)
rendererReader, a seventh cross-package pointer, fills env.renderer in the perf_end report. Its default is dusk's own answer: skwasm or canvaskit on web, unknown elsewhere, where the launch log scrape of dusk:perf_run covers native. A host may reassign it. Exported from the barrel. (lib/src/utils/perf_readers.dart, lib/src/extensions/ext_perf.dart, lib/dusk.dart)
perfInteractionAt(int us), exported. The interaction whose window [startUs, closedAtUs ?? now] holds a recorded time, the newest when windows overlap; for a host that recorded a time without recording the gesture behind it. (lib/src/utils/perf_interaction.dart, lib/dusk.dart)
dusk:perf_insight / dusk_perf_insight / ext.dusk.perf_insight: drill into one insight of the last perf_end report. Takes id (and an optional token naming the report's session) and returns Title / Summary / Detail / EstimatedSavings / NextStep, where detail is the raw rows behind the insight: the worst frames with their self-time blocks, the frame-number gaps, the frames where one block weighed most, or what a coverage gap left out. Ids are assigned before the report cuts its list, so an insight counted in omitted.insights is still drillable. An unknown id, a stale token or a refused session answers an error naming what to read instead; an unknown id points at perf_end's insights[]. (lib/src/extensions/ext_perf.dart, lib/src/commands/dusk_perf_insight_command.dart, lib/src/dusk_artisan_provider.dart, doc/commands/dusk-perf-insight.md)
perf_begin gains mode: attribution|timing. timing touches no debugProfile* flag and no collection flag, and its report carries frame timings only: the profiling that makes attribution possible inflates every duration it wraps, so milliseconds are only comparable between timing sessions. phases with timing is rejected, as is an unknown mode, before anything is touched. (lib/src/extensions/ext_perf.dart, lib/src/commands/dusk_perf_begin_command.dart)
perfInsightContributors, a fifth cross-package pointer, and a pure buildPerfReport, both exported from the barrel. The host (magic_devtools) appends rules that need to know what a wind or magic counter means; a contributor that throws or returns a malformed insight becomes one warn insight (contributorErrors) and never costs the report. buildPerfReport(framePerf, extras, wind, env: ...) is the function the extension calls, so a host's conformance test builds the same report from the same maps. (lib/src/utils/perf_insights.dart, lib/src/utils/perf_readers.dart, lib/dusk.dart)
A closable interaction per dusk gesture, carried in the zone. While a perf session is open, every verb that dispatches into the app (tap, dblclick, triple_click, right_click, hover, drag, type, clear, fill, press_key, focus, blur, scroll, select_option, set_checkbox, navigate, navigate_back, dismiss_modals, reset_overlays) runs its dispatch inside runZoned(zoneValues: {#fluttersdk_interaction: handle}), so the Timers, Futures and subscriptions its callbacks start can name the gesture that caused them. PerfInteraction {id, verb, target, startUs, closedAtUs} closes at settle (no frame scheduled for 300 ms, or 5 s, or the session closing), and a closed handle reads as absent: a socket opened during a tap keeps its zone forever and would otherwise be attributed to it for good. Frame-zone work (builds, initState refetches, post-frame callbacks), which the zone cannot reach, joins through activeInteraction(). A verb dispatched inside another joins its interaction, so fill is one. Outside a session nothing changes: no handle, no zone, no timer; the actionability gate and gesture dispatch are untouched. PerfInteraction and activeInteraction are exported from the barrel. (lib/src/utils/perf_interaction.dart, the gesture extensions, lib/dusk.dart, doc/reference/perf-trace.md)
ext.dusk.perf_trace: the closed session's timeline as Chrome Trace Event JSON, which ui.perfetto.dev and chrome://tracing open as is. Interactions and frames (placed at vsyncStartUs) are X slices; host rows from the new perfTimelineReader pointer map by kind, a span with an id to an async b/e pair, one without to X, an instant to i, a counter to C. An X slice that would straddle another on its track moves to an overflow lane (frames (2)) rather than being trimmed. Only what started inside the session window is exported; a malformed host row is counted in otherData.skippedRows. Takes an optional token; answers an error before any session closed, for a stale token, while a newer session is open (its perf_begin cleared the buffers the trace reads), and when a host reader throws. dusk:perf_trace / dusk_perf_trace write it to a file. (lib/src/extensions/ext_perf_trace.dart, lib/src/utils/perf_readers.dart, lib/src/extensions/register_dusk_extensions.dart, doc/reference/perf-trace.md)
ext.dusk.perf_end accepts full: 'true', which lifts every cut: block rankings, counter breakdowns, route transitions and insights carry every row and omitted reads all zeros. For a runner that writes the report to a file; the default stays bounded to about 6 KB. buildPerfReport gains the same full flag. (lib/src/extensions/ext_perf.dart, lib/src/utils/perf_insights.dart, doc/commands/dusk-perf-end.md)
dusk:perf_run / dusk_perf_run: a perf scenario, repeated from a clean start, to a file. A scenario YAML names setup (hot_restart, navigate, wait_for_text, wait_for_network_idle, plus the gestures tap, fill, type, press_key, wheel, drag and wait with the steps' grammar and validation, run before every repeat and before perf_begin, so the path to the measured screen is not measured), steps (tap, fill, type, press_key, scroll, wheel, drag, navigate, resize, wait, each optionally only: [...]), platforms, viewport, repeat and thresholds. A target is exactly one of {text}, {label}, {role, name}, {key} plus an optional index (not on a key or a label), resolved on the live screen right before its step; {role, name} is the node dusk:snap prints as that role and name, listed through ext.dusk.observe with snap's roles (button, textbox, checkbox, link, heading, image), since ext.dusk.find_by_label walks only the root pipeline owner and finds nothing in a running app; a literal ref, a wheel or resize that could run off Chrome, and a name or label outside [a-z0-9_-] are rejected, every problem at once. hot_restart is a hot restart on debug and a relaunch through artisan restart on a build that cannot (env.restartMode); either way the runner waits, 90 s at most after a hot restart, for ext.dusk.boot_id to answer a new id, not for a new isolate, which Flutter web never gets (DWDS keeps isolate "1"). Each repeat brings Chrome to front, then perf_begin, the steps, a 300 ms settle and perf_end full=true. Writes <out>/<scenario>-<label>.json: env (plus host and the run log's renderer), summary (medians of counts per painted frame and ms, with a spread block), the median repeat's insights, every repeat and the scenario; --json prints it minus repeats[]. --timing interleaves timing-mode repeats, --against <baseline.yaml> runs a second scenario in the same rounds, the order alternating each round. A refused repeat is recorded and left out of the medians; the command exits 1 only when every repeat refused. (lib/src/commands/dusk_perf_run_command.dart, lib/src/perf/scenario.dart, doc/commands/dusk-perf-run.md)
dusk:perf_run --semantics-pass and ext.dusk.semantics_hold. The pass records where each tap, drag and wheel dispatched with the tree on, then replays them by coordinates with dusk's process-wide semantics handle released for the timed window only (action=release after perf_begin, refused outside a session; action=acquire after perf_end, awaiting one frame so the tree exists again, run even when a step failed). Reported as a semanticsOff series; a scenario with a fill, type or scroll, or a replay that fails, records semanticsPass: "unsupported" with the reason instead of failing the run. DuskPlugin gains releaseSemantics, acquireSemantics and semanticsReleased. (lib/src/extensions/ext_semantics_hold.dart, lib/src/dusk_plugin.dart, doc/reference/semantics-hold.md)
Coordinate dispatch and reported points on ext.dusk.tap, drag and hover. tap {x, y} and drag {x, y, toX, toY} dispatch with no ref and read nothing from the semantics tree; their checks block always says gate: skipped and whether the handle is held or released. reportPoint: true adds the dispatched point (tap, hover) or from / to (drag), and drag accepts startRef plus dx / dy in place of endRef. Ref dispatch is otherwise unchanged. (lib/src/extensions/ext_pointer.dart)
dusk:perf_compare / dusk_perf_compare: judge one run file against another. Gates on counts per painted frame, never raw counts, so a run that drew 10% fewer frames with the same per-frame counts is unchanged, not improved; milliseconds only from timing-mode medians; emulator raster ms as info. A change inside either run's repeat-to-repeat range is unchanged. Default thresholds warn +10% and error +25%, overridden by the scenario. Prints a compact table, or the JSON with --json; exits 1 on an error-level regression. (lib/src/commands/dusk_perf_compare_command.dart, doc/commands/dusk-perf-compare.md)
dusk:perf_trace / dusk_perf_trace: write ext.dusk.perf_trace to a Chrome Trace JSON file and print only its path. (lib/src/commands/dusk_perf_trace_command.dart, doc/commands/dusk-perf-trace.md)
ext.dusk.boot_id, internal: the id DuskPlugin.install() mints for each run of main() (DuskPlugin.bootId). Registered last, so an answer means every other extension is registered too. No CLI command or MCP tool wraps it; dusk:perf_run reads it to tell a restarted app from the one before. (lib/src/extensions/ext_boot.dart, lib/src/dusk_plugin.dart, lib/src/extensions/register_dusk_extensions.dart)

Changed #

The artisan and contracts floors move to fluttersdk_artisan ^0.0.17 and fluttersdk_wind_diagnostics_contracts ^1.2.0. dusk:perf_campaign reads StartCommand.browserDevices, public from artisan 0.0.17, instead of a local copy, and its Android runs rely on the profile launch and force-stop artisan 0.0.17 ships; contracts 1.2.0 documents the widgetBuilds, wrapperEmissions and inheritedReads stats keys the perf snapshot reads. (pubspec.yaml, lib/src/commands/dusk_perf_campaign_command.dart, doc/getting-started/, CLAUDE.md)
dusk:perf_campaign opens one driver per attempt. after_start and dusk:perf_run described the host (a sysctl or uname spawn) and read the run log twice per attempt, each through its own connectArtisanPerfRun; the attempt now opens the driver once and hands it to DuskPerfRunCommand.connected, which runs on it and leaves it to its owner to close. The cold start's boot wait and perf_run's restart wait share one loop (pollDuskBoot), and PerfRunDriver, PerfRunEnvironment and PerfRunException moved to lib/src/perf/perf_run_driver.dart, so the perf library no longer imports a command. (lib/src/commands/dusk_perf_campaign_command.dart, lib/src/commands/dusk_perf_run_command.dart, lib/src/perf/perf_run_driver.dart, lib/src/perf/perf_support.dart)
dusk:install gates the install under !kReleaseMode, and every doc says the same. dusk:perf_run relaunches the app as a profile build, and the if (kDebugMode) block the installer wrote registered no ext.dusk.* there, so the first boot_id or perf_begin call against an app set up by the installer failed. The injected block, the MagicDuskIntegration block and the import (show kReleaseMode) now match the DuskPlugin docblock; release builds still tree-shake the branch. An app wired under kDebugMode before this is left alone: the installer now checks for the DuskPlugin.install() and MagicDuskIntegration.install() calls rather than for its own snippet, so a re-run adds neither a second block nor an unused import, and such an app keeps working in debug until its guard is changed by hand. The dusk:install page also stops claiming the installer wires Wind.installDebugResolver(); it never did. (lib/src/commands/dusk_install_command.dart, install.yaml, README.md, ARCHITECTURE.md, CLAUDE.md, doc/getting-started/, doc/commands/dusk-install.md, doc/plugins/, doc/mcp/tool-reference.md, skills/fluttersdk-dusk/, example/lib/main.dart)
ext.dusk.get_routes answers the Router's location as uri. location reads the root Navigator's top page name, which a Router-based app (go_router, MagicRouter) leaves empty on every screen, so a caller had no way to see where the app was. The new uri field is the first mounted Router's location, the value ext.dusk.navigate already verifies against, and null while no Router is mounted; location and title are unchanged. (lib/src/extensions/ext_navigation.dart, lib/src/dusk_artisan_provider.dart, doc/mcp/tool-reference.md)
yaml moves from dev_dependencies to dependencies, for the scenario files dusk:perf_run reads. No consumer graph gains a package: fluttersdk_artisan, which dusk already requires, depends on yaml ^3.1.3 itself. The only importer is lib/src/perf/scenario.dart, reached from the host-side dusk:perf_run and dusk:perf_compare commands; in an app it sits behind the same !kReleaseMode branch as the rest of dusk and is tree-shaken from release. (pubspec.yaml, CLAUDE.md)
Breaking: perfSessionBeginHook receives the session's PerfMode (void Function(PerfMode mode)), so a host can leave wind's counting off in a timing session. Counting sits on WindParser.parse, the hottest path in the framework, and switched on regardless it inflated exactly the milliseconds timing mode exists to report. A host assigning () {} no longer compiles; assign (PerfMode mode) {}. (lib/src/utils/perf_readers.dart, lib/src/extensions/ext_perf.dart, doc/commands/dusk-perf-begin.md)
Breaking: ext.dusk.perf_end answers an LLM-first report instead of a raw dump, with no alias of the old keys. A real session's payload was 7 to 13 KB of mixed micros and millis, top-N lists that did not say what they cut, and an overhead caveat buried in prose. The payload is now {sessionToken, refused, mode, env, coverage, summary, counters, insights, omitted}, bounded to about 6 KB for a 3600-frame session over 500 block names. Every duration is in ms against a stated budgetMs of 16.7; summary.frames gives count, painted, dropped (frame-number gaps), over-budget counts split by thread, and p50/p90/p99/worst build and raster; blocks are ranked by SELF time (selfMicros, never the nested micros, which blames a parent for its child's work) and by count per painted frame; every counter is given raw and per painted frame; omitted counts what each ranked list cut. env states platform, isWeb, buildMode (from kProfileMode/kDebugMode), semanticsEnabled and phases. coverage.missing names sources never read, so counters.wind: null plus missing: ['wind'] is no longer confusable with a wind that counted nothing. Built-in insight rules (over budget, dropped frames, a dominant self-time block, a count-per-frame outlier, incomplete coverage) each state their threshold in the evidence. Removed top-level keys: frameSummary, blockAttribution, note, wind, magic, liveness, phases (now env.phases); the refusal carries the liveness numbers under coverage. The stalled-engine refusal (1 frame or fewer) and the flag receipt are unchanged. (lib/src/extensions/ext_perf.dart, lib/src/utils/frame_summary.dart, lib/src/utils/perf_insights.dart, lib/src/commands/dusk_perf_end_command.dart, doc/commands/dusk-perf-end.md, doc/mcp/tool-reference.md)
perfExtrasReader documents the full magic key set (controllerNotifies, notifyCauses, queryReloads, actions, events, casts, timerTicks, broadcasts, routeTransitions), and its default returns an empty structure for each. Hosts that still return only the first and last keep working: unknown or absent keys cost nothing. (lib/src/utils/perf_readers.dart)
ext.dusk.snap registers in profile builds too (!kReleaseMode instead of kDebugMode), so a profile-mode perf session can still be driven. ext.dusk.evaluate stays debug-only. (lib/src/extensions/ext_snapshot.dart)

0.0.16 - 2026-09-23 #

Fixed #

dusk:fill, dusk:type and dusk:clear no longer write into a field on a route the visible one covers. The field is chosen by the largest overlap between each EditableText's rect and the ref's rect, over every editable in the tree. A route under an opaque one stays alive and laid out at its old rect, so a second instance of the same screen ties with the visible field and, visited first, won the tie. Reported from a consumer's login screen, where a login route sat on top of a redirected one: fill answered verified: true with the typed value while the visible field stayed empty, because the read-back came off the covered field's own controller; popping the top route showed the value in the form underneath. Only reproducible when the pages keep their exact rects, which is go_router's NoTransitionPage (what magic builds on web); a zoom or slide transition displaces the covered page and hides the tie. An editable under a TickerMode(enabled: false), which is how Overlay marks an entry below an opaque one, now ranks below every unmuted editable, overlapping or not: a handle found by its label carries the label's rect, and on a screen pushed over a lookalike that rect can overlap only the covered field. The muted fields are ranked only when nothing unmuted exists, so an app that mutes a visible form keeps its targeting. One gap is left open on purpose: such an app with an unmuted field elsewhere on screen (a search box) gets that field, because nothing in the ecosystem mutes a visible subtree and telling the two apart needs a hit test, which this package already documents as unreliable on web debug builds. type's actionability gate checks the ref's own rect, not the field this ranking resolves, so it does not refuse a wrong field either. Read by walking the ancestors rather than through TickerMode.of, which would subscribe the field to ticker changes from outside build, or getValuesNotifier, which needs Flutter 3.35. (lib/src/extensions/ext_text_input.dart, test/src/extensions/ext_text_input_test.dart) (#45)

0.0.15 - 2026-09-21 #

Fixed #

A dusk:observe candidate could not be told apart from another carrying the same label, so acting on one moved the other. Every handle observe minted carried the semantics label alone (ext_observe.dart), so N candidates sharing a label got N handles that all re-resolved to the first match, which contradicts the one-candidate-per-interactive-node contract the tool documents. It costs a real session: an agent that correctly picked the third row of a list by its bounds tapped the first, and both calls reported success. A consumer spent two releases recording an app defect that was this, with a viewport sweep and six eliminations behind it, because moving the viewport moved the wrong control in and out of a bottom bar's way. DuskQuery gains matchIndex, the node's position among every node whose label matched, in walk order. Observe counts it on SemanticsNode.label rather than on getSemanticsData().label, which are different strings under merged semantics (semantics.dart:3801-3804 concatenates every merged descendant's label into the data), and before its role filter and before its interactivity check, so the resolver's walk and its own count the same universe. An index that stops resolving reports no match rather than falling back to a surviving namesake; an index is a POSITION and not an identity, so a row inserted above a list after the observe call shifts every held handle with no staleness signal, which the docs now say. dusk:find is unchanged: a predicate a caller chose keeps answering the first match and reporting the total. (lib/src/ref_registry.dart, lib/src/extensions/ext_observe.dart, lib/src/extensions/ext_find.dart)

0.0.14 - 2026-09-19 #

Added #

server.json, the manifest that lists this package on the official MCP registry. The ecosystem was absent from every MCP directory while three competing Flutter MCP servers were listed, so an agent looking for a Flutter E2E driver found them and not this one. The entry carries repository and websiteUrl and deliberately no packages block: registryType documents npm, pypi, oci, nuget and mcpb with no pub equivalent, and both packages and remotes are optional on ServerDetail, which requires only name, description and version. Nothing in the package reads the file and no workflow publishes it, so test/server_json_version_test.dart guards the version against pubspec.yaml, along with the schema's 100 character description cap. Excluded from the pub archive for the same reason codecov.yml is. (server.json, .pubignore, test/server_json_version_test.dart)

Changed #

The fluttersdk_artisan floor moves ^0.0.10 to ^0.0.16. dusk is a plugin on artisan, and 0.0.16 is where a plugin injection that matches nothing stops reporting Success over a file it never touched. The old range admitted 0.0.16 already, so nothing resolves differently on a fresh pub get; what changes is that a consumer reading the floor sees the release this package is verified against. The requirements tables in doc/getting-started/installation.md and doc/getting-started/index.md still said ^0.0.8, which a reader following them would have pinned alongside fluttersdk_dusk: ^0.0.14 two lines below and hit a resolution failure. (pubspec.yaml, doc/getting-started/installation.md, doc/getting-started/index.md, CLAUDE.md)

0.0.13 - 2026-08-25 #

Fixed #

dusk:perf_end printed a complete-looking report over a subset of the session's frames, so an empty attribution read as "nothing was slow". Two counters in the payload measure different things and nothing compared them: liveness.advanced comes from a post-frame callback and cannot miss a frame, while frameSummary.frame_count counts what Flutter's onReportTimings delivered, and Flutter batches those. Measured driving a real app on Chrome, a theme toggle drew 4 frames, 2 were reported, and the 2 block maps that joined were the pre-tap frames, which were empty. The report said "2 frames, worst build 114ms" with blockAttribution: [], which is exactly what a session with no hot blocks looks like; the frames carrying the work had simply never arrived. The payload now carries coverage: {framesDrawn, framesSummarized, complete} plus a detail string on the incomplete case, and the CLI prints a Partial: line beside the human summary rather than leaving the caveat in the JSON. It reports rather than refuses, because a subset is still a measurement. (lib/src/extensions/ext_perf.dart, lib/src/commands/dusk_perf_end_command.dart, doc/commands/dusk-perf-end.md, doc/mcp/tool-reference.md)
The refusal explained a frameless session with the wrong cause first. It led with a backgrounded page, which sent a reader hunting for a visibility problem that usually is not there. On Flutter web the ordinary cause is an idle app: nothing schedules a frame when nothing is dirty, so a session that opens, sleeps and closes legitimately draws zero. Both causes were observed in one investigation, the idle one twice (once at advanced: 0 on a settled page, once at advanced: 1 when a wheel gesture hit a region that does not scroll). The message now names the idle case first and keeps the hidden-page case, which is still why the threshold is 1 rather than 0. (lib/src/extensions/ext_perf.dart, doc/commands/dusk-perf-end.md)

0.0.12 - 2026-08-25 #

Added #

dusk:perf_begin / dusk:perf_end: frame attribution around a driven interaction. A dusk session could tell you a screen was slow and nothing about why. The pair brackets an interaction: perf_begin turns FlutterTimeline collection on (first, because startSync and finishSync both read that flag and enabling the build flags ahead of it pushes a finish with no matching start), then debugProfileBuildsEnabled + debugProfileBuildsEnabledUserWidgets, and on --phases also debugProfileLayoutsEnabled + debugProfilePaintsEnabled. The flags live in two different libraries, package:flutter/widgets.dart and package:flutter/rendering.dart. perf_end returns the frame summary under Flutter's own metric names, a session-wide block ranking naming the widget and RenderObject types that ran, wind's cache hit/miss/bypass counters and magic's controller-notify counts, then puts every flag back to the value it had BEFORE the session rather than to false, because a host that had build profiling on for its own reasons must get it back. A perf_begin on an already-open session restarts it, restoring before it re-saves, so a dropped connection cannot strand the profiling flags on. New: lib/src/extensions/ext_perf.dart, lib/src/commands/dusk_perf_begin_command.dart, lib/src/commands/dusk_perf_end_command.dart, plus the dusk_perf_begin / dusk_perf_end MCP descriptors. 36 CLI commands, 35 MCP tools, 32 ext.dusk.* extensions.
A session the engine did not render through is refused, not reported. Every number in a stalled session is a zero, and a table of zeros reads as "fast": that is the reading a live probe produced three times against a Chrome tab that was merely behind another window. perf_end compares a liveness counter across the session and answers refused: true with a reason and NO metrics block at all when it did not advance. The counter is the authority rather than the warnings block on the same response: SchedulerBinding.framesEnabled, which that block reads, was measured reporting true with lifecycle resumed on a page that was hidden and had produced one frame in two seconds. Both signals can ride on one payload, so refused is always present and is the only discriminator. dusk:perf_end exits non-zero on a refusal so a shell caller cannot chain on a report that does not exist.
Four settable perf pointers on the public barrel, and a frame summarizer behind them. dusk's frozen contract #10 limits it to four dependencies and telescope, wind and magic are none of them, so the data crosses through function pointers magic_devtools assigns: framePerfReader (frames plus the liveness counter), perfExtrasReader (magic's controller notifies and route transitions), perfSessionBeginHook (zero wind's counters AND turn its counting on; WindPerfCounters.enabled defaults to false and dusk cannot reach it, so a hook that only zeroed would have produced a wind section of all zeros next to fully populated frame and magic sections with no error anywhere) and perfSessionEndHook (turn it back off, the same discipline perf_end applies to the debugProfile* flags). All four default to no-ops, so dusk and magic_devtools build independently. summarizeFramePerf in lib/src/utils/frame_summary.dart (package-internal, deliberately not on the barrel) turns the frame list into average_frame_build_time_millis, the 90th/99th percentiles, the worst frame, the missed-budget counts and the rasterizer equivalents, using flutter_driver's metric-name strings character for character so a reading here is comparable to devicelab's. Two additions Flutter's own summarizer has no counterpart for: a dropped-frame count derived from GAPS in the frame-number sequence, because on web a dropped scene is a missing frame number rather than a slow frame, and the worst N frames with their block attribution attached. New: lib/src/utils/perf_readers.dart, lib/src/utils/frame_summary.dart; the four pointers are exported from lib/dusk.dart and listed under ARCHITECTURE.md's frozen contracts.
Per-type durations are labelled indicative in the payload itself. Flutter's docblocks on the three debugProfile* flags say the overhead of adding timeline events is significant relative to the time each object takes, and this session runs against a debug build, which widens the gap again. A number that travels without that caveat gets quoted as a production fact, so perf_end carries a note saying it: the counts, the ratios and the ranking are what direct a fix.

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.

fluttersdk_dusk 0.0.18 fluttersdk_dusk: ^0.0.18 copied to clipboard

Metadata

Changelog #

Unreleased #

0.0.18 - 2026-10-07 #

Fixed #

Added #

0.0.17 - 2026-09-29 #

Fixed #

Added #

Changed #

0.0.16 - 2026-09-23 #

Fixed #

0.0.15 - 2026-09-21 #

Fixed #

0.0.14 - 2026-09-19 #

Added #

Changed #

0.0.13 - 2026-08-25 #

Fixed #

0.0.12 - 2026-08-25 #

Added #

0.0.11 - 2026-08-20 #

Fixed #

Documentation #

0.0.10 - 2026-08-20 #

Added #

Removed #

Fixed #

Docs #

0.0.9 - 2026-07-29 #

Added #

Changed #

Fixed #

0.0.8 - 2026-06-17 #

Changed #

Fixed #

Documentation #

0.0.7 - 2026-06-17 #

Added #

Fixed #

Changed #

0.0.6 - 2026-06-09 #

Added #

Changed #

0.0.5 - 2026-05-28 #

Changed #

Fixed #

0.0.4 - 2026-05-27 #

Added #

Changed #

Fixed #

0.0.3 - 2026-05-26 #

Added #

Changed #

Docs #

0.0.2 - 2026-05-24 #

Added #

Docs #

0.0.1 - 2026-05-23 #

Added #

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

Fixed #

Test coverage #

Known gaps #

Risks Accepted #

Backward compat #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

Topics

License

Dependencies

More

fluttersdk_dusk 0.0.18
fluttersdk_dusk: ^0.0.18 copied to clipboard