react-native-tapline 1.4.0 → 1.6.0

package/dist/actions.js

@@ -5,6 +5,7 @@ exports.configureActions = configureActions;
 exports.onActed = onActed;
 exports.settle = settle;
 exports.settleOutcome = settleOutcome;
+exports.beginAction = beginAction;
 exports.parseTarget = parseTarget;
 exports.labelOf = labelOf;
 exports.resolveTarget = resolveTarget;
@@ -15,10 +16,12 @@ exports.longPress = longPress;
 exports.setKeyboardControl = setKeyboardControl;
 exports.typeText = typeText;
 exports.scroll = scroll;
+exports.measureScrollState = measureScrollState;
 exports.toggle = toggle;
 exports.openURL = openURL;
 exports.inspect = inspect;
 exports.audit = audit;
+exports.uxCheck = uxCheck;
 exports.getLogs = getLogs;
 exports.reload = reload;
 exports.screenshotAvailable = screenshotAvailable;
@@ -26,15 +29,21 @@ exports.screenshot = screenshot;
 exports.swipe = swipe;
 const react_native_1 = require("react-native");
 const keyboard_1 = require("./keyboard");
+const guard_1 = require("./guard");
+const network_1 = require("./network");
+const loading_1 = require("./loading");
 const native_1 = require("./native");
 const inspect_1 = require("./inspect");
 const source_1 = require("./source");
 const closest_1 = require("./closest");
+const glassclip_1 = require("./glassclip");
 const checks_1 = require("./checks");
+const uxcheck_1 = require("./uxcheck");
 const alerts_1 = require("./alerts");
 const fiber_1 = require("./fiber");
 const logs_1 = require("./logs");
 const register_1 = require("./register");
+const idle_1 = require("./idle");
 const settle_1 = require("./settle");
 const types_1 = require("./types");
 var inspect_2 = require("./inspect");
@@ -126,14 +135,90 @@ async function sheetProbe() {
     }
     return null;
 }
+/**
+ * Where `startedRequests()` stood when the action began (or when the last settle ended): a request begun after
+ * it is one the action started (F1).
+ */
+let requestMark = 0;
+/** An action is starting: only requests begun from now on count as its own. */
+function beginAction() {
+    requestMark = (0, network_1.startedRequests)();
+}
+const FRAME_MS = 16;
+/** Whether an open or closing sheet hides the app's motion from the SDK. */
+function sheetPresent() {
+    return (0, inspect_1.openModalHosts)().length > 0 || (0, inspect_1.closingModalHosts)().length > 0;
+}
+/** The elements whose positions say the screen has stopped: the acting ones and the outermost. */
+function watchedFibers() {
+    try {
+        const entries = (0, inspect_1.takeSnapshot)().entries;
+        const picked = new Map();
+        for (const entry of [...entries.filter((e) => e.info.actions.length > 0).slice(0, 6), ...entries.slice(0, 6)]) {
+            picked.set(entry.node.index, entry.node.fiber);
+        }
+        return [...picked.values()];
+    }
+    catch {
+        return [];
+    }
+}
+function sameFrame(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return Math.abs(a.x - b.x) <= 1 && Math.abs(a.y - b.y) <= 1 && Math.abs(a.width - b.width) <= 1 && Math.abs(a.height - b.height) <= 1;
+}
+/**
+ * A native push, a Lottie or a gesture-handler sheet moves without a commit or an Animated call, so after the
+ * idle hold the visible positions are read twice, a frame apart. Says which element moved, and whether React
+ * committed in between.
+ */
+async function positionsMoved() {
+    const before = (0, register_1.commitRevision)();
+    const fibers = watchedFibers();
+    const read = () => Promise.all(fibers.map((fiber) => (0, inspect_1.measureFiber)(fiber).catch(() => null)));
+    const first = await read();
+    await new Promise((resolve) => setTimeout(resolve, FRAME_MS));
+    const second = await read();
+    const at = first.findIndex((frame, i) => !sameFrame(frame, second[i] ?? null));
+    return { moving: at >= 0 ? (fibers[at] ?? null) : null, committed: (0, register_1.commitRevision)() !== before };
+}
 async function settleNow() {
     const started = Date.now();
     let capped = false;
     const onCap = () => {
         capped = true;
     };
+    // Know-don't-watch (off unless `knowIdle`): answer when every signal the SDK can see is idle and still.
+    // An open sheet is out of its sight, so that keeps today's window and position poll.
+    let knowSpentMs = 0;
+    if ((0, idle_1.isKnowIdle)() && settings.capMs > 0 && !sheetPresent()) {
+        const known = await (0, idle_1.waitUntilIdle)({ frames: 2, capMs: settings.capMs, requestMark });
+        let moving = null;
+        let steady = !known.usedFallback && !known.capped;
+        if (steady && !sheetPresent()) {
+            const check = await positionsMoved();
+            moving = check.moving;
+            steady = moving === null && !check.committed;
+        }
+        if (!known.usedFallback && !sheetPresent() && (steady || known.capped)) {
+            requestMark = (0, network_1.startedRequests)();
+            const settledMs = Math.max(0, Math.min(settings.capMs, Date.now() - started));
+            return known.capped ? { settledMs, settleCapMs: settings.capMs } : { settledMs };
+        }
+        if (known.capped)
+            onCap();
+        knowSpentMs = Math.max(0, Date.now() - started);
+        // Something moved without a commit: today's poll waits for it to stop.
+        const left = settings.capMs - knowSpentMs;
+        if (moving && left > 0) {
+            await (0, settle_1.waitUntilSteady)(() => (0, inspect_1.measureFiber)(moving), { pollMs: SHEET_POLL_MS, capMs: left, now: Date.now, onCap });
+            knowSpentMs = Math.max(0, Date.now() - started);
+        }
+    }
     await (0, settle_1.waitUntilStill)({
         ...settings,
+        capMs: settings.capMs - knowSpentMs,
         onCommit: (listener) => (0, register_1.onCommit)(() => listener()),
         now: Date.now,
         onCap,
@@ -168,6 +253,7 @@ async function settleNow() {
         }
     }
     const settledMs = Math.max(0, Math.min(settings.capMs, Date.now() - started));
+    requestMark = (0, network_1.startedRequests)();
     return capped && settings.capMs > 0 ? { settledMs, settleCapMs: settings.capMs } : { settledMs };
 }
 function badParams(message) {
@@ -203,6 +289,22 @@ function callHandler(name, handler, args) {
         });
     }
 }
