verikun 0.14.0 → 0.16.0

package/README.md

@@ -390,15 +390,108 @@ class:Button    simplified type ("Button") or full class ("android.widget.Button
 ```
 
 Modifiers: `--contains` makes text/desc matches substring-based; `--index N`
-selects the Nth match (0-based) when a selector intentionally matches several;
-`--enabled` matches only a control that is **actionable right now** — use it for a
-Submit/Check button the app disables until a form is valid, since such a button is
-present long before it is usable and tapping presence taps a dead control (with
-auto-wait this reads as "wait until it is pressable").
+selects the Nth match (0-based) when a selector intentionally matches several.
 If a selector for an action matches more than one element and no `--index` is
 given, the command fails with exit code 2 and lists the candidates — it never
 taps a guess.
 
+### State modifiers
+
+A selector can also require an element's a11y **state**, in both polarities:
+
+| Modifier | Matches | Negative form |
+|---|---|---|
+| `--enabled` | actionable right now | `--not-enabled` |
+| `--selected` | the current option of a segmented control / tab bar / mode picker | `--not-selected` |
+| `--checked` | a ticked checkbox / switch / radio | `--not-checked` |
+| `--focused` | the element holding input focus | `--not-focused` |
+
+Unset means *don't care*; these never narrow a selector you didn't ask them to.
+
+Reach for `--enabled` on a Submit/Check button the app disables until a form is
+valid: such a button is present long before it is usable, so tapping presence taps
+a dead control (with auto-wait this reads as "wait until it is pressable").
+
+The **negative** forms are what make a toggle drivable. A segmented control whose
+options share one handler *flips* on any tap, so "tap the option I want" lands on
+the other one whenever it was already chosen — exit 0, nothing to notice, and the
+run exercises the wrong mode. Guard it instead:
+
+```sh
+vk find "@mode_video --not-selected" --no-wait && vk tap @mode_video
+```
+
+A modifier can be written as a flag **or appended to the selector string**, as
+above. The string form exists because a `vk ai` control node (`if-present`,
+`when`, `repeat`, `while-present`, `read`) holds a bare selector with nowhere to
+put a flag — and a guard is exactly where the toggle case needs one:
+
+```
+if-present "id:mode_video --not-selected" { tap id:mode_video }
+```
+
+**`--selected` and `--focused` are Android-only.** `idb` reports no such
+attribute for iOS — not merely unset, the key does not exist in its output — so
+using them with `--ios` exits **3** rather than silently matching nothing.
+`--enabled` and `--checked` work on both.
+
+### Auto scroll-into-view
+
+An element can be in the hierarchy without being reachable at the point a tap
+would land: scrolled past the edge of its list, or with a sticky bar drawn across
+its middle. Pressing its coordinates then hits whatever is actually there — and
+the step reports success, so the run continues from the wrong place.
+
+So **actions scroll; inspection does not**. `tap` and `text` bring their target
+into the clear first — into its scroll container, and out from under anything
+drawn over it — then act, adding `(scrolled into view: N swipes)` to the
+confirmation. "Scroll down to X and tap it" is therefore just `vk tap X`; you
+rarely need an explicit `swipe`.
+
+`ui`, `find` and `assert` never scroll and never hide anything: an element with no
+pixel on screen is listed as usual, marked `offscreen`. Where an element cannot be
+reached at all, the action **fails with exit 1** rather than pressing blind
+coordinates. `--no-scroll` opts out of the scrolling.
+
+> Note what this cannot see: a control covered by something the accessibility tree
+> does not contain (a decorative container with no label or id) is invisible to any
+> tool reading that tree. Scrolling the target clear of screen edges is what
+> avoids most of these; verikun warns on stderr when it presses an element it
+> believes is covered.
+
+### Which selector to reach for: `@id` first, `text:` second, `desc:` never
+
+Not all four selector kinds travel equally well. If a flow has to run on both
+Android and iOS, this ordering matters:
+
+| selector | Android | iOS | portable? |
+|---|---|---|---|
+| `@id` | `resource-id` | `AXUniqueId` | **yes — always prefer this** |
+| `text:` | visible text, falling back to `content-desc` | `AXLabel` / `title` / `AXValue` | yes |
+| `desc:` | `content-desc` | `accessibilityHint` only | **no — Android in practice** |
+| `class:` | widget class | element role | no — see below |
+
+Two traps worth knowing:
+
+- **`desc:` does not fall back.** `text:` falls back to `desc` when no text
+  matches, so a `text:Submit` selector finds an element carrying only an
+  accessibility label. The reverse is not true — `desc:Submit` will never match
+  visible text. On iOS an accessibility label arrives as `text`, so a `desc:`
+  selector written against Android silently stops matching there.
+- **`class:` is mostly useless on a cross-platform UI toolkit.** Flutter text
+  inputs report as `android.widget.EditText` / `TextField`, but almost everything
+  else is `android.view.View` — so `class:Button` cannot match a Flutter button
+  regardless of what the widget is.
+
+There is a further, sharper reason to prefer `@id`: it is the only selector that
+is not text, so it survives **localisation**. A flow pinned with `text:` breaks
+the moment the device is in a different language.
+
+For a Flutter app, `@id` comes from `Semantics(identifier:)`; `Semantics(label:)`
+gives you `desc` on Android but `text` on iOS. A worked example, with the
+cross-platform gotchas measured on real hardware, is in
+[`example/flutter-app`](example/flutter-app/).
+
 ## Auto-wait
 
 A UI rarely settles the instant the previous action returns. So selector

package/dist/agent/engine.js

@@ -4,6 +4,7 @@ exports.DEFAULT_GUARD_SETTLE_MS = exports.DEFAULT_RUN_TIMEOUT_MS = void 0;
 exports.runPlan = runPlan;
 const node_crypto_1 = require("node:crypto");
 const selector_1 = require("../ui/selector");
+const state_support_1 = require("../ui/state-support");
 const errors_1 = require("../errors");
 const ir_1 = require("./ir");
 /** An outcome is environment-flavoured if it carries an exit-3 CliError, or simply
@@ -191,6 +192,11 @@ async function runPlan(plan, deps) {
             deps.log(`[ai] guard selector '${selector}' did not parse (${e.message}) — treating as not present`);
             return false;
         }
+        // Outside the catch on purpose. A guard pinning state this platform cannot report
+        // would match nothing forever, so "not present" is a lie that silently skips the
+        // body — the plan is unrunnable HERE and must say so, not quietly do nothing.
+        if (deps.platform)
+            (0, state_support_1.assertStateSupported)(sel, deps.platform);
         const deadline = Date.now() + Math.max(0, settleMs);
         // A non-zero window must buy at least one SECOND look, independent of the clock.
         // Measured on emulator-5554: one uiautomator dump costs ~2.4s, which already exceeds
@@ -368,6 +374,8 @@ async function runPlan(plan, deps) {
         catch (e) {
             return { status: 'fail', where, reason: `read selector '${selector}' did not parse: ${e.message}` };
         }
+        if (deps.platform)
+            (0, state_support_1.assertStateSupported)(sel, deps.platform);
         // Same patience as a conditional guard: the value may not have rendered yet.
         const deadline = Date.now() + Math.max(0, guardSettleMs);
         let looks = 0;

package/dist/agent/grammar.js

@@ -20,7 +20,7 @@ Each step is one of three node types:
                                   rerun starts FRESH (--clear also wipes data → fresh-install;
                                   --no-restart skips the force-stop, just bringing it forward)
      stop <package>               — force-stop the app
-     tap <selector>               — tap the element a selector resolves to
+     tap <selector>               — tap the element a selector resolves to (scrolls it into view first)
      text <selector> <value...>   — focus a field and type value (--clear to clear first, --enter to submit)
      type <value...>              — type into the already-focused field
      key <name> | back | home | enter
@@ -35,9 +35,9 @@ Each step is one of three node types:
    keep a flow from breaking when an extra screen sometimes appears.
 
 3. REPEAT — { "type":"repeat", "selector":<sel>, "cap":<n>, "body":[<nodes>] }
-   Repeat body UNTIL the selector appears, up to cap iterations. Use for "scroll until X
-   is visible", or "keep answering until the results screen". Always set a sane cap (e.g.
-   10). The engine also stops early if the screen stops changing. A repeat that finishes
+   Repeat body UNTIL the selector appears, up to cap iterations. Use for "keep answering
+   until the results screen" — NOT for scrolling to something that is already in the
+   hierarchy, since tap scrolls to its own target. Always set a sane cap (e.g. 10). The engine also stops early if the screen stops changing. A repeat that finishes
    without its selector ever appearing FAILS the test — it did not do its job.
 
 4. WHEN — { "type":"when", "branches":[{ "selector":<sel>, "body":[<nodes>] }, ...],
@@ -112,14 +112,36 @@ SELECTORS (the engine auto-heals case/whitespace/partial, so prefer stable ident
   class:Button      type or class
   "Sign in"         bare string == text:Sign in
 
+A selector may also pin ELEMENT STATE, in both polarities:
+  --enabled  / --not-enabled     actionable right now
+  --selected / --not-selected    current option of a segmented control / tab bar / mode picker
+  --checked  / --not-checked     checkbox / switch / radio state
+  --focused  / --not-focused     holds input focus
+On a command leaf write it as a flag. On a CONTROL NODE append it to the selector string —
+that is the only place one can go, and it is what makes a state-conditional guard possible:
+  { "type":"if-present", "selector":"id:mode_video --not-selected",
+    "body":[ { "type":"command","command":"tap","positionals":["id:mode_video"],"flags":[] } ] }
+
 RULES:
 - --enabled on a tap makes it match only a control that is ACTIONABLE right now, and (with
   auto-wait) wait until it becomes so. Use it for any button that the app disables until
   something else is done — a Check/Submit/Continue that only lights up once an answer is
   selected or a form is valid. Without it the step taps a dead control, does nothing, and
   the failure surfaces later as a confusing timeout on the NEXT step.
+- A picker or toggle whose options share ONE handler FLIPS on any tap, so an unconditional
+  "tap the option you want" lands on the option you did NOT want whenever it was already
+  chosen — and its starting state is usually content-driven, so you cannot know it now.
+  Guard it: if-present "id:<option> --not-selected" { tap id:<option> }. The guard makes an
+  already-correct state a no-op instead of a flip. Unguarded, the flow completes either way
+  and the test PASSES having exercised the opposite mode — a false green, worse than a fail.
+  Same shape for a checkbox that toggles: guard with --not-checked / --checked.
 - assert is for VERIFICATION only and is terminal — never use it as a step you expect to
   fail. Put genuinely-optional UI behind if-present.
+- tap/text SCROLL THEIR TARGET INTO VIEW automatically, so "scroll down to X and tap it"
+  is just \`tap X\`. Do NOT wrap a tap in a repeat-until-visible loop to reach something
+  below the fold — that is now redundant. Emit an explicit swipe only when the SCROLLING
+  ITSELF is what the test asks for ("scroll the feed three times"), or to reveal content
+  that is not in the hierarchy until it is built (an infinite/lazy list).
 - Prefer resource-id / accessibility selectors over visible text where possible.
 - Translate the test literally and minimally: do not invent ACTION steps (tap/text/swipe/key/assert)
   the prose does not imply. The ONE exception is screenshot — insert screenshot steps liberally as
@@ -149,4 +171,7 @@ Emit ONLY an object matching the schema:
   { "decision":"repair", "step": { "type":"command","command","positionals":[...],"flags":[{"name","value"}] } }
   { "decision":"give_up", "reason": "<why no element on this screen matches the intent>" }
 Prefer a stable selector (resource-id / accessibility label) visible in the hierarchy.
-Do not invent elements that are not in the hierarchy.`;
+Do not invent elements that are not in the hierarchy.
+An element tagged \`offscreen\` is in the tree but scrolled out of view; tap/text scroll
+to their target on their own, so the fact a step failed on one means scrolling could not
+reach it — pick a different element only if one genuinely serves the same purpose.`;

package/dist/args.js

@@ -35,6 +35,7 @@ const BOOLEAN = new Set([
     'android',
     'fix',
     'no-wait',
+    'no-scroll',
     'full',
     'more',
     'show-plan',
@@ -43,6 +44,19 @@ const BOOLEAN = new Set([
     'no-restart',
     'allow-install',
     'allow-unsafe-anonymous',
+    // Selector state modifiers (STATE_ATTRS in ui/selector.ts) and their negations.
+    // `enabled` was missing here until 0.15.0, and the omission was not cosmetic: a
+    // non-BOOLEAN flag swallows the next token, so `vk tap --enabled @submit` bound
+    // the SELECTOR as the flag's value and died with "Missing selector". Only the
+    // trailing form worked. Any new modifier must be listed here.
+    'enabled',
+    'selected',
+    'checked',
+    'focused',
+    'not-enabled',
+    'not-selected',
+    'not-checked',
+    'not-focused',
 ]);
 function parseArgs(argv) {
     const positionals = [];

package/dist/cli.js

@@ -35,11 +35,13 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.platformFromFlags = platformFromFlags;
 exports.deviceFromFlags = deviceFromFlags;
+exports.stateFromFlags = stateFromFlags;
 exports.parsePoint = parsePoint;
 exports.healNote = healNote;
 exports.parseDuration = parseDuration;
 exports.waitWindowMs = waitWindowMs;
 exports.waitNote = waitNote;
+exports.scrollNote = scrollNote;
 exports.formatDeviceTable = formatDeviceTable;
 exports.guardSettleMs = guardSettleMs;
 exports.confineToCwd = confineToCwd;
@@ -57,7 +59,9 @@ const errors_1 = require("./errors");
 const exec_1 = require("./exec");
 const drivers_1 = require("./drivers");
 const selector_1 = require("./ui/selector");
+const state_support_1 = require("./ui/state-support");
 const format_1 = require("./ui/format");
+const viewport_1 = require("./ui/viewport");
 const output_1 = require("./output");
 const run_1 = require("./run");
 const image_1 = require("./image");
@@ -91,15 +95,42 @@ function deviceFromFlags(flags, platform) {
         (platform === 'android' ? process.env.ANDROID_SERIAL : undefined) ||
         undefined);
 }
-function buildSelector(raw, flags) {
+/**
+ * Read the `--enabled` / `--not-enabled` / `--selected` / … pairs off the flags.
+ *
+ * An ABSENT flag must stay `undefined`, never `false`: these modifiers are tri-state
+ * ("must be" / "must not be" / "don't care"), so passing `flagBool()` straight through —
+ * which is what this replaced — would quietly turn every selector on every command into
+ * "must be disabled, unselected, unchecked and unfocused".
+ */
+function stateFromFlags(flags) {
+    const state = {};
+    for (const attr of selector_1.STATE_ATTRS) {
+        const yes = (0, args_1.flagBool)(flags, attr);
+        const no = (0, args_1.flagBool)(flags, `not-${attr}`);
+        if (yes && no)
+            throw new errors_1.CliError(`Cannot combine --${attr} with --not-${attr}.`, 2);
+        if (yes)
+            state[attr] = true;
+        else if (no)
+            state[attr] = false;
+    }
+    return state;
+}
+function buildSelector(ctx, raw) {
     if (!raw) {
         throw new errors_1.CliError('Missing selector. e.g. `@login_button`, `text:Login`, `desc:Submit`.', 2);
     }
-    return (0, selector_1.parseSelector)(raw, {
-        contains: (0, args_1.flagBool)(flags, 'contains'),
-        index: (0, args_1.flagNum)(flags, 'index'),
-        enabled: (0, args_1.flagBool)(flags, 'enabled'),
+    const sel = (0, selector_1.parseSelector)(raw, {
+        contains: (0, args_1.flagBool)(ctx.flags, 'contains'),
+        index: (0, args_1.flagNum)(ctx.flags, 'index'),
+        ...stateFromFlags(ctx.flags),
     });
+    // Every command's selector — and so every `vk ai` leaf, which reaches these handlers
+    // through executeOutcome — funnels through here, which is why the platform check lives
+    // at this seam rather than in the (platform-free) selector layer.
+    (0, state_support_1.assertStateSupported)(sel, ctx.platform);
+    return sel;
 }
 function parsePoint(s) {
     const m = /^(-?\d+)\s*,\s*(-?\d+)$/.exec(s.trim());
@@ -173,7 +204,10 @@ async function resolveOneWaiting(ctx, sel, opts = {}) {
         const els = ctx.driver.getElements(opts);
         if ((0, selector_1.matchElements)(els, sel).matches.length >= 1) {
             const { element, tier } = (0, selector_1.resolveOne)(els, sel); // 1 → resolved; >1 → throws ambiguity
-            return { element, tier, waitedMs: Date.now() - start };
+            // The snapshot rides along: scroll-into-view needs the scrollable containers
+            // from the SAME dump the element came from, and re-capturing to find them
+            // would both cost a round-trip and risk describing a screen that moved on.
+            return { element, tier, waitedMs: Date.now() - start, elements: els };
         }
         if (Date.now() >= deadline) {
             const waited = windowMs > 0 ? ` after ${(windowMs / 1000).toFixed(1)}s` : '';
@@ -182,6 +216,146 @@ async function resolveOneWaiting(ctx, sel, opts = {}) {
         await sleep(pollStep(ctx.flags, deadline));
     }
 }
+// --- Auto scroll-into-view --------------------------------------------------
+// An element's centre is not always a point that reaches it, and a tap on the
+// wrong point still reported success — so the run carried on from the wrong place
+// and failed several steps later on an unrelated symptom (issue #42). Actions
+// therefore bring their target into the clear first, the same contract as
+// Playwright's scrollIntoViewIfNeeded.
+//
+// MEASURED, and it is not only the obvious case: Android's dumper already drops
+// nodes it considers invisible and clips the rest to the display, so the usual
+// shape is an element that IS on screen — a row cut off by its list, or one with a
+// sticky bar drawn across its middle. Both are handled by asking the question
+// against `clipRegion()` (screen ∩ scroll container) and `isOccluded()` (what is
+// painted after it), not against the screen alone.
+//
+// Load-bearing split, mirroring auto-wait: ACTIONS scroll, INSPECTION does not.
+// `ui`/`find`/`assert` report an element exactly as it is (tagged `offscreen` when
+// it has no pixel on screen) — hiding it would turn a wrong tap into a mysterious
+// miss — while `tap`/`text` refuse to press a point that would hit something else.
+//
+// Scrolling only ever happens when the alternative is a wrong tap, so a target
+// already in the clear costs nothing: no extra dump, no swipe.
+const SCROLL_INTO_VIEW_MAX = 10;
+/** Let the scroll settle before re-dumping — a mid-fling hierarchy reads as a stall. */
+const SCROLL_SETTLE_MS = 500;
+/** Movement below this is measurement noise, not progress. */
+const NO_PROGRESS_PX = 8;
+/** Consecutive non-moving swipes before we accept the list will not go further. */
+const NO_PROGRESS_STRIKES = 2;
+/** A short note appended to action output when the target had to be scrolled to. */
+function scrollNote(swipes) {
+    return swipes > 0 ? ` (scrolled into view: ${swipes} swipe${swipes === 1 ? '' : 's'})` : '';
+}
+/** Swipe until `target` sits fully inside its clip region, or we run out of room. */
+async function scrollIntoView(ctx, sel, target, elements, screen, opts = {}) {
+    let current = target;
+    let snapshot = elements;
+    let swipes = 0;
+    let stalled = 0;
+    while (swipes < SCROLL_INTO_VIEW_MAX && stalled < NO_PROGRESS_STRIKES) {
+        // Re-derived every iteration: scrolling can change which container holds the
+        // element, and a stale clip would aim the next swipe at the wrong box.
+        const clip = (0, viewport_1.clipRegion)(snapshot, current, screen);
+        const axis = Math.abs(current.center.y - (clip.y1 + clip.y2) / 2) >= Math.abs(current.center.x - (clip.x1 + clip.x2) / 2)
+            ? 'y'
+            : 'x';
+        // A covered element is scrolled to the MIDDLE of its container even though it is
+        // technically in view: a sticky bar overlaps the edges of a list, and moving the
+        // target away from them is the one reliable way to get a touch through to it.
+        const centre = (0, viewport_1.isOccluded)(snapshot, current, (0, viewport_1.tapPoint)(current, screen));
+        const plan = (0, viewport_1.scrollPlan)(current.bounds, (0, viewport_1.scrollSurface)(snapshot, current, screen, axis), clip, { centre });
+        if (!plan)
+            break; // in view, or no swipe big enough to be worth making
+        ctx.driver.swipe(plan.from.x, plan.from.y, plan.to.x, plan.to.y, (0, viewport_1.swipeDurationMs)(plan.distance));
+        swipes++;
+        await sleep(SCROLL_SETTLE_MS);
+        const before = current.bounds;
+        snapshot = ctx.driver.getElements(opts);
+        // An empty tree is a bad read, not a screen (the device returns partial dumps
+        // mid-transition) — retry rather than conclude the element is gone.
+        if (snapshot.length === 0)
+            continue;
+        if ((0, selector_1.matchElements)(snapshot, sel).matches.length === 0) {
+            // Android drops a node that scrolls out of view, so overshooting LOSES the
+            // target rather than leaving it visibly off-position. Give the last swipe back
+            // (half of it, to land between the two) and look once more before giving up.
+            const mid = { x: Math.round((plan.from.x + plan.to.x) / 2), y: Math.round((plan.from.y + plan.to.y) / 2) };
+            ctx.driver.swipe(plan.to.x, plan.to.y, mid.x, mid.y, (0, viewport_1.swipeDurationMs)(plan.distance / 2));
+            await sleep(SCROLL_SETTLE_MS);
+            snapshot = ctx.driver.getElements(opts);
+            if ((0, selector_1.matchElements)(snapshot, sel).matches.length === 0) {
+                throw new errors_1.SelectorNotFoundError(`'${sel.raw}' left the hierarchy while being scrolled into view (after ${swipes} swipe(s)) — ` +
+                    'a lazy list may have recycled it. Run `verikun ui` to inspect the current screen.');
+            }
+        }
+        current = (0, selector_1.resolveOne)(snapshot, sel).element; // >1 → ambiguity, exit 2, as everywhere else
+        const moved = Math.abs(plan.axis === 'y' ? current.bounds.y1 - before.y1 : current.bounds.x1 - before.x1);
+        stalled = moved < NO_PROGRESS_PX ? stalled + 1 : 0;
+    }
+    return { element: current, swipes, elements: snapshot };
+}
+/** The screen as a rectangle, or null on a device whose size could not be read. */
+function screenOf(ctx) {
+    const vp = ctx.driver.viewport();
+    return vp ? (0, viewport_1.screenRect)(vp) : null;
+}
+/** The point to press for `el`, preferring one nothing else is drawn over. Falls back
+ *  to the visible centre — an ordering-based guess must never block a real tap. */
+function pressPoint(els, el, screen) {
+    if (!screen)
+        return el.center;
+    return (0, viewport_1.reachablePoint)(els, el, screen) ?? (0, viewport_1.tapPoint)(el, screen);
+}
+/** Say so when the element we are about to press is only partly on screen, or is
+ *  covered by something drawn over it — both mean the touch may not reach it. */
+function reachWarning(els, el, screen) {
+    if (!screen)
+        return;
+    if (!(0, viewport_1.isFullyVisible)(el.bounds, screen)) {
+        (0, output_1.err)(`(only ${Math.round((0, viewport_1.visibleFraction)(el.bounds, screen) * 100)}% of ${(0, format_1.formatInline)(el)} is on screen)`);
+    }
+    if (!(0, viewport_1.reachablePoint)(els, el, screen)) {
+        (0, output_1.err)(`(${(0, format_1.formatInline)(el)} is covered by another element — the tap may land on whatever is on top)`);
+    }
+}
+/**
+ * Resolve a selector to something that can actually be pressed: wait for it, scroll it
+ * into view when it is not fully inside its scroll container, and fail loudly rather
+ * than tap blind.
+ *
+ * When the screen size is unknown this is exactly the old behaviour — resolve and
+ * press the element's centre.
+ */
+async function resolveTappable(ctx, sel, opts = {}) {
+    const { element, tier, waitedMs, elements } = await resolveOneWaiting(ctx, sel, opts);
+    const screen = screenOf(ctx);
+    const clip = screen ? (0, viewport_1.clipRegion)(elements, element, screen) : null;
+    // Scroll when the element is cut off by its container, and also when something is
+    // drawn over the point we would press — but only if it HAS a container to scroll
+    // (clip !== screen). Swiping the whole screen at a covered toolbar button would be
+    // a random gesture, and the point-picking fallback below handles that case.
+    const covered = !!screen && !!clip && clip !== screen && (0, viewport_1.isOccluded)(elements, element, (0, viewport_1.tapPoint)(element, screen));
+    if (!screen || !clip || ((0, viewport_1.isFullyVisible)(element.bounds, clip) && !covered)) {
+        reachWarning(elements, element, screen);
+        return { element, tier, waitedMs, swipes: 0, point: pressPoint(elements, element, screen) };
+    }
+    const scrolled = (0, args_1.flagBool)(ctx.flags, 'no-scroll')
+        ? { element, swipes: 0, elements }
+        : await scrollIntoView(ctx, sel, element, elements, screen, opts);
+    if ((0, viewport_1.isOffscreen)(scrolled.element.bounds, screen)) {
+        const why = (0, args_1.flagBool)(ctx.flags, 'no-scroll')
+            ? '--no-scroll is set'
+            : scrolled.swipes === 0
+                ? 'no scrollable container could move it'
+                : `${scrolled.swipes} swipe(s) did not bring it into view`;
+        throw new errors_1.SelectorNotFoundError(`'${sel.raw}' is in the screen's element tree but scrolled out of view (${why}), so tapping it ` +
+            'would press whatever is at those coordinates instead. Run `verikun ui` to inspect the current screen.');
+    }
+    reachWarning(scrolled.elements, scrolled.element, screen);
+    return { ...scrolled, tier, waitedMs, point: pressPoint(scrolled.elements, scrolled.element, screen) };
+}
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
@@ -313,7 +487,7 @@ function cmdUi(ctx) {
     return 0;
 }
 async function cmdFind(ctx) {
-    const sel = buildSelector(ctx.positionals[0], ctx.flags);
+    const sel = buildSelector(ctx, ctx.positionals[0]);
     const { matches, tier } = await matchWaiting(ctx, sel, { all: (0, args_1.flagBool)(ctx.flags, 'all') });
     if ((0, args_1.flagBool)(ctx.flags, 'json'))
         (0, output_1.json)(matches.map(format_1.toJsonShape));
@@ -346,38 +520,55 @@ async function cmdTap(ctx) {
     let target;
     let tier = null;
     let waitedMs = 0;
+    let swipes = 0;
+    let point;
     if (isBareIndex) {
         const els = ctx.driver.getElements({ all: (0, args_1.flagBool)(ctx.flags, 'all') });
         const idx = Number(raw);
         const found = els.find((e) => e.index === idx);
         if (!found)
             throw new errors_1.CliError(`No element with index [${idx}] on the current screen. Run \`verikun ui\`.`, 1);
+        // An index names a row of one specific dump, and scrolling renumbers every row —
+        // so this path cannot scroll. Refuse instead of pressing coordinates off-screen.
+        if (found.offscreen) {
+            throw new errors_1.CliError(`Element [${idx}] ${(0, format_1.formatInline)(found)} is scrolled out of view. Tap it by selector ` +
+                `(e.g. \`verikun tap @${found.idShort || 'id'}\`) so verikun can scroll it into view first.`, 1);
+        }
         target = found;
+        reachWarning(els, target, screenOf(ctx));
+        point = pressPoint(els, target, screenOf(ctx));
         ctx.record?.note({ element: target, message: `tapped by index [${idx}]` });
     }
     else {
-        const sel = buildSelector(raw, ctx.flags);
-        ({ element: target, tier, waitedMs } = await resolveOneWaiting(ctx, sel, { all: (0, args_1.flagBool)(ctx.flags, 'all') }));
-        ctx.record?.note({ selector: sel, tier, element: target });
+        const sel = buildSelector(ctx, raw);
+        ({ element: target, tier, waitedMs, swipes, point } = await resolveTappable(ctx, sel, {
+            all: (0, args_1.flagBool)(ctx.flags, 'all'),
+        }));
+        ctx.record?.note({
+            selector: sel,
+            tier,
+            element: target,
+            message: swipes > 0 ? `scrolled into view (${swipes} swipe(s)) and tapped` : undefined,
+        });
     }
-    ctx.driver.tap(target.center.x, target.center.y);
-    (0, output_1.out)(`tapped ${(0, format_1.formatInline)(target)}${healNote(tier)}${waitNote(waitedMs)}`);
+    ctx.driver.tap(point.x, point.y);
+    (0, output_1.out)(`tapped ${(0, format_1.formatInline)(target)}${healNote(tier)}${waitNote(waitedMs)}${scrollNote(swipes)}`);
     return 0;
 }
 async function cmdText(ctx) {
     if (ctx.positionals.length < 2) {
         throw new errors_1.CliError('Usage: verikun text <selector> <text...>  (use -- before text starting with "-")', 2);
     }
-    const sel = buildSelector(ctx.positionals[0], ctx.flags);
+    const sel = buildSelector(ctx, ctx.positionals[0]);
     const value = ctx.positionals.slice(1).join(' ');
-    const { element: target, tier, waitedMs } = await resolveOneWaiting(ctx, sel);
+    const { element: target, tier, waitedMs, swipes, point } = await resolveTappable(ctx, sel);
     ctx.record?.note({
         selector: sel,
         tier,
         element: target,
         message: target.password ? 'typed «redacted»' : `typed ${JSON.stringify(value)}`,
     });
-    ctx.driver.tap(target.center.x, target.center.y);
+    ctx.driver.tap(point.x, point.y);
     // Wait for field to be focused after tap
     await sleep(100);
     if ((0, args_1.flagBool)(ctx.flags, 'clear') && target.text) {
@@ -394,7 +585,7 @@ async function cmdText(ctx) {
     ctx.driver.inputText(value);
     if ((0, args_1.flagBool)(ctx.flags, 'enter'))
         ctx.driver.pressKey('enter');
-    (0, output_1.out)(`typed ${JSON.stringify(value)} into ${(0, format_1.formatInline)(target)}${healNote(tier)}${waitNote(waitedMs)}`);
+    (0, output_1.out)(`typed ${JSON.stringify(value)} into ${(0, format_1.formatInline)(target)}${healNote(tier)}${waitNote(waitedMs)}${scrollNote(swipes)}`);
     return 0;
 }
 function cmdType(ctx) {
@@ -444,7 +635,9 @@ async function cmdSwipe(ctx) {
     let waitedMs = 0;
     const on = (0, args_1.flagStr)(ctx.flags, 'on');
     if (on) {
-        const onSel = (0, selector_1.parseSelector)(on, { contains: (0, args_1.flagBool)(ctx.flags, 'contains') });
+        // Through buildSelector, not parseSelector: --on used to see only --contains, so
+        // `swipe --on X --enabled` silently ignored the modifier it was given.
+        const onSel = buildSelector(ctx, on);
         const { element, waitedMs: w } = await resolveOneWaiting(ctx, onSel);
         waitedMs = w;
         ctx.record?.note({ selector: onSel, element });
@@ -454,33 +647,11 @@ async function cmdSwipe(ctx) {
         const { width, height } = ctx.driver.screenSize();
         region = { x1: 0, y1: 0, x2: width, y2: height };
     }
-    const cx = Math.floor((region.x1 + region.x2) / 2);
-    const cy = Math.floor((region.y1 + region.y2) / 2);
-    const frac = Math.min(Math.max((0, args_1.flagNum)(ctx.flags, 'distance') ?? 0.6, 0.1), 0.95);
-    const dx = Math.floor(((region.x2 - region.x1) * frac) / 2);
-    const dy = Math.floor(((region.y2 - region.y1) * frac) / 2);
-    let a;
-    let b;
-    switch (dir) {
-        case 'up':
-            a = { x: cx, y: cy + dy };
-            b = { x: cx, y: cy - dy };
-            break;
-        case 'down':
-            a = { x: cx, y: cy - dy };
-            b = { x: cx, y: cy + dy };
-            break;
-        case 'left':
-            a = { x: cx + dx, y: cy };
-            b = { x: cx - dx, y: cy };
-            break;
-        case 'right':
-            a = { x: cx - dx, y: cy };
-            b = { x: cx + dx, y: cy };
-            break;
-        default:
-            throw new errors_1.CliError(`Unknown direction '${dir}' (use up|down|left|right)`, 2);
+    if (dir !== 'up' && dir !== 'down' && dir !== 'left' && dir !== 'right') {
+        throw new errors_1.CliError(`Unknown direction '${dir}' (use up|down|left|right)`, 2);
     }
+    const frac = Math.min(Math.max((0, args_1.flagNum)(ctx.flags, 'distance') ?? viewport_1.DEFAULT_SWIPE_FRACTION, 0.1), 0.95);
+    const { from: a, to: b } = (0, viewport_1.swipeVector)(region, dir, frac);
     ctx.driver.swipe(a.x, a.y, b.x, b.y, duration);
     ctx.record?.note({ message: `swiped ${dir}${on ? ` on ${on}` : ''}` });
     (0, output_1.out)(`swiped ${dir}${waitNote(waitedMs)}`);
@@ -622,7 +793,7 @@ function cmdLog(ctx) {
     return 0;
 }
 async function cmdWait(ctx) {
-    const sel = buildSelector(ctx.positionals[0], ctx.flags);
+    const sel = buildSelector(ctx, ctx.positionals[0]);
     const gone = (0, args_1.flagBool)(ctx.flags, 'gone');
     const timeout = (0, args_1.flagNum)(ctx.flags, 'timeout') ?? 10000;
     const interval = (0, args_1.flagNum)(ctx.flags, 'interval') ?? 400;
@@ -682,7 +853,7 @@ function evalAssert(els, sel, flags) {
     return { pass, reason, matches };
 }
 async function cmdAssert(ctx) {
-    const sel = buildSelector(ctx.positionals[0], ctx.flags);
+    const sel = buildSelector(ctx, ctx.positionals[0]);
     // Auto-wait subsumes the common "wait then assert": poll until the assertion
     // passes or the window elapses. `--gone` therefore waits for disappearance.
     const deadline = Date.now() + waitWindowMs(ctx.flags);
@@ -1213,6 +1384,9 @@ async function runAiTest(file, opts, backend, platform, device) {
             guardSettleMs: guardSettleMs(),
             runId: started.id,
             deadline,
+            // The RESOLVED platform — for --server that is the server's, which supersedes
+            // the client's --platform (leaves are gated server-side; guards run here).
+            platform,
         });
     }
     catch (e) {
@@ -1719,6 +1893,15 @@ SELECTORS
   class:Button    type or full class name
   "Sign in"       bare string == text:"Sign in"
   Modifiers: --contains (substring), --index N (pick Nth match)
+  State:     --enabled / --selected / --checked / --focused, each with a --not-
+             form (--not-selected). Unset = don't care. Use the negative to guard
+             a toggle: tapping a picker whose options share a handler FLIPS it, so
+             an unconditional tap lands on the wrong mode and still exits 0.
+             May be written as a flag or appended to the selector string
+             ("@mode_video --not-selected") — the latter is how a \`vk ai\`
+             if-present/when/repeat guard carries one.
+             --selected and --focused are Android-only (idb reports neither);
+             on iOS they exit 3 rather than matching nothing.
 
 AUTO-WAIT (selector lookups retry until they resolve)
   Selector commands (tap, text, find, assert, swipe --on) re-poll the screen for
@@ -1730,6 +1913,15 @@ AUTO-WAIT (selector lookups retry until they resolve)
   Ambiguity is never waited on (the elements are already there). The \`wait\`
   command stays for explicit polling, including --gone, with --timeout/--interval.
 
+AUTO-SCROLL (actions bring their target into view)
+  \`tap\` / \`text\` first scroll their target into the clear — inside its scroll
+  container, and out from under anything drawn over it (a sticky bar) — then act,
+  so "scroll down then tap X" is just \`tap X\`. \`ui\` / \`find\` / \`assert\` never
+  scroll and hide nothing: an element with no pixel on screen is listed as usual,
+  marked \`offscreen\`. One that cannot be reached fails with exit 1 rather than
+  being tapped at coordinates that would hit something else.
+  --no-scroll    act where the element is; do not scroll to it
+
 GLOBAL FLAGS
   -d, --device <serial>   target a specific device (or VERIKUN_DEVICE / ANDROID_SERIAL)
   -p, --platform <android|ios>   (default: android;  --ios / --android shortcuts)