From 9b8ed0b67e1244b5747733f221aa9b741c9ecaa8 Mon Sep 17 00:00:00 2001
From: richjun <junyoung.yoon@gmail.com>
Date: Sun, 10 May 2026 06:27:13 +0900
Subject: [PATCH 1/3] Web: findBySearch rejects non-tappable text containers
 (script/style/...)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rod's page.Search() uses CDP DOM.performSearch which matches against the
serialized HTML of every node — including the source text inside <script>
and <style> blocks. On a page whose JS source happens to contain a button
label as a literal string (e.g. "Close" in `await page.click('Close')`),
the cascade in findByText silently returned the <script> element itself
instead of falling through to the JS findByText path that walks shadow
roots and same-origin iframes.

The wrong-element pick had two visible failure modes:
  - Click coordinates resolve to the <script>'s zero-size box (or page
    origin), then the hit-target verifier reports occlusion by whatever
    real content sits there ("blocked by overlay (<flutter-view> …)" was
    the symptom on the createboard test). Non-deterministic depending on
    timing of which node the AX-tree cascade resolves first.
  - tapOn returned success silently when no hit-target check was active,
    landing the click on nonsense coordinates and reporting fake green.

Extends the existing IFRAME/FRAME rejection in findBySearch to also drop
SCRIPT, STYLE, TEMPLATE, NOSCRIPT, TITLE, META, LINK, HEAD — any tag
whose text content is source/inert and never represents a tappable user
affordance. The cascade then falls through to JS findByText which walks
_collectRoots() and returns the actual visible match.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 pkg/driver/browser/cdp/finder.go | 31 ++++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 11 deletions(-)

