@swmansion/argent 0.17.1-next.2 → 0.17.1-next.3

package/dist/tool-server.cjs

@@ -133654,6 +133654,9 @@ function textMatches(actual, expected, mode) {
   }
   return mode === "equals" ? equalsCI(actual, expected) : includesCI(actual, expected);
 }
+function hasOwnConstraint(selector) {
+  return selector.text !== void 0 || selector.textMatches !== void 0 || selector.identifier !== void 0 || selector.role !== void 0;
+}
 function matchNodeWithRegex(node, selector, textRegex) {
   if (selector.text !== void 0) {
     if (!includesCI(node.label, selector.text) && !includesCI(node.value, selector.text)) {
@@ -133676,15 +133679,111 @@ function matchNodeWithRegex(node, selector, textRegex) {
 function selectorTextRegex(selector) {
   return selector.textMatches === void 0 ? void 0 : uiTreeMatchInternals.createRegExp(selector.textMatches);
 }
-function collectMatches(node, selector, textRegex, acc) {
-  if (matchNodeWithRegex(node, selector, textRegex)) acc.push(node);
-  for (const child of node.children) collectMatches(child, selector, textRegex, acc);
+var WITHIN_EPS = 5e-3;
+function frameWithin(inner, outer) {
+  return inner.x >= outer.x - WITHIN_EPS && inner.y >= outer.y - WITHIN_EPS && inner.x + inner.width <= outer.x + outer.width + WITHIN_EPS && inner.y + inner.height <= outer.y + outer.height + WITHIN_EPS;
+}
+var CONTAINMENT_GRID_N = 16;
+var CONTAINMENT_GRID_MIN = 32;
+function gridCell(coord) {
+  const c = Math.floor(coord * CONTAINMENT_GRID_N);
+  return c < 0 ? 0 : c >= CONTAINMENT_GRID_N ? CONTAINMENT_GRID_N - 1 : c;
+}
+function containmentTester(containers) {
+  if (containers.length < CONTAINMENT_GRID_MIN) {
+    return (node) => containers.some((c) => c !== node && frameWithin(node.frame, c.frame));
+  }
+  const cells = /* @__PURE__ */ new Map();
+  for (const c of containers) {
+    const f = c.frame;
+    const colEnd = gridCell(f.x + f.width + WITHIN_EPS);
+    const rowEnd = gridCell(f.y + f.height + WITHIN_EPS);
+    for (let row = gridCell(f.y - WITHIN_EPS); row <= rowEnd; row++) {
+      for (let col = gridCell(f.x - WITHIN_EPS); col <= colEnd; col++) {
+        const key = row * CONTAINMENT_GRID_N + col;
+        const bucket = cells.get(key);
+        if (bucket) bucket.push(c);
+        else cells.set(key, [c]);
+      }
+    }
+  }
+  return (node) => {
+    const bucket = cells.get(gridCell(node.frame.y) * CONTAINMENT_GRID_N + gridCell(node.frame.x));
+    return bucket !== void 0 && bucket.some((c) => c !== node && frameWithin(node.frame, c.frame));
+  };
+}
+function frameAbove(a, b) {
+  return a.y + a.height <= b.y + WITHIN_EPS;
+}
+function followKind(node, anchor) {
+  const below = frameAbove(anchor, node);
+  const above = frameAbove(node, anchor);
+  if (below !== above) return below ? "below" : "no";
+  const right = anchor.x + anchor.width <= node.x + WITHIN_EPS;
+  const left = node.x + node.width <= anchor.x + WITHIN_EPS;
+  return right !== left && right ? "band" : "no";
+}
+function frameAfter(node, anchor) {
+  return followKind(node, anchor) !== "no";
+}
+function afterTester(anchors) {
+  return (node) => anchors.some((a) => a !== node && frameAfter(node.frame, a.frame));
+}
+function comparePick(a, b) {
+  return frameArea(a) - frameArea(b) || a.width - b.width || a.height - b.height;
+}
+function compareBandPick(a, b) {
+  return a.x - b.x || a.y - b.y || comparePick(a, b);
+}
+function compareBelowPick(a, b) {
+  return a.y - b.y || a.x - b.x || comparePick(a, b);
+}
+function nearestAfter(candidates, anchors) {
+  if (candidates.length === 0 || anchors.length === 0) return [];
+  const picked = /* @__PURE__ */ new Set();
+  for (const anchor of anchors) {
+    const af = anchor.frame;
+    let band;
+    let below;
+    for (const c of candidates) {
+      if (c === anchor) continue;
+      const f = c.frame;
+      const kind = followKind(f, af);
+      if (kind === "band") {
+        if (band === void 0 || compareBandPick(f, band.frame) < 0) band = c;
+      } else if (kind === "below") {
+        if (below === void 0 || compareBelowPick(f, below.frame) < 0) below = c;
+      }
+    }
+    const best = band ?? below;
+    if (best !== void 0) picked.add(best);
+  }
+  return candidates.filter((c) => picked.has(c));
 }
 function findAll(root2, selector) {
-  const acc = [];
-  const textRegex = selectorTextRegex(selector);
-  for (const child of root2.children) collectMatches(child, selector, textRegex, acc);
-  return acc;
+  const all = [];
+  const collect = (node) => {
+    all.push(node);
+    for (const child of node.children) collect(child);
+  };
+  for (const child of root2.children) collect(child);
+  return resolveSelector(all, selector);
+}
+var SELECTOR_RELATIONS = ["within", "after", "next"];
+var RELATION_RESOLVERS = {
+  within: (matches2, scope) => matches2.filter(containmentTester(scope)),
+  after: (matches2, scope) => matches2.filter(afterTester(scope)),
+  next: (matches2, scope) => nearestAfter(matches2, scope)
+};
+function resolveSelector(all, selector) {
+  const regex = selectorTextRegex(selector);
+  let matches2 = all.filter((n) => matchNodeWithRegex(n, selector, regex));
+  for (const relation of SELECTOR_RELATIONS) {
+    const scope = selector[relation];
+    if (scope === void 0) continue;
+    matches2 = RELATION_RESOLVERS[relation](matches2, resolveSelector(all, scope));
+  }
+  return matches2;
 }
 function isVisible(node) {
   return node.frame.width > 0 && node.frame.height > 0;
@@ -133765,6 +133864,13 @@ function exactFieldCount(node, selector, fullTextRegex) {
 function selectorToFrame(root2, selector) {
   const visible = findAll(root2, selector).filter(isVisible);
   if (visible.length === 0) return void 0;
+  if (!hasOwnConstraint(selector)) {
+    let first;
+    for (const n of visible) {
+      if (first === void 0 || compareBelowPick(n.frame, first.frame) < 0) first = n;
+    }
+    return first?.frame;
+  }
   const fullTextRegex = fullConsumptionRegex(selector);
   let best;
   let bestExact = -1;
@@ -146213,6 +146319,18 @@ function clearActiveFlow() {
   activeFlowName = null;
   recordingSession = null;
 }
+function selectorTree(sel) {
+  const out = [];
+  const walk = (s) => {
+    out.push(s);
+    for (const relation of SELECTOR_RELATIONS) {
+      const nested = s[relation];
+      if (nested !== void 0) walk(nested);
+    }
+  };
+  walk(sel);
+  return out;
+}
 function isE2eFlow(flow) {
   const first = flow.steps.find((s) => s.kind !== "echo");
   return first?.kind === "launch";
@@ -146246,11 +146364,35 @@ function selectorToYaml(sel) {
       "Cannot serialize flow selector: `text` must contain at least one visible character (icon-font/private-use and zero-width characters render as nothing). Select by identifier or role, or use a coordinate tap."
     );
   }
-  if (sel.loose && (sel.text === void 0 || sel.textMatches !== void 0 || sel.identifier !== void 0 || sel.role !== void 0)) {
+  const scopeCount = SELECTOR_RELATIONS.filter((relation) => sel[relation] !== void 0).length;
+  if (sel.any !== void 0) {
+    if (sel.any !== true) {
+      throw new Error(
+        "Cannot serialize flow selector: `any` is the universal selector and takes only `true` \u2014 omit it to select by text/id/role."
+      );
+    }
+    if (sel.text !== void 0 || sel.textMatches !== void 0 || sel.identifier || sel.role) {
+      throw new Error(
+        "Cannot serialize flow selector: `any` already matches every element, so it cannot be combined with text/id/role \u2014 keep one or the other."
+      );
+    }
+    if (scopeCount === 0) {
+      throw new Error(
+        `Cannot serialize flow selector: \`any\` matches every element on screen, so it needs a scope (${SELECTOR_RELATIONS.join("/")}) to narrow what it selects.`
+      );
+    }
+  } else if (scopeCount > 0 && sel.text === void 0 && sel.textMatches === void 0 && !sel.identifier && !sel.role) {
+    throw new Error(
+      `Cannot serialize flow selector: a scope (${SELECTOR_RELATIONS.join("/")}) only narrows where to look \u2014 the selector still needs its own text/id/role naming what to find there, or \`any: true\` for any element.`
+    );
+  }
+  if (sel.loose && (sel.text === void 0 || sel.textMatches !== void 0 || sel.identifier !== void 0 || sel.role !== void 0 || sel.any !== void 0 || SELECTOR_RELATIONS.some((relation) => sel[relation] !== void 0))) {
     const incompatible = [
       sel.textMatches !== void 0 ? "textMatches" : void 0,
       sel.identifier !== void 0 ? "identifier" : void 0,
-      sel.role !== void 0 ? "role" : void 0
+      sel.role !== void 0 ? "role" : void 0,
+      sel.any !== void 0 ? "any" : void 0,
+      ...SELECTOR_RELATIONS.map((relation) => sel[relation] !== void 0 ? relation : void 0)
     ].filter((field) => field !== void 0);
     throw new Error(
       "Cannot serialize loose flow selector without changing its meaning: bare-string YAML can represent only a loose text-only selector" + (incompatible.length > 0 ? `; incompatible fields: ${incompatible.join(", ")}` : "") + "."
@@ -146259,16 +146401,30 @@ function selectorToYaml(sel) {
   if (sel.loose && sel.text !== void 0 && sel.identifier === void 0 && sel.role === void 0) {
     return sel.text;
   }
-  const { loose: _loose, identifier, textMatches: textMatches2, ...rest } = sel;
+  const { loose: _loose, any: any2, identifier, textMatches: textMatches2, within, after, next, ...rest } = sel;
+  const scopes = { within, after, next };
   const out = { ...rest };
+  if (any2) out.any = true;
   if (textMatches2 !== void 0) out.text = { matches: textMatches2 };
   if (identifier !== void 0) out.id = identifier;
+  for (const relation of SELECTOR_RELATIONS) {
+    const scope = scopes[relation];
+    if (scope !== void 0) out[relation] = selectorToYaml(scope);
+  }
   return out;
 }
 function describeSelector(s) {
-  return Object.entries(s).filter(([k]) => k !== "loose").map(
+  const { loose: _loose, any: any2, within, after, next, ...rest } = s;
+  const scopes = { within, after, next };
+  const fields = Object.entries(rest).map(
     ([k, v]) => k === "textMatches" ? `text=/${v}/` : `${k === "identifier" ? "id" : k}="${v}"`
   ).join(" ");
+  const parts = [any2 ? "*" : void 0, fields || void 0].filter((p) => p !== void 0);
+  for (const relation of SELECTOR_RELATIONS) {
+    const scope = scopes[relation];
+    if (scope !== void 0) parts.push(`${relation} (${describeSelector(scope)})`);
+  }
+  return parts.join(" ");
 }
 function describeTextExpectation(expectedText, textMatch, verbForm = "mode") {
   const expected = expectedText ?? "";
@@ -146510,8 +146666,22 @@ function rejectUnknownKeys(raw, body, allowed, where) {
     `${where} has ${describeUnknownKeys(unknown2, allowed)} \u2014 allowed keys: ${allowed.join(", ")}`
   );
 }
-var SELECTOR_KEYS = ["text", "id", "identifier", "role"];
-function parseSelector(raw, where) {
+var SELECTOR_KEYS = [
+  "text",
+  "id",
+  "identifier",
+  "role",
+  "any",
+  ...SELECTOR_RELATIONS
+];
+var MAX_SELECTOR_SCOPES = 6;
+function parseSelector(raw, where, budget = { scopes: MAX_SELECTOR_SCOPES }) {
+  if (budget.scopes < 0) {
+    badEntry(
+      raw,
+      `${where}: a selector carries more than ${MAX_SELECTOR_SCOPES} scopes (${SELECTOR_RELATIONS.join("/")}) in total \u2014 check for a cyclic YAML alias (\`&s { \u2026, within: *s }\`)`
+    );
+  }
   if (typeof raw === "string") {
     const r2 = selectorSchema.safeParse({ text: raw });
     if (!r2.success) badEntry(raw, `${where}: ${r2.error.issues[0]?.message ?? "invalid selector"}`);
@@ -146520,9 +146690,55 @@ function parseSelector(raw, where) {
   if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
     rejectUnknownKeys(raw, raw, SELECTOR_KEYS, `${where}: selector`);
   }
-  let normalized = raw;
-  if (raw !== null && typeof raw === "object" && "id" in raw) {
-    const { id, ...rest } = raw;
+  const scopes = {};
+  let universal = false;
+  let fieldsRaw = raw;
+  if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+    const restRaw = { ...raw };
+    const present = SELECTOR_RELATIONS.filter((relation) => relation in restRaw);
+    for (const relation of present) {
+      budget.scopes--;
+      scopes[relation] = parseSelector(restRaw[relation], `${where}.${relation}`, budget);
+      delete restRaw[relation];
+    }
+    if ("any" in restRaw) {
+      if (restRaw.any !== true) {
+        badEntry(
+          raw,
+          `${where}: \`any\` takes only \`true\` \u2014 it is the CSS \`*\` universal selector (drop the key to select by text/id/role instead)`
+        );
+      }
+      delete restRaw.any;
+      if (Object.keys(restRaw).length > 0) {
+        badEntry(
+          raw,
+          `${where}: \`any: true\` already matches every element \u2014 drop it, or drop the ${Object.keys(
+            restRaw
+          ).map((k) => `\`${k}\``).join("/")} it makes redundant`
+        );
+      }
+      if (present.length === 0) {
+        badEntry(
+          raw,
+          `${where}: \`any: true\` matches every element on screen \u2014 pair it with a scope (${SELECTOR_RELATIONS.join(
+            "/"
+          )}) so it selects something specific`
+        );
+      }
+      universal = true;
+    } else if (present.length > 0 && Object.keys(restRaw).length === 0) {
+      badEntry(
+        raw,
+        `${where}: a selector's \`${present.join("`/`")}\` only scopes where to look \u2014 the selector still needs its own text/id/role naming what to find there (or \`any: true\` for any element)`
+      );
+    }
+    fieldsRaw = restRaw;
+  }
+  const attachScopes = (sel) => ({ ...sel, ...scopes });
+  if (universal) return attachScopes({ any: true });
+  let normalized = fieldsRaw;
+  if (fieldsRaw !== null && typeof fieldsRaw === "object" && "id" in fieldsRaw) {
+    const { id, ...rest } = fieldsRaw;
     if ("identifier" in rest) {
       badEntry(raw, `${where}: selector takes \`id\` or \`identifier\` (its alias), not both`);
     }
@@ -146555,12 +146771,12 @@ function parseSelector(raw, where) {
       if (!fields.success) {
         badEntry(raw, `${where}: ${fields.error.issues[0]?.message ?? "invalid selector"}`);
       }
-      return { ...fields.data, textMatches: pattern };
+      return attachScopes({ ...fields.data, textMatches: pattern });
     }
   }
   const r = selectorSchema.safeParse(normalized);
   if (!r.success) badEntry(raw, `${where}: ${r.error.issues[0]?.message ?? "invalid selector"}`);
-  return r.data;
+  return attachScopes(r.data);
 }
 var WAIT_CONDITIONS = ["exists", "visible", "hidden", "text"];
 var TEXT_MATCH_MODES = Object.keys({
@@ -146711,11 +146927,14 @@ function parseTapTimes(raw, entry) {
   }
   return raw === 1 ? void 0 : raw;
 }
+function hasSelectorField(obj) {
+  return obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0 || obj.any !== void 0 || SELECTOR_RELATIONS.some((relation) => obj[relation] !== void 0);
+}
 function parseTarget(raw, where) {
   if (raw !== null && typeof raw === "object") {
     const obj = raw;
     if (obj.x !== void 0 || obj.y !== void 0) {
-      if (obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0) {
+      if (hasSelectorField(obj)) {
         badEntry(raw, `${where} takes a selector or x/y coordinates, not both`);
       }
       if (typeof obj.x !== "number" || typeof obj.y !== "number") {
@@ -146738,7 +146957,7 @@ function parseTarget(raw, where) {
 function parseTap(body, entry) {
   const obj = body !== null && typeof body === "object" ? body : {};
   if (obj.on !== void 0 || obj.times !== void 0) {
-    if (obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0) {
+    if (hasSelectorField(obj)) {
       badEntry(
         entry,
         'the tap options form takes a nested selector \u2014 e.g. tap: { on: { text: "Photo" }, times: 2 }'
@@ -146766,7 +146985,7 @@ function parseTap(body, entry) {
 function parseLongPress(body, entry) {
   const obj = body !== null && typeof body === "object" ? body : {};
   if (obj.on !== void 0 || obj.duration !== void 0) {
-    if (obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0) {
+    if (hasSelectorField(obj)) {
       badEntry(
         entry,
         'the long-press options form takes a nested selector \u2014 e.g. long-press: { on: { text: "Row" }, duration: 1200 }'
@@ -146806,7 +147025,7 @@ function parsePinch(body, entry) {
     );
   }
   const obj = body;
-  if (obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0) {
+  if (hasSelectorField(obj)) {
     badEntry(entry, 'pinch takes a nested selector \u2014 e.g. pinch: { on: "Map", scale: 3 }');
   }
   rejectUnknownKeys(entry, obj, ["on", "scale"], "pinch");
@@ -146873,13 +147092,11 @@ function parseWhenCondition(raw) {
   }
   const { timeout: _timeout, ...cond } = parseWaitFields(raw, "when");
   const { selector, expectedText } = cond;
-  for (const s of [
-    expectedText,
-    selector.text,
-    selector.textMatches,
-    selector.identifier,
-    selector.role
-  ]) {
+  const guardStrings = [expectedText];
+  for (const s of selectorTree(selector)) {
+    guardStrings.push(s.text, s.textMatches, s.identifier, s.role);
+  }
+  for (const s of guardStrings) {
     if (s !== void 0 && s.includes(SECRET_PLACEHOLDER_MARKER)) {
       badEntry(
         { when: raw },
@@ -147004,6 +147221,12 @@ function fromYamlStep(raw, whenDepth = 0) {
     if (b.direction !== void 0 && (typeof b.direction !== "string" || !SCROLL_DIRECTIONS.includes(b.direction))) {
       badEntry(raw, `scroll-to direction must be one of ${SCROLL_DIRECTIONS.join(", ")}`);
     }
+    if (b.target === void 0) {
+      badEntry(
+        raw,
+        `scroll-to needs a \`target\` \u2014 its own \`within\` only anchors the gesture to a scroll container, e.g. scroll-to: { target: <selector>, within: { id: list } }. A selector scope (${SELECTOR_RELATIONS.join("/")}) goes inside \`target\`.`
+      );
+    }
     const step = {
       kind: "scroll-to",
       target: parseSelector(b.target, "scroll-to.target"),
@@ -148002,7 +148225,16 @@ function probeWhenCondition(env, cond) {
   return waitForCondition(env, cond, DEFAULT_ASSERT_TIMEOUT_MS);
 }
 function selectorAlternatives(sel) {
-  return sel.loose && sel.text !== void 0 ? [{ identifier: sel.text }, { text: sel.text }] : [sel];
+  const { loose, any: _any2, within, after, next, ...own } = sel;
+  const scopes = { within, after, next };
+  let alts = loose && own.text !== void 0 ? [{ identifier: own.text }, { text: own.text }] : [own];
+  for (const relation of SELECTOR_RELATIONS) {
+    const scope = scopes[relation];
+    if (scope === void 0) continue;
+    const scopeAlts = selectorAlternatives(scope);
+    alts = alts.flatMap((o) => scopeAlts.map((s) => ({ ...o, [relation]: s })));
+  }
+  return alts;
 }
 function flowFindAll(tree, sel) {
   let fallback = [];
@@ -150893,7 +151125,13 @@ function createRunFlowTool(registry2) {
 Steps run in order: \`launch\` starts an app from scratch (terminate + relaunch) and waits until it is
 ready; \`tool\` calls dispatch through the registry; \`tap\`/\`long-press\`/\`type\` resolve a selector to an
 element and act on it (\`tap: { on, times: 2 }\` double-taps; \`long-press: { on, duration }\` presses and
-holds; \`tap\`/\`long-press\` alternatively take a raw normalized point \u2014 bare \`{ x, y }\` or \`on: { x, y }\`);
+holds; \`tap\`/\`long-press\` alternatively take a raw normalized point \u2014 bare \`{ x, y }\` or \`on: { x, y }\`;
+any selector may scope its matches geometrically, the CSS combinators read off frames: \`within: <selector>\`
+(descendant \u2014 inside that container's frame), \`after: <selector>\` (CSS \`~\` \u2014 following it in reading
+order), \`next: <selector>\` (CSS \`+\` \u2014 the nearest such follower, which unlike CSS reaches past a
+non-matching neighbour rather than failing), plus \`any: true\` (CSS \`*\` \u2014 legal only WITH a scope and
+never beside text/id/role). Scopes nest to disambiguate \u2014 \`within: { id: card, within: { id: list } }\`
+reads "inside card inside list", each container's frame inside the next);
 \`scroll-to\` scrolls (momentum-free) until a target is visible; \`pinch\` zooms
 (\`pinch: { on?, scale }\` \u2014 scale > 1 in, < 1 out; screen center when \`on\` is omitted); \`rotate\` is the
 two-finger rotation gesture (\`rotate: { on?, by }\` \u2014 degrees, + clockwise, within \xB13000\xB0; screen center
@@ -151052,10 +151290,15 @@ function pushReport(state3, report) {
 }
 function selectorLabel2(sel) {
   const parts = [];
+  if (sel.any) parts.push("*");
   if (sel.text !== void 0) parts.push(`"${sel.text}"`);
   if (sel.textMatches !== void 0) parts.push(`/${sel.textMatches}/`);
   if (sel.identifier) parts.push(`id=${sel.identifier}`);
   if (sel.role) parts.push(`role=${sel.role}`);
+  for (const relation of SELECTOR_RELATIONS) {
+    const scope = sel[relation];
+    if (scope !== void 0) parts.push(`${relation} (${selectorLabel2(scope)})`);
+  }
   return parts.join(" ");
 }
 function conditionLabel(cond, renderSelector) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.17.1-next.2",
+  "version": "0.17.1-next.3",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",
   "repository": {

package/skills/argent-create-flow/SKILL.md

@@ -38,11 +38,35 @@ Beyond raw `tool:` steps and `echo:`, flows support declarative directives inter
 
 ### Selectors
 
-A **selector** is `{ text?, id?, role? }` (all-must-match; `text`/`role` are case-insensitive substrings, `id` matches the element's testID / accessibilityIdentifier / resource-id exactly, case-insensitive, also accepting the unqualified Android resource-id name — `submit` matches `com.example.app:id/submit`) — the same semantics `await-ui-element` uses, though that tool spells the `id` field `identifier` (flow YAML also accepts `identifier` as an alias for `id`, but `id` is the canonical spelling and what the recorder writes). A bare string is a _loose_ selector: it resolves **identifier-first, then falls back to text** (label/value), so `tap: Login` matches a `testID="Login"` or, failing that, visible text "Login" — no need to know which. Loose fallback applies uniformly to every selector slot (`tap`, `type.into`, `await`, `assert`, `scroll-to`). Use the map form to be strict: `{ id: submit-btn }` (identifier only) or `{ text: Login }` (text only, no fallback).
+A **selector** is `{ text?, id?, role? }` plus the optional scopes below (all-must-match; `text`/`role` are case-insensitive substrings, `id` matches the element's testID / accessibilityIdentifier / resource-id exactly, case-insensitive, also accepting the unqualified Android resource-id name — `submit` matches `com.example.app:id/submit`) — the same semantics `await-ui-element` uses, though that tool spells the `id` field `identifier` (flow YAML also accepts `identifier` as an alias for `id`, but `id` is the canonical spelling and what the recorder writes). A bare string is a _loose_ selector: it resolves **identifier-first, then falls back to text** (label/value), so `tap: Login` matches a `testID="Login"` or, failing that, visible text "Login" — no need to know which. Loose fallback applies uniformly to every selector slot (`tap`, `type.into`, `await`, `assert`, `scroll-to`). Use the map form to be strict: `{ id: submit-btn }` (identifier only) or `{ text: Login }` (text only, no fallback).
 
 `text` also takes a **regex matcher map** — `{ text: { matches: '^Order #\d+$' } }`, in any selector slot — for dynamic text no literal can pin. It tests each node's native **own** label/value (not the adapter-hoisted `subtreeText`), though on iOS a container's own label may itself aggregate descendant text, so a wrapper and its leaf can both match. Same regex rules as `text.in`'s `matches` (see _`await` and `assert`_): unanchored, **case-sensitive**, single-quoted, invalid pattern fails at parse. So `assert: { visible: { text: { matches: '^Taps: \d+$' } } }` asserts a counter is on screen with no locator at all, and `tap: { text: { matches: '^Order #\d+$' } }` taps a dynamic row — though a stable `id` stays the more robust action target.
 
-Selectors resolve against the **full native hierarchy** (iOS: the UIView tree; Android: the complete accessibility hierarchy including not-important views) — strictly more than `describe` or the raw `await-ui-element` tool see (both use the trimmed tree), with complete `testID`/`resource-id` coverage. So an `id` selector works even when `describe` collapses or omits the element — don't fall back to coordinate taps just because a testID isn't visible in `describe` output. And when several elements match — including wrappers whose native text aggregates descendant content — the action directives (`tap`, `type`, `scroll-to`) pick the **most specific** match: an exact text/identifier match beats a substring hit (for a regex matcher, a pattern consuming the element's whole text counts as exact), then the smallest frame wins.
+#### Scopes — CSS combinators, read off frames
+
+A map selector may also carry a **scope**: a nested selector naming another element the match must sit in a given spatial relation to. These are the geometric readings of the CSS combinators that survive a flattened tree — the child combinator `>` has no analog, since parent/child structure does not reach replay. They combine, and nest up to six scopes per selector:
+
+| Scope           | CSS     | Reads as                                                        | Example                                                               |
+| --------------- | ------- | --------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `within: <sel>` | `A B`   | the match's frame sits **inside** the scope element's frame     | `tap: { text: Delete, within: { id: profile-card } }`                 |
+| `after: <sel>`  | `A ~ B` | the match **follows** the scope element in reading order        | `assert: { visible: { role: Button, after: { text: Danger zone } } }` |
+| `next: <sel>`   | `A + B` | as `after`, narrowed to the **nearest** follower of each anchor | `tap: { role: Switch, next: { text: Wi-Fi } }`                        |
+
+And `any: true` is the CSS `*` universal selector. It carries no locator of its own, so the parser enforces two rules: it needs **at least one scope** (a bare `any: true` would match the whole screen), and it may **not** sit beside `text`/`id`/`role` (which it would only make redundant — write `{ role: Switch, next: … }`, not `{ any: true, role: Switch, next: … }`). Only the literal `true` is accepted. `assert: { hidden: { any: true, within: { id: empty-state } } }` asserts an empty container. It works for actions too — `tap: { any: true, next: { text: Airplane Mode } }` taps whatever sits right after that label — but on a real tree "whatever" includes spacers and wrappers, so **name the target** (`role`, `id`) whenever you can and keep `any` for conditions and for `next`, which reduces to a single element per anchor.
+
+All of it is **visual (frame-based), not tree ancestry** — flow trees are flattened, and "inside the card" / "the switch after this label" mean what the screen shows — the same frame-based reading of "within" that `scroll-to`'s container anchor uses. Every scope needs a **distinct element** (nothing scopes itself, so `{ id: card, within: { id: card } }` needs two nested elements), the synthetic screen root never counts, and a scope only narrows _where_ to look — the selector still needs its own `text`/`id`/`role` naming _what_ to find there, or `any: true`. The nested slot takes every selector form: a bare string keeps the loose identifier-first fallback (`within: profile-card`), the map form stays strict, the regex matcher works (`within: { text: { matches: '^Card \d+$' } }`). Scopes are flow-YAML only; the raw `await-ui-element` tool's selector accepts none of them. Prefer a unique `id` on the target itself when one exists — reach for a scope when the target has no unique locator of its own (repeated row actions, per-card buttons, list cells).
+
+**`within`** — `tap: { text: Delete, within: { id: profile-card } }` taps the Delete button in the profile card even when other cards show identical ones; `tap: { text: "Pin feed", within: { text: "For You" } }` picks one card's button out of a whole list. Scope to a container with a **tight frame** (a row, card, dialog, toast): a full-screen wrapper contains everything and scopes nothing. It chains outward: `{ text: Save, within: { id: cards, within: Settings } }` reads "Save inside cards inside Settings", each container's frame inside the next.
+
+**`after` / `next`** — reading order is row-band aware: an element **follows** the anchor when it starts below the anchor's bottom edge, _or_ shares its row band and sits entirely to its right. That is what makes `{ role: Switch, next: { text: Wi-Fi } }` resolve the Wi-Fi row's own switch even though the taller switch's frame starts a couple of pixels _higher_ than the label's. `next` keeps only the nearest follower — a match in the anchor's own row beats anything on the rows below, leftmost first — while `after` keeps them all, so `assert: { hidden: { role: Button, after: { text: Danger zone } } }` holds when nothing button-like appears past that heading. Both union over anchors exactly as CSS does: with three rows on screen, `{ role: Switch, next: { role: AXStaticText } }` yields all three switches, one per label. Note that "follows" is **not transitive** — against a tall anchor, an element can follow something that itself follows the anchor without following the anchor directly — so nesting `after` scopes is not the same as chaining CSS `~`: `{ after: { …, after: … } }` can match elements a single `after` excludes. Nest them only when each link is a container-sized step. An element sitting _inside_ the anchor does not follow **that** anchor — containment is not reading order — so scope by `within` for that.
+
+**Prefer the map form for a scope's anchor.** A bare-string scope (`next: wifi-row`) keeps the loose identifier-first fallback, and the runner takes the first pass that finds a _visible_ match — so if some unrelated element carries `testID="wifi-row"`, the identifier pass wins and the text pass never runs. Reproduced: with a decoy `testID="Wi-Fi"` elsewhere on screen, `tap: { role: Switch, next: Wi-Fi }` taps the decoy's neighbour and reports a pass. This is the ordinary identifier-first doctrine, but a scope makes a decoy likelier to "succeed": a decoy _container_ only wins if it actually holds a match, while a decoy _anchor_ wins if anything at all sits after it — which on a real screen it usually does. Spell an anchor you care about as a map: `next: { text: Wi-Fi }` or `next: { id: wifi-row }`.
+
+One way `next` is deliberately **looser than CSS `+`**: where `A + B` matches nothing unless the very next sibling is a `B`, `next` keeps looking and returns the nearest match further on. That is what makes it survive the wrapper and spacer nodes a flattened tree is full of, but it also means a row that is _missing_ the control you asked for silently resolves to the next row's — `{ role: Switch, next: { text: Wi-Fi } }` on a Wi-Fi row rendered without a switch returns the _Bluetooth_ row's switch rather than failing. When a row may legitimately lack the control, assert it first (`assert: { visible: { role: Switch, within: { id: wifi-row } } }`) or scope by `within` instead.
+
+Scopes compose, and it matters which one carries them. `{ role: Button, next: { text: Name, within: { id: card-b } } }` scopes the **anchor** — one label, so one pick, but that pick may land outside card-b. `{ role: Button, next: { text: Name }, within: { id: card-b } }` scopes the **target** — every label is still an anchor, but only card-b's buttons can be picked. They agree on a well-formed screen and diverge when card-b has no button: the first reaches on to the next card's, the second returns nothing. Scope the target when the container is the thing you trust. Conditions honor scopes like any other selector: `assert: { hidden: { text: Saved, within: { id: toast-area } } }` holds when nothing matching "Saved" is inside the toast area — matches elsewhere on screen don't count, and a missing scope element satisfies `hidden` (and fails `visible`/`exists`).
+
+Selectors resolve against the **full native hierarchy** (iOS: the UIView tree; Android: the complete accessibility hierarchy including not-important views) — strictly more than `describe` or the raw `await-ui-element` tool see (both use the trimmed tree), with complete `testID`/`resource-id` coverage. So an `id` selector works even when `describe` collapses or omits the element — don't fall back to coordinate taps just because a testID isn't visible in `describe` output. And when several elements match — including wrappers whose native text aggregates descendant content — the action directives (`tap`, `type`, `scroll-to`) pick the **most specific** match: an exact text/identifier match beats a substring hit (for a regex matcher, a pattern consuming the element's whole text counts as exact), then the smallest frame wins. (A universal `any: true` selector has no field to be exact about, so its matches rank by reading order instead — the first element in the scope, which is the element a condition reads too. Where two matches share a top-left corner, an action breaks the tie toward the smaller, more specific one and a condition does not, so those two can name different elements.)
 
 **Quote strings YAML would mangle.** An unquoted `#` starts a YAML comment — `tap: Order #1234` silently parses as `tap: Order` — and bare `yes`/`no`/`on`/`off`/numbers coerce to non-strings. When a selector or typed text contains `#`, `:`, quotes, or could read as a boolean/number, wrap it: `tap: "Order #1234"`.
 
@@ -65,7 +89,7 @@ For a custom poll interval or bundleId, drop to an explicit `- tool: await-ui-el
 
 Never record a real credential into a flow — the YAML is committed to the repo. Use a secret placeholder instead: `type: { into: password, text: "{{secret:APP_PASSWORD}}" }`. The placeholder is stored verbatim (the YAML stays secret-free) and is resolved at run time by the tool-server from the `ARGENT_SECRET_APP_PASSWORD` environment variable — including agent-less `argent flow run` in CI, where the variable comes from the job's secrets.
 
-`scroll-to` takes an optional `direction` (`up` | `down` | `left` | `right`, default `down` — so the common case is just `- scroll-to: <selector>`) and optionally a `within: <selector>` that anchors the scroll inside a specific container — required to drive a **nested** scroller (e.g. a horizontal carousel inside a vertical list), since the device can't be asked which container to scroll. It scrolls in bounded momentum-free increments, re-checks after each, and stops if a scroll reveals nothing new (end of the container). `tap`/`type` do **not** scroll — add a `scroll-to` before any target that may be off-screen. It's a no-op when the target is already visible, so a defensive `scroll-to` costs nothing on replay and keeps the flow working on smaller screens.
+`scroll-to` takes an optional `direction` (`up` | `down` | `left` | `right`, default `down` — so the common case is just `- scroll-to: <selector>`) and optionally a `within: <selector>` that anchors the scroll inside a specific container — required to drive a **nested** scroller (e.g. a horizontal carousel inside a vertical list), since the device can't be asked which container to scroll. This step-level `within` (a sibling of `target`) anchors the _gesture_, and it is the **only** scope key the step body takes — `after:`/`next:`/`any:` beside `target` are rejected. It is distinct from a selector's scopes (see Selectors), which `target` may itself carry — `scroll-to: { target: { text: Delete, within: { id: cards } }, within: { id: settings-list } }` scrolls the settings list until the Delete button _inside the cards container_ is visible. It scrolls in bounded momentum-free increments, re-checks after each, and stops if a scroll reveals nothing new (end of the container). `tap`/`type` do **not** scroll — add a `scroll-to` before any target that may be off-screen. It's a no-op when the target is already visible, so a defensive `scroll-to` costs nothing on replay and keeps the flow working on smaller screens.
 
 ### `snapshot` cropping