@keepsnappy/appium-driver 0.1.0-alpha.14 → 0.1.0-alpha.16

package/README.md

@@ -41,3 +41,34 @@ One GC command at the end of every run, after the journey's last step and its re
 ## driver-log.json while the run goes
 
 `<out>/driver-log.json` is rewritten atomically at every top-level step and iteration boundary, so a killed run still leaves a valid log. `status` is `running`, `done`, `terminated` or `error`; `lastStep` names the last step started and `steps` times every step (`ms: null` while one runs). On SIGTERM or SIGINT (the farm's step timeout) the driver flushes the log as `terminated` with the signal, captures the failure screen and source (at most 20 s), ends the session as failed (at most 10 s) and exits 143 or 130, within 45 s in all; a second signal exits at once. `keepsnappy farm run` counts a driver that exits non-zero as infrastructure.
+
+## List and gesture helpers
+
+Import standalone helpers and pass the journey's `Session` (`t`). Selectors, page boundaries and step names come from your journey. Selectors match whole values, so anchor a row label (`^Result 1$`) when another row starts with the same text:
+
+```ts
+import { childOf, id, text, scrollCycles } from '@keepsnappy/appium-driver';
+
+await scrollCycles(t, {
+  list: id('results.list'),
+  first: childOf(text('^Result 1$'), 'results.list'),
+  any: text('Result .*'),
+  pages: [text('^Result 21$'), text('^Result 41$')],
+  pageNumbers: [21, 41],
+  beforePages: [text('^Result 20$'), text('^Result 40$')],
+  lastPage: text('Result (41|42|43)'),
+  field: 'text',
+  scoped: true,
+  stepName: (toward, cycle) => `results.scroll-to-${toward}-${cycle}`,
+});
+```
+
+`longScroll` sends Android native flings at 12000 dp/s (density cached per driver) or iOS 150 ms swipes. `flingUntilShown` stops when any part of the target shows: three gestures maximum, five toward the top on iOS. `scrollUntilShown` exposes the same capped look/move loop for custom checks. `waitCoasted` waits for two matching row frames 300 ms apart (up to 3000 ms); `holdBeforeScroll` captures a row before an iOS gesture so coast checks can reuse its handle.
+
+`scrollToEnd` performs three long scrolls. Each page marker starts a 3000 ms load wait after coast stops (6000 ms Android, 10000 ms iOS); scrolls without a page marker pause 500 ms. Supply `beforePages` to permit exactly one additional fling when the loaded end was missed. `scrollCycles` repeats three end/top pairs, waiting for page markers only in cycle one and checking `lastPage` loaded in every cycle. `pageNumbers` preserves numeric page labels in command summaries; otherwise summaries use selector descriptions. Page sizes and seed data stay in the journey's page selectors. Options expose the counts and timeouts; their defaults are exported constants. `frameTimeoutMs` (20000) bounds the wait for the list frame to stop moving, `checkTimeoutMs` (20000) bounds a step check (`passChecked`, `endChecked`; in `scrollCycles` the top check reads `fling.checkTimeoutMs`), and `lookWindowMs` (1000) is the window in which a look after a gesture is retried. The `lookMs` field in the log stays the cumulative time spent looking.
+
+`passChecked` and `endChecked` create step checks; share a `ListCache` with `flingUntilShown`/`scrollToEnd` for each visit to a list. `passChecked` permits one repair using only the original pass's remaining budget. `scoped: false` searches globally when row selectors are unique. `field: 'text' | 'description'` limits Android row lookups to the attribute the app uses. `rowAlternatives(from, to, format)` builds page-marker alternations from journey data; `rowAtOrBelow` checks whether a row has moved under a boundary. `t.frameOf` and `t.settledFrame` expose the existing stale-safe frame readers for custom mechanics.
+
+`androidScreenScroll` extends an inverted-list fling to the screen edge at 3000 dp/s. `scrollFromDrawnRow` uses that Android path or starts iOS gestures on drawn rows, avoiding masked padding. Toward the top on iOS it starts on the lowest drawn row that ends above `above` (e.g. a composer), chosen by frame: rows in a list's faded top zone pass touches through. Pass `missingMessage` to keep your own error text when no drawn row is found. `scrollToTarget` waits for an initial target, optionally taps a reveal indicator, then uses a caller-supplied move with coast waits and a three-gesture cap. `closeSwipe`, `closeSwipeAt` (window percentages) and `closeSwipeFrom` (element centre) use native Android sheet drags or 400 ms iOS drags. `tapAllAt` sends points in one W3C sequence with a 100 ms hold and 45 ms gap per point.
+
+Helpers log the underlying WebDriver commands; list loops also record gesture counts, checks, durations and failure status. Re-scroll checks emit a `re-scrolled` event. Keep caller-specific log names and error messages by passing `cmd`, `field` and `missing` to the custom loop, or `cmd`/`missing` to `scrollToTarget`.

package/dist/src/browserstack.d.ts

@@ -3,7 +3,7 @@ import type { FetchLike } from './webdriver.js';
 export declare const HUB = "https://hub-cloud.browserstack.com/wd/hub";
 export declare const BS_API = "https://api-cloud.browserstack.com/app-automate";
 export declare const basicAuth: (user: string, key: string) => string;
-/** `bs://` passes through; a file is uploaded, or the recent upload under `customId` is reused. */
+/** `bs://` and `custom_id:` pass through; a file is uploaded, or the recent upload under `customId` is reused. */
 export declare function resolveApp(app: string, customId: string, auth: string, fetchImpl: FetchLike, platform?: Platform): Promise<string>;
 export interface CapsInput {
     appUrl: string;

package/dist/src/browserstack.js

@@ -5,9 +5,9 @@ import { IOS } from './platform.js';
 export const HUB = 'https://hub-cloud.browserstack.com/wd/hub';
 export const BS_API = 'https://api-cloud.browserstack.com/app-automate';
 export const basicAuth = (user, key) => `Basic ${Buffer.from(`${user}:${key}`).toString('base64')}`;
-/** `bs://` passes through; a file is uploaded, or the recent upload under `customId` is reused. */
+/** `bs://` and `custom_id:` pass through; a file is uploaded, or the recent upload under `customId` is reused. */
 export async function resolveApp(app, customId, auth, fetchImpl, platform = IOS) {
-    if (app.startsWith('bs://'))
+    if (app.startsWith('bs://') || app.startsWith('custom_id:'))
         return app;
     const headers = { Authorization: auth };
     if (customId) {

package/dist/src/browserstack.js.map

@@ -1 +1 @@
-{"version":3,"file":"browserstack.js","sourceRoot":"","sources":["../../src/browserstack.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browserstack.js","sourceRoot":"","sources":["../../src/browserstack.ts"],"names":[],"mappings":"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"}

package/dist/src/gestures.d.ts

@@ -0,0 +1,75 @@
+import type { Session } from './session.js';
+import { type SelectorLike } from './selectors.js';
+import type { Rect } from './webdriver.js';
+export type ScrollDirection = 'end' | 'top';
+export interface Point {
+    x: number;
+    y: number;
+}
+/** Default scroll budget; the third gesture is logged as extra. */
+export declare const LONG_SCROLL_CAP = 3;
+export declare const LONG_SCROLL_PLANNED = 2;
+/** Additional iOS gestures allowed when returning to the top. */
+export declare const IOS_TOP_EXTRA = 2;
+/** Native Android fling speeds (dp/s), list fractions, and iOS swipe fractions/duration. */
+export declare const LONG_SCROLL: {
+    readonly android: {
+        readonly from: 0.3;
+        readonly to: 0.85;
+        readonly dpPerSecond: 12000;
+    };
+    readonly androidScreen: {
+        readonly top: readonly [0.1, 0.95];
+        readonly end: readonly [0.9, 0.1];
+        readonly dpPerSecond: 3000;
+    };
+    readonly ios: {
+        readonly end: readonly [0.85, 0.1];
+        readonly top: readonly [0.3, 0.95];
+        readonly ms: 150;
+    };
+};
+export declare const CLOSE_SWIPE_MS = 400;
+export declare const TAP_HOLD_MS = 100;
+export declare const BURST_GAP_MS = 45;
+export declare const ROW_TOP_SWIPE_MS = 400;
+export declare const ROW_TOP_SCREEN_FRACTION = 0.98;
+export declare const ROW_END_SCREEN_FRACTION = 0.1;
+/**
+ * One long scroll inside window rectangle `r`, after readiness. Android sends a native fling at 12000 dp/s over
+ * 30–85% of the list; iOS drags 85→10% to the end or 30→95% to the top in 150 ms. Logs WebDriver commands only.
+ */
+export declare function longScroll(t: Session, r: Rect, toward: ScrollDirection): Promise<void>;
+/**
+ * Android inverted-list scroll extending from `list` to the window at 3000 dp/s. Top: 10% of the list to 95% of the
+ * window, direction up; end: 90% to 10%, direction down. Reads the list frame after readiness; logs commands only.
+ */
+export declare function androidScreenScroll(t: Session, list: SelectorLike, toward: ScrollDirection): Promise<void>;
+/**
+ * Closes a sheet between window points. Android uses native dragGesture; iOS uses a 400 ms drag. Logs commands only.
+ * Does not consume readiness itself; use closeSwipeAt/From when readiness is pending.
+ */
+export declare function closeSwipe(t: Session, from: Point, to: Point): Promise<void>;
+/** Closes a sheet between percentage window points (0–100), after readiness. Logs commands only. */
+export declare function closeSwipeAt(t: Session, [fx, fy]: readonly [number, number], [tx, ty]: readonly [number, number]): Promise<void>;
+/** Closes a sheet from `sel`'s centre to 90% of window height, after readiness. Logs commands only. */
+export declare function closeSwipeFrom(t: Session, sel: SelectorLike): Promise<void>;
+/**
+ * Taps window `points` in one W3C request, then releases actions (release errors are ignored). Each tap holds for
+ * holdMs (100) and pauses gapMs (45). No readiness or element lookup; prepare points before the measured step.
+ * Logs commands only; callers may add their own burst summary.
+ */
+export declare function tapAllAt(t: Session, points: readonly Point[], { holdMs, gapMs }?: {
+    holdMs?: number;
+    gapMs?: number;
+}): Promise<void>;
+/**
+ * Scrolls an inverted list using drawn `row` elements. Android delegates to androidScreenScroll. iOS top starts on the
+ * lowest row whose visible attribute is 'true' and that ends above `above` (or the lowest drawn row when none does or no
+ * `above` is given), chosen by frame, not tree order, dragging to 98% of the screen in 400 ms. End selects the bottommost visible
+ * row, clamps its centre inside `list` when found, and drags to 10% in 150 ms. Fails without a drawn row using missingMessage (default 'no drawn row to scroll from'). Logs commands only.
+ */
+export declare function scrollFromDrawnRow(t: Session, list: SelectorLike, row: SelectorLike, toward: ScrollDirection, { missingMessage, above }?: {
+    missingMessage?: string;
+    above?: SelectorLike;
+}): Promise<void>;

package/dist/src/gestures.js

@@ -0,0 +1,157 @@
+import { toSelector } from './selectors.js';
+/** Default scroll budget; the third gesture is logged as extra. */
+export const LONG_SCROLL_CAP = 3;
+export const LONG_SCROLL_PLANNED = 2;
+/** Additional iOS gestures allowed when returning to the top. */
+export const IOS_TOP_EXTRA = 2;
+/** Native Android fling speeds (dp/s), list fractions, and iOS swipe fractions/duration. */
+export const LONG_SCROLL = {
+    android: { from: 0.3, to: 0.85, dpPerSecond: 12_000 },
+    androidScreen: { top: [0.1, 0.95], end: [0.9, 0.1], dpPerSecond: 3_000 },
+    ios: { end: [0.85, 0.1], top: [0.3, 0.95], ms: 150 },
+};
+export const CLOSE_SWIPE_MS = 400;
+export const TAP_HOLD_MS = 100;
+export const BURST_GAP_MS = 45;
+export const ROW_TOP_SWIPE_MS = 400;
+export const ROW_TOP_SCREEN_FRACTION = 0.98;
+export const ROW_END_SCREEN_FRACTION = 0.1;
+const densities = new WeakMap();
+/** Reads pixels per dp once per driver; logs the native density command and rejects invalid dpi. */
+async function density(t) {
+    if (!densities.has(t.driver)) {
+        const dpi = Number(await t.driver.execute('mobile: getDisplayDensity'));
+        if (!(dpi > 0))
+            throw new Error(`mobile: getDisplayDensity answered ${dpi}, not a density`);
+        densities.set(t.driver, dpi / 160);
+    }
+    return densities.get(t.driver);
+}
+/**
+ * One long scroll inside window rectangle `r`, after readiness. Android sends a native fling at 12000 dp/s over
+ * 30–85% of the list; iOS drags 85→10% to the end or 30→95% to the top in 150 ms. Logs WebDriver commands only.
+ */
+export async function longScroll(t, r, toward) {
+    await t.ready();
+    if (t.driver.platform.name === 'android') {
+        const { from, to, dpPerSecond } = LONG_SCROLL.android;
+        const top = Math.round(r.y + r.height * from);
+        await t.driver.execute('mobile: flingGesture', {
+            left: r.x, top, width: r.width, height: Math.round(r.y + r.height * to) - top,
+            direction: toward === 'end' ? 'down' : 'up', speed: Math.round(dpPerSecond * (await density(t))),
+        });
+    }
+    else {
+        const [from, to] = LONG_SCROLL.ios[toward];
+        const x = Math.round(r.x + r.width / 2);
+        await t.driver.drag({ x, y: Math.round(r.y + r.height * from) }, { x, y: Math.round(r.y + r.height * to) }, LONG_SCROLL.ios.ms);
+    }
+}
+/**
+ * Android inverted-list scroll extending from `list` to the window at 3000 dp/s. Top: 10% of the list to 95% of the
+ * window, direction up; end: 90% to 10%, direction down. Reads the list frame after readiness; logs commands only.
+ */
+export async function androidScreenScroll(t, list, toward) {
+    await t.ready();
+    const r = (await t.frameOf(list, await t.waitVisible(list))).rect;
+    const w = await t.driver.screen();
+    const [inList, onScreen] = LONG_SCROLL.androidScreen[toward];
+    const start = Math.round(r.y + r.height * inList);
+    const end = Math.round(w.height * onScreen);
+    await t.driver.execute('mobile: flingGesture', {
+        left: r.x, top: Math.min(start, end), width: r.width, height: Math.abs(end - start),
+        direction: toward === 'top' ? 'up' : 'down', speed: Math.round(LONG_SCROLL.androidScreen.dpPerSecond * (await density(t))),
+    });
+}
+/**
+ * Closes a sheet between window points. Android uses native dragGesture; iOS uses a 400 ms drag. Logs commands only.
+ * Does not consume readiness itself; use closeSwipeAt/From when readiness is pending.
+ */
+export async function closeSwipe(t, from, to) {
+    if (t.driver.platform.name === 'android') {
+        await t.driver.execute('mobile: dragGesture', { startX: from.x, startY: from.y, endX: to.x, endY: to.y });
+    }
+    else {
+        await t.driver.drag(from, to, CLOSE_SWIPE_MS);
+    }
+}
+/** Closes a sheet between percentage window points (0–100), after readiness. Logs commands only. */
+export async function closeSwipeAt(t, [fx, fy], [tx, ty]) {
+    await t.ready();
+    const w = await t.driver.screen();
+    const pt = (x, y) => ({ x: Math.round(w.width * x / 100), y: Math.round(w.height * y / 100) });
+    await closeSwipe(t, pt(fx, fy), pt(tx, ty));
+}
+/** Closes a sheet from `sel`'s centre to 90% of window height, after readiness. Logs commands only. */
+export async function closeSwipeFrom(t, sel) {
+    await t.ready();
+    const el = await t.waitVisible(sel);
+    const r = await t.driver.cmd('GET', `/element/${el}/rect`);
+    const w = await t.driver.screen();
+    const x = Math.round(r.x + r.width / 2);
+    await closeSwipe(t, { x, y: Math.round(r.y + r.height / 2) }, { x, y: Math.round(w.height * 0.9) });
+}
+/**
+ * Taps window `points` in one W3C request, then releases actions (release errors are ignored). Each tap holds for
+ * holdMs (100) and pauses gapMs (45). No readiness or element lookup; prepare points before the measured step.
+ * Logs commands only; callers may add their own burst summary.
+ */
+export async function tapAllAt(t, points, { holdMs = TAP_HOLD_MS, gapMs = BURST_GAP_MS } = {}) {
+    await t.driver.cmd('POST', '/actions', { actions: [{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: points.flatMap(({ x, y }) => [
+                    { type: 'pointerMove', duration: 0, x, y }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: holdMs },
+                    { type: 'pointerUp', button: 0 }, { type: 'pause', duration: gapMs },
+                ]) }] });
+    await t.driver.cmd('DELETE', '/actions').catch(() => null);
+}
+/**
+ * Scrolls an inverted list using drawn `row` elements. Android delegates to androidScreenScroll. iOS top starts on the
+ * lowest row whose visible attribute is 'true' and that ends above `above` (or the lowest drawn row when none does or no
+ * `above` is given), chosen by frame, not tree order, dragging to 98% of the screen in 400 ms. End selects the bottommost visible
+ * row, clamps its centre inside `list` when found, and drags to 10% in 150 ms. Fails without a drawn row using missingMessage (default 'no drawn row to scroll from'). Logs commands only.
+ */
+export async function scrollFromDrawnRow(t, list, row, toward, { missingMessage = 'no drawn row to scroll from', above } = {}) {
+    if (t.driver.platform.name !== 'ios') {
+        await androidScreenScroll(t, list, toward);
+        return;
+    }
+    await t.ready();
+    const { using, value } = t.driver.platform.locators(toSelector(row))[0];
+    let start = null;
+    if (toward === 'top') {
+        // iOS lists rows outside the visible area too, and a drawn row in the list's faded top zone passes touches through:
+        // start on the lowest drawn row that ends above `above` (or the lowest drawn row), chosen by frame, never by tree order.
+        const limit = above ? (await t.driver.cmd('GET', `/element/${await t.waitVisible(toSelector(above))}/rect`)).y : Infinity;
+        let lowest = null;
+        for (const el of await t.driver.findAll(using, value)) {
+            if ((await t.driver.cmd('GET', `/element/${el}/attribute/visible`)) !== 'true')
+                continue;
+            const r = await t.driver.cmd('GET', `/element/${el}/rect`);
+            if (!lowest || r.y > lowest.y)
+                lowest = r;
+            if (r.y + r.height <= limit && (!start || r.y > start.y))
+                start = r;
+        }
+        start ??= lowest;
+    }
+    else {
+        for (const el of await t.driver.findAll(using, `${value} AND visible == 1`)) {
+            const r = await t.driver.cmd('GET', `/element/${el}/rect`);
+            if (!start || r.y > start.y)
+                start = r;
+        }
+    }
+    if (!start)
+        throw new Error(missingMessage);
+    const w = await t.driver.screen();
+    const x = Math.round(start.x + start.width / 2);
+    let y = Math.round(start.y + start.height / 2);
+    if (toward === 'end') {
+        const listEl = await t.driver.findShown(toSelector(list));
+        if (listEl) {
+            const l = await t.driver.cmd('GET', `/element/${listEl}/rect`);
+            y = Math.min(Math.max(y, l.y + 1), l.y + l.height - 1);
+        }
+    }
+    await t.driver.drag({ x, y }, { x, y: Math.round(w.height * (toward === 'top' ? ROW_TOP_SCREEN_FRACTION : ROW_END_SCREEN_FRACTION)) }, toward === 'top' ? ROW_TOP_SWIPE_MS : LONG_SCROLL.ios.ms);
+}
+//# sourceMappingURL=gestures.js.map

package/dist/src/gestures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gestures.js","sourceRoot":"","sources":["../../src/gestures.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -7,4 +7,6 @@ export { FLUSH_END_RUN_FAILED, FLUSH_ERROR, FLUSH_OFF, FLUSH_NOT_ACKNOWLEDGED, F
 export { loadElements, parseTokensJs, plan, type PlannedRun } from './tokens.js';
 export { runDriver, DRIVER_OPTIONS, type IterationRecord, type RunDeps } from './run.js';
 export { loadJourneyModule, main } from './load.js';
-export { driverVersion, journeyVersion } from './version.js';
+export { DRIVER_NAME, driverVersion, journeyVersion } from './version.js';
+export { longScroll, androidScreenScroll, closeSwipe, closeSwipeAt, closeSwipeFrom, tapAllAt, scrollFromDrawnRow, LONG_SCROLL, LONG_SCROLL_CAP, LONG_SCROLL_PLANNED, IOS_TOP_EXTRA, CLOSE_SWIPE_MS, TAP_HOLD_MS, BURST_GAP_MS, ROW_TOP_SWIPE_MS, ROW_TOP_SCREEN_FRACTION, ROW_END_SCREEN_FRACTION, type ScrollDirection, type Point } from './gestures.js';
+export { rowAlternatives, rowAtOrBelow, scrollUntilShown, waitCoasted, holdBeforeScroll, scrollCap, flingUntilShown, passChecked, scrollToEnd, endChecked, scrollCycles, scrollToTarget, END_SCROLLS, SCROLL_CYCLES, PAGE_PAUSE_MS, PAGE_WAIT_MS, PAGE_POLL_MS, PAGE_COAST_MAX_MS, PAGE_COAST_MAX_MS_IOS, COAST_POLL_MS, COAST_MAX_MS, LOOK_MS, LOOK_POLL_MS, CHECK_TIMEOUT_MS, TARGET_SETTLE_MS, type RowField, type ListHandle, type RowHold, type ListCache, type UntilShownOptions, type FlingUntilShownOptions, type ScrollToEndOptions, type EndCheckOptions, type PassCheckOptions, type ScrollCyclesOptions, type ScrollToTargetOptions } from './lists.js';

package/dist/src/index.js

@@ -7,5 +7,7 @@ export { FLUSH_END_RUN_FAILED, FLUSH_ERROR, FLUSH_OFF, FLUSH_NOT_ACKNOWLEDGED, F
 export { loadElements, parseTokensJs, plan } from './tokens.js';
 export { runDriver, DRIVER_OPTIONS } from './run.js';
 export { loadJourneyModule, main } from './load.js';
-export { driverVersion, journeyVersion } from './version.js';
+export { DRIVER_NAME, driverVersion, journeyVersion } from './version.js';
+export { longScroll, androidScreenScroll, closeSwipe, closeSwipeAt, closeSwipeFrom, tapAllAt, scrollFromDrawnRow, LONG_SCROLL, LONG_SCROLL_CAP, LONG_SCROLL_PLANNED, IOS_TOP_EXTRA, CLOSE_SWIPE_MS, TAP_HOLD_MS, BURST_GAP_MS, ROW_TOP_SWIPE_MS, ROW_TOP_SCREEN_FRACTION, ROW_END_SCREEN_FRACTION } from './gestures.js';
+export { rowAlternatives, rowAtOrBelow, scrollUntilShown, waitCoasted, holdBeforeScroll, scrollCap, flingUntilShown, passChecked, scrollToEnd, endChecked, scrollCycles, scrollToTarget, END_SCROLLS, SCROLL_CYCLES, PAGE_PAUSE_MS, PAGE_WAIT_MS, PAGE_POLL_MS, PAGE_COAST_MAX_MS, PAGE_COAST_MAX_MS_IOS, COAST_POLL_MS, COAST_MAX_MS, LOOK_MS, LOOK_POLL_MS, CHECK_TIMEOUT_MS, TARGET_SETTLE_MS } from './lists.js';
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAmD,MAAM,gBAAgB,CAAC;AAC7G,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAkB,MAAM,YAAY,CAAC;AAC5J,OAAO,EAAE,aAAa,EAA2D,MAAM,cAAc,CAAC;AACtG,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,UAAU,EAAoC,MAAM,eAAe,CAAC;AACtG,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAoC,MAAM,gBAAgB,CAAC;AACrJ,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,SAAS,EAAE,sBAAsB,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAsB,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAA8D,MAAM,cAAc,CAAC;AAC9Q,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,IAAI,EAAmB,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAsC,MAAM,UAAU,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAmD,MAAM,gBAAgB,CAAC;AAC7G,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAkB,MAAM,YAAY,CAAC;AAC5J,OAAO,EAAE,aAAa,EAA2D,MAAM,cAAc,CAAC;AACtG,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,UAAU,EAAoC,MAAM,eAAe,CAAC;AACtG,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAoC,MAAM,gBAAgB,CAAC;AACrJ,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,SAAS,EAAE,sBAAsB,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAsB,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAA8D,MAAM,cAAc,CAAC;AAC9Q,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,IAAI,EAAmB,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAsC,MAAM,UAAU,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,uBAAuB,EAAoC,MAAM,eAAe,CAAC;AAC3V,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,aAAa,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAiP,MAAM,YAAY,CAAC"}

package/dist/src/lists.d.ts

@@ -0,0 +1,182 @@
+import type { Session } from './session.js';
+import { type SelectorLike } from './selectors.js';
+import type { Rect } from './webdriver.js';
+import { type ScrollDirection } from './gestures.js';
+/** Default fixed end-pass gesture count. */
+export declare const END_SCROLLS = 3;
+/** Default end/top cycle count. */
+export declare const SCROLL_CYCLES = 3;
+/** Pause after an end scroll with no page marker. */
+export declare const PAGE_PAUSE_MS = 500;
+/** Page-load budget measured after coasting stops. */
+export declare const PAGE_WAIT_MS = 3000;
+export declare const PAGE_POLL_MS = 300;
+/** Android page-loading coast bound. */
+export declare const PAGE_COAST_MAX_MS = 6000;
+/** iOS page-loading coast bound. */
+export declare const PAGE_COAST_MAX_MS_IOS = 10000;
+export declare const COAST_POLL_MS = 300;
+/** Default non-page coast bound; a timeout returns false rather than failing. */
+export declare const COAST_MAX_MS = 3000;
+export declare const LOOK_MS = 1000;
+export declare const LOOK_POLL_MS = 100;
+/** Default settled-frame and pass-check timeout. */
+export declare const CHECK_TIMEOUT_MS = 20000;
+/** Initial visibility wait before trying an indicator or fallback scroll. */
+export declare const TARGET_SETTLE_MS = 10000;
+export type RowField = 'text' | 'description';
+export interface ListHandle {
+    sel: SelectorLike;
+    el?: string;
+}
+export interface RowHold {
+    el?: string | null;
+}
+/** Mutable frame/row cache for one visit to a list; share it with pass checks to share the gesture budget. */
+export interface ListCache {
+    at?: {
+        el: string;
+        rect: Rect;
+    };
+    hold?: RowHold;
+    used?: number;
+}
+export interface UntilShownOptions {
+    cmd: string;
+    field: string;
+    cap: number;
+    blind?: number;
+    planned?: number;
+    settle?: () => Promise<unknown>;
+    look: () => Promise<boolean>;
+    move: () => Promise<unknown>;
+    missing: (cap: number) => string;
+    extra?: () => Record<string, unknown>;
+    lookWindowMs?: number;
+    lookPollMs?: number;
+}
+export interface FlingUntilShownOptions {
+    scoped?: boolean;
+    blind?: number;
+    cache?: ListCache;
+    row?: SelectorLike;
+    used?: number;
+    cap?: number;
+    planned?: number;
+    iosTopExtra?: number;
+    frameTimeoutMs?: number;
+    coastMaxMs?: number;
+    lookWindowMs?: number;
+    lookPollMs?: number;
+}
+export interface ScrollToEndOptions {
+    pages: readonly SelectorLike[];
+    /** Values for the summary's pages field; defaults to selector descriptions. */
+    pageNumbers?: readonly number[];
+    beforePages?: readonly SelectorLike[];
+    scoped?: boolean;
+    field?: RowField;
+    any: SelectorLike;
+    scrolls?: number;
+    pauseMs?: number;
+    pageWaitMs?: number;
+    pagePollMs?: number;
+    coastMaxMs?: number;
+    coastMaxMsIos?: number;
+    frameTimeoutMs?: number;
+}
+export interface EndCheckOptions {
+    checkTimeoutMs?: number;
+    pagePollMs?: number;
+    scrolls?: number;
+}
+export interface PassCheckOptions extends Omit<FlingUntilShownOptions, 'cache' | 'scoped' | 'row' | 'used'> {
+    checkTimeoutMs?: number;
+}
+export interface ScrollCyclesOptions extends ScrollToEndOptions {
+    checkTimeoutMs?: number;
+    list: SelectorLike;
+    first: SelectorLike;
+    lastPage: SelectorLike;
+    cycles?: number;
+    stepName: (toward: ScrollDirection, cycle: number) => string;
+    fling?: PassCheckOptions;
+}
+export interface ScrollToTargetOptions {
+    target: SelectorLike;
+    row: SelectorLike;
+    indicator?: SelectorLike;
+    move: () => Promise<unknown>;
+    settleMs?: number;
+    cap?: number;
+    planned?: number;
+    cmd?: string;
+    missing?: (cap: number) => string;
+}
+/**
+ * Looks before each move until shown, failing at cap. Blind moves run first. A post-move look retries until a lookup
+ * 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 declare function scrollUntilShown(t: Session, { cmd, field, cap, blind, planned, settle, look: once, move, missing, extra, lookWindowMs, lookPollMs }: UntilShownOptions): Promise<number>;
+/**
+ * Captures a drawn row before a scroll when hold is provided and empty; lookup failures clear the hold. Use for iOS
+ * where visible-row queries during momentum can consume the coast budget. Logs lookup commands only.
+ */
+export declare function holdBeforeScroll(t: Session, row: SelectorLike, list?: ListHandle, field?: RowField, hold?: RowHold): Promise<void>;
+/**
+ * Waits for two matching row frames 300 ms apart, up to maxMs (3000), always attempting at least two reads.
+ * Optional list scopes the row and is re-found at most twice on missing/stale reads; field selects an Android text
+ * attribute. An optional hold reuses one row across calls until stale. Returns false when still moving. Logs commands only.
+ */
+export declare function waitCoasted(t: Session, row: SelectorLike, list?: ListHandle, field?: RowField, maxMs?: number, hold?: RowHold): Promise<boolean>;
+/** Platform gesture budget: cap (3), plus iosTopExtra (2) only when returning to the top on iOS. No commands or logs. */
+export declare const scrollCap: (t: Session, toward: ScrollDirection, cap?: number, iosTopExtra?: number) => number;
+/**
+ * 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.
+ * Logs fling-to-end/top with flings, blind/cap, looks/lookMs, extra, relists, settled, status and duration, including failures.
+ */
+export declare function flingUntilShown(t: Session, list: SelectorLike, target: SelectorLike, toward: ScrollDirection, { scoped, blind, cache, row, used, cap, planned, iosTopExtra, frameTimeoutMs, coastMaxMs, lookWindowMs, lookPollMs }?: FlingUntilShownOptions): Promise<void>;
+/**
+ * Creates a step check. On its first call only, a missing target triggers a re-scroll sharing cache.used; subsequent calls
+ * only wait for visibility (checkTimeoutMs defaults 20000). Logs re-scrolled with toward plus the nested fling summary.
+ * The re-scrolled event carries no ms/status fields. options overrides the original pass's fling settings.
+ */
+export declare function passChecked(t: Session, list: SelectorLike, target: SelectorLike, toward: ScrollDirection, scoped: boolean, cache: ListCache, row?: SelectorLike, options?: PassCheckOptions): () => Promise<void>;
+/**
+ * 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). scoped defaults true; field narrows Android lookups.
+ * Logs fling-to-end: flings, supplied pageNumbers (or descriptions), coastMs, waitMs, per-page extra, pauseMs, settled,
+ * status and duration. Page checks do not require visibility. All limits and frameTimeoutMs (20000) are configurable.
+ */
+export declare function scrollToEnd(t: Session, list: SelectorLike, cache: ListCache, { pages, pageNumbers, beforePages, scoped, field, any, scrolls, pauseMs, pageWaitMs, pagePollMs, coastMaxMs, coastMaxMsIos, frameTimeoutMs }: ScrollToEndOptions): Promise<void>;
+/**
+ * Creates an end-pass check requiring a loaded lastPage row, even off screen. Retries a stale lookup once, then polls
+ * every 300 ms for up to 20000 ms. checkTimeoutMs, pagePollMs and scrolls override the defaults in errors. Logs commands only.
+ */
+export declare function endChecked(t: Session, list: SelectorLike, lastPage: SelectorLike, scoped: boolean, field?: RowField, { checkTimeoutMs, pagePollMs, scrolls }?: EndCheckOptions): () => Promise<void>;
+/**
+ * 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.
+ */
+export declare function scrollCycles(t: Session, { list, first, lastPage, cycles, stepName, fling, ...options }: ScrollCyclesOptions): Promise<void>;
+/**
+ * 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.
+ */
+export declare function scrollToTarget(t: Session, { target, indicator, row, move, settleMs, cap, planned, cmd, missing }: ScrollToTargetOptions): Promise<void>;
+/**
+ * Builds a regex alternation from the inclusive from/to row numbers. The journey supplies row's formatting and regex
+ * escaping; an empty range returns ''. No commands or logs.
+ */
+export declare const rowAlternatives: (from: number, to: number, row: (n: number) => string) => string;
+/**
+ * Whether row is absent from the screen or its top is at/below boundary's top. Reads boundary first, then finds row and
+ * compares its frame. Use as a custom scrollUntilShown look for inverted lists. No readiness wait; logs commands only.
+ */
+export declare function rowAtOrBelow(t: Session, row: SelectorLike, boundary: SelectorLike): Promise<boolean>;