react-native-tapline 1.3.1 → 1.4.0

package/dist/actions.d.ts

@@ -72,12 +72,16 @@ export declare function back(rawParams: unknown): Promise<{
 /**
  * What `press` and `longPress` answer: the element, `closedKeyboard: true` when the keyboard was
  * closed first, and `forced` (the reason word) when `force` let through what the checks refuse.
+ * `scrolled` says the element was off screen and was scrolled into view first (§16.2); on a dry run,
+ * `scrolls` says it would be and `point` is where the touch is expected after the scroll.
  */
 export type PressResult = {
     element: TaplineElement;
     closedKeyboard?: true;
     forced?: string;
     dryRun?: true;
+    scrolled?: true;
+    scrolls?: true;
     point?: {
         x: number;
         y: number;
@@ -112,6 +116,12 @@ export declare function typeText(rawParams: unknown): Promise<{
     closedKeyboard?: true;
     forced?: string;
     dryRun?: true;
+    scrolled?: true;
+    scrolls?: true;
+    point?: {
+        x: number;
+        y: number;
+    };
 } & SettleOutcome>;
 /** What `scroll` answers; `target`, `reached` and `unchanged` only with `to: "target"`. */
 export type ScrollResult = {
@@ -139,6 +149,8 @@ export declare function toggle(rawParams: unknown): Promise<{
     unchanged?: true;
     forced?: string;
     dryRun?: true;
+    scrolled?: true;
+    scrolls?: true;
     point?: {
         x: number;
         y: number;

package/dist/actions.js

@@ -29,6 +29,7 @@ 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 checks_1 = require("./checks");
 const alerts_1 = require("./alerts");
 const fiber_1 = require("./fiber");
@@ -306,6 +307,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
@@ -504,7 +543,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));
@@ -911,25 +950,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);
+        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 +1004,7 @@ async function pressLike(kind, rawParams) {
         if (own)
             callHandler('onPress', own, [pressEvent(actor.node.fiber, frame)]);
     }
-    return { element, ...keyboardNote(closedKeyboard), ...forced, ...(await settleOutcome()) };
+    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) {
@@ -1118,13 +1178,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);
     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);
+        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 +1271,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 +1360,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 +1382,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 +1410,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 +1514,174 @@ 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) {
+    const frame = await (0, inspect_1.measureFiber)(entry.node.fiber);
+    if (frame === null)
+        return {};
+    // 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) {
+    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);
+    }
+    assertSameTarget(entry, found.entry);
+    return found;
+}
+/**
+ * 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
+    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;
+    }
+    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 +1887,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');
+    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);
+        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 +1928,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                                        */