You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This commit was created on GitHub.com and signed with GitHub’s verified signature.
Added
Dusk wakes a hidden or minimised app instead of driving a frozen one. A hidden, minimised or occluded desktop window moves the lifecycle to hidden and turns frame production off, so a tap reported "no observable change", a snapshot went stale and a screenshot returned the last cached frame. Every ext.dusk.* verb now delivers AppLifecycleState.inactive and then, once a frame has run, resumed through the flutter/lifecycle channel, and schedules a forced frame when frames are off and the lifecycle is hidden or paused (never detached); a response that forced carries framesForced: true. It is re-applied on every call because the OS flips the lifecycle back to hidden on its next occlusion event. The wake counts only when a frame actually runs after it (otherwise the previous lifecycle is delivered again, unless the engine sent one of its own meanwhile), and it is never attempted in the app on web, where Chrome withholds animation frames from a hidden tab; the CLI sends Page.bringToFront there instead (see the web recovery entry below). Verified on macOS with the window hidden through osascript (dusk:tap, dusk:snap, dusk:screenshot and dusk:navigate all work) and on web with a second tab in front (warnings returned, nothing claimed as forced). The perf verbs, boot_id, close_app, console, exceptions, semantics_hold and evaluate observe the engine as it is and do not force. The app's lifecycle observers see resumed while this happens; --dart-define=DUSK_FORCE_FRAMES=false (kDuskForceFrames) turns it off. (lib/src/utils/frame_sync.dart, lib/src/utils/dusk_register.dart, lib/src/utils/dusk_response.dart, lib/src/extensions/, doc/reference/frame-production.md)
dusk:snap and dusk:observe say when a control is off screen or covered. A ref line may end with [offscreen] (the widget lies outside the viewport) and/or [occluded] (a hit test at its centre reaches something painted above it), after [ref=eN]; a healthy screen prints neither. Each ext.dusk.observe candidate gains inViewport and occluded; isVisible is unchanged. (lib/src/utils/viewport_visibility.dart, lib/src/extensions/ext_snapshot.dart, lib/src/extensions/ext_observe.dart)
dusk:snap --grep reads an invalid regex as text. A label such as Container Sample (MP4, H.264 is an unterminated group and used to crash the snapshot; it now matches as a literal substring and the payload carries grepLiteral: true. A valid regex keeps its regex meaning. (lib/src/extensions/ext_snapshot.dart)
An e<N> ref survives a rebuild. Snapshots bind a label-and-index query and the match count to every labelled ref (RefBinding, with RefRegistry.bind, lookupBinding and rebind, additive statics). When the element behind a ref has left the tree, the action relocates it only if the live tree has the same number of matches as at snapshot time, and the response lists the ref under reresolved. With a different count the old defunct (element no longer mounted) error is unchanged. A ref is also pinned to the route it was minted on (RefBinding.route, held weakly): a same-label control on another route is never a match, so a ref taken on a page you have since left fails as defunct instead of acting on the next page. Known limit: the query has no role, so a node of another role with the same label in the same position on the same route could match. (lib/src/ref_registry.dart, lib/src/extensions/ext_pointer.dart, lib/src/extensions/ext_snapshot.dart)
dusk:screenshot infers the format from --output..png, .jpg and .jpeg pick the format when --format is not given, so a .png file no longer holds JPEG bytes. An explicit --format wins and a mismatch with the extension warns on stderr. (lib/src/commands/dusk_screenshot_command.dart)
dusk:run / dusk_run: several verbs in one call.dusk:run "tap --ref=e5" "fill --ref=q1 --text=\"a b\"" "snap" takes each step as a shell-tokenised verb line (a bare verb gets the dusk: prefix), parses it with that verb's own options and runs it on one shared VM connection. The output is one line per step ([1/3] tap --ref=e8 ok: Tapped e8, the first output line cut to 120 characters), then the last step's output. It stops at the first failing step with step N failed (exit C): <step> and that exit code; --continue runs every step and exits with the first non-zero code. A nested dusk:run, an unknown verb and a verb that does not boot connected (dusk:resize, dusk:device, dusk:install, dusk:doctor, dusk:perf_campaign, dusk:perf_compare) fail as their step, as does any step that throws (it exits 3); a step that ends the app (dusk:close_app, dusk:perf_run) belongs last. The MCP tool takes {steps: string[], continue?: boolean} and routes as artisan:dusk:run, the seventh substrate-routed tool. Between steps use --text, --key or q-refs, since e-refs belong to one snapshot. 42 commands and 40 tools now. (lib/src/commands/dusk_run_command.dart, lib/src/dusk_artisan_provider.dart, doc/commands/dusk-run.md)
--snapshot=full|diff|none on dusk:tap, fill, type, navigate and scroll, and a snapshot enum on dusk_tap, dusk_fill and dusk_navigate. It overrides includeSnapshot. diff returns only the lines that changed against the last unfiltered snapshot (a dusk:snap or an earlier action) in unified-diff form: a changed row is - <old line> then + <new line>, an added row + , a removed row - , then a (K of N lines changed) footer, and the payload adds snapshotMode: "diff". The mode is read case-insensitively, and an unknown one comes back as snapshotError in the payload rather than as a silently missing snapshot. With no baseline yet the full text comes back. A hot restart clears the baseline, and a filtered snap (grep, within, depth, interactiveOnly) or an enricher walk never records it. (lib/src/utils/snapshot_diff.dart, lib/src/extensions/ext_snapshot.dart, the action verbs and commands)
dusk:snap --json prints the whole envelope. The tree alone dropped grepLiteral, warnings and framesForced; text mode is unchanged. (lib/src/commands/dusk_snap_command.dart)
dusk:press_key --modifiers is applied.control (or ctrl), shift, alt and meta, in any case, as a comma list on the CLI and an array over MCP, are held down before the key and released after it, even when delivery throws, so exact-match shortcuts such as Ctrl+S and Shift+Tab fire. An unknown name is an error before anything is pressed. (lib/src/extensions/ext_text_input.dart, lib/src/utils/key_press.dart, lib/src/commands/dusk_press_key_command.dart)
A tap on a merge boundary goes to the control the ref names (#60). A MergeSemantics boundary taps at its own centre, which can belong to another handler (a full-frame stage that pauses on any tap) while the gate still says confirmed. When exactly one labelled control owns the merged label (a Semantics with a label that is part of it and an onTap or button) and a hit test at its centre reaches it, dusk:tap sends the pointer there and the payload adds retargeted {from, to, ownerRect} (with centreHandled: true when the centre has a tap handler of its own, so the stage or row it would have tapped is named); the summary reads Tapped e7 on its control at (x, y), not the merged centre (x, y). With several candidates, or an owner that is covered or off screen, the tap stays at the centre and the payload adds tapPointOutsideOwner {ownerRect, point} with one stderr line. retarget: false (CLI --no-retarget) taps the centre as before. Snapshot and observe say so before any tap: a tapOwner: {"x","y","w","h"} sub-line under the ref and a tapOwner candidate field, both present only when the centre misses the control, with centreHandled: true added when the centre has its own handler and retargets: false when a tap cannot go to the control. The gate and its reasons are unchanged; hover, dblclick, right_click, triple_click and drag still use the centre. (lib/src/utils/tap_owner.dart, lib/src/extensions/ext_pointer.dart, lib/src/extensions/ext_snapshot.dart, lib/src/extensions/ext_observe.dart, lib/src/commands/dusk_tap_command.dart)
effect.target says which field a text verb wrote.dusk:fill, dusk:type and dusk:clear add target {matchKind: overlap|nearest|element, label, rect} to the text effect, and the CLI prints a warning when the match was nearest. (lib/src/utils/effect_report.dart, lib/src/extensions/ext_text_input.dart, lib/src/commands/dusk_fill_command.dart, lib/src/commands/dusk_type_command.dart)
The CLI recovers a hidden web tab.snap, observe, tap, fill, type, navigate, scroll and press_key call the extension through callExtensionVisible. When the answer carries a web warnings block, or the call times out (the VM Service gives up on a hidden tab that never answers) and the tab reports hidden, and the session has a cdpPort, the CLI sends CDP Page.bringToFront once (it raises the Chrome window). Read-only verbs (snap, observe) are then called again once; a verb that acts is not repeated, since its gesture may already have fired, and a stderr notice says to run dusk:snap. A CDP failure leaves the original result and exit code; without a cdpPort nothing changes. (lib/src/cdp/page_visibility.dart, lib/src/commands/web_visibility.dart)
Changed
Every MCP tool schema is closed, and lists the knobs its handler reads. artisan validates each tools/call against the schema, so a key the schema did not list was either let through to a handler that ignored it (a typo answered with a clean response) or, when the schema was incomplete, impossible to pass. All 40 schemas now declare additionalProperties: false, and the keys the handlers read but the schemas omitted are listed: snapshot, includeSnapshot, checkStable and checkReceivesEvents on the pointer, text and navigation verbs that embed a snapshot or run the gate (dusk_tap, hover, drag, type, dblclick, fill, scroll, navigate, navigate_back, press_key, right_click, triple_click), includeEnrichers on dusk_snap and contains on dusk_find. The coordinate keys (x, y, toX, toY, drag dx / dy), reportPoint, perf_end's full, screenshot's geometry and dusk:resize --hold stay out on purpose: the perf runner and the CLI call the extensions and commands directly (and an MCP call cannot hold a CDP session), so over MCP they are now refused instead of accepted. dusk_snap takes includeEnrichers as a boolean while dusk_observe takes "true", "false" or "full". (lib/src/dusk_artisan_provider.dart)
dusk_resize_viewport takes dpr, not deviceScaleFactor. The command reads dpr; the schema advertised deviceScaleFactor, which passed validation and was then ignored, so an MCP resize that followed the schema ran at pixel ratio 1.0. A caller still sending deviceScaleFactor now gets Additional property "deviceScaleFactor" is not allowed instead of a silent 1.0. (lib/src/dusk_artisan_provider.dart, doc/mcp/tool-reference.md)
dusk_scroll no longer requires ref. The handler scrolls the first Scrollable it finds when none is given; the schema made every call name one. (lib/src/dusk_artisan_provider.dart)
The summary lines say what happened, not only that something was dispatched. In summary mode (--no-includeSnapshot, the default; --json is unchanged): dusk:fill and dusk:type print an error naming the value the field holds and exit 1 when effect.verified is false; dusk:navigate prints "Navigation to not confirmed: " when navigated is false (a Navigator 1.0 app without a Router cannot be URL-verified, so check with dusk:snap); dusk:navigate_back prints "Nothing to pop" when popped is false; dusk:scroll prints "nothing moved" when effect.changed is false; dusk:hot_reload_and_snap now exits 1 when reloaded is false (the JSON is still on stdout), where it exited 0. A script that treated those exits as success has to read the new code. (lib/src/commands/)
The frame-production warning names the real cause per platform. The warnings block gains platform and a platform-aware hint, and the CLI stderr banner says a backgrounded tab and Page.bringToFront on web, and a hidden, minimised or occluded window or an asleep display on desktop. It now appears only when dusk could not force frames (opt-out, a detached lifecycle, or a wake that produced no frame, or web). (lib/src/utils/frame_sync.dart, lib/src/commands/frame_warning_output.dart)
ext.dusk.scroll reports scrolled honestly.scrolled is true only when the scroll offset moved; it was always true. With no scrollable around the ref, effect.changed is false. (lib/src/extensions/ext_scroll.dart)
fill, type and clear refuse a ref that is not a text field. A ref whose node is an interactive non-text control (button, checkbox or radio, switch, slider, link) used to overlap no editable, so the nearest field on screen was cleared and written and the read-back of that field verified the write. It is now refused with ref eN is a <role>, not a text field. A label or static-text handle keeps the nearest-field fallback, which is what it is for, and fill resolves the field once for focus, clear and type. A script that filled through a non-text ref has to target the field. (lib/src/extensions/ext_text_input.dart, lib/src/extensions/ext_fill.dart)
effect.verified is read after the settle. The text verbs compare the value read after the two-frame settle, so a formatter or echo that reverts the write a frame later reports verified: false where it used to report true. (lib/src/extensions/ext_text_input.dart, lib/src/extensions/ext_fill.dart)
The gate, the snapshot and observe share one hit probe.probeHitAt in viewport_visibility.dart answers reached, platformOnly, ancestorOnly or covered for all three, and isHitOccluded is gone. The gate's check order and reason substrings, and the snapshot and observe output, are unchanged. (lib/src/utils/viewport_visibility.dart, lib/src/utils/actionability_gate.dart, lib/src/extensions/ext_snapshot.dart, lib/src/extensions/ext_observe.dart)
ext.dusk.navigate_back reports navigatedBack as popped.navigatedBack was always true; it now equals popped, so it is false at the root route. (lib/src/extensions/ext_navigation.dart)
The frame wake delivers inactive, waits for a frame, then resumed. Flutter drops a lifecycle message equal to the current state, so the order is what lets the wake notice an engine resumed that arrives meanwhile. (lib/src/utils/frame_sync.dart)
Fixed
dusk_resize_viewport with only reset is callable. The schema required width and height, so artisan refused the description's own example, {"reset": true}, before the command ran. Neither is required now; dusk:resize refuses a resize that names no positive --width and --height (parsed as 0 they would have reached Chrome as a 0x0 override), and its help text no longer calls them mandatory. The reference documented a { viewport: {...} } result; the command answers with a text line, and the page now says so. (lib/src/commands/dusk_resize_command.dart, lib/src/dusk_artisan_provider.dart, doc/mcp/tool-reference.md)
dusk_scroll honours direction and pixels. The MCP schema and its example ({ "ref": "e12", "direction": "down", "pixels": 500 }) advertised the pair, but ext.dusk.scroll read only dx and dy, so an agent that followed the schema got a scroll of nothing with a clean response. The extension now reads direction (default down) and pixels (default 300, a distance, so the direction alone gives the sign) when neither dx nor dy is given, and the schema lists dx, dy and intoView too. A value that cannot be a delta (not a number, NaN, infinite, or an unknown direction) is refused with invalidParams instead of defaulting; a non-finite delta used to jump the list to its end. dusk:scroll passes all four on instead of translating them itself, so the CLI and MCP read them the same way. (lib/src/extensions/ext_scroll.dart, lib/src/commands/dusk_scroll_command.dart, lib/src/dusk_artisan_provider.dart)
The MCP descriptors say what the handlers do.dusk_right_click and dusk_triple_click said includeSnapshot defaults to false while the handlers embed a snapshot unless told not to; dusk_wait_for said it polls every 100 ms (it is 200 ms), that expression is evaluated as Dart (it is matched as text, like text), that a timeout returns an error (it returns {matched: false, reason: "timeout"}), that several keys are refused (the first of text, textGone, expression wins), and that text matches a semantics label (it matches Text data), and its doc page named the success key waitedMs (it is elapsedMs); dusk_dblclick, dusk_right_click and dusk_triple_click named a 4-gate or 5-gate check where the gate has six steps. Descriptor and doc text only; no behaviour change. (lib/src/dusk_artisan_provider.dart, doc/mcp/tool-reference.md)
A stale e<N> after a rebuild no longer forces a re-snap. See the re-resolution entry under Added; the ref used to fail as defunct (element no longer mounted) after any rebuild of its widget. (lib/src/extensions/ext_pointer.dart)
A hidden macOS app no longer succeeds silently. The frame forcing above is the fix: a tap, a snapshot and a screenshot against a hidden window read as stale or as "no observable change". (lib/src/utils/dusk_register.dart)
Pointer, modal and checkbox verbs use the element's own view. They dispatched into implicitView!, which fails with a null-check error when no implicit view exists and ignores the view an element lives in. resolveViewFor takes the element's FlutterView, then the implicit view, then the first attached view, and the gate measures its viewport against the same one. (lib/src/utils/actionability_gate.dart, lib/src/extensions/ext_pointer.dart, lib/src/extensions/ext_modal_router.dart, lib/src/extensions/ext_checkbox.dart)
dusk:snap --grep no longer crashes on parentheses. See the grepLiteral entry under Added. (lib/src/extensions/ext_snapshot.dart)
ext.dusk.scroll no longer reports a change when nothing scrolled. With no scrollable, the effect compared a missing offset against a made-up 0.0, and a delta past the end of a list reported an offset beyond the extent because jumpTo does not clamp; the target is now clamped to the scroll extents. A list kept alive offstage (a covered overlay entry) has pixels but no extents until it is laid out, so a call with no ref could pick it and fail with a null check; the scrollable selection now skips a list that has not been laid out. (lib/src/extensions/ext_scroll.dart)
The wake no longer overwrites an engine resumed. When the wake produced no frame it put the old lifecycle back unconditionally, which could undo a real resumed the engine had just sent inside the 200 ms window. The put-back is skipped when the engine spoke meanwhile. (lib/src/utils/frame_sync.dart)
ext.dusk.navigate_back no longer says navigatedBack: true at the root. See the Changed entry; the flag now matches popped. (lib/src/extensions/ext_navigation.dart)
The dusk:perf_campaign preparation tests are no longer flaky. Their temporary directory had no pubspec.yaml, so an ancestor's pubspec became the project root. Test-only; no library change. (test/src/commands/dusk_perf_campaign_command_test.dart)
dusk:hot_reload_and_snap finds the session log. It polled the legacy ~/.artisan/flutter-dev.log while start writes ~/.artisan/sessions/<id>/flutter-dev.log, so a reload that worked read as "did not signal completion in time" (and, since reloaded: false now exits 1, as a failure). It reads the log beside the state file it used. (lib/src/commands/dusk_hot_reload_and_snap_command.dart)