@buoy-gg/highlight-updates 7.0.38 → 7.0.39

package/lib/commonjs/highlight-updates/utils/screenElements.js

@@ -1 +1,1248 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.describeScreen=describeScreen,exports.resolveTouchTarget=resolveTouchTarget,exports.tapElement=tapElement,exports.waitFor=waitFor;var _reactNative=require("react-native"),_tapMatch=require("./tapMatch");const HostComponent=5,OffscreenComponent=22,INTERNAL_NAMES=new Set(["View","RCTView","ScrollView","RCTScrollView","RCTScrollContentView","SafeAreaView","RCTSafeAreaView","AndroidHorizontalScrollContentView","KeyboardAvoidingView","Pressable","PlatformPressable","TouchableOpacity","TouchableHighlight","TouchableWithoutFeedback","TouchableNativeFeedback","AnimatedComponent","Wrapper"]);function getReactDevToolsHook(){return"undefined"==typeof global?null:global.__REACT_DEVTOOLS_GLOBAL_HOOK__??null}let commitCount=0,commitCounterInstalled=!1;function ensureCommitCounter(){if(commitCounterInstalled)return;const e=getReactDevToolsHook();if(!e)return;const t=e.onCommitFiberRoot;e.onCommitFiberRoot=function(...n){return commitCount++,"function"==typeof t?t.apply(e,n):void 0},commitCounterInstalled=!0}const TAP_SETTLE_MS=250;function makeChromeCheck(){const e=new Map;return t=>{const n=[];let o=t,r=0,a=!1;for(;o&&r<400;){const t=e.get(o);if(void 0!==t){a=t;break}if(getProps(o)?.__buoyDevToolsRoot){a=!0,e.set(o,!0);break}n.push(o),o=o.return,r++}for(const t of n)e.set(t,a);return a}}function getAllFiberRoots(){const e=getReactDevToolsHook();if(!e)return[];const t=[];try{if(e.renderers&&"function"==typeof e.renderers.forEach&&e.renderers.forEach((n,o)=>{try{const n=e.getFiberRoots?.(o);n&&n.forEach(e=>t.push(e))}catch{}}),0===t.length&&e.getFiberRoots){const n=e.getFiberRoots(1);n&&n.forEach(e=>t.push(e))}}catch{}return t}function isHiddenOffscreen(e){return 22===e.tag&&null!==e.memoizedState}function isInactiveScreen(e){const t=e.memoizedProps?.activityState;return 0===t||1===t||!1===e.memoizedProps?.isPageFocused}function traverseFiberTree(e,t,n=0,o=new Set){!e||o.has(e)||n>500||(o.add(e),isHiddenOffscreen(e)||isInactiveScreen(e)||(t(e),e.child&&traverseFiberTree(e.child,t,n+1,o)),e.sibling&&traverseFiberTree(e.sibling,t,n,o))}function getPublicInstance(e){if(!e)return null;const t=e;return t.canonical?.publicInstance?t.canonical.publicInstance:t.canonical&&"function"==typeof t.canonical.measure?t.canonical:"function"==typeof t.measure||"function"==typeof t.measureInWindow?t:null}function getNativeTag(e){if(null==e)return null;const t=e;if("number"==typeof t.__nativeTag)return t.__nativeTag;if("number"==typeof t._nativeTag)return t._nativeTag;if("number"==typeof t.nativeTag)return t.nativeTag;if(t.canonical){if("number"==typeof t.canonical.__nativeTag)return t.canonical.__nativeTag;if("number"==typeof t.canonical._nativeTag)return t.canonical._nativeTag;if("number"==typeof t.canonical.nativeTag)return t.canonical.nativeTag}return null}function findHostInstance(e){const t=getPublicInstance(e.stateNode);if(t)return{instance:t,nativeTag:getNativeTag(e.stateNode),stateNode:e.stateNode};const n=[];e.child&&n.push(e.child);let o=0;for(;n.length>0&&o<4e3;){o++;const e=n.pop();if(!e)continue;const t=getPublicInstance(e.stateNode);if(t)return{instance:t,nativeTag:getNativeTag(e.stateNode),stateNode:e.stateNode};e.child&&n.push(e.child),e.sibling&&n.push(e.sibling)}return null}function findScrollAncestor(e){let t=e,n=0;for(;t&&n++<200;){const e=t.stateNode;if(e&&"function"==typeof e.scrollTo){const t="function"==typeof e.getNativeScrollRef&&e.getNativeScrollRef()||null,n="function"==typeof e.getInnerViewNode&&e.getInnerViewNode()||"function"==typeof e.getScrollableNode&&e.getScrollableNode()||e;return{instance:e,nativeRef:t,innerNode:n}}t=t.return}return null}async function scrollIntoView(e,t,n,o){try{const n=findScrollAncestor(e);if(!n)return!1;const r=t;let a=null;const i=e=>new Promise(t=>{let n=!1;const o=e=>{n||(n=!0,t(e))},r=setTimeout(()=>o(null),600);try{e(e=>{clearTimeout(r),o(e)})}catch{clearTimeout(r),o(null)}});if(n.nativeRef&&"function"==typeof r.measureLayout&&(a=await i(e=>r.measureLayout(n.nativeRef,(t,n)=>e(n),()=>e(null)))),null==a){const e=(0,_reactNative.findNodeHandle)(t),o="number"==typeof n.innerNode?n.innerNode:(0,_reactNative.findNodeHandle)(n.innerNode);null!=e&&null!=o&&(a=await i(t=>_reactNative.UIManager.measureLayout(e,o,()=>t(null),(e,n)=>t(n))))}return null!=a&&(n.instance.scrollTo({y:Math.max(0,a-o),animated:!1}),await new Promise(e=>setTimeout(e,120)),!0)}catch{return!1}}function getComponentName(e){const t=e?.type;return t?"string"==typeof t?t:t.displayName||t.name||null:null}function getOwningComponentName(e){let t=e?._debugOwner||e?.return,n=0;for(;t&&n<30;){n++;const e=getComponentName(t);if(e&&!INTERNAL_NAMES.has(e)&&"string"!=typeof t.type)return e;t=t.return}return null}function getProps(e){return e?.memoizedProps??e?.pendingProps??null}function flattenText(e,t=0){if("string"==typeof e)return e;if("number"==typeof e&&Number.isFinite(e))return String(e);if(Array.isArray(e)&&t<4){const n=[];for(const o of e){const e=flattenText(o,t+1);e&&n.push(e)}return n.length>0?n.join(""):void 0}}function normalizeVisibleText(e){return e.replace(/\s+/g," ").trim()}function getVisibleText(e){if(!e)return;const t=e=>{const t=flattenText(e);if(void 0===t)return;const n=normalizeVisibleText(t);return n?n.slice(0,80):void 0};return t(e.children)??t(e.title)??t(e.label)??t(e.placeholder)??void 0}function collectDescendantText(e,t){const n=[],o=(r,a)=>{if(!r||a>t||n.length>=4)return;if(r!==e){const e=getProps(r);if(e&&("function"==typeof e.onPress||"function"==typeof e.onLongPress))return}const i=getVisibleText(getProps(r));i&&!n.includes(i)&&n.push(i),r.child&&o(r.child,a+1),r!==e&&r.sibling&&o(r.sibling,a)};e.child&&o(e.child,1);const r=n.join(" ").trim();return r?r.slice(0,80):void 0}function findPressHandler(e){let t=e,n=0,o=null,r=null;for(;t&&n<25&&(!o||!r);){const e=getProps(t);e&&(o||"function"!=typeof e.onPress||(o=e.onPress),r||"function"!=typeof e.onLongPress||(r=e.onLongPress)),t=t.return,n++}return o?{handler:o,kind:"onPress",longPress:r??void 0}:r?{handler:r,kind:"onLongPress"}:null}function measureInstance(e){return new Promise(t=>{let n=!1;const o=e=>{n||(n=!0,t(e))};setTimeout(()=>o(null),1e3);try{"function"==typeof e.measureInWindow?e.measureInWindow((e,t,n,r)=>{o(n>0&&r>0?{x:e,y:t,width:n,height:r}:null)}):"function"==typeof e.measure?e.measure((e,t,n,r,a,i)=>{o(n>0&&r>0&&null!=a&&null!=i?{x:a,y:i,width:n,height:r}:null)}):o(null)}catch{o(null)}})}function collectCandidates(){const e=getAllFiberRoots();if(0===e.length)return[];const t=[],n=new Map,o=new Map,r=makeChromeCheck();for(const a of e)traverseFiberTree(a.current,e=>{const a=getProps(e);if(!a)return;const i="function"==typeof a.onPress||"function"==typeof a.onLongPress,s="function"==typeof a.onValueChange,l="function"==typeof a.onChangeText,c=a.testID||void 0,u=a.accessibilityLabel||void 0,f=a.accessibilityRole||a.role||void 0;let d=getVisibleText(a);if(!(i||s||l||c||u||d||"button"===f||"link"===f||"menuitem"===f||"tab"===f||"switch"===f||"checkbox"===f))return;let m=null,g=null,p=null;if(s){const e=a.value,t="number"==typeof e||"number"==typeof a.minimumValue;g={handler:a.onValueChange,kind:t?"slider":"toggle",current:e,min:"number"==typeof a.minimumValue?a.minimumValue:void 0,max:"number"==typeof a.maximumValue?a.maximumValue:void 0}}else l?p={handler:a.onChangeText,current:"string"==typeof a.value?a.value:void 0}:m=findPressHandler(e);const h=getComponentName(e);let v=h??"Unknown";h&&!INTERNAL_NAMES.has(h)&&"string"!=typeof e.type||(v=getOwningComponentName(e)??h??"Unknown");const T=findHostInstance(e);if(!T&&!c)return;d||u||!i||(d=collectDescendantText(e,6));const b=T?.instance??null,y=T?.nativeTag??null,C=(b?n.get(b):void 0)??(null!=y?o.get(y):void 0);if(C)return!C.press&&m?C.press=m:C.press&&m?.longPress&&!C.press.longPress&&(C.press.longPress=m.longPress),!C.valueControl&&g&&(C.valueControl=g),!C.textControl&&p&&(C.textControl=p),!C.testID&&c&&(C.testID=c),!C.label&&u&&(C.label=u),!C.text&&d&&(C.text=d),b&&!n.has(b)&&n.set(b,C),void(null==y||o.has(y)||o.set(y,C));const w={nativeTag:y,name:v,role:f,testID:c,label:u,text:d,instance:b,stateNode:T?.stateNode??null,fiber:e,press:m,valueControl:g,textControl:p,rect:null,buoy:r(e)};t.push(w),b&&n.set(b,w),null!=y&&o.set(y,w)});return t}function explicitlyTargets(e,t){return null!=t.nativeTag?e.nativeTag===t.nativeTag:!(!t.testID||!e.testID)&&e.testID.toLowerCase()===t.testID.toLowerCase()}function appCandidates(e){const t=collectCandidates();return e.includeBuoy?t:t.filter(t=>!t.buoy||explicitlyTargets(t,e))}async function measureCandidates(e){await Promise.all(e.map(async e=>{e.instance&&(e.rect=await measureInstance(e.instance))}))}async function describeScreen(e={}){const t=collectCandidates(),n=e.includeBuoy?t:t.filter(e=>!e.buoy),o=t.length-n.length;await measureCandidates(n);const r=_reactNative.Dimensions.get("window"),a=Math.round(r.width)||1,i=Math.round(r.height)||1,s=[];for(const e of n){const t=e.rect;if(!t&&!e.testID)continue;let n,o;if(t){const e=t.x+t.width/2,r=t.y+t.height/2;if(r<.1*-i||r>1.1*i||e<.1*-a||e>1.1*a)continue;n={x:round2(e/a),y:round2(r/i)},o={x:round2(t.x/a),y:round2(t.y/i),width:round2(t.width/a),height:round2(t.height/i)}}const r=e.valueControl?e.valueControl.kind:e.textControl?"text":void 0,l=e.valueControl?e.valueControl.current:e.textControl?.current;s.push({nativeTag:e.nativeTag,name:e.name,role:e.role,testID:e.testID,label:e.label,text:e.text,interactive:!!(e.press||e.valueControl||e.textControl),longPressable:!(!e.press||"onLongPress"!==e.press.kind&&!e.press.longPress)||void 0,control:r,value:l,tap:n,frame:o})}return s.sort((e,t)=>{const n=e.tap?.y??2,o=t.tap?.y??2;return Math.abs(n-o)>.02?n-o:(e.tap?.x??2)-(t.tap?.x??2)}),{screen:{width:a,height:i},count:s.length,elements:s,...o>0?{hiddenBuoy:o}:{}}}function round2(e){return Math.round(100*e)/100}function fieldsOf(e){return{nativeTag:e.nativeTag,testID:e.testID,label:e.label,text:e.text,name:e.name}}function matchScore(e,t){return(0,_tapMatch.scoreTapMatch)(fieldsOf(e),t)}function tapPoint(e,t,n){if(e&&t&&n)return{x:(e.x+e.width/2)/t,y:(e.y+e.height/2)/n}}function makeSyntheticPressEvent(e){const t=e?e.x+e.width/2:0,n=e?e.y+e.height/2:0;return{nativeEvent:{locationX:e?e.width/2:0,locationY:e?e.height/2:0,pageX:t,pageY:n,timestamp:0,target:null,identifier:1,touches:[],changedTouches:[]},persist:()=>{},preventDefault:()=>{},stopPropagation:()=>{},isDefaultPrevented:()=>!1,isPropagationStopped:()=>!1,target:null,currentTarget:null,type:"press",timeStamp:0}}async function tapElement(e){const t=appCandidates(e);if(0===t.length)return{tapped:!1,reason:"No React fiber roots / elements found on screen."};const n=t.map(t=>({c:t,score:matchScore(t,e)})).filter(e=>e.score>0).sort((e,t)=>t.score-e.score),o=e=>!!(e.press||e.valueControl||e.textControl);if(0===n.length)return{tapped:!1,reason:"No element matched. Call describe_screen to see available elements (match by testID, text, or name).",candidates:t.filter(o).slice(0,12).map(e=>({nativeTag:e.nativeTag,name:e.name,testID:e.testID,text:e.text}))};const r=_reactNative.Dimensions.get("window"),a=r.width||1,i=r.height||1,s=n.slice(0,15);await Promise.all(s.map(async e=>{e.c.instance&&!e.c.rect&&(e.c.rect=await measureInstance(e.c.instance))}));for(const t of s)t.score=(0,_tapMatch.scoreTapMatch)({...fieldsOf(t.c),tap:tapPoint(t.c.rect,a,i)},e);s.sort((e,t)=>t.score-e.score);const l=s.find(e=>o(e.c))??n.find(e=>o(e.c))??s[0],c=l.c,u=(e,t)=>e.press&&e.press.handler===t.press?.handler||e.valueControl&&e.valueControl.handler===t.valueControl?.handler||e.textControl&&e.textControl.handler===t.textControl?.handler,f=s.filter(e=>e!==l&&o(e.c)&&e.score===l.score).filter(e=>!u(e.c,c)).filter((e,t,n)=>n.findIndex(t=>u(t.c,e.c))===t).slice(0,3).map(e=>({nativeTag:e.c.nativeTag,name:e.c.name,testID:e.c.testID,text:e.c.text,tap:tapPoint(e.c.rect,a,i)}));if(!o(c))return{tapped:!1,reason:`Matched "${c.name}"${c.text?` ("${c.text}")`:""} but it has no onPress / onValueChange / onChangeText handler (e.g. a react-native-gesture-handler GestureDetector). This element can't be driven in JS.`,matched:{nativeTag:c.nativeTag,name:c.name,testID:c.testID,label:c.label,text:c.text,via:"onPress"}};c.instance&&!c.rect&&(c.rect=await measureInstance(c.instance));let d=!1;(null==c.rect||!(0,_tapMatch.isRectCenterOnScreen)(c.rect,a,i))&&!1!==e.scrollIntoView&&c.instance&&(d=await scrollIntoView(c.fiber,c.instance,c.stateNode,80),d&&(c.rect=await measureInstance(c.instance)));const m={nativeTag:c.nativeTag,name:c.name,testID:c.testID,label:c.label,text:c.text};ensureCommitCounter();const g=commitCount,p=Date.now(),h=async e=>(await new Promise(e=>setTimeout(e,TAP_SETTLE_MS)),{tapped:!0,scrolled:d,matched:e,effect:{commits:commitCount-g,observedMs:Date.now()-p},...f.length?{alsoMatched:f}:{}});try{if(c.press){if(e.longPress){const e="onLongPress"===c.press.kind?c.press.handler:c.press.longPress;return e?(e(makeSyntheticPressEvent(c.rect)),await h({...m,via:"onLongPress"})):{tapped:!1,scrolled:d,reason:`Matched "${c.name}"${c.text?` ("${c.text}")`:""} but it has no onLongPress handler — call tap_element without longPress to tap it normally.`,matched:{...m,via:"onPress"}}}return c.press.handler(makeSyntheticPressEvent(c.rect)),await h({...m,via:c.press.kind})}if(c.valueControl){const t=c.valueControl;let n;if("toggle"===t.kind)n="boolean"==typeof e.value?e.value:!t.current;else{const o=t.min??0,r=t.max??1;n="number"==typeof e.value?Math.min(r,Math.max(o,e.value)):t.current===r?o:r}return t.handler(n),await h({...m,via:"onValueChange",value:n})}const t=e.text??("string"==typeof e.value?e.value:"");return c.textControl.handler(t),await h({...m,via:"onChangeText",value:t})}catch(e){return{tapped:!1,scrolled:d,reason:`handler threw: ${e instanceof Error?e.message:String(e)}`,matched:{...m,via:c.press?c.press.kind:c.valueControl?"onValueChange":"onChangeText"}}}}const WAIT_DEFAULT_MS=5e3,WAIT_MAX_MS=3e4,WAIT_MIN_POLL_MS=50,WAIT_DEFAULT_POLL_MS=150;async function waitFor(e){if(null==e.nativeTag&&!String(e.testID??"").trim()&&!String(e.query??"").trim())return{ok:!1,waitedMs:0,polls:0,reason:"Nothing to wait for — pass nativeTag, testID or query."};const t=Math.min(Math.max(e.timeoutMs??WAIT_DEFAULT_MS,0),WAIT_MAX_MS),n=Math.max(e.pollMs??WAIT_DEFAULT_POLL_MS,WAIT_MIN_POLL_MS),o=!0===e.gone,r=Date.now();let a=0;for(;;){a+=1;const{hit:i,closest:s}=await findOnScreen(e);if(o?!i:i)return{ok:!0,waitedMs:Date.now()-r,polls:a,matched:i??void 0};if(Date.now()-r>=t){const e=s?.length?s:void 0,n=o?`Still on screen after ${t}ms.`:e?`Not on screen after ${t}ms — ${1===e.length?"one element":`${e.length} elements`} matched but ${e.some(e=>e.onScreen)?"not well enough":"none is visible"}. See \`closest\`; do not retry with different words, call describeScreen.`:`Not on screen after ${t}ms, and nothing matched those words at all. Call describeScreen to see what is there.`;return{ok:!1,waitedMs:Date.now()-r,polls:a,reason:n,matched:i??void 0,closest:e}}await new Promise(e=>setTimeout(e,n))}}async function findOnScreen(e){const t=appCandidates(e).map(t=>({c:t,score:matchScore(t,e)})).filter(e=>e.score>0).sort((e,t)=>t.score-e.score).slice(0,8);if(0===t.length)return{hit:null,closest:void 0};await measureCandidates(t.map(e=>e.c));const n=_reactNative.Dimensions.get("window"),o=Math.round(n.width)||1,r=Math.round(n.height)||1;let a=null;for(const{c:e}of t)if((0,_tapMatch.isRectCenterOnScreen)(e.rect,o,r)){a={nativeTag:e.nativeTag,name:e.name,testID:e.testID,label:e.label,text:e.text,interactive:!!(e.press||e.valueControl||e.textControl)};break}return{hit:a,closest:t.slice(0,3).map(({c:e})=>({name:e.name,testID:e.testID,text:e.text,onScreen:(0,_tapMatch.isRectCenterOnScreen)(e.rect,o,r)}))}}function isBuoyChrome(e){let t=e,n=0;for(;t&&n<400;){if(getProps(t)?.__buoyDevToolsRoot)return!0;t=t.return,n++}return!1}function preferHandlerOwner(e,t){const n=getProps(e.fiber);if("function"==typeof n?.onPress||"function"==typeof n?.onValueChange||"function"==typeof n?.onChangeText)return e;let o=null,r=e.fiber?.return,a=0;for(;r&&a<25;){if("function"==typeof getProps(r)?.onPress){o=r;break}r=r.return,a++}if(!o)return e;let i=o;for(let e=0;e<6&&i;e++){const e=t.get(i);if(e)return e;i=i.return}return e}function resolveTouchTarget(e){const t=collectCandidates();if(0===t.length)return null;const n=new Map;for(const e of t)n.set(e.fiber,e);const o=t.find(t=>t.nativeTag===e);let r=null;if(!o)for(const t of getAllFiberRoots())if(traverseFiberTree(t.current,t=>{r||t.stateNode&&getNativeTag(t.stateNode)===e&&(r=t)}),r)break;let a=o??null;if(!a&&r){let e=r,t=0,o=null;for(;e&&t<25;){const r=n.get(e);if(r){if(r.press||r.valueControl||r.textControl){a=r;break}o||(o=r)}e=e.return,t++}a||(a=o)}if(!a)return null;if(a=preferHandlerOwner(a,n),!a.press&&!a.valueControl&&!a.textControl)return null;if(isBuoyChrome(a.fiber))return null;const i=a.valueControl?a.valueControl.kind:a.textControl?"text":"press";return{nativeTag:a.nativeTag,name:a.name,role:a.role,testID:a.testID,label:a.label,text:a.text,control:i,value:a.valueControl?a.valueControl.current:a.textControl?a.textControl.current:void 0}}
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.describeScreen = describeScreen;
+exports.resolveTouchTarget = resolveTouchTarget;
+exports.tapElement = tapElement;
+exports.waitFor = waitFor;
+var _reactNative = require("react-native");
+var _tapMatch = require("./tapMatch");
+/**
+ * On-device screen element discovery + in-JS tap.
+ *
+ * This powers the MCP "describe_screen" / "tap_element" tools. It walks the
+ * live React fiber tree (all renderers), collects the meaningful / interactive
+ * elements on the current screen, and measures each one's on-screen rect — the
+ * same idea as the desktop screenshot tool's component-locate, but producing a
+ * whole-screen list with normalized tap coordinates instead of a single crop.
+ *
+ * Tapping is done PURELY in JS: we resolve the target element, find the nearest
+ * `onPress` handler up its fiber chain, and invoke it with a synthetic press
+ * event. No screenshots, no OS-level touch injection, and it works on physical
+ * devices — because Buoy runs INSIDE the app (unlike external simulator drivers
+ * that have to inject an OS touch at a pixel coordinate).
+ *
+ * Fiber traversal is adapted from image-overlay/utils/fiberScanner.ts and
+ * debug-borders/utils/fiberTreeTraversal.js; the fiber-access triad matches the
+ * rest of highlight-updates (Fabric / Paper / RN-CLI-dev).
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// --- React fiber tag / renderer plumbing ---------------------------------
+
+const HostComponent = 5;
+const OffscreenComponent = 22;
+
+// Component names that are pure infrastructure and never worth listing on
+// their own. Kept small on purpose — a candidate still needs a real signal
+// (onPress / testID / label / text / role) to be emitted, so this only
+// suppresses the *name* of wrappers that happen to also carry one.
+const INTERNAL_NAMES = new Set(["View", "RCTView", "ScrollView", "RCTScrollView", "RCTScrollContentView", "SafeAreaView", "RCTSafeAreaView", "AndroidHorizontalScrollContentView", "KeyboardAvoidingView", "Pressable", "PlatformPressable", "TouchableOpacity", "TouchableHighlight", "TouchableWithoutFeedback", "TouchableNativeFeedback", "AnimatedComponent", "Wrapper"]);
+function getReactDevToolsHook() {
+  if (typeof global === "undefined") return null;
+  return global.__REACT_DEVTOOLS_GLOBAL_HOOK__ ?? null;
+}
+
+/**
+ * React commits observed since this counter was installed.
+ *
+ * `tapElement` reads it either side of firing a handler to say whether
+ * ANYTHING re-rendered afterwards. Without that a tap that matched a button
+ * on the screen BENEATH the current one (a stack keeps it mounted) came back
+ * `tapped:true` — the handler really did run — and an agent then built its
+ * next three turns on a sign-in that never happened. Zero commits inside the
+ * settle window is the honest signal: the handler ran and the app did nothing
+ * visible with it.
+ *
+ * Installed once and chained, the same way CommitProfiler wraps the hook;
+ * counting is the only work it does on the commit path.
+ */
+let commitCount = 0;
+let commitCounterInstalled = false;
+function ensureCommitCounter() {
+  if (commitCounterInstalled) return;
+  const hook = getReactDevToolsHook();
+  if (!hook) return;
+  const original = hook.onCommitFiberRoot;
+  hook.onCommitFiberRoot = function (...args) {
+    commitCount++;
+    return typeof original === "function" ? original.apply(hook, args) : undefined;
+  };
+  commitCounterInstalled = true;
+}
+
+/** How long a tap waits to see the app react before reporting. */
+const TAP_SETTLE_MS = 250;
+
+/**
+ * Per-walk memo of "is this fiber under Buoy's own overlay". Every candidate
+ * asks, and they share ancestors, so the answer is cached along the path
+ * walked rather than recomputed 400 levels deep per row.
+ */
+function makeChromeCheck() {
+  const memo = new Map();
+  return fiber => {
+    const path = [];
+    let cur = fiber;
+    let depth = 0;
+    let inChrome = false;
+    while (cur && depth < 400) {
+      const known = memo.get(cur);
+      if (known !== undefined) {
+        inChrome = known;
+        break;
+      }
+      if (getProps(cur)?.__buoyDevToolsRoot) {
+        inChrome = true;
+        memo.set(cur, true);
+        break;
+      }
+      path.push(cur);
+      cur = cur.return;
+      depth++;
+    }
+    for (const f of path) memo.set(f, inChrome);
+    return inChrome;
+  };
+}
+
+/**
+ * Collect fiber roots across ALL renderers. A single renderer id is not safe
+ * to assume: secondary reconcilers (react-native-skia, react-native-svg, …)
+ * register their own renderer, sometimes first as id 1, whose roots contain
+ * none of the tappable app UI.
+ */
+function getAllFiberRoots() {
+  const hook = getReactDevToolsHook();
+  if (!hook) return [];
+  const roots = [];
+  try {
+    if (hook.renderers && typeof hook.renderers.forEach === "function") {
+      hook.renderers.forEach((_r, rendererId) => {
+        try {
+          const set = hook.getFiberRoots?.(rendererId);
+          if (set) set.forEach(root => roots.push(root));
+        } catch {
+          /* ignore a single renderer failing */
+        }
+      });
+    }
+    if (roots.length === 0 && hook.getFiberRoots) {
+      const legacy = hook.getFiberRoots(1);
+      if (legacy) legacy.forEach(root => roots.push(root));
+    }
+  } catch {
+    /* ignore */
+  }
+  return roots;
+}
+function isHiddenOffscreen(fiber) {
+  return fiber.tag === OffscreenComponent && fiber.memoizedState !== null;
+}
+function isInactiveScreen(fiber) {
+  // react-native-screens: activityState 0/1 = inactive/transitioning.
+  const as = fiber.memoizedProps?.activityState;
+  if (as === 0 || as === 1) return true;
+  // pagers
+  if (fiber.memoizedProps?.isPageFocused === false) return true;
+  return false;
+}
+function traverseFiberTree(fiber, callback, depth = 0, visited = new Set()) {
+  if (!fiber || visited.has(fiber) || depth > 500) return;
+  visited.add(fiber);
+  if (isHiddenOffscreen(fiber) || isInactiveScreen(fiber)) {
+    // Prune the whole subtree, but keep walking siblings.
+    if (fiber.sibling) traverseFiberTree(fiber.sibling, callback, depth, visited);
+    return;
+  }
+  callback(fiber);
+  if (fiber.child) traverseFiberTree(fiber.child, callback, depth + 1, visited);
+  if (fiber.sibling) traverseFiberTree(fiber.sibling, callback, depth, visited);
+}
+
+// --- Fiber → host instance / name / props --------------------------------
+
+/** Get a measurable public instance from a host fiber's stateNode. */
+function getPublicInstance(stateNode) {
+  if (!stateNode) return null;
+  const node = stateNode;
+  if (node.canonical?.publicInstance) return node.canonical.publicInstance;
+  if (node.canonical && typeof node.canonical.measure === "function") {
+    return node.canonical;
+  }
+  if (typeof node.measure === "function" || typeof node.measureInWindow === "function") {
+    return node;
+  }
+  return null;
+}
+function getNativeTag(stateNode) {
+  if (stateNode == null) return null;
+  const n = stateNode;
+  if (typeof n.__nativeTag === "number") return n.__nativeTag;
+  if (typeof n._nativeTag === "number") return n._nativeTag;
+  if (typeof n.nativeTag === "number") return n.nativeTag;
+  if (n.canonical) {
+    if (typeof n.canonical.__nativeTag === "number") return n.canonical.__nativeTag;
+    if (typeof n.canonical._nativeTag === "number") return n.canonical._nativeTag;
+    if (typeof n.canonical.nativeTag === "number") return n.canonical.nativeTag;
+  }
+  return null;
+}
+
+/** The first host node in a fiber's own subtree (self first, then descendants). */
+function findHostInstance(fiber) {
+  const selfInst = getPublicInstance(fiber.stateNode);
+  if (selfInst) {
+    return {
+      instance: selfInst,
+      nativeTag: getNativeTag(fiber.stateNode),
+      stateNode: fiber.stateNode
+    };
+  }
+
+  // DFS restricted to this fiber's subtree (child + siblings-of-children).
+  const stack = [];
+  if (fiber.child) stack.push(fiber.child);
+  let guard = 0;
+  while (stack.length > 0 && guard < 4000) {
+    guard++;
+    const f = stack.pop();
+    if (!f) continue;
+    const inst = getPublicInstance(f.stateNode);
+    if (inst) return {
+      instance: inst,
+      nativeTag: getNativeTag(f.stateNode),
+      stateNode: f.stateNode
+    };
+    if (f.child) stack.push(f.child);
+    if (f.sibling) stack.push(f.sibling);
+  }
+  return null;
+}
+
+/**
+ * Walk up from a fiber to the nearest ScrollView-like instance (exposes
+ * scrollTo). Mirrors HighlightUpdatesController.findScrollAncestor.
+ */
+function findScrollAncestor(fiber) {
+  let cur = fiber;
+  let guard = 0;
+  while (cur && guard++ < 200) {
+    const inst = cur.stateNode;
+    if (inst && typeof inst.scrollTo === "function") {
+      const nativeRef = typeof inst.getNativeScrollRef === "function" && inst.getNativeScrollRef() || null;
+      const innerNode = typeof inst.getInnerViewNode === "function" && inst.getInnerViewNode() || typeof inst.getScrollableNode === "function" && inst.getScrollableNode() || inst;
+      return {
+        instance: inst,
+        nativeRef,
+        innerNode
+      };
+    }
+    cur = cur.return;
+  }
+  return null;
+}
+
+/**
+ * Best-effort scroll of an ancestor ScrollView so the target sits near the top
+ * of its viewport. Returns true only if a scroll was issued. Never throws.
+ * Ported from HighlightUpdatesController.scrollDescendantIntoView.
+ */
+async function scrollIntoView(targetFiber, publicInstance, stateNode, margin) {
+  try {
+    const ancestor = findScrollAncestor(targetFiber);
+    if (!ancestor) return false;
+    const inst = publicInstance;
+    let top = null;
+
+    // measureLayout can invoke NEITHER callback on some architectures — race
+    // every call against a short timeout so the await can't hang.
+    const withTimeout = run => new Promise(resolve => {
+      let done = false;
+      const settle = v => {
+        if (done) return;
+        done = true;
+        resolve(v);
+      };
+      const timer = setTimeout(() => settle(null), 600);
+      try {
+        run(v => {
+          clearTimeout(timer);
+          settle(v);
+        });
+      } catch {
+        clearTimeout(timer);
+        settle(null);
+      }
+    });
+
+    // Fabric: ref.measureLayout against the inner view ref.
+    if (ancestor.nativeRef && typeof inst.measureLayout === "function") {
+      top = await withTimeout(resolve => inst.measureLayout(ancestor.nativeRef, (_left, t) => resolve(t), () => resolve(null)));
+    }
+
+    // Legacy: UIManager.measureLayout with numeric node handles.
+    if (top == null) {
+      const targetHandle = (0, _reactNative.findNodeHandle)(publicInstance);
+      const innerHandle = typeof ancestor.innerNode === "number" ? ancestor.innerNode : (0, _reactNative.findNodeHandle)(ancestor.innerNode);
+      if (targetHandle != null && innerHandle != null) {
+        top = await withTimeout(resolve => _reactNative.UIManager.measureLayout(targetHandle, innerHandle, () => resolve(null), (_left, t) => resolve(t)));
+      }
+    }
+    if (top == null) return false;
+    ancestor.instance.scrollTo({
+      y: Math.max(0, top - margin),
+      animated: false
+    });
+    await new Promise(r => setTimeout(r, 120)); // let scroll + layout settle
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getComponentName(fiber) {
+  const t = fiber?.type;
+  if (!t) return null;
+  if (typeof t === "string") return t;
+  return t.displayName || t.name || null;
+}
+
+/** Walk up to the nearest user-defined component name (skips host/internal). */
+function getOwningComponentName(fiber) {
+  let cur = fiber?._debugOwner || fiber?.return;
+  let depth = 0;
+  while (cur && depth < 30) {
+    depth++;
+    const name = getComponentName(cur);
+    if (name && !INTERNAL_NAMES.has(name) && typeof cur.type !== "string") {
+      return name;
+    }
+    cur = cur.return;
+  }
+  return null;
+}
+function getProps(fiber) {
+  return fiber?.memoizedProps ?? fiber?.pendingProps ?? null;
+}
+
+/**
+ * The text of a `children` value, INCLUDING one assembled from several pieces.
+ *
+ * `<Text>{value} {label}</Text>` compiles to `children: ["1,450", " ", "Points"]`
+ * and `Check Back Soon{"\n"}For Available Offers` to three strings. This used
+ * to accept a lone string or number and nothing else, so EVERY composed label
+ * in an app was invisible to describeScreen, tapElement and waitFor — while
+ * native accessibility, which concatenates the same children, could read them.
+ * Measured on a live QA run: five waits failed against an empty state that was
+ * on screen the whole time, and the agent then reported the app was missing
+ * one; a points balance could not be found by its own number.
+ *
+ * Nested React ELEMENTS are not walked here — `collectDescendantText` owns
+ * that, with its stop-at-a-nested-button rule — so this stays a leaf join, and
+ * adjacent pieces are concatenated exactly as React renders them.
+ */
+function flattenText(value, depth = 0) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (Array.isArray(value) && depth < 4) {
+    const parts = [];
+    for (const child of value) {
+      const part = flattenText(child, depth + 1);
+      if (part) parts.push(part);
+    }
+    return parts.length > 0 ? parts.join("") : undefined;
+  }
+  return undefined;
+}
+
+/** What a person reads: newlines and runs of spaces collapse to one space. */
+function normalizeVisibleText(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function getVisibleText(props) {
+  if (!props) return undefined;
+  const pick = v => {
+    const flat = flattenText(v);
+    if (flat === undefined) return undefined;
+    const text = normalizeVisibleText(flat);
+    return text ? text.slice(0, 80) : undefined;
+  };
+  return pick(props.children) ?? pick(props.title) ?? pick(props.label) ?? pick(props.placeholder) ?? undefined;
+}
+
+/**
+ * Gather visible text from a fiber's descendants (its own label), stopping at
+ * nested interactive subtrees so a button doesn't absorb another button's text.
+ * Lets an icon-button whose label is a child <Text> (e.g. a dial icon) still be
+ * matched/shown by that label — the button host measures even when the inner
+ * Text host doesn't.
+ */
+function collectDescendantText(root, maxDepth) {
+  const parts = [];
+  const visit = (f, depth) => {
+    if (!f || depth > maxDepth || parts.length >= 4) return;
+    // Don't cross into a nested interactive element (another button's label).
+    if (f !== root) {
+      const p = getProps(f);
+      if (p && (typeof p.onPress === "function" || typeof p.onLongPress === "function")) return;
+    }
+    const t = getVisibleText(getProps(f));
+    if (t && !parts.includes(t)) parts.push(t);
+    if (f.child) visit(f.child, depth + 1);
+    if (f !== root && f.sibling) visit(f.sibling, depth); // siblings stay in subtree
+  };
+  if (root.child) visit(root.child, 1);
+  const joined = parts.join(" ").trim();
+  return joined ? joined.slice(0, 80) : undefined;
+}
+
+/** Nearest onPress / onLongPress handlers at or above a fiber. */
+
+function findPressHandler(fiber) {
+  let cur = fiber;
+  let depth = 0;
+  let press = null;
+  let longPress = null;
+  while (cur && depth < 25 && !(press && longPress)) {
+    const p = getProps(cur);
+    if (p) {
+      if (!press && typeof p.onPress === "function") press = p.onPress;
+      if (!longPress && typeof p.onLongPress === "function") longPress = p.onLongPress;
+    }
+    cur = cur.return;
+    depth++;
+  }
+  if (press) return {
+    handler: press,
+    kind: "onPress",
+    longPress: longPress ?? undefined
+  };
+  return longPress ? {
+    handler: longPress,
+    kind: "onLongPress"
+  } : null;
+}
+
+// --- Measurement ----------------------------------------------------------
+
+/** Absolute on-screen rect in points (or null), with a hang guard. */
+function measureInstance(instance) {
+  return new Promise(resolve => {
+    let settled = false;
+    const done = r => {
+      if (settled) return;
+      settled = true;
+      resolve(r);
+    };
+    // Detached / off-screen nodes can fire neither callback.
+    setTimeout(() => done(null), 1000);
+    try {
+      if (typeof instance.measureInWindow === "function") {
+        instance.measureInWindow((x, y, width, height) => {
+          if (width > 0 && height > 0) done({
+            x,
+            y,
+            width,
+            height
+          });else done(null);
+        });
+      } else if (typeof instance.measure === "function") {
+        instance.measure((_x, _y, width, height, pageX, pageY) => {
+          if (width > 0 && height > 0 && pageX != null && pageY != null) {
+            done({
+              x: pageX,
+              y: pageY,
+              width,
+              height
+            });
+          } else {
+            done(null);
+          }
+        });
+      } else {
+        done(null);
+      }
+    } catch {
+      done(null);
+    }
+  });
+}
+
+// --- Public types ---------------------------------------------------------
+
+// Internal record carries the live fiber refs that `describeScreen`'s
+// serializable result drops.
+
+// --- Collection -----------------------------------------------------------
+
+function collectCandidates() {
+  const roots = getAllFiberRoots();
+  if (roots.length === 0) return [];
+  const out = [];
+  /**
+   * De-dup indexes. Two fibers resolving to the same host node collapse to one
+   * row — a Pressable and its inner View, but ALSO the same native view reached
+   * twice by the walk, which produces two different `instance` objects for one
+   * `nativeTag`. Measured on a live QA run: a 141-row screen dump held 70
+   * distinct elements, every one listed twice, and the agent told the user
+   * their layout had duplicate elements. Keyed both ways so either collision
+   * collapses, and as Maps because the old `out.find(…)` was a linear scan per
+   * candidate on a list that can run to hundreds.
+   */
+  const byInstance = new Map();
+  const byTag = new Map();
+  const inBuoyChrome = makeChromeCheck();
+  for (const root of roots) {
+    traverseFiberTree(root.current, fiber => {
+      const props = getProps(fiber);
+      if (!props) return;
+      const hasPress = typeof props.onPress === "function" || typeof props.onLongPress === "function";
+      const hasValue = typeof props.onValueChange === "function";
+      const hasText = typeof props.onChangeText === "function";
+      const testID = props.testID || undefined;
+      const label = props.accessibilityLabel || undefined;
+      const role = props.accessibilityRole || props.role || undefined;
+      let text = getVisibleText(props);
+      const roleInteractive = role === "button" || role === "link" || role === "menuitem" || role === "tab" || role === "switch" || role === "checkbox";
+
+      // A fiber earns a row only if it carries a real signal.
+      if (!hasPress && !hasValue && !hasText && !testID && !label && !text && !roleInteractive) {
+        return;
+      }
+
+      // Resolve how this element is driven. A value/text control is a leaf
+      // (Switch/Slider/TextInput) whose OWN handler wins over an ancestor
+      // onPress; otherwise fall back to the nearest onPress up the tree.
+      let press = null;
+      let valueControl = null;
+      let textControl = null;
+      if (hasValue) {
+        const current = props.value;
+        const numeric = typeof current === "number" || typeof props.minimumValue === "number";
+        valueControl = {
+          handler: props.onValueChange,
+          kind: numeric ? "slider" : "toggle",
+          current,
+          min: typeof props.minimumValue === "number" ? props.minimumValue : undefined,
+          max: typeof props.maximumValue === "number" ? props.maximumValue : undefined
+        };
+      } else if (hasText) {
+        textControl = {
+          handler: props.onChangeText,
+          current: typeof props.value === "string" ? props.value : undefined
+        };
+      } else {
+        press = findPressHandler(fiber);
+      }
+      const rawName = getComponentName(fiber);
+      // Prefer a user component name over a bare host/internal wrapper name.
+      let name = rawName ?? "Unknown";
+      if (!rawName || INTERNAL_NAMES.has(rawName) || typeof fiber.type === "string") {
+        name = getOwningComponentName(fiber) ?? rawName ?? "Unknown";
+      }
+      const host = findHostInstance(fiber);
+      if (!host && !testID) return; // unmeasurable & unnamed → skip
+
+      // Interactive element with no own text/label (icon button, dial icon) —
+      // adopt a descendant <Text> as its label so it's matchable by that text.
+      if (!text && !label && hasPress) {
+        text = collectDescendantText(fiber, 6);
+      }
+      const instance = host?.instance ?? null;
+      const nativeTag = host?.nativeTag ?? null;
+      const existing = (instance ? byInstance.get(instance) : undefined) ?? (nativeTag != null ? byTag.get(nativeTag) : undefined);
+      if (existing) {
+        // Keep the more interactive / better-labelled of the two.
+        if (!existing.press && press) existing.press = press;else if (existing.press && press?.longPress && !existing.press.longPress) {
+          existing.press.longPress = press.longPress;
+        }
+        if (!existing.valueControl && valueControl) existing.valueControl = valueControl;
+        if (!existing.textControl && textControl) existing.textControl = textControl;
+        if (!existing.testID && testID) existing.testID = testID;
+        if (!existing.label && label) existing.label = label;
+        if (!existing.text && text) existing.text = text;
+        // Index the alias too, so a third sighting through either key finds it.
+        if (instance && !byInstance.has(instance)) byInstance.set(instance, existing);
+        if (nativeTag != null && !byTag.has(nativeTag)) byTag.set(nativeTag, existing);
+        return;
+      }
+      const candidate = {
+        nativeTag,
+        name,
+        role,
+        testID,
+        label,
+        text,
+        instance,
+        stateNode: host?.stateNode ?? null,
+        fiber,
+        press,
+        valueControl,
+        textControl,
+        rect: null,
+        buoy: inBuoyChrome(fiber)
+      };
+      out.push(candidate);
+      if (instance) byInstance.set(instance, candidate);
+      if (nativeTag != null) byTag.set(nativeTag, candidate);
+    });
+  }
+  return out;
+}
+
+/**
+ * Whether the caller named THIS element, rather than described one like it.
+ * An exact nativeTag or testID is a deliberate choice, and is honoured even
+ * inside Buoy's own chrome — that is how a test or an editor agent drives a
+ * Buoy tool on purpose. A fuzzy `query` is not.
+ */
+function explicitlyTargets(c, params) {
+  if (params.nativeTag != null) return c.nativeTag === params.nativeTag;
+  if (params.testID && c.testID) return c.testID.toLowerCase() === params.testID.toLowerCase();
+  return false;
+}
+
+/**
+ * The app under test, not the tool looking at it.
+ *
+ * Buoy runs INSIDE the app, so its own sheet is in the same fiber tree as the
+ * screens it inspects — and Ask Buoy's activity log echoes whatever the model
+ * is searching for back as visible text. Left in, that echo was the best
+ * match for the next fuzzy tap or wait, so every text-driven action landed on
+ * Buoy's own panel and nothing in the app moved. The agent diagnosed it
+ * itself, four chats in ("every text-based tap and wait I've done this
+ * session has been landing on Buoy's panel"), and still could not escape it.
+ *
+ * `includeBuoy` lists the chrome for callers that want it; an exact id gets
+ * through regardless (see `explicitlyTargets`).
+ */
+function appCandidates(params) {
+  const all = collectCandidates();
+  if (params.includeBuoy) return all;
+  return all.filter(c => !c.buoy || explicitlyTargets(c, params));
+}
+async function measureCandidates(candidates) {
+  await Promise.all(candidates.map(async c => {
+    if (c.instance) c.rect = await measureInstance(c.instance);
+  }));
+}
+
+// --- describeScreen -------------------------------------------------------
+
+async function describeScreen(params = {}) {
+  const all = collectCandidates();
+  const candidates = params.includeBuoy ? all : all.filter(c => !c.buoy);
+  const hiddenBuoy = all.length - candidates.length;
+  await measureCandidates(candidates);
+  const win = _reactNative.Dimensions.get("window");
+  const screenW = Math.round(win.width) || 1;
+  const screenH = Math.round(win.height) || 1;
+  const elements = [];
+  for (const c of candidates) {
+    const r = c.rect;
+    // Keep on-screen elements; drop rect-less rows unless they carry a testID.
+    if (!r && !c.testID) continue;
+    let tap;
+    let frame;
+    if (r) {
+      const cx = r.x + r.width / 2;
+      const cy = r.y + r.height / 2;
+      // Drop previous Expo Router screens (centers well outside the window).
+      // Keep a 10% slack so the floating menu / home-indicator-clipped rows stay.
+      if (cy < -screenH * 0.1 || cy > screenH * 1.1 || cx < -screenW * 0.1 || cx > screenW * 1.1) {
+        continue;
+      }
+      tap = {
+        x: round2(cx / screenW),
+        y: round2(cy / screenH)
+      };
+      frame = {
+        x: round2(r.x / screenW),
+        y: round2(r.y / screenH),
+        width: round2(r.width / screenW),
+        height: round2(r.height / screenH)
+      };
+    }
+    const control = c.valueControl ? c.valueControl.kind : c.textControl ? "text" : undefined;
+    const value = c.valueControl ? c.valueControl.current : c.textControl?.current;
+    elements.push({
+      nativeTag: c.nativeTag,
+      name: c.name,
+      role: c.role,
+      testID: c.testID,
+      label: c.label,
+      text: c.text,
+      interactive: !!(c.press || c.valueControl || c.textControl),
+      longPressable: c.press && (c.press.kind === "onLongPress" || c.press.longPress) ? true : undefined,
+      control,
+      value,
+      tap,
+      frame
+    });
+  }
+
+  // Reading order: top-to-bottom, then left-to-right.
+  elements.sort((a, b) => {
+    const ay = a.tap?.y ?? 2;
+    const by = b.tap?.y ?? 2;
+    if (Math.abs(ay - by) > 0.02) return ay - by;
+    return (a.tap?.x ?? 2) - (b.tap?.x ?? 2);
+  });
+  return {
+    screen: {
+      width: screenW,
+      height: screenH
+    },
+    count: elements.length,
+    elements,
+    ...(hiddenBuoy > 0 ? {
+      hiddenBuoy
+    } : {})
+  };
+}
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// --- tapElement -----------------------------------------------------------
+
+function fieldsOf(c) {
+  return {
+    nativeTag: c.nativeTag,
+    testID: c.testID,
+    label: c.label,
+    text: c.text,
+    name: c.name
+  };
+}
+function matchScore(c, params) {
+  return (0, _tapMatch.scoreTapMatch)(fieldsOf(c), params);
+}
+function tapPoint(rect, screenW, screenH) {
+  if (!rect || !screenW || !screenH) return undefined;
+  return {
+    x: (rect.x + rect.width / 2) / screenW,
+    y: (rect.y + rect.height / 2) / screenH
+  };
+}
+function makeSyntheticPressEvent(rect) {
+  const pageX = rect ? rect.x + rect.width / 2 : 0;
+  const pageY = rect ? rect.y + rect.height / 2 : 0;
+  const nativeEvent = {
+    locationX: rect ? rect.width / 2 : 0,
+    locationY: rect ? rect.height / 2 : 0,
+    pageX,
+    pageY,
+    timestamp: 0,
+    target: null,
+    identifier: 1,
+    touches: [],
+    changedTouches: []
+  };
+  return {
+    nativeEvent,
+    persist: () => {},
+    preventDefault: () => {},
+    stopPropagation: () => {},
+    isDefaultPrevented: () => false,
+    isPropagationStopped: () => false,
+    target: null,
+    currentTarget: null,
+    type: "press",
+    timeStamp: 0
+  };
+}
+async function tapElement(params) {
+  const candidates = appCandidates(params);
+  if (candidates.length === 0) {
+    return {
+      tapped: false,
+      reason: "No React fiber roots / elements found on screen."
+    };
+  }
+
+  // Rank; only elements with a reachable press handler are tappable.
+  const ranked = candidates.map(c => ({
+    c,
+    score: matchScore(c, params)
+  })).filter(r => r.score > 0).sort((a, b) => b.score - a.score);
+  const isInteractive = c => !!(c.press || c.valueControl || c.textControl);
+  if (ranked.length === 0) {
+    return {
+      tapped: false,
+      reason: "No element matched. Call describe_screen to see available elements (match by testID, text, or name).",
+      candidates: candidates.filter(isInteractive).slice(0, 12).map(c => ({
+        nativeTag: c.nativeTag,
+        name: c.name,
+        testID: c.testID,
+        text: c.text
+      }))
+    };
+  }
+
+  // Measure the top matches so an on-screen DialIcon beats an off-screen nav
+  // chip whose testID happens to contain the same substring.
+  const win = _reactNative.Dimensions.get("window");
+  const screenW = win.width || 1;
+  const screenH = win.height || 1;
+  const top = ranked.slice(0, 15);
+  await Promise.all(top.map(async r => {
+    if (r.c.instance && !r.c.rect) r.c.rect = await measureInstance(r.c.instance);
+  }));
+  for (const r of top) {
+    r.score = (0, _tapMatch.scoreTapMatch)({
+      ...fieldsOf(r.c),
+      tap: tapPoint(r.c.rect, screenW, screenH)
+    }, params);
+  }
+  top.sort((a, b) => b.score - a.score);
+
+  // Fall back to the FULL ranked list for an interactive match — the top-15
+  // re-score is only a tiebreak, and on a busy screen the pressable match can
+  // sit below 15 text-score peers.
+  const target = top.find(r => isInteractive(r.c)) ?? ranked.find(r => isInteractive(r.c)) ?? top[0];
+  const c = target.c;
+
+  // Everything else that matched just as well. A fuzzy "SIGN IN" on a stack
+  // that still has the home screen mounted underneath has two equal answers,
+  // and the caller has to know that before trusting whichever one fired.
+  const sameControl = (a, b) => a.press && a.press.handler === b.press?.handler || a.valueControl && a.valueControl.handler === b.valueControl?.handler || a.textControl && a.textControl.handler === b.textControl?.handler;
+  const alsoMatched = top.filter(r => r !== target && isInteractive(r.c) && r.score === target.score)
+  // The label Text inside the tapped button matches its own button's text
+  // and inherits its onPress: same control, not a rival.
+  .filter(r => !sameControl(r.c, c)).filter((r, i, arr) => arr.findIndex(o => sameControl(o.c, r.c)) === i).slice(0, 3).map(r => ({
+    nativeTag: r.c.nativeTag,
+    name: r.c.name,
+    testID: r.c.testID,
+    text: r.c.text,
+    tap: tapPoint(r.c.rect, screenW, screenH)
+  }));
+  if (!isInteractive(c)) {
+    return {
+      tapped: false,
+      reason: `Matched "${c.name}"${c.text ? ` ("${c.text}")` : ""} but it has no onPress / onValueChange / onChangeText handler (e.g. a react-native-gesture-handler GestureDetector). This element can't be driven in JS.`,
+      matched: {
+        nativeTag: c.nativeTag,
+        name: c.name,
+        testID: c.testID,
+        label: c.label,
+        text: c.text,
+        via: "onPress"
+      }
+    };
+  }
+
+  // Measure the target so we can decide whether to scroll it on-screen (and,
+  // for a press, give the synthetic event real coordinates).
+  if (c.instance && !c.rect) c.rect = await measureInstance(c.instance);
+
+  // Bring it into view if it's off-screen and scrolling is wanted. The action
+  // doesn't NEED this (handlers are invoked directly), but it keeps the element
+  // visible for the human watching / a follow-up describe.
+  let scrolled = false;
+  // A failed measure (rect == null) counts as off-screen: the node may be in
+  // a virtualized list that hasn't materialized it, and scrolling can help.
+  const offScreen = c.rect == null || !(0, _tapMatch.isRectCenterOnScreen)(c.rect, screenW, screenH);
+  if (offScreen && params.scrollIntoView !== false && c.instance) {
+    scrolled = await scrollIntoView(c.fiber, c.instance, c.stateNode, 80);
+    if (scrolled) c.rect = await measureInstance(c.instance); // fresh coords
+  }
+  const base = {
+    nativeTag: c.nativeTag,
+    name: c.name,
+    testID: c.testID,
+    label: c.label,
+    text: c.text
+  };
+
+  // Fire, then watch. The handler is the app's own; what it did — or did
+  // not do — shows up as commits (or none) in the settle window.
+  ensureCommitCounter();
+  // Read BEFORE the handler runs: a synchronous setState commits inside it.
+  const c0 = commitCount;
+  const t0 = Date.now();
+  const fired = async matched => {
+    await new Promise(resolve => setTimeout(resolve, TAP_SETTLE_MS));
+    return {
+      tapped: true,
+      scrolled,
+      matched,
+      effect: {
+        commits: commitCount - c0,
+        observedMs: Date.now() - t0
+      },
+      ...(alsoMatched.length ? {
+        alsoMatched
+      } : {})
+    };
+  };
+  try {
+    if (c.press) {
+      if (params.longPress) {
+        const lp = c.press.kind === "onLongPress" ? c.press.handler : c.press.longPress;
+        if (!lp) {
+          return {
+            tapped: false,
+            scrolled,
+            reason: `Matched "${c.name}"${c.text ? ` ("${c.text}")` : ""} but it has no onLongPress handler — call tap_element without longPress to tap it normally.`,
+            matched: {
+              ...base,
+              via: "onPress"
+            }
+          };
+        }
+        lp(makeSyntheticPressEvent(c.rect));
+        return await fired({
+          ...base,
+          via: "onLongPress"
+        });
+      }
+      c.press.handler(makeSyntheticPressEvent(c.rect));
+      return await fired({
+        ...base,
+        via: c.press.kind
+      });
+    }
+    if (c.valueControl) {
+      const vc = c.valueControl;
+      let next;
+      if (vc.kind === "toggle") {
+        next = typeof params.value === "boolean" ? params.value : !vc.current;
+      } else {
+        const min = vc.min ?? 0;
+        const max = vc.max ?? 1;
+        if (typeof params.value === "number") {
+          next = Math.min(max, Math.max(min, params.value));
+        } else {
+          // No target given → move to the far end so the change is visible.
+          next = vc.current === max ? min : max;
+        }
+      }
+      vc.handler(next);
+      return await fired({
+        ...base,
+        via: "onValueChange",
+        value: next
+      });
+    }
+    // textControl
+    const next = params.text ?? (typeof params.value === "string" ? params.value : "");
+    c.textControl.handler(next);
+    return await fired({
+      ...base,
+      via: "onChangeText",
+      value: next
+    });
+  } catch (e) {
+    return {
+      tapped: false,
+      scrolled,
+      reason: `handler threw: ${e instanceof Error ? e.message : String(e)}`,
+      matched: {
+        ...base,
+        via: c.press ? c.press.kind : c.valueControl ? "onValueChange" : "onChangeText"
+      }
+    };
+  }
+}
+
+// --- waitFor --------------------------------------------------------------
+
+const WAIT_DEFAULT_MS = 5_000;
+const WAIT_MAX_MS = 30_000;
+const WAIT_MIN_POLL_MS = 50;
+const WAIT_DEFAULT_POLL_MS = 150;
+
+/**
+ * Block until an element appears (or disappears), then report how long it took.
+ *
+ * WHY THIS EXISTS. `navigate` returns the moment the route is pushed, not when
+ * the new screen has data on it, so "go to /shop then tap Fire Grill" reliably
+ * tapped a loading skeleton. A remote driver solves that with a wait step
+ * (MCP's `run_flow` has `waitFor`/`waitMs`); anything driving the tools from
+ * INSIDE the app had nothing, and its only option was to re-run
+ * `describeScreen` in a loop — which for an agent means burning turns against a
+ * step budget, and for a Scenario means a fixed sleep that is either flaky or
+ * slow.
+ *
+ * MATCHING IS `tapElement`'S, EXACTLY. Same `scoreTapMatch`, same fields, so
+ * "wait for X" and "tap X" can never disagree about what X is. A wait that
+ * resolves on an element the tap then cannot find is worse than no wait.
+ *
+ * PRESENCE MEANS ON SCREEN. An identity scan alone would resolve against a
+ * previous Expo Router screen still mounted behind the current one — the exact
+ * false positive `describeScreen` drops by rect. So a candidate that matches by
+ * name is measured before it counts, and only the matches are measured: the
+ * per-poll cost stays one fiber walk plus a handful of `measureInWindow`
+ * calls, not a full `describeScreen`.
+ *
+ * The poll floor is deliberate. This runs on the JS thread the app is drawing
+ * on, and a caller asking for `pollMs: 0` would starve the very render it is
+ * waiting for.
+ */
+async function waitFor(params) {
+  // Coerced, not optional-chained: a model sends `query: 1450` often enough,
+  // and `.trim()` on a number throws before the wait ever starts.
+  const hasTarget = params.nativeTag != null || !!String(params.testID ?? "").trim() || !!String(params.query ?? "").trim();
+  if (!hasTarget) {
+    return {
+      ok: false,
+      waitedMs: 0,
+      polls: 0,
+      reason: "Nothing to wait for — pass nativeTag, testID or query."
+    };
+  }
+  const timeoutMs = Math.min(Math.max(params.timeoutMs ?? WAIT_DEFAULT_MS, 0), WAIT_MAX_MS);
+  const pollMs = Math.max(params.pollMs ?? WAIT_DEFAULT_POLL_MS, WAIT_MIN_POLL_MS);
+  const wantGone = params.gone === true;
+  const started = Date.now();
+  let polls = 0;
+  for (;;) {
+    polls += 1;
+    const {
+      hit,
+      closest
+    } = await findOnScreen(params);
+    if (wantGone ? !hit : !!hit) {
+      return {
+        ok: true,
+        waitedMs: Date.now() - started,
+        polls,
+        matched: hit ?? undefined
+      };
+    }
+    if (Date.now() - started >= timeoutMs) {
+      const nearMisses = closest?.length ? closest : undefined;
+      // Say which of the two failures this is. "Nothing is called that" and
+      // "it exists but is not visible" need opposite next moves, and a caller
+      // that cannot tell them apart tries the same wait with new words.
+      const why = wantGone ? `Still on screen after ${timeoutMs}ms.` : nearMisses ? `Not on screen after ${timeoutMs}ms — ${nearMisses.length === 1 ? "one element" : `${nearMisses.length} elements`} matched but ${nearMisses.some(n => n.onScreen) ? "not well enough" : "none is visible"}. See \`closest\`; do not retry with different words, call describeScreen.` : `Not on screen after ${timeoutMs}ms, and nothing matched those words at all. Call describeScreen to see what is there.`;
+      return {
+        ok: false,
+        waitedMs: Date.now() - started,
+        polls,
+        reason: why,
+        matched: hit ?? undefined,
+        closest: nearMisses
+      };
+    }
+    await new Promise(resolve => setTimeout(resolve, pollMs));
+  }
+}
+
+/** One scan: rank by identity, then confirm the best match is really visible. */
+async function findOnScreen(params) {
+  const ranked = appCandidates(params).map(c => ({
+    c,
+    score: matchScore(c, params)
+  })).filter(r => r.score > 0).sort((a, b) => b.score - a.score)
+  // Only the plausible few get measured; a broad query can match dozens.
+  .slice(0, 8);
+  if (ranked.length === 0) return {
+    hit: null,
+    closest: undefined
+  };
+  await measureCandidates(ranked.map(r => r.c));
+  const win = _reactNative.Dimensions.get("window");
+  const screenW = Math.round(win.width) || 1;
+  const screenH = Math.round(win.height) || 1;
+  let hit = null;
+  for (const {
+    c
+  } of ranked) {
+    if (!(0, _tapMatch.isRectCenterOnScreen)(c.rect, screenW, screenH)) continue;
+    hit = {
+      nativeTag: c.nativeTag,
+      name: c.name,
+      testID: c.testID,
+      label: c.label,
+      text: c.text,
+      interactive: !!(c.press || c.valueControl || c.textControl)
+    };
+    break;
+  }
+
+  // Built from the same measured ranking, so a failed wait can say what it
+  // nearly matched and whether that thing was visible.
+  const closest = ranked.slice(0, 3).map(({
+    c
+  }) => ({
+    name: c.name,
+    testID: c.testID,
+    text: c.text,
+    onScreen: (0, _tapMatch.isRectCenterOnScreen)(c.rect, screenW, screenH)
+  }));
+  return {
+    hit,
+    closest
+  };
+}
+
+// --- resolveTouchTarget ---------------------------------------------------
+
+/**
+ * What a recorded touch landed on, in the vocabulary `tapElement` searches by.
+ *
+ * Deliberately the SAME fields `describeScreen` emits: a macro recorded from a
+ * human's finger has to replay through `tapElement`, and the only way to
+ * guarantee that is for the recorder to name the element exactly the way the
+ * matcher will look for it. Anything richer here is a selector that records
+ * fine and then can't be found again.
+ */
+
+/**
+ * Resolve the native tag from a raw touch event to the element a HUMAN would
+ * say they tapped.
+ *
+ * Synchronous on purpose. The tag arrives on `topTouchStart`, and by the time
+ * an async resolve came back the press handler may already have navigated —
+ * leaving the recorder to name the element on the screen it moved TO. Everything
+ * here is a fiber walk (no measure), which is what makes that affordable.
+ *
+ * Returns null when the tag belongs to nothing interesting (the background, a
+ * scroll surface): the recorder treats that as "not a step", which is exactly
+ * right — a tap on empty space is not something to replay.
+ */
+/**
+ * Is this fiber inside Buoy's own overlay?
+ *
+ * `FloatingDevTools` marks its single root View with `__buoyDevToolsRoot`, and
+ * everything the tool draws — the bubble, the dial, every modal, every tool
+ * overlay — is under it. Walking the whole chain (rather than a fixed depth) is
+ * the point: a control deep inside a tool's modal is still the tool.
+ */
+function isBuoyChrome(fiber) {
+  let cur = fiber;
+  let depth = 0;
+  while (cur && depth < 400) {
+    if (getProps(cur)?.__buoyDevToolsRoot) return true;
+    cur = cur.return;
+    depth++;
+  }
+  return false;
+}
+
+/**
+ * Climb from the node that was touched to the element that OWNS the press.
+ *
+ * A finger lands on the deepest host view, which for a button is the `<Text>`
+ * inside it. That Text is a legitimate candidate — `findPressHandler` walks up
+ * and finds the button's `onPress`, so it looks drivable — but it carries the
+ * TEXT's identity: no testID, and "visible text" that is whatever string
+ * happens to be in that node.
+ *
+ * Left alone, every recorded step is named after a fragment of copy and
+ * replayed by fuzzy-matching that fragment. In the Poké Mart flow, all six
+ * steps came back as `Text` with no testID at all, so "tap the Charizard row"
+ * was recorded as "The signature. Flame-broiled, wings on, worth the wait." —
+ * the brittlest possible selector, chosen when `shop-item-charizard` was one
+ * fiber up.
+ *
+ * So we walk to the fiber that DECLARES `onPress` and take the candidate there.
+ * Stopping at the declaring fiber matters: keep climbing and a row inside a
+ * pressable list resolves to the list.
+ */
+function preferHandlerOwner(match, byFiber) {
+  // Already the owner (or a Switch/TextInput, whose handler is its own).
+  const own = getProps(match.fiber);
+  if (typeof own?.onPress === "function" || typeof own?.onValueChange === "function" || typeof own?.onChangeText === "function") {
+    return match;
+  }
+
+  // 1. Find the fiber that actually declares the handler.
+  let declaring = null;
+  let cur = match.fiber?.return;
+  let depth = 0;
+  while (cur && depth < 25) {
+    if (typeof getProps(cur)?.onPress === "function") {
+      declaring = cur;
+      break;
+    }
+    cur = cur.return;
+    depth++;
+  }
+  if (!declaring) return match;
+
+  // 2. Take the candidate AT that fiber, or the first one above it.
+  //
+  //    Stopping exactly at the declaring fiber isn't enough: a `<Pressable>`
+  //    declares onPress but is de-duped into the component that renders it
+  //    (`PrimaryButton`), and de-duping keeps the OUTERMOST fiber of everything
+  //    sharing a host instance — which is where the testID ends up. Climbing a
+  //    few levels past the handler is what turns "Text: Add to bag" into
+  //    "PrimaryButton [testID=shop-add-to-bag]". The bound keeps a row inside a
+  //    pressable list from resolving to the list.
+  let probe = declaring;
+  for (let i = 0; i < 6 && probe; i++) {
+    const candidate = byFiber.get(probe);
+    if (candidate) return candidate;
+    probe = probe.return;
+  }
+  return match;
+}
+function resolveTouchTarget(nativeTag) {
+  const candidates = collectCandidates();
+  if (candidates.length === 0) return null;
+  const byFiber = new Map();
+  for (const c of candidates) byFiber.set(c.fiber, c);
+
+  // Fast path: the touched host IS a candidate's host.
+  const direct = candidates.find(c => c.nativeTag === nativeTag);
+
+  // Otherwise find the touched fiber and walk up to the nearest candidate. The
+  // touch lands on the deepest host view (the <Text> inside the button), so the
+  // interesting element is almost always an ancestor.
+  let touched = null;
+  if (!direct) {
+    for (const root of getAllFiberRoots()) {
+      traverseFiberTree(root.current, fiber => {
+        if (touched) return;
+        if (fiber.stateNode && getNativeTag(fiber.stateNode) === nativeTag) {
+          touched = fiber;
+        }
+      });
+      if (touched) break;
+    }
+  }
+  let match = direct ?? null;
+  if (!match && touched) {
+    let cur = touched;
+    let depth = 0;
+    // Prefer an ancestor that is actually drivable; fall back to the nearest
+    // named one so an unlabeled tap still records something a human can read.
+    let named = null;
+    while (cur && depth < 25) {
+      const c = byFiber.get(cur);
+      if (c) {
+        if (c.press || c.valueControl || c.textControl) {
+          match = c;
+          break;
+        }
+        if (!named) named = c;
+      }
+      cur = cur.return;
+      depth++;
+    }
+    if (!match) match = named;
+  }
+  if (!match) return null;
+  match = preferHandlerOwner(match, byFiber);
+  if (!match.press && !match.valueControl && !match.textControl) return null;
+  // Buoy's own chrome is not part of the app under test. Without this, the tap
+  // that stops a recording is recorded as its final step.
+  if (isBuoyChrome(match.fiber)) return null;
+  const control = match.valueControl ? match.valueControl.kind : match.textControl ? "text" : "press";
+  return {
+    nativeTag: match.nativeTag,
+    name: match.name,
+    role: match.role,
+    testID: match.testID,
+    label: match.label,
+    text: match.text,
+    control,
+    value: match.valueControl ? match.valueControl.current : match.textControl ? match.textControl.current : undefined
+  };
+}