diff --git a/pkg/driver/browser/cdp/finder.go b/pkg/driver/browser/cdp/finder.go
index 76330d8..2cf1ceb 100644
--- a/pkg/driver/browser/cdp/finder.go
+++ b/pkg/driver/browser/cdp/finder.go
@@ -511,14 +511,19 @@ func (d *Driver) findByAXTree(text, role string, sel flow.Selector) (*rod.Elemen
 
 // findBySearch uses Rod's page.Search() which handles Shadow DOM via DOMPerformSearch.
 //
-// Reject IFRAME results: CDP DOM.performSearch matches against the iframe
-// element's serialized attributes, including srcdoc — for an iframe whose
-// srcdoc HTML happens to contain the search text, the iframe element itself
-// is returned. That is essentially never what the caller wants (the caller
-// is looking for a tappable text element, not the iframe wrapper). Falling
-// through here lets the cascade reach the JS findByText path, which walks
-// _collectRoots() into the iframe document and shadow DOM and returns the
-// actual visible match. (Issues #71/#72 acting layer.)
+// Reject non-tappable text containers: CDP DOM.performSearch matches against
+// the serialized HTML of every node, including the source text of <script>
+// and <style> blocks and the srcdoc attribute of <iframe>. For a page whose
+// JS source happens to contain "Close" (a button label coincidentally also
+// found in the source code), the <script> element itself is returned — it's
+// never visible, never tappable, and any subsequent click translates to
+// nonsense coordinates that the hit-target verifier then reports as occluded
+// by whatever real content sits at the page origin. Same shape for <style>,
+// <template>, and other inert text containers; same shape for <iframe> when
+// its srcdoc contains the search text. Falling through here lets the cascade
+// reach the JS findByText path, which walks _collectRoots() into the iframe
+// document and shadow DOM and returns the actual visible match. (Issues
+// #71/#72 acting layer.)
 func (d *Driver) findBySearch(text string, sel flow.Selector) (*rod.Element, *core.ElementInfo, error) {
 	p := d.page.Timeout(2 * time.Second)
 	res, err := p.Search(text)
@@ -532,9 +537,13 @@ func (d *Driver) findBySearch(text string, sel flow.Selector) (*rod.Element, *co
 	}
 
 	elem := res.First
-	if tag, _ := elem.Eval(`() => this.tagName`); tag != nil &&
-		(tag.Value.Str() == "IFRAME" || tag.Value.Str() == "FRAME") {
-		return nil, nil, fmt.Errorf("search returned iframe element (likely srcdoc text match) — falling through to JS findByText")
+	if tag, _ := elem.Eval(`() => this.tagName`); tag != nil {
+		switch tag.Value.Str() {
+		case "IFRAME", "FRAME":
+			return nil, nil, fmt.Errorf("search returned iframe element (likely srcdoc text match) — falling through to JS findByText")
+		case "SCRIPT", "STYLE", "TEMPLATE", "NOSCRIPT", "TITLE", "META", "LINK", "HEAD":
+			return nil, nil, fmt.Errorf("search returned non-tappable %s element (text matched in source/inert content) — falling through to JS findByText", strings.ToLower(tag.Value.Str()))
+		}
 	}
 	if !d.matchesStateFilters(elem, sel) {
 		return nil, nil, fmt.Errorf("search found element but state filters don't match")

From da3268282be542efbe9cdf69c30f3229f554b44f Mon Sep 17 00:00:00 2001
From: richjun <junyoung.yoon@gmail.com>
Date: Sun, 10 May 2026 06:27:35 +0900
Subject: [PATCH 2/3] Web: hit-target verifier accepts Flutter Web glass-pane
 occlusion
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Playwright-port hit-target check in expectHitTarget walks roots from
the target element outward and asserts that elementsFromPoint at the
click coordinate returns an ancestor of the target. That assumption
holds for normal HTML and for shadow-DOM widgets, but it is structurally
wrong for Flutter Web semantics:

  - <flutter-view> (Flutter 3.x) acts as a glass pane that intercepts
    every pointer event and routes it to the appropriate <flt-semantics>
    via Flutter's own internal hit testing.
  - The accessibility tree may live in light DOM under flutter-view, in
    its shadow root, or as a sibling <flt-semantics-host> with the
    rendering canvas (flt-scene-host) stacked above. In all of these
    layouts elementsFromPoint at a semantics target returns flutter-view
    (or its canvas), never the semantics node.

So a strict same-element walk-up always reports false occlusion and
refuses to dispatch — observable as intermittent
"Click on text=\"Close\" blocked by overlay (<flutter-view> …)" failures
on real Flutter Web pages whenever timing made the canvas the topmost
hit (vs occasionally finding the semantics directly).

Adds a concession at the end of expectHitTarget: when both target and
the topmost hit element live inside the same Flutter app's iframe (any
ancestor with `flutter-view` or an `flt-*` tag, walked across shadow
boundaries), accept the dispatch. Flutter routes the trusted click to
the right semantics action. Non-Flutter occlusion (overlay div, modal,
genuine z-stack) continues to reject as before — the Occluded /
Transformed regression tests still fail-fast.

The 5 existing TestTapOnCrossRoot_* iframe tests continue to pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 pkg/driver/browser/cdp/jshelper.js | 38 +++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/pkg/driver/browser/cdp/jshelper.js b/pkg/driver/browser/cdp/jshelper.js
index 7cfac31..5be3767 100644
--- a/pkg/driver/browser/cdp/jshelper.js
+++ b/pkg/driver/browser/cdp/jshelper.js
@@ -488,6 +488,25 @@ window.__maestro = {
     return null;
   },
 
+  // _isInFlutterContext: walks up (piercing shadow boundaries) and returns
+  // true if the node lives inside a Flutter Web app — i.e. has any ancestor
+  // with a Flutter-namespaced tag (`flutter-view` or `flt-*`). Real Flutter
+  // Web DOMs vary by embedder/version: in some <flutter-view> wraps both the
+  // canvas and <flt-semantics-host>; in others <flt-semantics-host> is a
+  // SIBLING of <flutter-view> (semantics tree rendered separately for screen
+  // readers). Either layout is "inside Flutter" for hit-target purposes —
+  // Flutter's pointer router intercepts events through its glass pane and
+  // dispatches to semantics via its own internal hit testing.
+  _isInFlutterContext: function(node) {
+    var n = node;
+    while (n) {
+      var tag = n.tagName ? n.tagName.toLowerCase() : '';
+      if (tag === 'flutter-view' || tag.indexOf('flt-') === 0) return true;
+      n = this._parentElementOrShadowHost(n);
+    }
+    return false;
+  },
+
   // _isInIframe: cheap check used by Go to decide whether to use the new
   // coord-translated dispatch path. True iff the element's owner document has
   // a non-null frameElement (i.e. it lives inside an iframe at any depth).
@@ -624,7 +643,24 @@ window.__maestro = {
       hitElement = hitElement.assignedSlot || this._parentElementOrShadowHost(hitElement);
     }
     if (hitElement === targetElement) return 'done';
-    var description = this._previewNode(hitParents[0] || document.documentElement);
+    // Flutter Web concession: <flutter-view> (and the legacy <flt-glass-pane>)
+    // acts as a glass pane that intercepts every pointer event and routes it
+    // to the appropriate <flt-semantics> action via Flutter's internal hit
+    // testing. The accessibility tree may live in light DOM under flutter-
+    // view, in its shadow root, or as a sibling <flt-semantics-host> with the
+    // rendering canvas stacked above — either way DOM elementsFromPoint at a
+    // semantics target returns the canvas / glass pane, never the semantics
+    // node. A strict same-element walk-up would therefore always report false
+    // occlusion and refuse to dispatch. Accept when both target and the hit
+    // element are inside the same Flutter app's iframe — Flutter will route
+    // the trusted click to the right semantics action.
+    var topHit = hitParents[0];
+    if (topHit && this._isInFlutterContext(targetElement) &&
+        this._isInFlutterContext(topHit) &&
+        targetElement.ownerDocument === topHit.ownerDocument) {
+      return 'done';
+    }
+    var description = this._previewNode(topHit || document.documentElement);
     return { hitTargetDescription: description };
   },
 

From 0a3f4c3dd1917df1759ce73e30b706ae818900be Mon Sep 17 00:00:00 2001
From: richjun <junyoung.yoon@gmail.com>
Date: Sun, 10 May 2026 07:16:44 +0900
Subject: [PATCH 3/3] Web: hit-target post-click verifier accepts Flutter Web
 glass-pane consumption
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Companion to 1be423d (pre-flight Flutter concession). The pre-flight
expectHitTarget walk was made permissive for Flutter Web semantics —
<flutter-view> / <flt-glass-pane> sit on top of <flt-semantics> at the
DOM layer and elementsFromPoint always returns the canvas, so a strict
walk-up was a false-occlusion source. That fix lets dispatch proceed.

The post-click verifier was still strict, and that asymmetry is the
bug. setupHitTargetInterceptor installs a one-shot
addEventListener('pointerdown'|'mousedown', listener, true) on the
target frame's window and pollHitTargetResult retries 5 × 20ms for the
trusted event to fire so it can re-run expectHitTarget against the
actual fire-time clientX/Y. For Flutter targets this listener never
fires: Flutter's pointer router intercepts trusted pointer events at
the document/flutter-view capture layer, routes them into its own
internal hit testing for semantics dispatch, and does not re-emit them
at the window level for third-party listeners. So every cross-iframe
tap on a Flutter semantics node — Welcome dialog Close, More Tools
menu items, color picker swatches — failed with
"Click on text=\"Close\" dispatched but verification timed out", even
though Chromium delivered the trusted click to the right coordinates
and Flutter handled it.

Mirror the pre-flight Flutter concession in the verifier:
  - jshelper.js: setupHitTargetInterceptor records inFlutter on the
    state object. pollHitTargetResult is also unified to always return
    a single object shape (was bare 'pending' / 'done' strings mixed
    with { hitTargetDescription } objects — four shapes the Go side had
    to branch on). Now exactly three: { status: 'done' },
    { status: 'pending', inFlutter }, { status: 'failed',
    hitTargetDescription }.
  - commands.go: the post-click Flutter concession lives in the shared
    dispatchCrossRoot helper (introduced in 9f17508). When poll budget
    exhausts and inFlutter is true, accept the dispatch — pre-flight
    already validated the static hit point and Flutter's own hit
    testing handled the trusted click. Living in dispatchCrossRoot
    means doubleTapOn / longPressOn / scrollUntilVisible inherit the
    concession for free, since they share this path.
    Non-Flutter timeouts continue to fail-fast as before, so the
    "click never landed" detection on real DOM stays intact.

Verified end-to-end on createboard.lgbusinesscloud.com Board Editor:
flow now passes through Welcome dialog dismiss → Pen panel → Red color
→ Close panel → More Tools → Help → Gesture page → Select Object.
Pre-fix: failed at the first Flutter semantics tap with verifier
timeout.

The five existing TestTapOnCrossRoot_* tests (TopFrame / Iframe /
IframeShadow / Occluded / Transformed) continue to pass — the Flutter
concession does not relax non-Flutter occlusion rejection.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 pkg/driver/browser/cdp/commands.go | 46 +++++++++++++++++++++++-------
 pkg/driver/browser/cdp/jshelper.js | 32 +++++++++++++++------
 2 files changed, 59 insertions(+), 19 deletions(-)

diff --git a/pkg/driver/browser/cdp/commands.go b/pkg/driver/browser/cdp/commands.go
index 1fb9d6c..7bbad27 100644
--- a/pkg/driver/browser/cdp/commands.go
+++ b/pkg/driver/browser/cdp/commands.go
@@ -155,29 +155,55 @@ func (d *Driver) dispatchCrossRoot(elem *rod.Element, info *core.ElementInfo, de
 		return errorResult(err, fmt.Sprintf("Failed to dispatch input for %s", desc))
 	}
 
-	// Step 4: poll hit-target verify.
+	// Step 4: poll for verify result. Chromium delivers trusted events
+	// synchronously during Mouse.Click, so the first poll is usually
+	// decisive. Brief retry window absorbs scheduler jitter on slower
+	// machines / CI.
+	//
+	// pollHitTargetResult always returns an object with a `status` field:
+	//   { status: 'done' }
+	//   { status: 'pending', inFlutter: bool }
+	//   { status: 'failed', hitTargetDescription: string }
+	inFlutter := false
 	for i := 0; i < 5; i++ {
 		pollRes, pollErr := d.page.Eval(`(t) => window.__maestro.pollHitTargetResult(t)`, token)
 		if pollErr != nil {
 			return errorResult(pollErr, fmt.Sprintf("Failed to poll hit-target result for %s", desc))
 		}
 		v := pollRes.Value
-		if v.Has("hitTargetDescription") {
-			hd := v.Get("hitTargetDescription").Str()
-			return errorResult(
-				fmt.Errorf("input did not reach %s — landed on %s", desc, hd),
-				fmt.Sprintf("Input on %s did not reach the target (landed on %s)", desc, hd))
-		}
-		switch v.Str() {
+		switch v.Get("status").Str() {
 		case "pending":
+			if v.Get("inFlutter").Bool() {
+				inFlutter = true
+			}
 			time.Sleep(20 * time.Millisecond)
 			continue
 		case "done":
 			return successResult(fmt.Sprintf("%s on %s", verbed, desc), info)
-		default:
-			return successResult(fmt.Sprintf("%s on %s", verbed, desc), info)
+		case "failed":
+			hd := v.Get("hitTargetDescription").Str()
+			return errorResult(
+				fmt.Errorf("input did not reach %s — landed on %s", desc, hd),
+				fmt.Sprintf("Input on %s did not reach the target (landed on %s)", desc, hd))
 		}
 	}
+	// Flutter Web concession (post-click): the trusted event verifier never
+	// captured a pointerdown/mousedown on the target frame's window. For
+	// Flutter targets this is the expected steady state — Flutter's pointer
+	// router sits at the document/flutter-view capture layer and routes the
+	// trusted event to its own internal hit testing for semantics dispatch;
+	// it generally does not bubble back out as a window-level
+	// pointerdown/mousedown that a third-party listener can observe. Pre-
+	// flight expectHitTarget already validated the static hit point and
+	// applied the same Flutter concession (jshelper.js:expectHitTarget). So
+	// when we got past pre-flight and the target lives in Flutter, accept
+	// the dispatch — Chromium delivered a trusted click at the target's
+	// coordinates and Flutter handled it. Living in dispatchCrossRoot means
+	// doubleTapOn / longPressOn / scrollUntilVisible inherit the concession
+	// for free, since they share this dispatch path.
+	if inFlutter {
+		return successResult(fmt.Sprintf("%s on %s", verbed, desc), info)
+	}
 	return errorResult(
 		fmt.Errorf("hit-target verify did not capture trusted event within timeout"),
 		fmt.Sprintf("Input on %s dispatched but verification timed out", desc))
diff --git a/pkg/driver/browser/cdp/jshelper.js b/pkg/driver/browser/cdp/jshelper.js
index 5be3767..ddacfdc 100644
--- a/pkg/driver/browser/cdp/jshelper.js
+++ b/pkg/driver/browser/cdp/jshelper.js
@@ -730,7 +730,11 @@ window.__maestro = {
     var token = this._hitTargetNextToken++;
     var win = targetElement.ownerDocument && targetElement.ownerDocument.defaultView;
     if (!win) return { error: '<target window unavailable>' };
-    var state = { captured: false, result: undefined, target: targetElement, win: win };
+    var inFlutter = this._isInFlutterContext(targetElement);
+    var state = {
+      captured: false, result: undefined, target: targetElement, win: win,
+      inFlutter: inFlutter
+    };
     this._hitTargetState[token] = state;
 
     var listener = function(ev) {
@@ -758,17 +762,21 @@ window.__maestro = {
     return { token: token };
   },
 
-  // pollHitTargetResult: returns the captured verify outcome for a token, or
-  // 'pending' if the listener hasn't fired yet. Caller should poll a few
-  // times after dispatch (a real trusted pointerdown is delivered
-  // synchronously to JS during Mouse.Click, so 'pending' should be rare —
-  // but a brief retry window absorbs scheduler jitter).
+  // pollHitTargetResult: returns the captured verify outcome for a token.
+  // Caller should poll a few times after dispatch (a real trusted pointerdown
+  // is delivered synchronously to JS during Mouse.Click, so 'pending' should
+  // be rare — but a brief retry window absorbs scheduler jitter).
+  //
+  // Always returns an object with a `status` field:
+  //   { status: 'done' }                                 → success
+  //   { status: 'pending', inFlutter: bool }             → trusted event not seen yet
+  //   { status: 'failed', hitTargetDescription: string } → landed on the wrong element
   //
   // After returning a non-'pending' result, the token is cleaned up.
   pollHitTargetResult: function(token) {
     var state = this._hitTargetState[token];
-    if (!state) return 'done'; // unknown token → don't block caller
-    if (!state.captured) return 'pending';
+    if (!state) return { status: 'done' }; // unknown token → don't block caller
+    if (!state.captured) return { status: 'pending', inFlutter: !!state.inFlutter };
     var r = state.result;
     // Cleanup listener if still attached (defensive — listener removes itself
     // on capture, but if the click never fired we want to stop leaking).
@@ -777,7 +785,13 @@ window.__maestro = {
       state.win.removeEventListener('mousedown', state.listener, true);
     } catch (e) {}
     delete this._hitTargetState[token];
-    return r;
+    // Normalize the listener-stashed expectHitTarget result into the unified
+    // shape. expectHitTarget returns 'done' or { hitTargetDescription }.
+    if (r === 'done') return { status: 'done' };
+    if (r && typeof r === 'object' && 'hitTargetDescription' in r) {
+      return { status: 'failed', hitTargetDescription: r.hitTargetDescription };
+    }
+    return { status: 'done' }; // defensive fallback
   },
 
   // disposeHitTargetInterceptor: called by Go to abandon a token without