react-native-tapline 1.3.1 → 1.5.0

package/dist/actions.js

@@ -15,10 +15,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;
@@ -29,7 +31,10 @@ const keyboard_1 = require("./keyboard");
 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");
@@ -306,6 +311,44 @@ function notFoundMessage(target) {
             return `nothing on screen at (${target.x}, ${target.y}); look, then pick another target.`;
     }
 }
+/** Where an off-screen frame lies from the screen: `above`, `below`, `left` or `right`; null when any of it is on screen. */
+function sideOffScreen(frame, screen) {
+    if (visiblePart(frame, screen) !== null)
+        return null;
+    if (frame.y + frame.height <= 0)
+        return 'above';
+    if (frame.y >= screen.height)
+        return 'below';
+    if (frame.x + frame.width <= 0)
+        return 'left';
+    return 'right';
+}
+/**
+ * A `not_found`, with up to 3 closest matches when there are any (AGENT-TOOLS 1.12 §16.2):
+ * `Closest: e12 button "Save draft" id=save-draft, e30 text "Saved" (off screen, below).` An element
+ * the list doesn't show gets its ref here, so the agent can use it (refs count on from the highest given).
+ */
+async function notFoundError(snapshot, target) {
+    const base = notFoundMessage(target);
+    if (target.kind !== 'testID' && target.kind !== 'label' && target.kind !== 'text')
+        return new types_1.TaplineError('not_found', base);
+    const pool = inFrontLayer(snapshot.entries.filter((entry) => entry.info.interesting && !entry.tab));
+    const picks = (0, closest_1.closestMatches)(target.kind, target.value, pool.map((entry) => ({ testID: entry.info.testID, label: entry.info.label, text: entry.info.text }))).map((index) => pool[index]);
+    const lines = [];
+    for (const entry of picks) {
+        if (!entry)
+            continue;
+        const { info } = entry;
+        const shown = (0, inspect_1.cutText)(info.text !== '' ? info.text : (info.label ?? ''), 0, inspect_1.MAX_TEXT);
+        const frame = await (0, inspect_1.measureFiber)(entry.node.fiber);
+        const side = frame ? sideOffScreen(frame, snapshot.screen) : null;
+        const line = [(0, inspect_1.refFor)(entry.node.fiber), (0, inspect_1.roleName)(info), shown !== '' ? `"${shown}"` : '', info.testID ? `id=${info.testID}` : '']
+            .filter((part) => part !== '')
+            .join(' ');
+        lines.push(side ? `${line} (off screen, ${side})` : line);
+    }
+    return new types_1.TaplineError('not_found', lines.length > 0 ? `${base} Closest: ${lines.join(', ')}.` : base);
+}
 /**
  * What a `label` target matches: the element's own accessibility label, else its text. iOS forms
  * the label of an element that has none from the text inside it, and Tapwright reads that label, so
@@ -448,7 +491,7 @@ function inFrontLayer(matches) {
     return inAlert.length > 0 ? inAlert : matches;
 }
 /** Resolve a protocol target to exactly one element, or throw not_found / ambiguous. */
