@buoy-gg/highlight-updates 4.0.1 → 4.0.2

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

@@ -0,0 +1,721 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.describeScreen = describeScreen;
+exports.tapElement = tapElement;
+var _reactNative = require("react-native");
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+function getVisibleText(props) {
+  if (!props) return undefined;
+  const pick = v => {
+    if (typeof v === "string") return v.trim() ? v.trim().slice(0, 80) : undefined;
+    // Numeric children are common (counters, badges) — coerce them too.
+    if (typeof v === "number" && Number.isFinite(v)) return String(v);
+    return 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 (then onLongPress) handler at or above a fiber. */
+function findPressHandler(fiber) {
+  let cur = fiber;
+  let depth = 0;
+  let longPress = null;
+  while (cur && depth < 25) {
+    const p = getProps(cur);
+    if (p) {
+      if (typeof p.onPress === "function") return {
+        handler: p.onPress,
+        kind: "onPress"
+      };
+      if (!longPress && typeof p.onLongPress === "function") longPress = p.onLongPress;
+    }
+    cur = cur.return;
+    depth++;
+  }
+  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 = [];
+  const seenInstances = new Set();
+  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;
+      // De-dup: two fibers resolving to the same host instance (e.g. Pressable
+      // and its inner View) collapse to one row — keep the more interactive.
+      if (instance && seenInstances.has(instance)) {
+        const existing = out.find(c => c.instance === instance);
+        if (existing) {
+          if (!existing.press && press) existing.press = press;
+          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;
+          return;
+        }
+      }
+      if (instance) seenInstances.add(instance);
+      out.push({
+        nativeTag: host?.nativeTag ?? null,
+        name,
+        role,
+        testID,
+        label,
+        text,
+        instance,
+        stateNode: host?.stateNode ?? null,
+        fiber,
+        press,
+        valueControl,
+        textControl,
+        rect: null
+      });
+    });
+  }
+  return out;
+}
+async function measureCandidates(candidates) {
+  await Promise.all(candidates.map(async c => {
+    if (c.instance) c.rect = await measureInstance(c.instance);
+  }));
+}
+
+// --- describeScreen -------------------------------------------------------
+
+async function describeScreen() {
+  const candidates = collectCandidates();
+  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;
+      // Skip elements entirely off-screen.
+      if (cy < -screenH * 0.1 || cy > screenH * 1.1 || cx < -screenW * 0.1 || cx > screenW * 1.1) {
+        if (!c.testID) 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),
+      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
+  };
+}
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// --- tapElement -----------------------------------------------------------
+
+function matchScore(c, params) {
+  if (params.nativeTag != null && c.nativeTag === params.nativeTag) return 1000;
+  const q = (params.query ?? params.testID ?? "").trim().toLowerCase();
+  if (!q) return 0;
+  const fields = [c.testID, c.label, c.text, c.name].filter(Boolean).map(s => s.toLowerCase());
+  let best = 0;
+  for (const f of fields) {
+    if (f === q) best = Math.max(best, 100);else if (f.startsWith(q)) best = Math.max(best, 50);else if (f.includes(q)) best = Math.max(best, 25);
+  }
+  // testID exact match should win over a fuzzy name hit.
+  if (params.testID && c.testID && c.testID.toLowerCase() === params.testID.toLowerCase()) {
+    best = Math.max(best, 200);
+  }
+  return best;
+}
+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 = collectCandidates();
+  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
+      }))
+    };
+  }
+  const target = ranked.find(r => isInteractive(r.c)) ?? ranked[0];
+  const c = target.c;
+  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 = 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;
+  if (params.scrollIntoView !== false && c.instance) {
+    const win = _reactNative.Dimensions.get("window");
+    const centerY = c.rect ? c.rect.y + c.rect.height / 2 : null;
+    const offScreen = c.rect == null || centerY < 0 || centerY > win.height;
+    if (offScreen) {
+      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
+  };
+  try {
+    if (c.press) {
+      c.press.handler(makeSyntheticPressEvent(c.rect));
+      return {
+        tapped: true,
+        scrolled,
+        matched: {
+          ...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 {
+        tapped: true,
+        scrolled,
+        matched: {
+          ...base,
+          via: "onValueChange",
+          value: next
+        }
+      };
+    }
+    // textControl
+    const next = params.text ?? (typeof params.value === "string" ? params.value : "");
+    c.textControl.handler(next);
+    return {
+      tapped: true,
+      scrolled,
+      matched: {
+        ...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"
+      }
+    };
+  }
+}