verikun 0.9.0 → 0.11.0

package/dist/agent/engine.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_RUN_TIMEOUT_MS = void 0;
+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 errors_1 = require("../errors");
 const ir_1 = require("./ir");
@@ -13,23 +14,120 @@ const describe = (leaf) => [leaf.command, ...leaf.positionals, ...leaf.flags.map
  *  fails (a device hiccup on screencap) must never turn a green run red — see
  *  the guard in execLeaf. */
 const isScreenshotLeaf = (leaf) => leaf.command === 'screenshot' || leaf.command === 'shot';
-/** A structural fingerprint of the screen: sorted id+text+type set. Used for the
- *  loop no-progress check — deliberately NOT the raw hierarchy (its node ordering
- *  is nondeterministic between identical states, which would false-trip). */
+/** A structural fingerprint of the screen: a sorted id+text+desc+type set. Used for the
+ *  loop no-progress check — deliberately NOT the raw hierarchy (its node ordering is
+ *  nondeterministic between identical states, which would false-trip).
+ *
+ *  BOTH content fields are sampled, and that is load-bearing rather than belt-and-braces.
+ *  Sampling `text` alone made this blind on Flutter apps, which map `Semantics(label:)` to
+ *  Android's `contentDescription` — i.e. to `desc`, never to `text`. Measured on a live
+ *  Flutter screen: 14 elements, **0** carrying `text`, 8 carrying `desc`. The fingerprint
+ *  degenerated to `id||type` for the entire screen, so two completely different questions
+ *  hashed byte-identically and a loop answering them correctly was declared stalled.
+ *
+ *  Uses the full `id`, not `idShort` (the suffix after the last '/'), so elements from
+ *  different packages/namespaces cannot collide in what is meant to be a fingerprint.
+ *
+ *  When in doubt, sample MORE: an over-sensitive hash only costs a loop running to its cap;
+ *  an under-sensitive one fails a passing test, since a stalled loop is now fatal. */
 function structuralHash(els) {
     return els
-        .map((e) => `${e.idShort}|${e.text}|${e.type}`)
+        .map((e) => `${e.id}|${e.text}|${e.desc}|${e.type}`)
         .sort()
         .join('\n');
 }
+/** An unresolvable {{...}} placeholder. Terminal and never healed: the model cannot
+ *  repair a missing value, and substituting one would be inventing test data. */
+class CtxError extends Error {
+}
 function isHealable(outcome) {
     return (!!outcome.error &&
         (outcome.error instanceof errors_1.SelectorNotFoundError || outcome.error instanceof errors_1.AmbiguousSelectorError));
 }
 /** Default wall-clock ceiling for a whole `vk ai` run (overridable via --timeout). */
 exports.DEFAULT_RUN_TIMEOUT_MS = 15 * 60 * 1000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** How long a CONDITIONAL guard (`if-present`) waits for its selector to show up
+ *  before concluding "absent". Interstitials animate in: a permission dialog or promo
+ *  panel typically lands a few hundred ms after the transition that triggers it. Every
+ *  selector-resolving leaf command already auto-waits ~5s (cli.ts resolveOneWaiting),
+ *  so before this window existed a guard was strictly LESS patient than a bare `tap` —
+ *  and an optional dialog could be missed by the very construct meant to catch it.
+ *  Kept far below the leaf 5s because an ABSENT guard pays this window, every time, and
+ *  skipping fast is the common case.
+ *
+ *  NOTE the floor in present(): any non-zero window buys at least TWO looks at the screen.
+ *  Wall clock alone is not a usable unit here — a uiautomator dump measured ~2.4s on
+ *  emulator-5554 and can be ~10x faster on a physical device, so a pure time box gives a
+ *  fast phone a dozen looks and a slow emulator none. Set 0 to restore the old
+ *  single-shot probe. Override per run with VERIKUN_GUARD_SETTLE_MS (see cli.ts). */
+exports.DEFAULT_GUARD_SETTLE_MS = 1500;
+/** Re-dump cadence inside a guard's settle window. */
+const GUARD_POLL_MS = 150;
+/** Consecutive identical screen snapshots before a loop is believed to be stuck.
+ *
+ *  This check is a TIME SAVER and nothing more. A loop already fails when its exit
+ *  selector never appears, so stopping early buys no safety — it only decides how long we
+ *  wait before reaching the same verdict. That asymmetry is the whole design: a false
+ *  positive fails a passing test, while a false negative costs `cap` iterations of runtime.
+ *
+ *  Tuned from a measured false positive, twice over. At 2 strikes the same plan answered
+ *  17 questions on one run and bailed after 4 on the next — the loop bodies drive screen
+ *  transitions, and a single dump lands mid-transition often enough to produce a
+ *  coincidental pair of matching hashes.
+ *
+ *  4 discriminates well because the two cases differ in character, not just degree: a loop
+ *  genuinely at rest (a scrolled-to-the-bottom list — the case this exists for) yields
+ *  identical hashes indefinitely, whereas an animating screen rarely yields four in a row. */
+const NO_PROGRESS_STRIKES = 4;
 async function runPlan(plan, deps) {
     const maxRepairs = deps.maxRepairs ?? 3;
+    const guardSettleMs = deps.guardSettleMs ?? exports.DEFAULT_GUARD_SETTLE_MS;
+    // The run's mutable state, scoped to THIS runPlan call — never module-level. `vk suite`
+    // runs every test in one process, so a shared store would hand two sign-up tests the
+    // same {{uuid}} and recreate the collision it exists to prevent. Per-leaf generation
+    // would be equally wrong: a sign-up needs the same address in the email field, the
+    // confirm field, and a later assert.
+    const ctx = new Map(Object.entries(deps.initialCtx ?? {}));
+    const generated = new Map();
+    const runId = deps.runId ?? 'run';
+    /** Resolve {{...}} placeholders. A closed set on purpose — this is a template
+     *  substitution, not an expression language, so there is nothing to sandbox.
+     *  Unknown placeholders are left verbatim rather than blanked: a silent empty string
+     *  is how a typo becomes a false green. */
+    function interpolate(s) {
+        if (!s.includes('{{'))
+            return s;
+        return s.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_.]*)\s*\}\}/g, (whole, name) => {
+            if (name.startsWith('ctx.')) {
+                const key = name.slice(4);
+                const v = ctx.get(key);
+                if (v === undefined)
+                    throw new CtxError(`{{${name}}} is not set — no earlier step stored it`);
+                return v;
+            }
+            if (name.startsWith('env.')) {
+                const key = name.slice(4);
+                const v = process.env[key];
+                // Loud, not empty: a missing CI secret must fail the step, not type "" into a field.
+                if (v === undefined || v === '')
+                    throw new CtxError(`{{${name}}} is not set in the environment`);
+                return v;
+            }
+            if (name === 'run_id')
+                return runId;
+            // uuid/timestamp are generated ONCE per run and memoized by placeholder name.
+            if (name === 'uuid' || name === 'timestamp') {
+                const existing = generated.get(name);
+                if (existing !== undefined)
+                    return existing;
+                const v = name === 'uuid' ? (0, node_crypto_1.randomUUID)() : String(Date.now());
+                generated.set(name, v);
+                return v;
+            }
+            return whole;
+        });
+    }
     const overDeadline = () => deps.deadline !== undefined && Date.now() >= deps.deadline;
     const improvements = [];
     let modelRepairs = 0;
