verikun 0.14.0 → 0.16.0

package/dist/drivers/adb.js

@@ -6,6 +6,7 @@ exports.escapeText = escapeText;
 const errors_1 = require("../errors");
 const exec_1 = require("../exec");
 const android_parse_1 = require("../ui/android-parse");
+const viewport_1 = require("../ui/viewport");
 const ADB = process.env.ADB || 'adb';
 const ADB_HINT = 'install the Android platform-tools (`brew install --cask android-platform-tools`), or point ADB at the binary';
 /** Is `adb` present and runnable? Shared by `vk doctor` and AdbDriver.preflight() so
@@ -96,6 +97,11 @@ class AdbDriver {
     platform = 'android';
     requested;
     cachedSerial;
+    /** null = asked and failed. Cached either way: getElements runs on a ~300ms poll
+     *  during auto-wait, and a broken `wm size` must not cost a round-trip every time. */
+    cachedScreen;
+    /** Rotation of the most recent dump — see viewport(). */
+    lastRotation;
     constructor(serial) {
         this.requested = serial;
     }
@@ -178,7 +184,28 @@ class AdbDriver {
         return (0, exec_1.runText)(ADB, this.withSerial(['shell', ...args]), { timeout }).stdout;
     }
     getElements(opts = {}) {
-        return (0, android_parse_1.parseHierarchy)(this.dumpXml(), opts);
+        const xml = this.dumpXml();
+        // Read off the dump we already have: free, and it refreshes every capture, so a
+        // device rotated mid-run is handled without re-asking for the screen size.
+        this.lastRotation = (0, android_parse_1.parseRotation)(xml);
+        return (0, android_parse_1.parseHierarchy)(xml, { ...opts, screen: this.screenOrNull() ?? undefined });
+    }
+    viewport() {
+        const screen = this.screenOrNull();
+        return screen ? (0, viewport_1.viewportFor)(screen, this.lastRotation) : null;
+    }
+    /** screenSize() memoized, failure included — the parser uses it to mark elements
+     *  scrolled out of view, and "we could not tell" must degrade to "all visible". */
+    screenOrNull() {
+        if (this.cachedScreen === undefined) {
+            try {
+                this.cachedScreen = this.screenSize();
+            }
+            catch {
+                this.cachedScreen = null;
+            }
+        }
+        return this.cachedScreen;
     }
     dumpXml() {
         let lastErr = '';

package/dist/drivers/ios.js

@@ -10,6 +10,7 @@ const node_fs_1 = require("node:fs");
 const errors_1 = require("../errors");
 const exec_1 = require("../exec");
 const ios_parse_1 = require("../ui/ios-parse");
+const viewport_1 = require("../ui/viewport");
 // iOS driver. `xcrun simctl` / `devicectl` cover device discovery and — on a
 // simulator — screenshots, app lifecycle, and logs (no extra install needed).
 // Everything interactive (UI hierarchy, tap, type, swipe, keys, screen size) and
@@ -147,6 +148,9 @@ class IdbDriver {
     requested;
     cachedSerial;
     cachedIsSim;
+    /** null = asked and failed. Memoized because screenSize()'s fallback path runs a
+     *  SECOND full hierarchy dump, which auto-wait would otherwise pay every poll. */
+    cachedScreen;
     constructor(device) {
         // 'booted' is a simctl-only alias idb can't address, so treat it as "auto-resolve".
         this.requested = device && device !== 'booted' ? device : undefined;
@@ -250,7 +254,28 @@ class IdbDriver {
     getElements(opts = {}) {
         // `idb ui describe-all` prints the accessibility tree as JSON (array or NDJSON);
         // parseIosHierarchy handles either.
-        return (0, ios_parse_1.parseIosHierarchy)(this.idbText(['ui', 'describe-all'], { timeout: 15000 }), opts);
+        return (0, ios_parse_1.parseIosHierarchy)(this.idbText(['ui', 'describe-all'], { timeout: 15000 }), {
+            ...opts,
+            screen: this.screenOrNull() ?? undefined,
+        });
+    }
+    viewport() {
+        const screen = this.screenOrNull();
+        // No orientation signal from idb, so viewportFor uses the max(w,h) square: exact
+        // on the vertical axis lists scroll on, permissive across it.
+        return screen ? (0, viewport_1.viewportFor)(screen) : null;
+    }
+    /** screenSize() memoized, failure included — see AdbDriver.screenOrNull. */
+    screenOrNull() {
+        if (this.cachedScreen === undefined) {
+            try {
+                this.cachedScreen = this.screenSize();
+            }
+            catch {
+                this.cachedScreen = null;
+            }
+        }
+        return this.cachedScreen;
     }
     screenshot() {
         const tmp = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `verikun-ios-${process.pid}.png`);

package/dist/ui/android-parse.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isInteresting = isInteresting;
+exports.parseRotation = parseRotation;
 exports.parseHierarchy = parseHierarchy;
+const viewport_1 = require("./viewport");
 // Parses uiautomator XML (from `adb shell uiautomator dump`) into normalized
 // Element[]. We hand-roll a tiny tag scanner rather than pulling in an XML
 // dependency: uiautomator output is regular and entity-escaped, so a
@@ -99,6 +101,18 @@ function isInteresting(el) {
         return true;
     return false;
 }
+/**
+ * The dump's `<hierarchy rotation="N">` (Surface.ROTATION_*), or undefined if absent.
+ *
+ * `adb shell wm size` always reports the device's NATURAL orientation, so this is the
+ * only thing in the dump that says whether the coordinates are portrait or landscape.
+ * Exported so the driver can read it off the same XML it just fetched, rather than
+ * paying another round-trip to ask the device which way up it is.
+ */
+function parseRotation(xml) {
+    const m = /<hierarchy\b[^>]*\brotation="(\d+)"/.exec(xml);
+    return m ? Number(m[1]) : undefined;
+}
 function parseHierarchy(xml, opts = {}) {
     const all = [];
     const n = xml.length;
@@ -142,8 +156,13 @@ function parseHierarchy(xml, opts = {}) {
         }
     }
     const result = opts.all ? all : all.filter(isInteresting);
+    // No screen size (the driver could not read one) → nothing is marked, which is
+    // exactly the behaviour before viewport awareness existed.
+    const vp = opts.screen ? (0, viewport_1.screenRect)((0, viewport_1.viewportFor)(opts.screen, parseRotation(xml))) : undefined;
     result.forEach((el, idx) => {
         el.index = idx;
+        if (vp && (0, viewport_1.isOffscreen)(el.bounds, vp))
+            el.offscreen = true;
     });
     return result;
 }

package/dist/ui/format.js

@@ -34,6 +34,10 @@ function formatInline(el) {
         flags.push('selected');
     if (!el.enabled)
         flags.push('disabled');
+    // Shown rather than hidden: the element IS there, just scrolled away — and an
+    // action will scroll it into view. Hiding it would only make the miss mysterious.
+    if (el.offscreen)
+        flags.push('offscreen');
     if (flags.length)
         parts.push(flags.join(','));
     return parts.join(' ');
@@ -67,5 +71,6 @@ function toJsonShape(el) {
         password: el.password || undefined,
         enabled: el.enabled,
         selected: el.selected || undefined,
+        offscreen: el.offscreen || undefined,
     };
 }

package/dist/ui/ios-parse.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IOS_UNREPORTED_STATE = void 0;
 exports.isInteresting = isInteresting;
 exports.parseIosHierarchy = parseIosHierarchy;
+const viewport_1 = require("./viewport");
 // XCUIElementType names (idb `type`) that are meaningful tap targets — used to
 // derive `clickable`, which iOS accessibility does not expose as a flag.
 const TAPPABLE_TYPES = new Set([
@@ -12,6 +14,23 @@ const TAPPABLE_TYPES = new Set([
 const SCROLLABLE_TYPES = new Set(['ScrollView', 'Table', 'TableView', 'CollectionView', 'WebView']);
 const CHECKABLE_TYPES = new Set(['Switch', 'Toggle', 'CheckBox', 'RadioButton']);
 const TEXT_INPUT_TYPES = new Set(['TextField', 'SecureTextField', 'SearchField', 'TextView']);
+/**
+ * State attributes idb does not report, so `Element` can only ever say `false`.
+ *
+ * MEASURED against the Flutter fixture's `@vk_state` screen on an iPhone 17 Pro simulator
+ * (iOS 26.5): a selected and an unselected segment came back byte-identical apart from
+ * label and frame, and a focused text field was indistinguishable from an unfocused one.
+ * The key is not merely unset — `idb ui describe-all` has no such key in its schema at all
+ * (it emits AXFrame, AXLabel, AXUniqueId, AXValue, content_required, custom_actions,
+ * enabled, frame, help, role, role_description, subrole, title, type, and nothing else),
+ * so no app can supply it and there is nothing to derive it from.
+ *
+ * Exported so `--selected` / `--focused` can be REJECTED on iOS rather than silently
+ * matching nothing — a filter that can never match is exactly the false-green failure the
+ * modifier exists to prevent. Keep this list next to the hard-coded `false`s below; if idb
+ * ever starts reporting one, delete it from here in the same change that parses it.
+ */
+exports.IOS_UNREPORTED_STATE = ['selected', 'focused'];
 function str(v) {
     return typeof v === 'string' ? v : v == null ? '' : String(v);
 }
@@ -80,6 +99,7 @@ function buildElement(raw) {
         checkable,
         checked: checkable && isTrue(raw.AXValue),
         focusable: false,
+        // `focused` and `selected` are not derivable — see IOS_UNREPORTED_STATE above.
         focused: false,
         scrollable: SCROLLABLE_TYPES.has(type),
         enabled: raw.enabled === undefined ? true : isTrue(raw.enabled),
@@ -111,8 +131,13 @@ function isInteresting(el) {
 function parseIosHierarchy(jsonText, opts = {}) {
     const all = parseIdbJson(jsonText).map(buildElement);
     const result = opts.all ? all : all.filter(isInteresting);
+    // idb reports no orientation, so viewportFor falls back to the max(w,h) square —
+    // exact vertically (the axis lists scroll on), deliberately permissive across.
+    const vp = opts.screen ? (0, viewport_1.screenRect)((0, viewport_1.viewportFor)(opts.screen)) : undefined;
     result.forEach((el, idx) => {
         el.index = idx;
+        if (vp && (0, viewport_1.isOffscreen)(el.bounds, vp))
+            el.offscreen = true;
     });
     return result;
 }

package/dist/ui/selector.js

@@ -1,19 +1,68 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.STATE_ATTRS = void 0;
 exports.parseSelector = parseSelector;
 exports.matchElements = matchElements;
 exports.resolveOne = resolveOne;
 const errors_1 = require("../errors");
 const format_1 = require("./format");
+/**
+ * The element state a selector can require. Each is TRI-STATE on a Selector:
+ * unset = don't care, `true` = must be, `false` = must NOT be.
+ *
+ * The negative half is not symmetry for its own sake. A segmented control whose
+ * options share one handler *flips* on any tap, so "tap it unless it is already
+ * selected" is the only safe way to land on a known option — and a plan that
+ * cannot say that taps blind, completes either way, and passes having exercised
+ * the opposite mode.
+ */
+exports.STATE_ATTRS = ['enabled', 'selected', 'checked', 'focused'];
+/** Trailing ` --selected` / ` --not-checked` / … on a selector STRING. */
+const STATE_MODIFIER = new RegExp(`\\s+--(not-)?(${exports.STATE_ATTRS.join('|')})\\s*$`, 'i');
+/**
+ * Peel state modifiers off the END of a selector string.
+ *
+ * Flags normally arrive as flags, but a control node's selector has nowhere to put
+ * one: `if-present` / `when` / `repeat` / `while-present` / `read` all hold a bare
+ * `selector: string` (and `swipe --on` is a flag value). Guards are exactly where
+ * "tap it only if it is not already selected" needs to be expressed, so the string
+ * itself carries them and every caller converges on this one parser:
+ *
+ *     if-present "id:mode_video --not-selected" { tap id:mode_video }
+ *
+ * Only these modifiers, only at the end, and only after whitespace — so `text:--selected`
+ * and `text:a --selected b` are still plain values. A `text:` value that genuinely ENDS
+ * in " --selected" would be misread; use `--contains` on a shorter substring if you ever
+ * meet one. Note the engine interpolates `{{ctx.…}}` before parsing, so a value captured
+ * by `read` could in principle end in a modifier — end-anchoring plus the required space
+ * is what keeps that from being a practical concern.
+ */
+function splitStateModifiers(raw) {
+    const state = {};
+    let rest = raw;
+    for (;;) {
+        const m = STATE_MODIFIER.exec(rest);
+        if (!m)
+            return { rest, state };
+        const attr = m[2].toLowerCase();
+        const want = !m[1];
+        if (state[attr] !== undefined && state[attr] !== want) {
+            throw new errors_1.CliError(`Selector '${raw}' asks for both --${attr} and --not-${attr}.`, 2);
+        }
+        state[attr] = want;
+        rest = rest.slice(0, m.index);
+    }
+}
 function parseSelector(raw, opts = {}) {
+    const { rest, state } = splitStateModifiers(raw);
     let kind = 'text';
-    let value = raw;
-    if (raw.startsWith('@')) {
+    let value = rest;
+    if (rest.startsWith('@')) {
         kind = 'id';
-        value = raw.slice(1);
+        value = rest.slice(1);
     }
     else {
-        const m = /^(id|text|desc|class):([\s\S]*)$/.exec(raw);
+        const m = /^(id|text|desc|class):([\s\S]*)$/.exec(rest);
         if (m) {
             kind = m[1];
             value = m[2];
@@ -21,20 +70,35 @@ function parseSelector(raw, opts = {}) {
     }
     if (!value)
         throw new errors_1.CliError(`Empty selector value in '${raw}'`, 2);
-    return { kind, value, contains: !!opts.contains, index: opts.index, enabled: opts.enabled, raw };
+    const sel = { kind, value, contains: !!opts.contains, index: opts.index, raw };
+    for (const attr of exports.STATE_ATTRS) {
+        // An explicit flag beats one embedded in the string; absent means absent, not false.
+        const want = opts[attr] !== undefined ? opts[attr] : state[attr];
+        if (want !== undefined)
+            sel[attr] = want;
+    }
+    return sel;
 }
-/** Is this element actionable right now?
+/** Keep only elements whose state matches every attribute the selector pins.
  *
- *  Just `enabled` — the a11y attribute, matching what Maestro's `enabled: true` means.
- *  An earlier version also required `clickable || longClickable`, reasoning that a
- *  disabled Button might report clickable=false. That was speculation and it was wrong in
- *  the direction that hurts: plenty of legitimate tap targets are CONTAINERS whose own
- *  clickable flag is false (the tappable child is inside), so the extra conjunct filtered
- *  out real elements and turned `--enabled` into a source of phantom "not found" misses —
- *  which then burned model repairs. Prefer under-filtering here: a tap on a present-but-
- *  odd element fails loudly, whereas a selector that silently matches nothing looks like
- *  app drift and sends the heal loop chasing it. */
-const isActionable = (e) => e.enabled;
+ *  Each predicate is exactly the one a11y attribute and nothing else — `--enabled` is
+ *  `enabled`, matching what Maestro's `enabled: true` means. An earlier version also
+ *  required `clickable || longClickable`, reasoning that a disabled Button might report
+ *  clickable=false. That was speculation and it was wrong in the direction that hurts:
+ *  plenty of legitimate tap targets are CONTAINERS whose own clickable flag is false (the
+ *  tappable child is inside), so the extra conjunct filtered out real elements and turned
+ *  `--enabled` into a source of phantom "not found" misses — which then burned model
+ *  repairs. Prefer under-filtering here: a tap on a present-but-odd element fails loudly,
+ *  whereas a selector that silently matches nothing looks like app drift and sends the
+ *  heal loop chasing it. Same rule for any attribute added to STATE_ATTRS — do not
+ *  strengthen a predicate with a conjunct the platform reports unreliably (`--not-checked`
+ *  deliberately does NOT also require `checkable`). */
+function filterByState(elements, sel) {
+    const pinned = exports.STATE_ATTRS.filter((attr) => sel[attr] !== undefined);
+    if (pinned.length === 0)
+        return elements;
+    return elements.filter((el) => pinned.every((attr) => el[attr] === sel[attr]));
+}
 const norm = (s) => s.trim().toLowerCase();
 const strip = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '');
 /** The ordered match tiers for a selector. First tier with a hit wins. */
@@ -91,8 +155,7 @@ function tiers(sel) {
 function matchElements(elements, sel) {
     // Applied BEFORE the tier ladder, not after: filtering the candidate pool keeps a
     // disabled exact match from shadowing an enabled partial one.
-    if (sel.enabled)
-        elements = elements.filter(isActionable);
+    elements = filterByState(elements, sel);
     for (const { tier, test } of tiers(sel)) {
         const found = elements.filter(test);
         if (found.length === 0)

package/dist/ui/state-support.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unsupportedStateAttrs = unsupportedStateAttrs;
+exports.assertStateSupported = assertStateSupported;
+const errors_1 = require("../errors");
+const selector_1 = require("./selector");
+const ios_parse_1 = require("./ios-parse");
+// Which state attributes a platform's accessibility backend can actually answer for.
+//
+// A state modifier narrows the candidate pool, so one the platform never populates does
+// not fail — it matches NOTHING, quietly, after burning the full auto-wait window, and
+// then reports "No element matched selector", which is a claim about the screen that
+// isn't true. That is the same false-signal failure mode `--selected` was added to fix,
+// so it is refused here instead: an unsupported modifier is an environment error (exit
+// 3), the way `clearApp` and `currentApp` already refuse on iOS rather than pretending.
+//
+// This is a capability table, not device I/O — the per-platform truth lives with the
+// parser that hard-codes the value (see IOS_UNREPORTED_STATE), so the two cannot drift.
+const UNREPORTED = {
+    android: [], // uiautomator dumps all four as real node attributes
+    ios: ios_parse_1.IOS_UNREPORTED_STATE,
+};
+/** State attributes this selector pins that the platform cannot report. */
+function unsupportedStateAttrs(sel, platform) {
+    const blind = UNREPORTED[platform];
+    if (blind.length === 0)
+        return [];
+    return selector_1.STATE_ATTRS.filter((attr) => sel[attr] !== undefined && blind.includes(attr));
+}
+/** Throw unless every state modifier on `sel` means something on `platform`. */
+function assertStateSupported(sel, platform) {
+    const bad = unsupportedStateAttrs(sel, platform);
+    if (bad.length === 0)
+        return;
+    // Name both polarities: --not-selected is refused for the same reason as --selected,
+    // and echoing only the attribute reads as though the wrong flag was typed.
+    const named = bad.map((a) => `--${a}/--not-${a}`).join(' and ');
+    throw new errors_1.CliError(`${named} cannot be used on ${platform}: its accessibility backend does not report ` +
+        `${bad.join(' or ')}, so the selector could only ever match nothing. ` +
+        `Match on ${platform === 'ios' ? '@id, text or --enabled/--checked' : 'another attribute'} instead.`, 3);
+}

package/dist/ui/viewport.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SWIPE_FRACTION = void 0;
+exports.viewportFor = viewportFor;
+exports.screenRect = screenRect;
+exports.isOffscreen = isOffscreen;
+exports.visibleRect = visibleRect;
+exports.isFullyVisible = isFullyVisible;
+exports.visibleFraction = visibleFraction;
+exports.tapPoint = tapPoint;
+exports.clipRegion = clipRegion;
+exports.swipeVector = swipeVector;
+exports.scrollSurface = scrollSurface;
+exports.reachablePoint = reachablePoint;
+exports.isOccluded = isOccluded;
+exports.swipeDurationMs = swipeDurationMs;
+exports.scrollPlan = scrollPlan;
+/** How much of a region a directional swipe drags across, as a fraction of its span. */
+exports.DEFAULT_SWIPE_FRACTION = 0.6;
+/** Below this the gesture reads as a tap rather than a drag, so scrolling by less
+ *  than this is refused — pressing the wrong control is exactly what we are fixing. */
+const MIN_DRAG_PX = 40;
+/** Bounds within a pixel of the viewport edge count as inside: uiautomator rounds,
+ *  and a 1px overhang is not a reason to swipe a screen. */
+const EDGE_TOLERANCE_PX = 1;
+/**
+ * The screen rectangle a dump's coordinates live in.
+ *
+ * `rotation` is Android's `<hierarchy rotation="N">` (Surface.ROTATION_*): `adb shell
+ * wm size` always reports the NATURAL orientation, so on a landscape device (1/3) the
+ * axes must be swapped — without that, everything past the portrait width looks
+ * off-screen and every tap on a landscape app would try to scroll.
+ *
+ * `undefined` means no orientation signal (iOS: `idb describe` has none). Rather than
+ * guess, use the max(w,h) square: it can never be SMALLER than the true viewport, so
+ * it can only under-detect off-screen elements — i.e. degrade to today's behaviour —
+ * and never claim a visible element is out of view.
+ */
+function viewportFor(screen, rotation) {
+    const w = Math.max(0, Math.round(screen.width));
+    const h = Math.max(0, Math.round(screen.height));
+    if (rotation === undefined) {
+        const square = Math.max(w, h);
+        return { width: square, height: square };
+    }
+    return rotation === 1 || rotation === 3 ? { width: h, height: w } : { width: w, height: h };
+}
+/** The screen as a rectangle — the outermost clip region. */
+function screenRect(vp) {
+    return { x1: 0, y1: 0, x2: vp.width, y2: vp.height };
+}
+/** No overlap with the region at all — there is no honest point to press. */
+function isOffscreen(b, region) {
+    return b.x2 <= region.x1 || b.y2 <= region.y1 || b.x1 >= region.x2 || b.y1 >= region.y2;
+}
+/** The part of `b` inside the region (empty rect when there is no overlap). */
+function visibleRect(b, region) {
+    return {
+        x1: Math.max(b.x1, region.x1),
+        y1: Math.max(b.y1, region.y1),
+        x2: Math.min(b.x2, region.x2),
+        y2: Math.min(b.y2, region.y2),
+    };
+}
+/** Entirely within the region — the state "scroll into view" aims for. */
+function isFullyVisible(b, region) {
+    return (b.x1 >= region.x1 - EDGE_TOLERANCE_PX &&
+        b.y1 >= region.y1 - EDGE_TOLERANCE_PX &&
+        b.x2 <= region.x2 + EDGE_TOLERANCE_PX &&
+        b.y2 <= region.y2 + EDGE_TOLERANCE_PX);
+}
+const area = (b) => Math.max(0, b.x2 - b.x1) * Math.max(0, b.y2 - b.y1);
+/** 0..1 — how much of the element the region shows. 1 when fully visible (or degenerate). */
+function visibleFraction(b, region) {
+    const total = area(b);
+    if (total <= 0)
+        return isOffscreen(b, region) ? 0 : 1;
+    return area(visibleRect(b, region)) / total;
+}
+/**
+ * Where a tap on this element should land.
+ *
+ * The centre of the VISIBLE part, not of the raw bounds: an element straddling an
+ * edge has a geometric centre that can sit outside it, and pressing that is the blind
+ * tap this module exists to prevent. Identical to `el.center` whenever the element is
+ * fully visible (or no region is known), so the ordinary path is unchanged.
+ */
+function tapPoint(el, region) {
+    if (!region || isOffscreen(el.bounds, region) || isFullyVisible(el.bounds, region))
+        return el.center;
+    const v = visibleRect(el.bounds, region);
+    return { x: Math.floor((v.x1 + v.x2) / 2), y: Math.floor((v.y1 + v.y2) / 2) };
+}
+/**
+ * The region an element must be inside to be reliably tappable: the screen, further
+ * clipped to its nearest SCROLLABLE ancestor.
+ *
+ * This is what catches the case the platform hides from us. Android reports a row
+ * scrolled past the fold with bounds already clipped to the display, so nothing about
+ * the row itself says it is cut off — but it still overflows the list it lives in,
+ * and that is visible in the tree. Elements outside any scroll container (a toolbar,
+ * a sticky bar) get the plain screen, so nothing pins them into a smaller box.
+ *
+ * The hierarchy is pre-order, so an element's ancestors are the nodes before it whose
+ * depth keeps decreasing — walking back is exact, not a containment guess.
+ */
+function clipRegion(els, target, screen) {
+    const at = els.indexOf(target);
+    let depth = target.depth;
+    for (let i = at - 1; i >= 0; i--) {
+        const el = els[i];
+        if (el.depth >= depth)
+            continue; // not an ancestor: a sibling or its subtree
+        depth = el.depth;
+        if (el.scrollable)
+            return visibleRect(el.bounds, screen);
+    }
+    return screen;
+}
+/** The two points of a directional swipe across `region`, `frac` of its span. */
+function swipeVector(region, dir, frac) {
+    const cx = Math.floor((region.x1 + region.x2) / 2);
+    const cy = Math.floor((region.y1 + region.y2) / 2);
+    const dx = Math.floor(((region.x2 - region.x1) * frac) / 2);
+    const dy = Math.floor(((region.y2 - region.y1) * frac) / 2);
+    switch (dir) {
+        case 'up':
+            return { from: { x: cx, y: cy + dy }, to: { x: cx, y: cy - dy } };
+        case 'down':
+            return { from: { x: cx, y: cy - dy }, to: { x: cx, y: cy + dy } };
+        case 'left':
+            return { from: { x: cx + dx, y: cy }, to: { x: cx - dx, y: cy } };
+        case 'right':
+            return { from: { x: cx - dx, y: cy }, to: { x: cx + dx, y: cy } };
+    }
+}
+/**
+ * The region to swipe within to move `target`: its own scroll container when it has
+ * one, else the largest scrollable that spans it, else the whole screen.
+ *
+ * The ancestor is exact (see clipRegion) and therefore preferred. The span-based
+ * fallback picks by extent ALONG THE SCROLL AXIS, so a page-level vertical list wins
+ * over a horizontal carousel nested inside it. Falling back to the screen matters: a
+ * framework that never sets `scrollable` still gets a working full-screen swipe.
+ */
+function scrollSurface(els, target, screen, axis) {
+    const ancestor = clipRegion(els, target, screen);
+    if (ancestor !== screen)
+        return ancestor;
+    const spans = (b) => (axis === 'y' ? b.y2 - b.y1 : b.x2 - b.x1);
+    const crossCentre = axis === 'y' ? target.center.x : target.center.y;
+    const covers = (b) => axis === 'y' ? b.x1 <= crossCentre && b.x2 >= crossCentre : b.y1 <= crossCentre && b.y2 >= crossCentre;
+    let best = null;
+    for (const el of els) {
+        if (!el.scrollable || el === target)
+            continue;
+        if (isOffscreen(el.bounds, screen))
+            continue;
+        const visible = visibleRect(el.bounds, screen);
+        if (spans(visible) < MIN_DRAG_PX || !covers(el.bounds))
+            continue;
+        if (!best || spans(visible) > spans(best))
+            best = visible;
+    }
+    return best ?? screen;
+}
+const contains = (b, p) => p.x >= b.x1 && p.x < b.x2 && p.y >= b.y1 && p.y < b.y2;
+/**
+ * Where a tap on this element can actually reach it: the centre of its visible part,
+ * or the nearest point to that centre which nothing else is drawn over.
+ *
+ * MEASURED, and the other half of the bug in #42: a row can be entirely inside the
+ * screen AND inside its list, yet have a sticky bottom bar drawn across its lower
+ * half — so pressing its centre presses the bar, and the step reports success having
+ * tapped a completely different control. There is no occlusion flag in any dump; what
+ * there IS, is order. The hierarchy is pre-order, later siblings paint over earlier
+ * ones, so an element listed AFTER the target which covers the point is on top of it.
+ *
+ * Ancestors are excluded for free (they precede the target); descendants are the
+ * contiguous run after it with greater depth, and they ARE the target for tapping
+ * purposes. Returns null when every candidate point is covered — the caller warns
+ * rather than failing, since this is an ordering heuristic and a wrong refusal would
+ * be worse than the tap it prevents.
+ */
+function reachablePoint(els, target, region) {
+    const visible = visibleRect(target.bounds, region);
+    if (visible.x2 <= visible.x1 || visible.y2 <= visible.y1)
+        return null;
+    // Centre first, then inward-inset points: any interior point of a control taps it,
+    // and staying inset keeps us off a neighbour's edge.
+    const xs = [0.5, 0.5, 0.5, 0.25, 0.75, 0.25, 0.75];
+    const ys = [0.5, 0.25, 0.75, 0.5, 0.5, 0.25, 0.75];
+    for (let i = 0; i < xs.length; i++) {
+        const p = {
+            x: Math.floor(visible.x1 + (visible.x2 - visible.x1) * xs[i]),
+            y: Math.floor(visible.y1 + (visible.y2 - visible.y1) * ys[i]),
+        };
+        if (contains(visible, p) && !isOccluded(els, target, p))
+            return p;
+    }
+    return null;
+}
+/** Is `point` covered by an element painted after `target` (and not part of it)? */
+function isOccluded(els, target, point) {
+    const at = els.indexOf(target);
+    if (at < 0)
+        return false;
+    let i = at + 1;
+    while (i < els.length && els[i].depth > target.depth)
+        i++; // the target's own subtree is the target
+    for (; i < els.length; i++)
+        if (contains(els[i].bounds, point))
+            return true;
+    return false;
+}
+/**
+ * How long to spend dragging `distance` pixels.
+ *
+ * MEASURED on emulator-5554 (API 34), and the reason this is not a constant: the same
+ * 1118px swipe delivered over 400ms took the app off the screen entirely — the fling
+ * velocity is read as another gesture — while over 1500ms it scrolled cleanly and
+ * stopped where it was put. Pacing by distance keeps a scroll a DRAG: the list lands
+ * where we aimed, so the next measurement is of the screen we asked for.
+ */
+function swipeDurationMs(distance) {
+    const PX_PER_MS = 0.75;
+    return Math.min(2000, Math.max(300, Math.round(Math.abs(distance) / PX_PER_MS)));
+}
+/**
+ * The swipe that brings `target` into view within `surface`, or null when no useful
+ * one exists (already visible, or the move would be too small to be a drag).
+ *
+ * Aims to CENTRE the target rather than merely nudge it past the edge: an element
+ * resting against a screen edge is the case most likely to sit under a sticky app
+ * bar, which no hierarchy dump can tell us about. Centring costs nothing extra —
+ * the swipe is capped by the surface either way — and lands well clear of both.
+ */
+function scrollPlan(target, surface, clip, opts = {}) {
+    if (!opts.centre && isFullyVisible(target, clip))
+        return null;
+    // Distance the CONTENT must move for the target to end up centred. Positive means
+    // the target is too far down/right, so the content has to move up/left.
+    const needY = Math.round((target.y1 + target.y2) / 2 - (clip.y1 + clip.y2) / 2);
+    const needX = Math.round((target.x1 + target.x2) / 2 - (clip.x1 + clip.x2) / 2);
+    const fitsY = target.y2 - target.y1 <= clip.y2 - clip.y1;
+    const fitsX = target.x2 - target.x1 <= clip.x2 - clip.x1;
+    // Only chase an axis the element is actually clipped on: a full-width row is
+    // "outside the region in x" by its own size, which no sideways swipe fixes.
+    // `centre` overrides that — the caller wants the element moved to the middle even
+    // though it is already inside the region (something is drawn over it there).
+    const wantY = fitsY && (opts.centre || target.y1 < clip.y1 || target.y2 > clip.y2) ? Math.abs(needY) : 0;
+    const wantX = fitsX && (opts.centre || target.x1 < clip.x1 || target.x2 > clip.x2) ? Math.abs(needX) : 0;
+    if (wantY === 0 && wantX === 0)
+        return null;
+    const axis = wantY >= wantX ? 'y' : 'x';
+    const need = axis === 'y' ? needY : needX;
+    const region = visibleRect(surface, clip);
+    const span = axis === 'y' ? region.y2 - region.y1 : region.x2 - region.x1;
+    if (span < MIN_DRAG_PX * 2)
+        return null;
+    const drag = Math.min(Math.abs(need), Math.floor(span * exports.DEFAULT_SWIPE_FRACTION));
+    if (drag < MIN_DRAG_PX)
+        return null;
+    // `up` scrolls the page DOWN (content moves up), revealing what was below.
+    const direction = axis === 'y' ? (need > 0 ? 'up' : 'down') : need > 0 ? 'left' : 'right';
+    return { ...swipeVector(region, direction, drag / span), axis, direction, distance: drag };
+}

package/dist/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // GENERATED by scripts/gen-version.mjs from package.json's "version" at build time
 // (the `prebuild` script). Do NOT edit by hand; bump package.json instead.
-exports.VERSION = '0.14.0';
+exports.VERSION = '0.16.0';