-async function resolveTarget(raw, hint) {
+async function resolveTarget(raw, hint, glassOnly = false) {
     const target = parseTarget(raw);
     const snapshot = (0, inspect_1.takeSnapshot)();
     if (target.kind === 'ref') {
@@ -492,7 +535,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) {
@@ -504,7 +554,7 @@ async function resolveTarget(raw, hint) {
     }
     const [only, ...rest] = matches;
     if (!only)
-        throw new types_1.TaplineError('not_found', notFoundMessage(target));
+        throw await notFoundError(snapshot, target);
     if (rest.length > 0) {
         const shown = matches.slice(0, 5);
         throw new types_1.TaplineError('ambiguous', `${matches.length} elements match ${describeTarget(target)}.`, shown.map((entry) => (0, inspect_1.refFor)(entry.node.fiber)), await candidateElements(shown));
@@ -896,7 +946,8 @@ function focusInput(entry, frame) {
 }
 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 { snapshot, entry } = await resolveTarget(params.target, kind, params.noScroll === true);
     if (entry.tab) {
         if (kind === 'longPress')
             throw notActionable('no_action', `${describe(entry)} has no long-press action`);
@@ -911,25 +962,46 @@ async function pressLike(kind, rawParams) {
         const { route: _route, ...outcome } = await back({});
         return { element: (0, inspect_1.toElement)(entry, null), ...outcome };
     }
-    const actor = findActionable(snapshot, entry, kind, false);
     const handlerName = kind === 'press' ? 'onPress' : 'onLongPress';
     const actionName = kind === 'press' ? 'tap' : 'long-press';
-    if (!actor) {
-        if (entry.info.disabled)
-            throw notActionable('disabled', `${describe(entry)} is disabled; ${ENABLE_FIRST}.`);
-        throw notActionable('no_action', `${describe(entry)} has no ${actionName} action`);
-    }
-    if (actor.info.disabled || entry.info.disabled) {
-        throw notActionable('disabled', `${describe(actor)} is disabled; ${ENABLE_FIRST}.`);
-    }
-    // A finger on an input focuses it (AGENT-TOOLS v1.3): an input never answers no_action to a tap.
-    const focusing = kind === 'press' && actor.info.actions.includes('type');
-    const handler = focusing ? null : (0, inspect_1.findHandler)(actor.node, handlerName);
-    if (!handler && !focusing) {
-        throw notActionable('no_action', `${describe(actor)} has no ${actionName} action`);
+    const plan = (snap, picked) => {
+        const found = findActionable(snap, picked, kind, false);
+        if (!found) {
+            if (picked.info.disabled)
+                throw notActionable('disabled', `${describe(picked)} is disabled; ${ENABLE_FIRST}.`);
+            throw notActionable('no_action', `${describe(picked)} has no ${actionName} action`);
+        }
+        if (found.info.disabled || picked.info.disabled) {
+            throw notActionable('disabled', `${describe(found)} is disabled; ${ENABLE_FIRST}.`);
+        }
+        // A finger on an input focuses it (AGENT-TOOLS v1.3): an input never answers no_action to a tap.
+        const isInput = kind === 'press' && found.info.actions.includes('type');
+        const own = isInput ? null : (0, inspect_1.findHandler)(found.node, handlerName);
+        if (!own && !isInput) {
+            throw notActionable('no_action', `${describe(found)} has no ${actionName} action`);
+        }
+        return { actor: found, handler: own, focusing: isInput };
+    };
+    let planned = plan(snapshot, 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, params.noScroll === true);
+        if (reach.scrolled) {
+            const again = await reresolve(planned.actor, kind, params.target);
+            current = again.snapshot;
+            planned = plan(again.snapshot, again.entry);
+            await assertRefoundOnScreen(current, planned.actor, reach);
+        }
     }
+    const { actor, handler, focusing } = planned;
     const { element, frame } = await elementFor(actor);
-    const forced = await checkedOrForced(params.force === true, () => assertReachable(snapshot, actor, frame));
+    if (reach.scrolls)
+        return { element, dryRun: true, scrolls: true, ...(reach.point ? { point: reach.point } : {}), settledMs: 0 };
+    const forced = await checkedAfterScroll(params.force === true, reach, () => assertReachable(current, actor, frame));
     // 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 };
@@ -944,7 +1016,61 @@ async function pressLike(kind, rawParams) {
         if (own)
             callHandler('onPress', own, [pressEvent(actor.node.fiber, frame)]);
     }
-    return { element, ...keyboardNote(closedKeyboard), ...forced, ...(await settleOutcome()) };
+    const second = afterMs === undefined ? undefined : await pressAgain(actor, params, afterMs);
+    return {
+        element,
+        ...(reach.scrolled ? { scrolled: true } : {}),
+        ...keyboardNote(closedKeyboard),
+        ...forced,
+        ...(second !== undefined ? { second } : {}),
+        ...(await settleOutcome()),
+    };
+}
+/** `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;
+        callHandler('onPress', handler, [pressEvent(found.node.fiber, frame)]);
+        return { done: true, afterMs: at };
+    }
+    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 };
+    }
 }
 /** Where a finger would land: the middle of the element (points, rounded). */
 function pointOf(frame) {
@@ -1069,9 +1195,9 @@ async function moveFocusAboveKeyboard(entry) {
 function keyboardNote(closed) {
     return closed ? { closedKeyboard: true } : {};
 }
-async function resolveInput(snapshot, rawTarget) {
+async function resolveInput(snapshot, rawTarget, glassOnly = false) {
     if (rawTarget !== undefined && rawTarget !== null) {
-        const { snapshot: snap, entry } = await resolveTarget(rawTarget, 'type');
+        const { snapshot: snap, entry } = await resolveTarget(rawTarget, 'type', glassOnly);
         const input = findActionable(snap, entry, 'type', true);
         if (!input)
             throw notActionable('no_action', `${describe(entry)} is not an input`);
@@ -1118,13 +1244,44 @@ 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;
-    const { snapshot, entry } = await resolveInput(null, params.target);
+    let { snapshot, entry } = await resolveInput(null, params.target, params.noScroll === true);
     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
+    // call). The input that already has focus is typed into without touching it, so it is not scrolled to.
+    let reach = {};
+    if (params.force !== true)
+        assertNoBlockingAlert(entry);
+    if (params.force !== true && !ownsInstance(entry, keyboard.focusedInput())) {
+        reach = await scrollIntoReach(snapshot, entry, params.dryRun === true, params.noScroll === true);
+        if (reach.scrolled) {
+            let again;
+            try {
+                again = await resolveInput(null, { ref: (0, inspect_1.refFor)(entry.node.fiber) });
+            }
+            catch (error) {
+                // a list unmounted the row while scrolling: find it again by the original target
+                const refind = error instanceof types_1.TaplineError && error.code === 'not_found' ? refindTarget(entry, params.target) : null;
+                if (refind === null)
+                    throw error;
+                again = await resolveInput(null, refind);
+            }
+            assertSameTarget(entry, again.entry);
+            snapshot = again.snapshot;
+            entry = again.entry;
+            if (entry.info.disabled)
+                throw notActionable('disabled', `${describe(entry)} is not editable; ${ENABLE_FIRST}.`);
+            await assertRefoundOnScreen(snapshot, entry, reach);
+        }
+    }
+    if (reach.scrolls) {
+        const { element } = await elementFor(entry);
+        return { element, value: (0, inspect_1.displayText)((0, inspect_1.currentInputValue)(entry.node)), dryRun: true, scrolls: true, ...(reach.point ? { point: reach.point } : {}), settledMs: 0 };
+    }
     // Typing is a tap that focuses the input, then keys: a person couldn't do it where they couldn't tap,
     // so the checks are a tap's, with the same reasons and the same `force`. The input that already has
     // focus is the exception: the keyboard is up for it and a person types without touching it.
-    const forced = await checkedOrForced(params.force === true, async () => {
+    const forced = await checkedAfterScroll(params.force === true, reach, async () => {
         if (ownsInstance(entry, keyboard.focusedInput())) {
             // An alert takes the keyboard away even from the focused input: a person answers it first.
             assertNoBlockingAlert(entry);
@@ -1180,6 +1337,7 @@ async function typeText(rawParams) {
         element: { ...rest, ...(next === '' && placeholder !== undefined ? { placeholder } : {}), value: shown },
         value: shown,
         ...(secure ? { secure: true } : {}),
+        ...(reach.scrolled ? { scrolled: true } : {}),
         ...keyboardNote(closedKeyboard),
         ...forced,
         ...outcome,
@@ -1268,6 +1426,18 @@ async function scrollToTarget(params) {
         throw badParams('to: "target" needs an element (ref, id, label or text), not a point');
     }
     const { snapshot, entry: wanted } = await resolveTarget(raw);
+    const scrollers = scrollersOf(snapshot, wanted);
+    if (params.dryRun === true) {
+        const first = scrollers[0];
+        const target = (await elementFor(wanted)).element;
+        if (!first)
+            return { element: target, target, offset: { x: 0, y: 0 }, moved: false, dryRun: true, settledMs: 0 };
+        return { element: (await elementFor(first)).element, target, offset: { x: 0, y: 0 }, moved: false, dryRun: true, settledMs: 0 };
+    }
+    return scrollEntryIntoView(snapshot, wanted, scrollers);
+}
+/** The scroll views that hold an element, innermost first. */
+function scrollersOf(snapshot, wanted) {
     const scrollers = [];
     for (let p = wanted.node.parent; p >= 0;) {
         const candidate = snapshot.entries[p];
@@ -1278,26 +1448,22 @@ async function scrollToTarget(params) {
             break;
         p = node.parent;
     }
-    if (params.dryRun === true) {
-        const first = scrollers[0];
-        const target = (await elementFor(wanted)).element;
-        if (!first)
-            return { element: target, target, offset: { x: 0, y: 0 }, moved: false, dryRun: true, settledMs: 0 };
-        return { element: (await elementFor(first)).element, target, offset: { x: 0, y: 0 }, moved: false, dryRun: true, settledMs: 0 };
-    }
+    return scrollers;
+}
+/**
+ * How far the element is from clear inside a scroll view, per axis. The area is the part of the
+ * scroll view that is on screen between the bars. A scroll view that is itself out of view (a
+ * list further down the page) has no such part: there the element only has to be inside the
+ * scroll view, and the outer one brings both onto the screen. Without a scroll view the area is
+ * the screen between the bars.
+ */
+function shiftsFor(snapshot, wanted) {
     const { width, height } = snapshot.screen;
     const navBar = (0, inspect_1.nativeNavBar)(snapshot);
     const tabBar = (0, inspect_1.nativeTabBar)(snapshot);
     const clearTop = navBar && !(0, inspect_1.inNavBarHeader)(navBar, wanted.node.fiber) ? navBar.bottom : 0;
     const clearBottom = tabBar ? tabBar.top : height;
-    /**
-     * How far the element is from clear inside a scroll view, per axis. The area is the part of the
-     * scroll view that is on screen between the bars. A scroll view that is itself out of view (a
-     * list further down the page) has no such part: there the element only has to be inside the
-     * scroll view, and the outer one brings both onto the screen. Without a scroll view the area is
-     * the screen between the bars.
-     */
-    const shiftsIn = (frame, area) => {
+    return (frame, area) => {
         let left = Math.max(area?.x ?? 0, 0);
         let right = Math.min(area ? area.x + area.width : width, width);
         let top = Math.max(area?.y ?? 0, clearTop);
@@ -1310,6 +1476,10 @@ async function scrollToTarget(params) {
         }
         return { x: axisShift(frame.x, frame.width, left, right), y: axisShift(frame.y, frame.height, top, bottom) };
     };
+}
+/** The scrolling half of `scroll` with `to: "target"`: scrolls the given scroll views until `wanted` is clear. */
+async function scrollEntryIntoView(snapshot, wanted, scrollers) {
+    const shiftsIn = shiftsFor(snapshot, wanted);
     let settledMs = 0;
     let settleCapMs;
     let scrolled = null;
@@ -1410,6 +1580,184 @@ async function scrollToTarget(params) {
     const { element } = await elementFor(scrolled.entry);
     return { element, target, offset: scrolled.offset, moved: true, reached, ...settle };
 }
+/** The part of a frame that is on the screen, or null when none of it is. */
+function visiblePart(frame, screen) {
+    const left = Math.max(frame.x, 0);
+    const top = Math.max(frame.y, 0);
+    const right = Math.min(frame.x + frame.width, screen.width);
+    const bottom = Math.min(frame.y + frame.height, screen.height);
+    return right <= left || bottom <= top ? null : { x: left, y: top, width: right - left, height: bottom - top };
+}
+/**
+ * An action on an element that is in the tree but entirely off screen scrolls it into view first, clear
+ * of the bars (§16.2). The caller has run the policy check already. The touch checks (covered, behind an
+ * 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, 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;
+    if (partial && !isNotClear(snapshot, entry, frame))
+        return {};
+    const { width, height } = snapshot.screen;
+    const name = describe(entry);
+    const where = `at ${Math.round(frame.x)},${Math.round(frame.y)}; the screen is ${width}x${height}`;
+    const scrollers = scrollersOf(snapshot, entry);
+    if (scrollers.length === 0 && partial)
+        return {};
+    if (scrollers.length === 0) {
+        throw notActionable('off_screen', `${name} is off screen (${where}). It isn't inside a scroll view, so no scroll can bring it on screen; pass force: true to call its handler anyway.`);
+    }
+    if (dry) {
+        const shiftsIn = shiftsFor(snapshot, entry);
+        let predicted = frame;
+        for (const scroller of scrollers) {
+            const [area, state] = await Promise.all([(0, inspect_1.measureFiber)(scroller.node.fiber), measureScrollState(scroller)]);
+            if (!area)
+                continue;
+            const horizontal = (0, inspect_1.findProp)(scroller.node, 'horizontal') === true;
+            const shifts = shiftsIn(predicted, area);
+            const wanted = horizontal ? shifts.x : shifts.y;
+            if (Math.abs(wanted) < 1)
+                continue;
+            let delta = wanted;
+            if (state) {
+                const current = horizontal ? state.offset.x : state.offset.y;
+                const max = horizontal ? state.max.x : state.max.y;
+                delta = Math.max(Math.min(0, current), Math.min(current + wanted, Math.max(max, current))) - current;
+            }
+            predicted = horizontal ? { ...predicted, x: predicted.x - delta } : { ...predicted, y: predicted.y - delta };
+        }
+        if (partial) {
+            return predicted.x === frame.x && predicted.y === frame.y ? {} : { scrolls: true, ...pointOf(visiblePart(predicted, snapshot.screen)) };
+        }
+        const seen = visiblePart(predicted, snapshot.screen);
+        if (seen === null) {
+            throw notActionable('off_screen', `${name} is off screen (${where}), and its scroll view can't bring it on screen: it is as far as it goes; pass force: true to call its handler anyway.`);
+        }
+        return { scrolls: true, ...pointOf(seen) };
+    }
+    let outcome;
+    try {
+        outcome = await scrollEntryIntoView(snapshot, entry, scrollers);
+    }
+    catch (error) {
+        if (partial && error instanceof types_1.TaplineError)
+            return {};
+        throw error;
+    }
+    const after = await (0, inspect_1.measureFiber)(entry.node.fiber);
+    if (partial) {
+        if (!outcome.moved)
+            return {};
+        return after === null ? { scrolled: true, unverified: true } : { scrolled: true };
+    }
+    // A list may have unmounted the row on the way: the caller finds it again, and checks it is on screen.
+    if (after === null && outcome.moved)
+        return { scrolled: true, unverified: true };
+    if (after === null || visiblePart(after, snapshot.screen) === null) {
+        throw notActionable('off_screen', `${name} is off screen (${where}), and scrolling its scroll view${outcome.moved ? '' : ' (already as far as it goes)'} didn't bring it on screen; pass force: true to call its handler anyway.`);
+    }
+    return outcome.moved ? { scrolled: true } : {};
+}
+/** Whether a partly visible element is off the screen edge or under a bar, and would fit clear of them if scrolled. */
+function isNotClear(snapshot, entry, frame) {
+    const navBar = (0, inspect_1.nativeNavBar)(snapshot);
+    const tabBar = (0, inspect_1.nativeTabBar)(snapshot);
+    const clearTop = navBar && !(0, inspect_1.inNavBarHeader)(navBar, entry.node.fiber) ? navBar.bottom : 0;
+    const clearBottom = tabBar ? tabBar.top : snapshot.screen.height;
+    // Taller or wider than the room there is: no scroll makes it clear, so it is left as it is.
+    if (frame.height > clearBottom - clearTop || frame.width > snapshot.screen.width)
+        return false;
+    const shift = shiftsFor(snapshot, entry)(frame, null);
+    return Math.abs(shift.x) >= 1 || Math.abs(shift.y) >= 1;
+}
+/** A target that finds an element again by what it shows: the app's own target, else its id, label or text. */
+function refindTarget(entry, original) {
+    if ((0, types_1.isRecord)(original) && original.ref === undefined && original.x === undefined && original.y === undefined)
+        return original;
+    const { testID, label, text } = entry.info;
+    if (testID)
+        return { testID };
+    if (label)
+        return { label };
+    if (text !== '')
+        return { text };
+    return null;
+}
+/**
+ * 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, checkSame = true) {
+    let found;
+    try {
+        found = await resolveTarget({ ref: (0, inspect_1.refFor)(entry.node.fiber) }, hint);
+    }
+    catch (error) {
+        if (!(error instanceof types_1.TaplineError) || error.code !== 'not_found')
+            throw error;
+        const again = refindTarget(entry, original);
+        if (again === null)
+            throw error;
+        found = await resolveTarget(again, hint);
+    }
+    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) {
+    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) };
+    if (was.name === now.name) {
+        was.name = before.info.text;
+        now.name = after.info.text;
+    }
+    throw new types_1.TaplineError('not_found', `the element changed while the list scrolled (it was ${JSON.stringify(was.name || was.id || "?")}, now ${JSON.stringify(now.name || now.id || "?")}); nothing was touched: look, then try again`);
+}
+/** After an element was found again because it could not be measured: it must now be on screen. */
+async function assertRefoundOnScreen(snapshot, entry, reach) {
+    if (!reach.unverified)
+        return;
+    const frame = await (0, inspect_1.measureFiber)(entry.node.fiber);
+    if (frame === null || visiblePart(frame, snapshot.screen) === null) {
+        throw notActionable('off_screen', `${describe(entry)} is off screen, and scrolling its scroll view didn't bring it on screen; pass force: true to call its handler anyway.`);
+    }
+}
+/** `checkedOrForced`, and a refusal that comes after Tapline scrolled to the element says so. */
+async function checkedAfterScroll(force, reach, check) {
+    try {
+        return await checkedOrForced(force, check);
+    }
+    catch (error) {
+        if (reach.scrolled && error instanceof types_1.TaplineError && error.code === 'not_actionable') {
+            throw new types_1.TaplineError(error.code, `${error.message} (after scrolling to it)`, error.refs, error.candidates);
+        }
+        throw error;
+    }
+}
 async function scroll(rawParams) {
     const params = paramsOf(rawParams);
     const to = params.to;
@@ -1615,18 +1963,40 @@ async function toggle(rawParams) {
     const params = paramsOf(rawParams);
     if (params.value !== undefined && typeof params.value !== 'boolean')
         throw badParams('value must be a boolean');
-    const { snapshot, entry } = await resolveTarget(params.target, 'toggle');
-    const control = findActionable(snapshot, entry, 'toggle', true);
-    if (!control)
-        throw notActionable('no_action', `${describe(entry)} is not a switch`);
-    if (control.info.disabled)
-        throw notActionable('disabled', `${describe(control)} is disabled; ${ENABLE_FIRST}.`);
-    const handler = (0, inspect_1.findHandler)(control.node, 'onValueChange');
-    if (!handler)
-        throw notActionable('no_action', `${describe(control)} is not a switch`);
+    const first = await resolveTarget(params.target, 'toggle', params.noScroll === true);
+    const plan = (snap, picked) => {
+        const found = findActionable(snap, picked, 'toggle', true);
+        if (!found)
+            throw notActionable('no_action', `${describe(picked)} is not a switch`);
+        if (found.info.disabled)
+            throw notActionable('disabled', `${describe(found)} is disabled; ${ENABLE_FIRST}.`);
+        const own = (0, inspect_1.findHandler)(found.node, 'onValueChange');
+        if (!own)
+            throw notActionable('no_action', `${describe(found)} is not a switch`);
+        return { control: found, handler: own };
+    };
+    let snapshot = first.snapshot;
+    let planned = plan(snapshot, first.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 = {};
+    if (params.force !== true) {
+        assertNoBlockingAlert(planned.control);
+        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;
+            planned = plan(snapshot, again.entry);
+            await assertRefoundOnScreen(snapshot, planned.control, reach);
+        }
+    }
+    const { control, handler } = planned;
     const current = control.info.checked === true;
     const next = typeof params.value === 'boolean' ? params.value : !current;
-    const forced = await checkedOrForced(params.force === true, async () => assertReachable(snapshot, control, await (0, inspect_1.measureFiber)(control.node.fiber)));
+    if (reach.scrolls) {
+        const { element } = await elementFor(control);
+        return { element, value: next, dryRun: true, scrolls: true, ...(reach.point ? { point: reach.point } : {}), settledMs: 0 };
+    }
+    const forced = await checkedAfterScroll(params.force === true, reach, async () => assertReachable(snapshot, control, await (0, inspect_1.measureFiber)(control.node.fiber)));
     if (params.dryRun === true) {
         const { element, frame } = await elementFor(control);
         return { element, value: next, dryRun: true, ...pointOf(frame), ...forced, settledMs: 0 };
@@ -1634,13 +2004,13 @@ async function toggle(rawParams) {
     if (typeof params.value === 'boolean' && control.info.checked === params.value) {
         // Already there: a person wouldn't touch it, so the handler isn't called and the keyboard stays.
         const { element } = await elementFor(control);
-        return { element, value: params.value, unchanged: true, settledMs: 0 };
+        return { element, value: params.value, unchanged: true, ...(reach.scrolled ? { scrolled: true } : {}), settledMs: 0 };
     }
     const closedKeyboard = closeKeyboardFor(control);
     callHandler('onValueChange', handler, [next]);
     const outcome = await settleOutcome();
     const { element } = await elementFor(control);
-    return { element: { ...element, checked: next }, value: next, ...keyboardNote(closedKeyboard), ...forced, ...outcome };
+    return { element: { ...element, checked: next }, value: next, ...(reach.scrolled ? { scrolled: true } : {}), ...keyboardNote(closedKeyboard), ...forced, ...outcome };
 }
 /* -------------------------------------------------------------------------- */
 /* openURL / logs / reload / screenshot                                        */
@@ -1742,6 +2112,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')