@keepsnappy/appium-driver 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/src/lists.js

@@ -1,6 +1,6 @@
 import { describeSelector, toSelector } from './selectors.js';
-import { LONG_SCROLL_CAP, LONG_SCROLL_PLANNED, IOS_TOP_EXTRA } from './gestures.js';
-import { COAST_MAX_MS, GestureNotTaken, scrollList, waitCoasted } from './scroll.js';
+import { LONG_SCROLL_CAP, LONG_SCROLL_PLANNED, TOP_STEP, IOS_TOP_EXTRA } from './gestures.js';
+import { COAST_MAX_MS, COAST_POLL_MS, GestureNotTaken, NavigationStuck, rowEdges, rowsUnderList, scrollList, waitCoasted } from './scroll.js';
 /** Default fixed end-pass gesture count. */
 export const END_SCROLLS = 3;
 /** Default end/top cycle count. */
@@ -20,6 +20,10 @@ export const LOOK_POLL_MS = 100;
 export const CHECK_TIMEOUT_MS = 20_000;
 /** Initial visibility wait before trying an indicator or fallback scroll. */
 export const TARGET_SETTLE_MS = 10_000;
+/** A navigation pass that still has not arrived after this long fails (it has no stroke count to end it). */
+export const NAV_MAX_MS = 120_000;
+/** Two navigation strokes in a row that leave the first and last visible rows as they were stop the pass. */
+export const NAV_STUCK_STROKES = 2;
 /** Finds any part of target on screen through a list handle. Logs lookup/frame commands only. */
 async function shownIn(t, listEl, target) {
     const { childOf: _list, ...inList } = toSelector(target);
@@ -36,13 +40,14 @@ async function shownIn(t, listEl, target) {
  * begins at least lookWindowMs (1000) after it; lookPollMs defaults to 100. Optional settle runs before those looks.
  * Logs cmd with the gesture count under field, blind/cap, looks/lookMs, status, duration, optional extra and planned overrun.
  */
-export async function scrollUntilShown(t, { cmd, field, cap, blind = 0, planned, settle, look: once, move, missing, extra = () => ({}), lookWindowMs = LOOK_MS, lookPollMs = LOOK_POLL_MS }) {
+export async function scrollUntilShown(t, { cmd, field, cap, blind = 0, planned, settle, look: once, move, missing, extra = () => ({}), lookWindowMs = LOOK_MS, lookPollMs = LOOK_POLL_MS, soft = false, lookBetweenBlind = false }) {
     await t.ready();
     const start = t.now();
     let moves = 0;
     let looks = 0;
     let lookMs = 0;
     let status = 1;
+    let reached = true;
     try {
         const look = async () => {
             if (settle && moves > 0)
@@ -65,12 +70,36 @@ export async function scrollUntilShown(t, { cmd, field, cap, blind = 0, planned,
                 lookMs += t.now() - at;
             }
         };
+        let shownEarly = false;
         for (; moves < blind; moves++) {
+            // A touch on a list that still coasts stops it (iOS): each blind move waits for the one before to come to rest.
+            if (moves > 0 && settle)
+                await settle();
+            if (moves > 0 && lookBetweenBlind) {
+                looks++;
+                if (await once()) {
+                    shownEarly = true;
+                    break;
+                }
+            }
             await move();
         }
+        if (shownEarly) {
+            status = 0;
+            return moves;
+        }
+        // All of a soft budget sent blind: nothing is left to decide in the step (the navigation pass after it looks).
+        if (soft && blind >= cap && moves >= cap) {
+            status = 0;
+            reached = false;
+            return moves;
+        }
         while (!(await look())) {
             if (moves >= cap) {
-                throw new Error(missing(cap));
+                if (!soft)
+                    throw new Error(missing(cap));
+                reached = false;
+                break;
             }
             await move();
             moves++;
@@ -80,22 +109,29 @@ export async function scrollUntilShown(t, { cmd, field, cap, blind = 0, planned,
     }
     finally {
         const over = planned === undefined ? {} : { extra: Math.max(0, moves - planned) };
-        t.driver.log.push({ ...t.driver.context, cmd, t: t.now(), ms: t.now() - start, status, [field]: moves, blind, cap, looks, lookMs, ...over, ...extra() });
+        t.driver.log.push({ ...t.driver.context, cmd, t: t.now(), ms: t.now() - start, status, [field]: moves, blind, cap, looks, lookMs, ...over, ...(reached ? {} : { reached }), ...extra() });
     }
 }
 /** Platform gesture budget: cap (3), plus iosTopExtra (2) only when returning to the top on iOS. No commands or logs. */
 export const scrollCap = (t, toward, cap = LONG_SCROLL_CAP, iosTopExtra = IOS_TOP_EXTRA) => cap + (t.driver.platform.name === 'ios' && toward === 'top' ? iosTopExtra : 0);
 const iosHold = (t, cache) => t.driver.platform.name === 'ios' ? (cache.hold ??= {}) : undefined;
 /**
- * Long-scrolls list toward a partly visible target; scoped defaults true. Refetches missing/stale list handles before
+ * Brings `target` of `list` into view toward `toward`. Outside a measured step it is a navigation pass (`navigate`: marked `nav`,
+ * the navigation stroke, no gesture cap: it ends on the target found by lookup and the rows at rest, and stops when two strokes
+ * leave the rows as they were; `blind`, `cap`, `planned`, `iosTopExtra` and `used` do not apply). Inside a step its gestures stay
+ * the measured gesture, as below, and nothing is marked `nav`.
+ *
+ * In a step it long-scrolls list toward a partly visible target; scoped defaults true. Refetches missing/stale list handles before
  * moving and rereads the frame before every gesture. A shared cache stores the settled frame, held iOS row and moves used.
  * Defaults: 3 gestures (5 to top on iOS), 2 planned, 20 s frameTimeoutMs, 3 s coast. used subtracts the prior pass budget.
- * A to-top gesture is checked (scrollList `mustMove`); its retry is a logged defect and does not use the budget.
+ * A to-top gesture is checked (scrollList `mustMove`); its retry is a logged defect and does not use the budget. With `soft`, the
+ * cap ends the loop quietly (`reached: false` in the log) where it would throw.
  * Logs fling-to-end/top with flings, blind/cap, looks/lookMs, extra, relists, settled, status and duration, including failures.
  */
-export async function flingUntilShown(t, list, target, toward, { scoped = true, blind = 0, cache = {}, row, used = 0, cap = LONG_SCROLL_CAP, planned = LONG_SCROLL_PLANNED, iosTopExtra = IOS_TOP_EXTRA, frameTimeoutMs = CHECK_TIMEOUT_MS, coastMaxMs = COAST_MAX_MS, lookWindowMs, lookPollMs } = {}) {
+export async function flingUntilShown(t, list, target, toward, { scoped = true, blind = 0, cache = {}, row, used = 0, cap = LONG_SCROLL_CAP, planned = LONG_SCROLL_PLANNED, iosTopExtra = IOS_TOP_EXTRA, frameTimeoutMs = CHECK_TIMEOUT_MS, coastMaxMs = COAST_MAX_MS, lookWindowMs, lookPollMs, soft } = {}) {
     let relists = 0;
     let settled = false;
+    let sent = 0;
     const { childOf: _list, ...anywhere } = toSelector(target);
     const frame = async () => {
         if (!cache.at) {
@@ -104,45 +140,59 @@ export async function flingUntilShown(t, list, target, toward, { scoped = true,
         }
         return cache.at;
     };
+    const look = async () => {
+        const at = await frame();
+        if (!scoped) {
+            // Under the list handle when the rows are there; the target need not be a row (a header): a miss there asks the whole screen.
+            if ((await rowsUnderList(t, row ?? target, cache)) && (await t.driver.findShown(toSelector(anywhere), false, at.el)))
+                return true;
+            return Boolean(await t.driver.findShown(toSelector(anywhere)));
+        }
+        try {
+            if (await shownIn(t, at.el, target)) {
+                return true;
+            }
+        }
+        catch (e) {
+            if (e?.wdError !== 'stale element reference') {
+                throw e;
+            }
+        }
+        cache.at = { ...at, el: await t.waitVisible(list) };
+        relists++;
+        try {
+            return await shownIn(t, cache.at.el, target);
+        }
+        catch (e) {
+            if (e?.wdError !== 'stale element reference') {
+                throw e;
+            }
+            return false;
+        }
+    };
+    if (t.stepDepth === 0 && !t.navigating) {
+        // A navigation stroke coasts far longer than the measured gesture: the pass keeps navigate's own rest bound.
+        await navigate(t, list, toward, { until: look, row: row ?? target, scoped, cache, frameTimeoutMs, label: selectorLabel(target), turnRound: true });
+        return;
+    }
     cache.used = await scrollUntilShown(t, {
         cmd: `fling-to-${toward}`,
-        field: 'flings', lookWindowMs, lookPollMs,
+        field: 'flings', lookWindowMs, lookPollMs, soft,
+        // A to-top gesture with the first row shown can drag a sheet closed (F7): blind to-top gestures stop once it shows.
+        lookBetweenBlind: toward === 'top',
         cap: Math.max(0, scrollCap(t, toward, cap, iosTopExtra) - used),
         planned: Math.max(0, planned - used),
         blind: Math.min(blind, Math.max(0, scrollCap(t, toward, cap, iosTopExtra) - used)),
-        settle: () => waitCoasted(t, row ?? target, scoped ? { sel: list, el: cache.at?.el } : undefined, undefined, coastMaxMs, iosHold(t, cache)),
+        settle: async () => waitCoasted(t, row ?? target, scoped || (await rowsUnderList(t, row ?? target, cache)) ? { sel: list, el: cache.at?.el } : undefined, undefined, coastMaxMs, iosHold(t, cache)),
         extra: () => ({ relists, settled }),
-        async look() {
-            const at = await frame();
-            if (!scoped) {
-                return Boolean(await t.driver.findShown(toSelector(anywhere)));
-            }
-            try {
-                if (await shownIn(t, at.el, target)) {
-                    return true;
-                }
-            }
-            catch (e) {
-                if (e?.wdError !== 'stale element reference') {
-                    throw e;
-                }
-            }
-            cache.at = { ...at, el: await t.waitVisible(list) };
-            relists++;
-            try {
-                return await shownIn(t, cache.at.el, target);
-            }
-            catch (e) {
-                if (e?.wdError !== 'stale element reference') {
-                    throw e;
-                }
-                return false;
-            }
-        },
+        look,
         async move() {
             await frame();
-            // Before a to-top gesture the first row was not shown, so the list has room: the gesture is checked.
-            await scrollList(t, { list, row: row ?? target, scoped }, toward, toward === 'top' ? { cache, mustMove: true, hold: iosHold(t, cache), coastMaxMs } : { cache });
+            // Before a looked-for to-top gesture the first row was not shown, so the list has room: the gesture is checked. Of blind
+            // gestures only the first is: the list may reach its top before the last.
+            const checked = toward === 'top' && (sent === 0 || blind === 0);
+            sent++;
+            await scrollList(t, { list, row: row ?? target, scoped }, toward, toward === 'top' ? { cache, mustMove: checked, hold: iosHold(t, cache), coastMaxMs } : { cache });
         },
         missing: () => `${selectorLabel(target)} not on screen after ${scrollCap(t, toward, cap, iosTopExtra)} long scrolls to the ${toward} of ${selectorLabel(list)}`,
     });
@@ -151,6 +201,99 @@ const selectorLabel = (sel) => {
     const s = toSelector(sel);
     return s.text ?? s.id ?? describeSelector(s);
 };
+/**
+ * A navigation pass: gets `list` toward its top or end until `until` finds the target, with the navigation stroke, between `nav`
+ * markers (`Session.navigation`; never inside a measured step). Before the pass and after each stroke it waits for the list to
+ * come to rest: its first and last row (`rowEdges`) read twice, 300 ms apart, are the same. The pass ends when the target is
+ * found by lookup with the list at rest; toward the end, a stroke that rests with no target waits `pageWaitMs` for one (a page
+ * lands only once the list rests at its loaded end) before the next. No frame test decides arrival. There is no stroke count: when
+ * two strokes in a row leave those rows as they were after the list had moved, the target was passed: the pass turns round once
+ * with `NAV_STROKE.precise` drags; when two strokes leave them as they were again (or the list never moved) it throws `NavigationStuck` (counted in `t.defects.navStuck`; the run
+ * is invalid), and `maxMs` bounds the pass in time. Logs `nav` with toward, strokes, arrived, status and ms, also on failure.
+ */
+export async function navigate(t, list, toward, { until, row, field, scoped = true, cache = {}, pageWaitMs = 0, coastMaxMs, frameTimeoutMs = CHECK_TIMEOUT_MS, maxMs = NAV_MAX_MS, label = selectorLabel(list), catchUp = false, turnRound = false, restBefore = true }) {
+    await t.ready();
+    const start = t.now();
+    const rest = coastMaxMs ?? (t.driver.platform.name === 'ios' ? PAGE_COAST_MAX_MS_IOS : PAGE_COAST_MAX_MS);
+    const spec = { list, row, field, scoped };
+    let strokes = 0;
+    let arrived = false;
+    try {
+        await t.navigation(async () => {
+            if (!cache.at)
+                cache.at = await t.settledFrame(list, frameTimeoutMs);
+            // A stroke coasts several screens: one can carry a mid-list target past the view to the list's edge. Stalled at that edge
+            // with the target unseen, the pass turns round once with drags that move a list less than its own height (no coast).
+            let way = toward;
+            let turned = false;
+            let moved = false;
+            const atRest = async () => {
+                const deadline = t.now() + rest;
+                let reads = 1;
+                for (let last = await rowEdges(t, spec, cache);;) {
+                    await t.driver.sleep(COAST_POLL_MS);
+                    const now = await rowEdges(t, spec, cache);
+                    reads++;
+                    // An empty read (no row found: a list re-rendering as a page lands) is never a rest.
+                    if (now === last && now !== '')
+                        return now;
+                    // The bound is for a list that keeps moving, so it needs at least two comparisons: one read can outlast it on a real
+                    // device (A23 gate, iPhone in TapIn's live room: a row lookup took 6 s, the first read found no row, the second came at 16 s).
+                    if (t.now() >= deadline && reads >= 3)
+                        throw new Error(`${selectorLabel(list)} still moving ${rest} ms ${strokes === 0 ? 'before the first navigation stroke' : 'after a navigation stroke'} toward the ${way}`);
+                    last = now;
+                }
+            };
+            const waitFor = async () => {
+                for (const from = t.now();;) {
+                    if (await until())
+                        return true;
+                    if (t.now() - from >= pageWaitMs)
+                        return false;
+                    await t.driver.sleep(PAGE_POLL_MS);
+                }
+            };
+            // A caller that saw the list at rest (an end step that waited out its coast and its page) takes one read for the stall
+            // baseline instead of two (gate 41000166764: a read is a 2.2 s page source in the live room).
+            let rows = restBefore ? await atRest() : await rowEdges(t, spec, cache);
+            let before = null;
+            let stalled = 0;
+            for (;;) {
+                if (strokes === 0 ? await until() : await waitFor()) {
+                    arrived = true;
+                    return;
+                }
+                if (before !== null)
+                    stalled = rows === before ? stalled + 1 : 0;
+                if (before !== null && rows !== before)
+                    moved = true;
+                // A list no stroke ever moved is stuck as it is; one that moved and then stopped stands at an edge.
+                if (stalled >= NAV_STUCK_STROKES && turnRound && !turned && moved) {
+                    turned = true;
+                    way = toward === 'end' ? 'top' : 'end';
+                    stalled = 0;
+                    before = null;
+                }
+                if (stalled >= NAV_STUCK_STROKES) {
+                    t.defects.navStuck++;
+                    throw new NavigationStuck(`${selectorLabel(list)} did not move after ${NAV_STUCK_STROKES} navigation strokes toward the ${way} (${label} not found; rows ${JSON.stringify(rows.split('\n'))})`);
+                }
+                if (t.now() - start > maxMs)
+                    throw new Error(`${label} not reached after ${maxMs} ms of navigation toward the ${way} of ${selectorLabel(list)}`);
+                before = rows;
+                await scrollList(t, spec, way, { cache, ...(turned ? { precise: true } : {}) });
+                strokes++;
+                rows = await atRest();
+            }
+        });
+    }
+    finally {
+        if (catchUp && strokes > 0)
+            t.defects.navCatchUp++;
+        t.driver.log.push({ ...t.driver.context, cmd: 'nav', t: t.now(), ms: t.now() - start, status: arrived ? 0 : 1, toward, list: selectorLabel(list), strokes, arrived });
+    }
+    return { strokes, arrived, ms: t.now() - start };
+}
 /** Keeps parent scoping only when requested. */
 function shownOf(row, scoped) {
     const { childOf: _list, ...anywhere } = toSelector(row);
@@ -178,17 +321,17 @@ export function passChecked(t, list, target, toward, scoped, cache, row, options
     };
 }
 /** Finds a loaded row without checking its frame; a stale parent is reported to the caller. Logs lookups only. */
-async function rowLoaded(t, list, row, scoped, listEl, field) {
-    const found = await loadedRow(t, list, row, scoped, listEl, field);
+async function rowLoaded(t, list, row, scoped, listEl, field, under) {
+    const found = await loadedRow(t, list, row, scoped, listEl, field, under);
     return found === 'stale' ? found : found !== null;
 }
-async function loadedRow(t, list, row, scoped, listEl, field) {
+async function loadedRow(t, list, row, scoped, listEl, field, under) {
     const { childOf: _list, ...inList } = toSelector(row);
     const all = t.driver.platform.locators(inList);
     const call = field === 'text' ? /textMatches/ : /descriptionMatches/;
     const locators = t.driver.platform.name === 'android' && field ? all.filter(l => call.test(l.value)) : all;
     try {
-        const parent = scoped ? (listEl ?? (await t.waitVisible(list))) : undefined;
+        const parent = scoped ? (listEl ?? (await t.waitVisible(list))) : under;
         for (const { using, value } of locators.length ? locators : all) {
             const el = await t.driver.find(using, value, parent);
             if (el)
@@ -215,26 +358,27 @@ async function rowEndsInside(t, list, listRect, row, scoped, listEl, field) {
     return t.driver.platform.name === 'android' ? r.y + r.height < bottom : r.y + r.height <= bottom;
 }
 /**
- * Performs scrolls (3) end gestures. A gesture with no page marker pauses pauseMs (500). Otherwise it waits for coast
- * (Android 6000 ms, iOS 10000), optionally adds one gesture if beforePages was not reached, then waits pageWaitMs (3000)
- * for the page's first loaded row, polling every pagePollMs (300). A page that has not landed by then while its beforePages
- * row is cut by (or touches) the list's bottom edge gets that one gesture instead, and a new wait; waitMs counts from the
- * last gesture's coast. scoped defaults true; field narrows Android lookups.
+ * Performs scrolls (3) end gestures, exactly that many and no other: a page that has not landed never gets a catch-up gesture
+ * here (a navigation pass outside the step fetches it). A gesture with no page marker pauses pauseMs (500). Otherwise it waits
+ * for coast (Android 6000 ms, iOS 10000), then waitMs (3000) for the page's first loaded row, polling every pagePollMs (300),
+ * counted from the coast. A page that has not landed by then fails the pass, or with `deferPages` is logged as not landed.
+ * scoped defaults true; field narrows Android lookups. `beforePages` is no longer read.
  * The pass is taken to start at the top, so its first gesture is checked (scrollList `mustMove`): one that moved nothing is
  * sent once more and counted in `t.defects`; `unmoved` is 1 then, and 2 when the retry moved nothing either (GestureNotTaken).
- * Logs fling-to-end: flings, supplied pageNumbers (or descriptions), coastMs, waitMs, per-page extra, unmoved, pauseMs, settled,
- * status and duration. Page checks do not require visibility. All limits and frameTimeoutMs (20000) are configurable.
+ * Logs fling-to-end: flings, supplied pageNumbers (or descriptions), coastMs, waitMs, landed (per page), unmoved, pauseMs,
+ * settled, status and duration. Page checks do not require visibility. All limits and frameTimeoutMs (20000) are configurable.
  */
-export async function scrollToEnd(t, list, cache, { pages, pageNumbers, beforePages = [], scoped = true, field, any, scrolls = END_SCROLLS, pauseMs = PAGE_PAUSE_MS, pageWaitMs = PAGE_WAIT_MS, pagePollMs = PAGE_POLL_MS, coastMaxMs = PAGE_COAST_MAX_MS, coastMaxMsIos = PAGE_COAST_MAX_MS_IOS, frameTimeoutMs = CHECK_TIMEOUT_MS }) {
+export async function scrollToEnd(t, list, cache, { pages, pageNumbers, scoped = true, field, any, scrolls = END_SCROLLS, pauseMs = PAGE_PAUSE_MS, pageWaitMs = PAGE_WAIT_MS, pagePollMs = PAGE_POLL_MS, coastMaxMs = PAGE_COAST_MAX_MS, coastMaxMsIos = PAGE_COAST_MAX_MS_IOS, frameTimeoutMs = CHECK_TIMEOUT_MS, deferPages = false }) {
     await t.ready();
     const start = t.now();
     let status = 1;
     let settled = false;
     const coastMs = [];
     const waitMs = [];
-    const extra = [];
+    const landed = [];
     let unmoved = 0;
     const spec = { list, row: any, field, scoped };
+    const coastBound = t.driver.platform.name === 'ios' ? coastMaxMsIos : coastMaxMs;
     try {
         if (!cache.at) {
             cache.at = await t.settledFrame(list, frameTimeoutMs);
@@ -244,7 +388,7 @@ export async function scrollToEnd(t, list, cache, { pages, pageNumbers, beforePa
             // A pass starts at the top, so its first fling has room and is checked.
             let sent;
             try {
-                sent = await scrollList(t, spec, 'end', { cache, hold: iosHold(t, cache), mustMove: i === 0, coastMaxMs: t.driver.platform.name === 'ios' ? coastMaxMsIos : coastMaxMs });
+                sent = await scrollList(t, spec, 'end', { cache, hold: iosHold(t, cache), mustMove: i === 0, coastMaxMs: coastBound });
             }
             catch (e) {
                 if (e instanceof GestureNotTaken)
@@ -259,66 +403,38 @@ export async function scrollToEnd(t, list, cache, { pages, pageNumbers, beforePa
                 continue;
             }
             const coastFrom = t.now();
-            const stopped = await waitCoasted(t, any, scoped ? { sel: list, el: cache.at.el } : undefined, field, (t.driver.platform.name === 'ios' ? coastMaxMsIos : coastMaxMs), iosHold(t, cache));
+            const stopped = await waitCoasted(t, any, scoped || (await rowsUnderList(t, any, cache)) ? { sel: list, el: cache.at.el } : undefined, field, coastBound, iosHold(t, cache));
             coastMs.push(t.now() - coastFrom);
             if (!stopped)
-                throw new Error(`${selectorLabel(list)} still moving ${(t.driver.platform.name === 'ios' ? coastMaxMsIos : coastMaxMs)} ms after a long scroll to the end`);
-            extra.push(0);
-            const before = beforePages[i];
-            let reached = true;
-            if (before && t.driver.platform.name === 'android') {
-                let found = await rowLoaded(t, list, before, scoped, cache.at.el, field);
-                if (found === 'stale' || (found !== true && scoped)) {
-                    cache.at = { ...cache.at, el: await t.waitVisible(list) };
-                    found = await rowLoaded(t, list, before, scoped, cache.at.el, field);
-                }
-                reached = found === true;
-            }
-            else if (before) {
-                reached = await t.isVisible(shownOf(before, scoped));
-            }
-            const again = async () => {
-                extra[i] = 1;
-                await scrollList(t, spec, 'end', { cache });
-                if (!(await waitCoasted(t, any, scoped ? { sel: list, el: cache.at.el } : undefined, field, (t.driver.platform.name === 'ios' ? coastMaxMsIos : coastMaxMs), iosHold(t, cache)))) {
-                    throw new Error(`${selectorLabel(list)} still moving ${(t.driver.platform.name === 'ios' ? coastMaxMsIos : coastMaxMs)} ms after a long scroll to the end`);
-                }
-            };
-            if (!reached)
-                await again();
-            let from = t.now();
+                throw new Error(`${selectorLabel(list)} still moving ${coastBound} ms after a long scroll to the end`);
+            const from = t.now();
             let listEl = cache.at.el;
             let refound = !scoped;
+            let found = false;
             for (;;) {
-                const found = await rowLoaded(t, list, page, scoped, listEl, field);
-                if (found === true)
-                    break;
-                if (found === 'stale' || !refound) {
+                // Unscoped Android rows that sit under the list are looked up under its handle (a whole-screen lookup costs ~4×).
+                const under = !scoped && (await rowsUnderList(t, any, cache)) ? listEl : undefined;
+                found = await rowLoaded(t, list, page, scoped, listEl, field, under);
+                if (found === 'stale' || (found !== true && !refound)) {
                     refound = true;
                     listEl = await t.waitVisible(list);
                     cache.at = { ...cache.at, el: listEl };
-                    if ((await rowLoaded(t, list, page, scoped, listEl, field)) === true)
-                        break;
-                }
-                if (t.now() - from >= pageWaitMs) {
-                    // The app loads a page only once the list rests at its loaded end; a cut last row means it rests short of it.
-                    if (before && !extra[i] && !(await rowEndsInside(t, list, cache.at.rect, before, scoped, listEl, field))) {
-                        await again();
-                        from = t.now();
-                        continue;
-                    }
-                    waitMs.push(t.now() - from);
-                    throw new Error(`${selectorLabel(page)} not loaded ${pageWaitMs} ms after a long scroll to the end of ${selectorLabel(list)}`);
+                    found = await rowLoaded(t, list, page, scoped, listEl, field, under === undefined ? undefined : listEl);
                 }
+                if (found === true || t.now() - from >= pageWaitMs)
+                    break;
                 await t.driver.sleep(pagePollMs);
             }
             waitMs.push(t.now() - from);
+            landed.push(found === true);
+            if (found !== true && !deferPages)
+                throw new Error(`${selectorLabel(page)} not loaded ${pageWaitMs} ms after a long scroll to the end of ${selectorLabel(list)}`);
         }
         status = 0;
     }
     finally {
         const numbers = pageNumbers ?? pages.map(p => describeSelector(toSelector(p)));
-        t.driver.log.push({ ...t.driver.context, cmd: 'fling-to-end', t: t.now(), ms: t.now() - start, status, flings: scrolls, pages: numbers, coastMs, waitMs, extra, unmoved, pauseMs, settled });
+        t.driver.log.push({ ...t.driver.context, cmd: 'fling-to-end', t: t.now(), ms: t.now() - start, status, flings: scrolls, pages: numbers, coastMs, waitMs, landed, unmoved, pauseMs, settled });
     }
 }
 /**
@@ -344,30 +460,84 @@ export function endChecked(t, list, lastPage, scoped, field, { checkTimeoutMs =
     };
 }
 /**
- * Runs cycles (3) end/top measured step pairs with names from stepName(toward, oneBasedCycle). Only cycle one waits for
- * page markers; every end check requires lastPage loaded. Shares frame/row cache and each top pass's budget with its
- * check. frameTimeoutMs feeds the end frame wait; checkTimeoutMs feeds its end check. fling configures top passes/checks. Logs step markers and nested helper summaries.
+ * Runs cycles (3) end/top measured step pairs with names from stepName(toward, oneBasedCycle). Each step sends exactly its
+ * planned controlled gestures, the same in every run: the end step `scrolls` (3) end gestures, the top step 2, the top one looking
+ * before the second (a gesture at the top drags a sheet) and stopping quietly short of the top. Nothing is checked inside a step.
+ * After each step's end marker a navigation pass (`navigate`, marked `nav`, evidence only) finishes the way: to the loaded end
+ * until a lastPage row is loaded (strokes needed there are counted as the harness defect `navCatchUp`), to the top until `first`
+ * shows; the pass ends on lookups and rows at rest, never on frames. Then the end check (lastPage loaded, checkTimeoutMs for the
+ * end check) and the top check (first shown). Only cycle one waits for page markers. Shares the frame/row cache across steps and
+ * passes. frameTimeoutMs feeds the end frame wait. `fling` configures the top step: its `cap` and `iosTopExtra` no longer widen
+ * it. Logs step markers, nav passes and nested helper summaries.
  */
 export async function scrollCycles(t, { list, first, lastPage, cycles = SCROLL_CYCLES, stepName, fling = {}, ...options }) {
     const cache = {};
     const scoped = options.scoped ?? true;
+    const topPlanned = fling.planned ?? TOP_STEP.gestures;
+    const lastLoaded = async () => {
+        const loaded = await rowLoaded(t, list, lastPage, scoped, undefined, options.field);
+        return (loaded === 'stale' ? await rowLoaded(t, list, lastPage, scoped, undefined, options.field) : loaded) === true;
+    };
+    const firstShown = () => t.isVisible(shownOf(first, scoped));
     for (let i = 1; i <= cycles; i++) {
         await t.waitVisible(list);
-        await t.step(stepName('end', i), () => scrollToEnd(t, list, cache, { ...options, pages: i === 1 ? options.pages : [], pageNumbers: i === 1 ? options.pageNumbers : undefined }), endChecked(t, list, lastPage, scoped, options.field, options));
-        await t.step(stepName('top', i), () => flingUntilShown(t, list, first, 'top', { ...fling, scoped, cache, row: options.any }), passChecked(t, list, first, 'top', scoped, cache, options.any, fling));
+        await t.step(stepName('end', i), () => scrollToEnd(t, list, cache, { ...options, pages: i === 1 ? options.pages : [], pageNumbers: i === 1 ? options.pageNumbers : undefined, deferPages: true }));
+        // The end step waited out its last gesture's coast (and page): the list is at rest.
+        await navigate(t, list, 'end', { until: lastLoaded, row: options.any, field: options.field, scoped, cache, pageWaitMs: options.pageWaitMs ?? PAGE_WAIT_MS, label: selectorLabel(lastPage), catchUp: true, restBefore: false });
+        await endChecked(t, list, lastPage, scoped, options.field, options)();
+        await t.step(stepName('top', i), () => flingUntilShown(t, list, first, 'top', { ...fling, scoped, cache, row: options.any, cap: topPlanned, planned: topPlanned, iosTopExtra: 0, blind: topPlanned, used: 0, soft: true }));
+        await navigate(t, list, 'top', { until: firstShown, row: options.any, field: options.field, scoped, cache, coastMaxMs: fling.coastMaxMs, label: selectorLabel(first) });
+        await t.waitAll([{ shown: shownOf(first, scoped) }], fling.checkTimeoutMs ?? CHECK_TIMEOUT_MS);
+    }
+}
+/**
+ * A list paged by a marker at its end ("Show more"), measured the D1 way: per page a step of exactly `gestures` controlled
+ * gestures toward the end (each after the coast of the one before, nothing looked for inside the step), then a navigation pass
+ * outside the step finishes the way to the page's marker, then `onMore`. The measured count is a constant, wherever the list
+ * comes to rest (gate runs 10-30: TapIn's hand-written loop looked before every gesture, audience to-end sent 10/10/8).
+ */
+export async function pagedToEnd(t, { list, row, pages, gestures = 1, more, stepName, onMore, field, scoped = true, coastMaxMs }) {
+    const cache = {};
+    for (let p = 1; p <= pages; p++) {
+        const marker = more(p);
+        await t.waitVisible(list);
+        await t.step(stepName(p), () => flingUntilShown(t, list, marker, 'end', { scoped, cache, row, cap: gestures, planned: gestures, blind: gestures, iosTopExtra: 0, used: 0, soft: true, ...(coastMaxMs ? { coastMaxMs } : {}) }));
+        const { childOf: _list, ...anywhere } = toSelector(marker);
+        await navigate(t, list, 'end', { until: () => t.isVisible(scoped ? marker : anywhere), row, field, scoped, cache, pageWaitMs: PAGE_WAIT_MS, label: selectorLabel(marker) });
+        await onMore(p);
+        // The marker's action loads more rows: the next page starts from a list frame read again.
+        cache.at = undefined;
     }
 }
+/**
+ * The measured way back to the top of a list: a step of TOP_STEP.gestures (2) controlled gestures, fewer only when the first row
+ * already shows after the first (F7: a gesture at the top drags a sheet), then a navigation pass outside the step to the first row.
+ * The same as `scrollCycles`' top half, for lists a journey pages itself (gate runs 10-30: audience to-top sent 6/6/5).
+ */
+export async function topMeasured(t, { list, first, row, stepName, field, scoped = true, coastMaxMs, checkTimeoutMs = CHECK_TIMEOUT_MS }) {
+    const cache = {};
+    const top = TOP_STEP.gestures;
+    await t.waitVisible(list);
+    await t.step(stepName, () => flingUntilShown(t, list, first, 'top', { scoped, cache, row, cap: top, planned: top, iosTopExtra: 0, blind: top, used: 0, soft: true, ...(coastMaxMs ? { coastMaxMs } : {}) }));
+    await navigate(t, list, 'top', { until: () => t.isVisible(shownOf(first, scoped)), row, field, scoped, cache, label: selectorLabel(first) });
+    await t.waitAll([{ shown: shownOf(first, scoped) }], checkTimeoutMs);
+}
 /**
  * Waits settleMs (10000) for target, then taps an optional indicator and/or runs move until visible, at most cap (3)
- * times, coasting on row after each action. Logs cmd (scroll-to-target) with tapped, swipes, extra above planned (2),
- * status and duration. An initially visible target returns without a summary. missing customizes the failure message.
+ * times, coasting on row after each action. Outside a measured step this is a navigation pass: marked `nav`, and the list
+ * gestures `move` sends are the navigation stroke (the pass has no list to read rows on, so `cap` still ends it). Logs cmd
+ * (scroll-to-target) with tapped, swipes, extra above planned (2), status and duration. An initially visible target returns without a summary. missing customizes the failure message.
  */
-export async function scrollToTarget(t, { target, indicator, row, move, settleMs = TARGET_SETTLE_MS, cap = LONG_SCROLL_CAP, planned = LONG_SCROLL_PLANNED, cmd = 'scroll-to-target', missing = n => `${selectorLabel(target)} not on screen after ${n} long scrolls` }) {
+export async function scrollToTarget(t, options) {
+    const { target, settleMs = TARGET_SETTLE_MS } = options;
     try {
         await t.waitVisible(target, settleMs);
         return;
     }
     catch { }
+    await t.navigationUnlessStep(() => bringToTarget(t, options));
+}
+async function bringToTarget(t, { target, indicator, row, move, cap = LONG_SCROLL_CAP, planned = LONG_SCROLL_PLANNED, cmd = 'scroll-to-target', missing = n => `${selectorLabel(target)} not on screen after ${n} long scrolls` }) {
     const start = t.now();
     let swipes = 0;
     let tapped = false;