@@ -44,24 +142,22 @@ async function runPlan(plan, deps) {
             return [];
         }
     };
-    const present = async (selector) => {
-        // Re-fetch on a dump FAILURE (uiautomator can throw transiently) so a flaky dump at
-        // a guard check doesn't silently read as "absent" and skip a body that should run.
-        // Once a dump SUCCEEDS (even if empty) we trust it — no slow re-poll, so a genuinely
-        // absent guard still skips fast (the common if-present case).
-        let els;
-        for (let i = 0; i < 2 && els === undefined; i++) {
-            try {
-                els = await deps.getElements();
-            }
-            catch {
-                /* transient dump failure — retry once before concluding "absent" */
-            }
-        }
-        if (els === undefined)
-            return false;
+    /** Is `selector` on screen? `settleMs` is how long to keep re-dumping while it is
+     *  absent before answering "no" — see DEFAULT_GUARD_SETTLE_MS.
+     *
+     *  Two retry behaviours here are deliberately ORTHOGONAL, and conflating them is the
+     *  bug this signature exists to prevent:
+     *    - a dump that THROWS is always retried once, even at settleMs=0, so a flaky
+     *      uiautomator call never silently reads as "absent" and skips a body that
+     *      should run;
+     *    - a dump that SUCCEEDS but does not match is re-polled only while settleMs
+     *      remains. At settleMs=0 that means exactly one pass — the fast, single-shot
+     *      probe a loop-exit check needs.
+     *  So one dump attempt always happens regardless of the window. */
+    const present = async (selector, settleMs) => {
+        let sel;
         try {
-            return (0, selector_1.matchElements)(els, (0, selector_1.parseSelector)(selector)).matches.length > 0;
+            sel = (0, selector_1.parseSelector)(selector);
         }
         catch (e) {
             // A guard selector that won't parse is a compiler/plan bug — surface it (then treat
@@ -69,14 +165,68 @@ async function runPlan(plan, deps) {
             deps.log(`[ai] guard selector '${selector}' did not parse (${e.message}) — treating as not present`);
             return false;
         }
+        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
+        // a 1.5s window — so a purely time-boxed loop returns after a single dump and the
+        // window is a silent no-op on exactly the slow devices that need it most. Dump cost
+        // swings ~10x across devices, so "how long to wait" cannot be expressed in wall clock
+        // alone without making the guard's patience device-dependent.
+        let looks = 0;
+        const minLooks = settleMs > 0 ? 2 : 1;
+        for (;;) {
+            let els;
+            for (let i = 0; i < 2; i++) {
+                try {
+                    els = await deps.getElements();
+                }
+                catch {
+                    els = undefined; // transient dump failure — retry once before concluding "absent"
+                }
+                // An EMPTY tree is not a screen, it is a bad read: a live app always has nodes, and
+                // this device routinely returns a partial/blank dump mid-transition (measured: `ui`
+                // reported zero elements while `tap`'s auto-wait found its target 3.1s later).
+                // Trusting it means "absent" — which silently skips a guard, or sends a loop round
+                // again to tap something that already went away. Retry once even at settleMs=0,
+                // which is what the loop-exit check runs at.
+                if (els !== undefined && els.length > 0)
+                    break;
+            }
+            looks++;
+            if (els !== undefined && (0, selector_1.matchElements)(els, sel).matches.length > 0)
+                return true;
+            const remaining = deadline - Date.now();
+            if (looks >= minLooks && remaining <= 0)
+                return false;
+            await sleep(Math.max(0, Math.min(GUARD_POLL_MS, remaining)));
+        }
+    };
+    const runLeaf = (leaf) => {
+        const flags = (0, ir_1.leafToFlags)(leaf);
+        for (const k of Object.keys(flags))
+            flags[k] = interpolate(flags[k]);
+        return deps.exec(leaf.command, leaf.positionals.map(interpolate), flags);
     };
-    const runLeaf = (leaf) => deps.exec(leaf.command, leaf.positionals, (0, ir_1.leafToFlags)(leaf));
     /** Execute one leaf, healing a selector miss/ambiguity via the model up to the cap.
      *  `replace` writes a repaired leaf back into the plan so it persists on green. */
-    async function execLeaf(leaf, where, replace) {
+    async function execLeaf(leaf, where, replace, guard) {
         deps.log(`[ai] ${where}: ${describe(leaf)}`);
         let current = leaf;
         let outcome = await runLeaf(current);
+        // Guard raced the body: `if-present X { … tap X … }` checked X, X was there, and by
+        // the time the tap ran it had gone. That is not drift and there is nothing to repair —
+        // it is exactly the transient the guard exists to tolerate, and on a fast-transitioning
+        // app it happens routinely. Checked BEFORE the heal loop, because otherwise it costs
+        // three model calls to conclude that a thing which was optional is absent.
+        // Deliberately narrow: only the leaf that targets the guard's own selector, and only
+        // once the guard is confirmed false again.
+        if (guard !== undefined &&
+            outcome.error instanceof errors_1.SelectorNotFoundError &&
+            current.positionals.some((p) => interpolate(p) === interpolate(guard)) &&
+            !(await present(interpolate(guard), 0))) {
+            deps.log(`[ai] ${where}: '${interpolate(guard)}' disappeared after the guard matched — ending the guarded body`);
+            return { status: 'guard-gone' };
+        }
         let attempts = 0;
         while (isHealable(outcome) && attempts < maxRepairs) {
             if (deps.cost.exceeded()) {
@@ -154,49 +304,189 @@ async function runPlan(plan, deps) {
         const reason = outcome.error ? outcome.error.message.split('\n')[0] : `exited ${outcome.code}`;
         return { status: 'fail', where, reason };
     }
-    async function walkBody(body, parentWhere) {
+    async function walkBody(body, parentWhere, guard) {
         for (let j = 0; j < body.length; j++) {
-            const res = await execLeaf(body[j], `${parentWhere}.body[${j}]`, (l) => (body[j] = l));
+            const res = await walkNode(body[j], `${parentWhere}[${j}]`, (l) => (body[j] = l), guard);
+            // 'guard-gone' ends this body, not the run: the thing the guard matched went away
+            // mid-body, which is precisely the situation the guard exists to tolerate.
+            if (res.status === 'guard-gone')
+                return { status: 'ok' };
             if (res.status !== 'ok')
                 return res;
         }
         return { status: 'ok' };
     }
-    async function walkNode(node, where, replace) {
+    /** Capture a value from the live tree into ctx. Not routed through `exec`: the
+     *  ExecFn contract returns only {code,error}, so a leaf could never hand a value back. */
+    async function execRead(node, where) {
+        const selector = interpolate(node.selector);
+        let sel;
+        try {
+            sel = (0, selector_1.parseSelector)(selector);
+        }
+        catch (e) {
+            return { status: 'fail', where, reason: `read selector '${selector}' did not parse: ${e.message}` };
+        }
+        // Same patience as a conditional guard: the value may not have rendered yet.
+        const deadline = Date.now() + Math.max(0, guardSettleMs);
+        let looks = 0;
+        const minLooks = guardSettleMs > 0 ? 2 : 1;
+        for (;;) {
+            const els = await safeElements();
+            const { matches } = (0, selector_1.matchElements)(els, sel);
+            looks++;
+            if (matches.length > 0) {
+                const value = String(matches[0][node.field] ?? '');
+                ctx.set(node.into, value);
+                deps.log(`[ai] ${where}: read ${node.field} of '${selector}' → ctx.${node.into} = ${JSON.stringify(value)}`);
+                return { status: 'ok' };
+            }
+            const remaining = deadline - Date.now();
+            if (looks >= minLooks && remaining <= 0) {
+                // Terminal, not healable: a missing source value would silently propagate an
+                // empty string into every later {{ctx.*}} use, which is a false green waiting
+                // to happen. Fail where the information is.
+                return { status: 'fail', where, reason: `read found no element matching '${selector}' (nothing to store in ctx.${node.into})` };
+            }
+            await sleep(Math.max(0, Math.min(GUARD_POLL_MS, remaining)));
+        }
+    }
+    async function walkNode(node, where, replace, guard) {
+        try {
+            return await walkNodeInner(node, where, replace, guard);
+        }
+        catch (e) {
+            // An unresolvable placeholder is a plan defect, not a device failure: report it
+            // as this step's terminal failure rather than letting it abort the whole run as
+            // an "unexpected error" (exit 3).
+            if (e instanceof CtxError)
+                return { status: 'fail', where, reason: e.message };
+            throw e;
+        }
+    }
+    async function walkNodeInner(node, where, replace, guard) {
         switch (node.type) {
             case 'command':
-                return execLeaf(node, where, replace);
+                return execLeaf(node, where, replace, guard);
+            case 'read':
+                return execRead(node, where);
             case 'if-present': {
-                if (await present(node.selector)) {
-                    deps.log(`[ai] ${where}: if-present '${node.selector}' → present, running ${node.body.length} step(s)`);
-                    return walkBody(node.body, where);
+                const selector = interpolate(node.selector);
+                if (await present(selector, guardSettleMs)) {
+                    deps.log(`[ai] ${where}: if-present '${selector}' → present, running ${node.body.length} step(s)`);
+                    return walkBody(node.body, `${where}.body`, selector);
                 }
-                deps.log(`[ai] ${where}: if-present '${node.selector}' → absent, skipping`);
+                deps.log(`[ai] ${where}: if-present '${selector}' → absent, skipping`);
                 return { status: 'ok' };
             }
+            case 'when': {
+                for (let b = 0; b < node.branches.length; b++) {
+                    const selector = interpolate(node.branches[b].selector);
+                    // Ordered: first present branch wins, and only it runs. The settle window is
+                    // per NODE, spent on the first branch checked — re-polling every branch would
+                    // cost cap x branches x window inside a loop, and would let a slower-appearing
+                    // earlier branch beat an already-present later one (making dispatch depend on
+                    // timing rather than on order).
+                    if (await present(selector, b === 0 ? guardSettleMs : 0)) {
+                        deps.log(`[ai] ${where}: when → branch ${b} '${selector}' matched`);
+                        return walkBody(node.branches[b].body, `${where}.branches[${b}].body`);
+                    }
+                }
+                if (node.else) {
+                    deps.log(`[ai] ${where}: when → no branch matched, running else (${node.else.length} step(s))`);
+                    return walkBody(node.else, `${where}.else`);
+                }
+                // No branch, no else => FAIL. Skipping here is the false-green this node exists
+                // to prevent: inside a loop it would spin to the cap doing nothing and pass.
+                const tried = node.branches.map((b) => `'${interpolate(b.selector)}'`).join(', ');
+                return {
+                    status: 'fail',
+                    where,
+                    reason: `when: no branch matched (tried ${tried}) and no else was given — the screen is one this test does not handle`,
+                };
+            }
             case 'repeat': {
                 let prevHash = '';
-                for (let i = 0; i < node.cap; i++) {
+                let stalled = 0;
+                let satisfied = false;
+                let i = 0;
+                for (; i < node.cap; i++) {
                     if (overDeadline()) {
                         deps.log(`[ai] ${where}: run timeout reached — stopping repeat after ${i} iteration(s)`);
                         return { status: 'timeout' };
                     }
-                    if (await present(node.selector)) {
+                    // settleMs=0 on purpose: this guard is absent on EVERY iteration by construction
+                    // (that is what makes it a loop), so a settle window here would be paid `cap`
+                    // times — 25 × 1.5s ≈ 37s of dead wall-clock per loop — to discover something
+                    // we already expect. The interstitial case that needs patience is `if-present`.
+                    if (await present(interpolate(node.selector), 0)) {
+                        satisfied = true;
                         deps.log(`[ai] ${where}: repeat reached '${node.selector}' after ${i} iteration(s)`);
-                        return { status: 'ok' };
+                        break;
                     }
-                    const hash = structuralHash(await safeElements());
-                    if (i > 0 && hash === prevHash) {
-                        deps.log(`[ai] ${where}: repeat made no progress (screen unchanged) — stopping after ${i} iteration(s)`);
-                        return { status: 'ok' };
+                    // No-progress detection over a SINGLE un-settled dump is unreliable on a real
+                    // app: mid-transition frames read as empty (measured — `vk ui` reported zero
+                    // elements on a screen where `tap`'s auto-wait found its target 3.1s later).
+                    // Two such frames hash identically and look exactly like a stuck loop. Since a
+                    // stalled loop is now a FAILURE, a false positive here fails a passing test, so
+                    // this needs two independent guards:
+                    //   1. an empty dump is UNKNOWN, not "unchanged" — never a progress sample;
+                    //   2. require consecutive identical NON-EMPTY snapshots before believing it.
+                    const els = await safeElements();
+                    if (els.length === 0) {
+                        deps.log(`[ai] ${where}: screen read as empty (mid-transition?) — not counting it as progress either way`);
+                    }
+                    else {
+                        const hash = structuralHash(els);
+                        stalled = i > 0 && hash === prevHash ? stalled + 1 : 0;
+                        prevHash = hash;
+                        if (stalled >= NO_PROGRESS_STRIKES) {
+                            deps.log(`[ai] ${where}: repeat made no progress across ${stalled + 1} checks — stopping after ${i} iteration(s)`);
+                            break;
+                        }
                     }
-                    prevHash = hash;
                     deps.log(`[ai] ${where}: repeat iteration ${i + 1}/${node.cap}`);
-                    const res = await walkBody(node.body, `${where}#${i + 1}`);
+                    const res = await walkBody(node.body, `${where}#${i + 1}.body`);
+                    if (res.status !== 'ok')
+                        return res;
+                }
+                // A loop that stopped without ever seeing its target did NOT do its job. Both
+                // exits (cap exhausted, and the no-progress bail) used to return ok, which let a
+                // loop whose body did nothing report green — the reachable false green.
+                if (!satisfied && !(await present(interpolate(node.selector), guardSettleMs))) {
+                    return {
+                        status: 'fail',
+                        where,
+                        reason: `repeat stopped after ${i} iteration(s) without '${interpolate(node.selector)}' ever appearing`,
+                    };
+                }
+                return { status: 'ok' };
+            }
+            case 'while-present': {
+                if (node.bind)
+                    ctx.set(node.bind, '0');
+                let ran = 0;
+                for (let i = 0; i < node.cap; i++) {
+                    if (overDeadline()) {
+                        deps.log(`[ai] ${where}: run timeout reached — stopping while-present after ${i} iteration(s)`);
+                        return { status: 'timeout' };
+                    }
+                    const selector = interpolate(node.selector);
+                    // First check gets the settle window (the list may still be rendering); later
+                    // checks are single-shot, since by then the list is up and we are just walking it.
+                    if (!(await present(selector, i === 0 ? guardSettleMs : 0))) {
+                        deps.log(`[ai] ${where}: while-present '${selector}' → absent, loop done after ${ran} iteration(s)`);
+                        return { status: 'ok' };
+                    }
+                    deps.log(`[ai] ${where}: while-present iteration ${i + 1}/${node.cap} ('${selector}')`);
+                    const res = await walkBody(node.body, `${where}#${i + 1}.body`, selector);
                     if (res.status !== 'ok')
                         return res;
+                    ran++;
+                    if (node.bind)
+                        ctx.set(node.bind, String(Number(ctx.get(node.bind) ?? '0') + 1));
                 }
-                deps.log(`[ai] ${where}: repeat hit cap ${node.cap} without '${node.selector}' (continuing)`);
+                deps.log(`[ai] ${where}: while-present hit cap ${node.cap}`);
                 return { status: 'ok' };
             }
         }

package/dist/agent/grammar.js

@@ -34,13 +34,75 @@ Each step is one of three node types:
    permission dialogs, "rate us" popups, cookie banners, A/B variants. This is how you
    keep a flow from breaking when an extra screen sometimes appears.
 
-3. REPEAT — { "type":"repeat", "selector":<sel>, "cap":<n>, "body":[<command leaves>] }
-   Repeat body until the selector appears, up to cap iterations. Use for "scroll until X
-   is visible". Always set a sane cap (e.g. 10). The engine also stops early if the screen
-   stops changing.
+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
+   without its selector ever appearing FAILS the test — it did not do its job.
 
-NESTING: control-node bodies hold COMMAND leaves only — do NOT nest if-present/repeat
-inside another control node.
+4. WHEN — { "type":"when", "branches":[{ "selector":<sel>, "body":[<nodes>] }, ...],
+            "else":[<nodes>]  (optional) }
+   Ordered n-way dispatch: the FIRST branch whose selector is on screen runs, and only it.
+   Use when a screen is one of several KINDS that each need different handling —
+   "the question is multiple-choice, or match-the-pairs, or arrange-the-words".
+   If no branch matches and there is no "else", the test FAILS (the app showed something
+   this test does not handle — that is a real result, not something to skip past).
+   Use "else": [] to say explicitly "if none match, do nothing".
+   WHEN vs IF-PRESENT: if-present = "this may or may not be there, carry on either way".
+   when = "it is one of these; if it is none of them, that is a failure".
+
+5. WHILE-PRESENT — { "type":"while-present", "selector":<sel>, "bind":<name>,
+                     "cap":<n>, "body":[<nodes>] }
+   Repeat body WHILE the selector is present. With "bind", the named counter starts at 0
+   and increments after each iteration, and you reference it as {{ctx.<name>}} inside the
+   selector and the body. This is how you walk an index-addressed list whose LENGTH you
+   cannot know when compiling:
+     { "type":"while-present", "selector":"id:word_bubble_container_id_{{ctx.i}}",
+       "bind":"i", "cap":20,
+       "body":[ { "type":"command","command":"tap",
+                  "positionals":["id:word_bubble_container_id_{{ctx.i}}"],"flags":[] } ] }
+
+6. READ — { "type":"read", "selector":<sel>, "field":"text"|"desc"|"id"|"idShort",
+            "into":<name> }
+   Capture a value off the live screen into {{ctx.<name>}} for a later step to use. Use it
+   when the test must ACT ON a value it cannot know in advance — e.g. read the correct
+   answer's text, then type that text into a field.
+
+PLACEHOLDERS — any positional or flag value, and any control-node selector, may contain:
+  {{ctx.NAME}}   a value stored by read, or a while-present counter
+  {{env.NAME}}   an environment variable (use for credentials; never inline a secret)
+  {{uuid}}       a fresh id, generated once per run (same value everywhere in the run)
+  {{timestamp}}  epoch ms, once per run       {{run_id}}  this run's id
+Use {{uuid}} when the test needs data that must be unique per run, e.g. a signup email
+like "user-{{uuid}}@example.com" — never a hard-coded literal, which collides on rerun.
+
+NESTING: control nodes may nest ONE level — a control node inside a control node, whose
+body is command leaves. A repeat containing a when is the shape for "until the flow ends,
+handle whichever screen is showing", and it is legal. Three levels is not.
+EXCEPT: if-present and while-present may go one level deeper (their bodies are leaves), so
+  repeat { when { while-present { tap ... } } }     — walk an index-addressed list
+  repeat { when { if-present { tap ... } } }        — an optional step inside a branch
+are both legal. Use them rather than approximating.
+In particular: "if X appears, tap it" inside a branch is an if-present. Do NOT turn it
+into a bare wait + tap — wait FAILS the test when X never appears, and "if" means it
+might not. That mistake reads as a passing plan and fails on the first run where the app
+skips that step.
+
+Inside a "repeat until X" loop, GUARD a tap whose target is the thing that brings X about:
+  repeat until <form> { if-present <button> { tap <button> } ; screenshot }
+Once the transition starts, <button> is gone — so on the final iteration an unguarded tap
+misses and fails the whole run, even though the loop did its job. The guard makes that
+last lap a no-op instead of an error. Apply this whenever the prose says "tap ... until"
+or "repeatedly until".
+
+Do NOT flatten a branch into an unconditional sequence: emitting the taps for ALL the
+kinds of screen one after another is wrong — on any given iteration most of them are not
+there, and the test will fail on the first one that is missing. Use when.
+
+Do NOT hard-code a run of indices you were not told the length of. If the prose says
+"tap each pair", "until every pair is matched", or "tap the bubbles in order", the COUNT
+varies per run — emit a while-present over {{ctx.i}} rather than tap _0, _1, _2, _3.
+A hard-coded list is right only when the prose states the exact count.
 
 SELECTORS (the engine auto-heals case/whitespace/partial, so prefer stable identifiers):
   @login            resource-id 'login' (shorthand for id:login)
@@ -51,6 +113,11 @@ SELECTORS (the engine auto-heals case/whitespace/partial, so prefer stable ident
   "Sign in"         bare string == text:Sign in
 
 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.
 - 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.
 - Prefer resource-id / accessibility selectors over visible text where possible.