+/**
+ * Calls a press handler as `callHandler` does, but a throw is not an error of the action: a person's tap
+ * on a button whose handler throws still happened. The message goes to the logs and to the answer's facts
+ * (AGENT-TOOLS 1.13 §3). Returns the message, or undefined when the handler didn't throw.
+ */
+function callHandlerCaught(name, handler, args) {
+    try {
+        callHandler(name, handler, args);
+    }
+    catch (error) {
+        const message = error instanceof types_1.TaplineError ? error.message.replace(/^[^:]*threw: /, '') : String(error);
+        console.error(`[tapline] ${name} threw: ${message}`);
+        return message.slice(0, 500);
+    }
+    return undefined;
+}
 function parseTarget(raw) {
     if (!(0, types_1.isRecord)(raw))
         throw badParams('target must be an object such as {"testID":"login"}');
@@ -486,8 +588,38 @@ function inFrontLayer(matches) {
     const inAlert = matches.filter((entry) => inStandInAlert(entry.node.fiber));
     return inAlert.length > 0 ? inAlert : matches;
 }
-/** Resolve a protocol target to exactly one element, or throw not_found / ambiguous. */
-async function resolveTarget(raw, hint) {
+/**
+ * Resolve a protocol target to exactly one element, or throw not_found / ambiguous. A target that isn't there while the screen
+ * is loading (a request in flight, a spinner) is waited for up to the settle cap before `not_found` is answered (AGENT-TOOLS
+ * 1.13 §18.7); the answer after the wait is made from the screen as it is then, so its closest matches are unchanged.
+ */
+async function resolveTarget(raw, hint, glassOnly = false, loadingWait = true) {
+    try {
+        return await resolveNow(raw, hint, glassOnly);
+    }
+    catch (error) {
+        if (!(error instanceof types_1.TaplineError) || error.code !== 'not_found' || !loadingWait || !isNamedTarget(raw) || settings.capMs <= 0)
+            throw error;
+        await (0, loading_1.waitWhileLoading)({
+            requestMark,
+            capMs: settings.capMs,
+            // Anything but `not_found` (ambiguous, covered) means the target has come.
+            isThere: () => resolveNow(raw, hint, glassOnly).then(() => true, (again) => !(again instanceof types_1.TaplineError && again.code === 'not_found')),
+        });
+        return resolveNow(raw, hint, glassOnly);
+    }
+}
+/** A target by id, label or text: the kinds a screen can still be loading. A ref or a point is never waited for. */
+function isNamedTarget(raw) {
+    try {
+        const kind = parseTarget(raw).kind;
+        return kind === 'testID' || kind === 'label' || kind === 'text';
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveNow(raw, hint, glassOnly = false) {
     const target = parseTarget(raw);
     const snapshot = (0, inspect_1.takeSnapshot)();
     if (target.kind === 'ref') {
@@ -531,7 +663,14 @@ async function resolveTarget(raw, hint) {
         }
         return { snapshot, entry: hit };
     }
-    const matches = inFrontLayer(matchEntries(snapshot, target));
+    let matches = inFrontLayer(matchEntries(snapshot, target));
+    // A journey in a user's eyes (§17.1): visible text matches only what shows on the glass, not what a scroll view
+    // clips or the keyboard covers (1.5 review, finding 11).
+    if (glassOnly && target.kind === 'text' && matches.length > 0) {
+        const scrollers = await (0, glassclip_1.measureScrollers)(snapshot);
+        const frames = await Promise.all(matches.map((entry) => (0, inspect_1.measureFiber)(entry.node.fiber)));
+        matches = matches.filter((entry, i) => (0, glassclip_1.visiblePartOnGlass)(snapshot, entry, frames[i] ?? null, scrollers) !== null);
+    }
     if (matches.length === 0)
         await refuseBehindSheet(snapshot, target);
     if (target.index !== undefined) {
@@ -724,7 +863,8 @@ async function assertReachable(snapshot, actor, frame) {
     const name = describe(actor);
     if (right <= left || bottom <= top) {
         throw notActionable('off_screen', `${name} is off screen (at ${Math.round(frame.x)},${Math.round(frame.y)}; the screen is ${width}x${height}). ` +
-            `Scroll to it first ${SCROLL_TO_TARGET_HINT}, or pass force: true to call its handler anyway.`);
+            'It lies in a part of the screen that nothing scrolls (behind a fixed bar, or outside every list); look at the screen, then target something else or report it. ' +
+            'Pass force: true to call its handler anyway.');
     }
     const bar = (0, inspect_1.nativeTabBar)(snapshot);
     const navBar = (0, inspect_1.nativeNavBar)(snapshot);
@@ -933,20 +1073,28 @@ function focusInput(entry, frame) {
             callHandler(key, handler, [pressEvent(entry.node.fiber, frame)]);
     }
 }
+/** The guard a `move` hands to the touch it makes, never part of a plain call. */
+function recipientGuardOf(params) {
+    return params.recipientGuard === undefined ? undefined : (0, guard_1.parseRecipientGuard)(params.recipientGuard);
+}
 async function pressLike(kind, rawParams) {
     const params = paramsOf(rawParams);
-    const { snapshot, entry } = await resolveTarget(params.target, kind);
+    const afterMs = kind === 'press' ? againAfter(params.again) : undefined;
+    const guard = recipientGuardOf(params);
+    const { snapshot, entry } = await resolveTarget(params.target, kind, params.noScroll === true, params.dryRun !== true);
     if (entry.tab) {
         if (kind === 'longPress')
             throw notActionable('no_action', `${describe(entry)} has no long-press action`);
         if (params.dryRun === true)
             return { element: (0, inspect_1.toElement)(entry, null), dryRun: true, settledMs: 0 };
+        (0, guard_1.assertRecipient)(guard, entry);
         selectTab(snapshot, entry.tab);
         return { element: (0, inspect_1.toElement)(entry, null), ...keyboardNote(closeKeyboardFor(entry)), ...(await settleOutcome()) };
     }
     if (entry.navBack) {
         if (params.dryRun === true)
             return { element: (0, inspect_1.toElement)(entry, null), dryRun: true, settledMs: 0 };
+        (0, guard_1.assertRecipient)(guard, entry);
         const { route: _route, ...outcome } = await back({});
         return { element: (0, inspect_1.toElement)(entry, null), ...outcome };
     }
@@ -971,21 +1119,24 @@ async function pressLike(kind, rawParams) {
         return { actor: found, handler: own, focusing: isInput };
     };
     let planned = plan(snapshot, entry);
+    // The element the agent named; a scroll may find it again.
+    let touched = entry;
     // Off screen, in the tree: scroll it into view first (AGENT-TOOLS 1.12 §16.2). The policy ran before this call.
     let reach = {};
     let current = snapshot;
     if (params.force !== true) {
         // What doesn't depend on where the element is comes first: an open alert is answered before anything scrolls.
         assertNoBlockingAlert(planned.actor);
-        reach = await scrollIntoReach(snapshot, planned.actor, params.dryRun === true);
+        reach = await scrollIntoReach(snapshot, planned.actor, params.dryRun === true, params.noScroll === true);
         if (reach.scrolled) {
             const again = await reresolve(planned.actor, kind, params.target);
             current = again.snapshot;
+            touched = again.entry;
             planned = plan(again.snapshot, again.entry);
             await assertRefoundOnScreen(current, planned.actor, reach);
         }
     }
-    const { actor, handler, focusing } = planned;
+    const { actor, handler } = planned;
     const { element, frame } = await elementFor(actor);
     if (reach.scrolls)
         return { element, dryRun: true, scrolls: true, ...(reach.point ? { point: reach.point } : {}), settledMs: 0 };
@@ -993,18 +1144,88 @@ async function pressLike(kind, rawParams) {
     // A dry run (AGENT-TOOLS 1.8 §11.4): every check ran; nothing is touched.
     if (params.dryRun === true)
         return { element, dryRun: true, ...pointOf(frame), ...forced, settledMs: 0 };
+    // The policy checked this very element: refuse when the one that takes the touch is another now (§18.4).
+    (0, guard_1.assertRecipient)(guard, actor);
     const closedKeyboard = closeKeyboardFor(actor);
+    const requestsBefore = (0, network_1.startedRequests)();
+    let threw;
+    // An input with no onPress of its own was only focused: no handler ran, so none is reported.
+    let handled = handler !== null;
     if (handler)
-        callHandler(handlerName, handler, [pressEvent(actor.node.fiber, frame)]);
+        threw = callHandlerCaught(handlerName, handler, [pressEvent(actor.node.fiber, frame)]);
     else {
         // A finger focuses the input and also fires the input's own onPress (not an ancestor's: the
         // input takes the touch).
         focusInput(actor, frame);
         const own = appHandler(actor, 'onPress');
-        if (own)
-            callHandler('onPress', own, [pressEvent(actor.node.fiber, frame)]);
+        if (own) {
+            handled = true;
+            threw = callHandlerCaught('onPress', own, [pressEvent(actor.node.fiber, frame)]);
+        }
+    }
+    // Whose handler it was: the touched element's own, or an ancestor's that took the touch (§3).
+    const facts = !handled ? undefined : (0, fiber_1.sameFiber)(actor.node.fiber, touched.node.fiber)
+        ? { kind: 'own', ...(threw !== undefined ? { threw } : {}) }
+        : { kind: 'parent', element, ...(threw !== undefined ? { threw } : {}) };
+    const second = afterMs === undefined ? undefined : await pressAgain(actor, params, afterMs);
+    const settled = await settleOutcome();
+    return {
+        ...(facts !== undefined ? { handler: facts } : {}),
+        startedRequests: Math.max(0, (0, network_1.startedRequests)() - requestsBefore),
+        element,
+        ...(reach.scrolled ? { scrolled: true } : {}),
+        ...keyboardNote(closedKeyboard),
+        ...forced,
+        ...(second !== undefined ? { second } : {}),
+        ...settled,
+    };
+}
+/** `again`: a second tap this many milliseconds after the first (a stress double tap, AGENT-TOOLS 1.12 §17.4). */
+function againAfter(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 20 || raw > 1000) {
+        throw badParams('again must be milliseconds from 20 to 1000');
+    }
+    return Math.round(raw);
+}
+/**
+ * The second tap of a double tap, made `afterMs` after the first on whatever is there by then, as a finger would
+ * land: the app may have disabled or removed the control (that is the guard against a double submit working).
+ * It goes through the same checks as a tap; a refusal is the answer's `second`, never an error.
+ */
+async function pressAgain(first, params, afterMs) {
+    const started = Date.now();
+    await new Promise((resolve) => setTimeout(resolve, afterMs));
+    try {
+        const again = await reresolve(first, 'press', params.target, false);
+        const found = findActionable(again.snapshot, again.entry, 'press', false);
+        if (!found || found.info.disabled || again.entry.info.disabled) {
+            return { done: false, reason: found ? 'disabled' : 'no_action', afterMs: Date.now() - started };
+        }
+        // The second tap is refused as `changed` when the id, label or text is no longer what the first tap found: a
+        // control that renames itself ("Added 1") and a list row that was recycled are both another element now.
+        if (!sameTarget(first, again.entry))
+            return { done: false, reason: 'changed', afterMs: Date.now() - started };
+        const handler = (0, inspect_1.findHandler)(found.node, 'onPress');
+        if (!handler)
+            return { done: false, reason: 'no_action', afterMs: Date.now() - started };
+        const { frame } = await elementFor(found);
+        if (params.force !== true)
+            await assertReachable(again.snapshot, found, frame);
+        const at = Date.now() - started;
+        // A handler that throws on the second tap was reached: that is the app's failure, not a tap that didn't land.
+        const threw = callHandlerCaught('onPress', handler, [pressEvent(found.node.fiber, frame)]);
+        return threw === undefined ? { done: true, afterMs: at } : { done: true, afterMs: at, threw };
+    }
+    catch (error) {
+        const reason = error instanceof types_1.TaplineError
+            ? error.code === 'not_actionable'
+                ? (error.message.split(':')[0] ?? error.code)
+                : error.code
+            : 'internal';
+        return { done: false, reason, afterMs: Date.now() - started };
     }
-    return { element, ...(reach.scrolled ? { scrolled: true } : {}), ...keyboardNote(closedKeyboard), ...forced, ...(await settleOutcome()) };
 }
 /** Where a finger would land: the middle of the element (points, rounded). */
 function pointOf(frame) {
@@ -1129,9 +1350,9 @@ async function moveFocusAboveKeyboard(entry) {
 function keyboardNote(closed) {
     return closed ? { closedKeyboard: true } : {};
 }
-async function resolveInput(snapshot, rawTarget) {
+async function resolveInput(snapshot, rawTarget, glassOnly = false, loadingWait = true) {
     if (rawTarget !== undefined && rawTarget !== null) {
-        const { snapshot: snap, entry } = await resolveTarget(rawTarget, 'type');
+        const { snapshot: snap, entry } = await resolveTarget(rawTarget, 'type', glassOnly, loadingWait);
         const input = findActionable(snap, entry, 'type', true);
         if (!input)
             throw notActionable('no_action', `${describe(entry)} is not an input`);
@@ -1164,6 +1385,12 @@ function setNativeText(entry, text) {
         }
     }
 }
+function assertFieldKind(entry, kind) {
+    const isSecure = (0, inspect_1.isSecureInput)(entry.node);
+    if (kind !== undefined && (kind === 'secure') !== isSecure) {
+        throw new types_1.TaplineError('bad_params', `${describe(entry)} is ${isSecure ? 'a secure field' : 'not a secure field'}, not a ${kind} field`, undefined, undefined, { secure: isSecure });
+    }
+}
 async function typeText(rawParams) {
     const params = paramsOf(rawParams);
     const submit = params.submit === true;
@@ -1178,7 +1405,13 @@ async function typeText(rawParams) {
         throw badParams('text is required (or pass submit: true)');
     // Deleting from the end edits what is there, so it never replaces the whole text.
     const replace = params.replace !== false && !deleting;
-    let { snapshot, entry } = await resolveInput(null, params.target);
+    const kind = params.kind;
+    if (kind !== undefined && kind !== 'secure' && kind !== 'plain')
+        throw badParams('kind is "secure" or "plain"');
+    let { snapshot, entry } = await resolveInput(null, params.target, params.noScroll === true, params.dryRun !== true);
+    // A test account's value goes only into the kind of field it is for (AGENT-TOOLS 1.13 §18.6). The refusal
+    // comes before anything is typed or scrolled, and says only whether the field is secure, never its text.
+    assertFieldKind(entry, kind);
     if (entry.info.disabled)
         throw notActionable('disabled', `${describe(entry)} is not editable; ${ENABLE_FIRST}.`);
     // Off screen, in the tree: scroll it into view first (AGENT-TOOLS 1.12 §16.2; the policy ran before this
@@ -1187,7 +1420,7 @@ async function typeText(rawParams) {
     if (params.force !== true)
         assertNoBlockingAlert(entry);
     if (params.force !== true && !ownsInstance(entry, keyboard.focusedInput())) {
-        reach = await scrollIntoReach(snapshot, entry, params.dryRun === true);
+        reach = await scrollIntoReach(snapshot, entry, params.dryRun === true, params.noScroll === true);
         if (reach.scrolled) {
             let again;
             try {
@@ -1201,6 +1434,8 @@ async function typeText(rawParams) {
                 again = await resolveInput(null, refind);
             }
             assertSameTarget(entry, again.entry);
+            // A recycled row may hold another kind of field under the same names.
+            assertFieldKind(again.entry, kind);
             snapshot = again.snapshot;
             entry = again.entry;
             if (entry.info.disabled)
@@ -1528,10 +1763,17 @@ function visiblePart(frame, screen) {
  * alert, under a bar) run afterwards, as for any element. Refused as `off_screen`, with the reason, when
  * no scroll can bring it on screen. `dry` predicts the point after the scroll and scrolls nothing.
  */
-async function scrollIntoReach(snapshot, entry, dry) {
+async function scrollIntoReach(snapshot, entry, dry, noScroll = false) {
     const frame = await (0, inspect_1.measureFiber)(entry.node.fiber);
     if (frame === null)
         return {};
+    // A journey in a user's eyes (`noScroll`, §17.1): nothing scrolls by itself. An element wholly off screen is refused.
+    if (noScroll) {
+        // On the glass, not just on screen: a scroll view clips it, the keyboard covers it (1.5 review, finding 11).
+        if ((0, glassclip_1.visiblePartOnGlass)(snapshot, entry, frame, await (0, glassclip_1.measureScrollers)(snapshot)) !== null)
+            return {};
+        throw notActionable('off_screen', `${describe(entry)} is off screen; in a journey nothing scrolls by itself: scroll the way a person would, then try again.`);
+    }
     // Partly on screen (over the edge, or under a bar): scrolled clear too, with one attempt; if that
     // can't be done the action goes on as before and the touch checks decide. Never refused for this.
     const partial = visiblePart(frame, snapshot.screen) !== null;
@@ -1627,7 +1869,7 @@ function refindTarget(entry, original) {
  * The same element after a scroll, from a fresh snapshot (the list may have laid out other rows on the
  * way). When a list unmounted the row, the ref is gone: it is found again by the original target.
  */
-async function reresolve(entry, hint, original) {
+async function reresolve(entry, hint, original, checkSame = true) {
     let found;
     try {
         found = await resolveTarget({ ref: (0, inspect_1.refFor)(entry.node.fiber) }, hint);
@@ -1640,21 +1882,24 @@ async function reresolve(entry, hint, original) {
             throw error;
         found = await resolveTarget(again, hint);
     }
-    assertSameTarget(entry, found.entry);
+    if (checkSame)
+        assertSameTarget(entry, found.entry);
     return found;
 }
+/** The same element by id, label and text, each on its own (a row can keep its id and label while its text changes). */
+function sameTarget(before, after) {
+    return before.info.testID === after.info.testID && before.info.label === after.info.label && before.info.text === after.info.text;
+}
 /**
  * After a scroll the element found again must still be the one the safety check saw: a list that recycles its rows
  * can hand the same component another row ("Continue" becomes "Delete account"). A changed id, label or text is
  * refused before anything is touched (Codex review of 1.4.0).
  */
 function assertSameTarget(before, after) {
-    // id, label and text each on their own: a row can keep its id and accessibility label while its text changes
+    if (sameTarget(before, after))
+        return;
     const was = { id: before.info.testID, name: labelOf(before.info) };
     const now = { id: after.info.testID, name: labelOf(after.info) };
-    const same = was.id === now.id && before.info.label === after.info.label && before.info.text === after.info.text;
-    if (same)
-        return;
     if (was.name === now.name) {
         was.name = before.info.text;
         now.name = after.info.text;
@@ -1709,7 +1954,7 @@ async function scroll(rawParams) {
     let entry;
     let frame = null;
     if (params.target !== undefined && params.target !== null) {
-        const resolved = await resolveTarget(params.target, 'scroll');
+        const resolved = await resolveTarget(params.target, 'scroll', undefined, params.dryRun !== true);
         const scroller = findActionable(resolved.snapshot, resolved.entry, 'scroll', true);
         if (!scroller)
             throw notActionable('no_action', `${describe(resolved.entry)} is not inside a scroll view`);
@@ -1887,7 +2132,7 @@ async function toggle(rawParams) {
     const params = paramsOf(rawParams);
     if (params.value !== undefined && typeof params.value !== 'boolean')
         throw badParams('value must be a boolean');
-    const first = await resolveTarget(params.target, 'toggle');
+    const first = await resolveTarget(params.target, 'toggle', params.noScroll === true, params.dryRun !== true);
     const plan = (snap, picked) => {
         const found = findActionable(snap, picked, 'toggle', true);
         if (!found)
@@ -1905,7 +2150,7 @@ async function toggle(rawParams) {
     let reach = {};
     if (params.force !== true) {
         assertNoBlockingAlert(planned.control);
-        reach = await scrollIntoReach(snapshot, planned.control, params.dryRun === true);
+        reach = await scrollIntoReach(snapshot, planned.control, params.dryRun === true, params.noScroll === true);
         if (reach.scrolled) {
             const again = await reresolve(planned.control, 'toggle', params.target);
             snapshot = again.snapshot;
@@ -1930,6 +2175,7 @@ async function toggle(rawParams) {
         const { element } = await elementFor(control);
         return { element, value: params.value, unchanged: true, ...(reach.scrolled ? { scrolled: true } : {}), settledMs: 0 };
     }
+    (0, guard_1.assertRecipient)(recipientGuardOf(params), control);
     const closedKeyboard = closeKeyboardFor(control);
     callHandler('onValueChange', handler, [next]);
     const outcome = await settleOutcome();
@@ -2036,6 +2282,68 @@ async function audit(rawParams) {
     }
     return { issues, checked: [...types] };
 }
+/** `ux_check {wayBack?, earlier?}` (AGENT-TOOLS 1.12 §17.3): the screen against the usability basics. */
+async function uxCheck(rawParams) {
+    const params = paramsOf(rawParams);
+    if (params.wayBack !== undefined && typeof params.wayBack !== 'boolean')
+        throw badParams('wayBack must be true or false');
+    const earlierRaw = params.earlier;
+    let earlier;
+    if (earlierRaw !== undefined && earlierRaw !== null) {
+        if (!Array.isArray(earlierRaw))
+            throw badParams('earlier must be a list of {label, id?}');
+        earlier = [];
+        for (const item of earlierRaw) {
+            if (!(0, types_1.isRecord)(item) || typeof item.label !== 'string')
+                throw badParams('earlier must be a list of {label, id?}');
+            earlier.push({ label: item.label, ...(typeof item.id === 'string' && item.id !== '' ? { id: item.id } : {}) });
+        }
+    }
+    if (params.glass !== undefined && typeof params.glass !== 'boolean')
+        throw badParams('glass must be true or false');
+    const result = await (0, uxcheck_1.uxScreen)({
+        ...(params.glass === true ? { glass: true } : {}),
+        ...(params.wayBack === true ? { wayBack: true } : {}),
+        ...(earlier !== undefined ? { earlier } : {}),
+    });
+    let sources = [];
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        const fibers = result.findings.flatMap((f) => (f.entry !== null ? [f.entry.node.fiber] : []));
+        try {
+            sources = fibers.length > 0 ? await (0, source_1.sourcesOf)(fibers) : [];
+        }
+        catch {
+            sources = []; // Metro unreachable: the report still stands, without lines
+        }
+    }
+    let next = 0;
+    const issues = [];
+    for (const finding of result.findings) {
+        const source = finding.entry !== null ? sources[next++] : undefined;
+        let element = null;
+        if (finding.entry !== null) {
+            try {
+                element = (await elementFor(finding.entry, finding.frame)).element;
+            }
+            catch {
+                element = null;
+            }
+        }
+        const where = element === null && finding.entry !== null
+            ? whereOf({ type: 'description', entry: finding.entry, frame: finding.frame, problem: '', fix: '' })
+            : null;
+        const location = source?.location ?? null;
+        issues.push({
+            kind: finding.kind,
+            element,
+            ...(where !== null ? { where } : {}),
+            problem: finding.problem,
+            basis: finding.basis,
+            ...(location !== null ? { at: { file: location.file, line: location.line, direct: location.direct } } : {}),
+        });
+    }
+    return { issues, checked: result.checked, choices: result.choices, actions: result.actions };
+}
 async function getLogs(rawParams) {
     const params = paramsOf(rawParams);
     if (params.since !== undefined && typeof params.since !== 'number')