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

package/dist/cli-cmds.mjs

@@ -7755,7 +7755,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.17.1-next.1";
+    return "0.17.0";
   }
   return "0.0.0";
 }

package/dist/installer.mjs

@@ -17044,7 +17044,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID3();
 function readCliVersion() {
   if (true) {
-    return "0.17.1-next.1";
+    return "0.17.0";
   }
   return "0.0.0";
 }

package/dist/tool-server.cjs

@@ -81164,7 +81164,7 @@ var require_websocket = __commonJS({
     var http5 = require("http");
     var net6 = require("net");
     var tls = require("tls");
-    var { randomBytes, createHash: createHash3 } = require("crypto");
+    var { randomBytes, createHash: createHash4 } = require("crypto");
     var { Duplex, Readable } = require("stream");
     var { URL: URL2 } = require("url");
     var PerMessageDeflate2 = require_permessage_deflate();
@@ -81832,7 +81832,7 @@ var require_websocket = __commonJS({
           abortHandshake(websocket, socket, "Invalid Upgrade header");
           return;
         }
-        const digest = createHash3("sha1").update(key + GUID).digest("base64");
+        const digest = createHash4("sha1").update(key + GUID).digest("base64");
         if (res.headers["sec-websocket-accept"] !== digest) {
           abortHandshake(websocket, socket, "Invalid Sec-WebSocket-Accept header");
           return;
@@ -82201,7 +82201,7 @@ var require_websocket_server = __commonJS({
     var EventEmitter2 = require("events");
     var http5 = require("http");
     var { Duplex } = require("stream");
-    var { createHash: createHash3 } = require("crypto");
+    var { createHash: createHash4 } = require("crypto");
     var extension2 = require_extension();
     var PerMessageDeflate2 = require_permessage_deflate();
     var subprotocol2 = require_subprotocol();
@@ -82508,7 +82508,7 @@ var require_websocket_server = __commonJS({
           );
         }
         if (this._state > RUNNING) return abortHandshake(socket, 503);
-        const digest = createHash3("sha1").update(key + GUID).digest("base64");
+        const digest = createHash4("sha1").update(key + GUID).digest("base64");
         const headers = [
           "HTTP/1.1 101 Switching Protocols",
           "Upgrade: websocket",
@@ -83162,10 +83162,10 @@ function avdRootCandidates() {
   return candidates.filter((p) => Boolean(p && (0, import_node_path6.isAbsolute)(p)));
 }
 async function resolveAvdPath(avdName) {
-  const { readFile: readFile11 } = await import("node:fs/promises");
+  const { readFile: readFile12 } = await import("node:fs/promises");
   for (const root2 of avdRootCandidates()) {
     try {
-      const content = await readFile11(`${root2}/${avdName}.ini`, "utf-8");
+      const content = await readFile12(`${root2}/${avdName}.ini`, "utf-8");
       const raw = (0, import_ini.parse)(content).path;
       if (typeof raw !== "string") continue;
       const trimmed = raw.trim();
@@ -90969,7 +90969,7 @@ var require_png = __commonJS({
     var Parser = require_parser_async();
     var Packer = require_packer_async();
     var PNGSync = require_png_sync();
-    var PNG3 = exports2.PNG = function(options) {
+    var PNG4 = exports2.PNG = function(options) {
       Stream2.call(this);
       options = options || {};
       this.width = options.width | 0;
@@ -90998,9 +90998,9 @@ var require_png = __commonJS({
       this._parser.on("close", this._handleClose.bind(this));
       this._packer.on("error", this.emit.bind(this, "error"));
     };
-    util.inherits(PNG3, Stream2);
-    PNG3.sync = PNGSync;
-    PNG3.prototype.pack = function() {
+    util.inherits(PNG4, Stream2);
+    PNG4.sync = PNGSync;
+    PNG4.prototype.pack = function() {
       if (!this.data || !this.data.length) {
         this.emit("error", "No data provided");
         return this;
@@ -91012,7 +91012,7 @@ var require_png = __commonJS({
       );
       return this;
     };
-    PNG3.prototype.parse = function(data, callback) {
+    PNG4.prototype.parse = function(data, callback) {
       if (callback) {
         let onParsed, onError;
         onParsed = function(parsedData) {
@@ -91030,27 +91030,27 @@ var require_png = __commonJS({
       this.end(data);
       return this;
     };
-    PNG3.prototype.write = function(data) {
+    PNG4.prototype.write = function(data) {
       this._parser.write(data);
       return true;
     };
-    PNG3.prototype.end = function(data) {
+    PNG4.prototype.end = function(data) {
       this._parser.end(data);
     };
-    PNG3.prototype._metadata = function(metadata) {
+    PNG4.prototype._metadata = function(metadata) {
       this.width = metadata.width;
       this.height = metadata.height;
       this.emit("metadata", metadata);
     };
-    PNG3.prototype._gamma = function(gamma) {
+    PNG4.prototype._gamma = function(gamma) {
       this.gamma = gamma;
     };
-    PNG3.prototype._handleClose = function() {
+    PNG4.prototype._handleClose = function() {
       if (!this._parser.writable && !this._packer.readable) {
         this.emit("close");
       }
     };
-    PNG3.bitblt = function(src, dst, srcX, srcY, width, height, deltaX, deltaY) {
+    PNG4.bitblt = function(src, dst, srcX, srcY, width, height, deltaX, deltaY) {
       srcX |= 0;
       srcY |= 0;
       width |= 0;
@@ -91072,11 +91072,11 @@ var require_png = __commonJS({
         );
       }
     };
-    PNG3.prototype.bitblt = function(dst, srcX, srcY, width, height, deltaX, deltaY) {
-      PNG3.bitblt(this, dst, srcX, srcY, width, height, deltaX, deltaY);
+    PNG4.prototype.bitblt = function(dst, srcX, srcY, width, height, deltaX, deltaY) {
+      PNG4.bitblt(this, dst, srcX, srcY, width, height, deltaX, deltaY);
       return this;
     };
-    PNG3.adjustGamma = function(src) {
+    PNG4.adjustGamma = function(src) {
       if (src.gamma) {
         for (let y = 0; y < src.height; y++) {
           for (let x = 0; x < src.width; x++) {
@@ -91091,8 +91091,8 @@ var require_png = __commonJS({
         src.gamma = 0;
       }
     };
-    PNG3.prototype.adjustGamma = function() {
-      PNG3.adjustGamma(this);
+    PNG4.prototype.adjustGamma = function() {
+      PNG4.adjustGamma(this);
     };
   }
 });
@@ -104493,7 +104493,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.17.1-next.1";
+    return "0.17.0";
   }
   return "0.0.0";
 }
@@ -105881,7 +105881,7 @@ var import_node_path5 = __toESM(require("node:path"));
 var import_semver = __toESM(require_semver2());
 
 // ../tool-server/package.json
-var version3 = "0.17.1-next.1";
+var version3 = "0.17.0";
 
 // ../tool-server/src/utils/update-checker.ts
 var import_update_core = __toESM(require_dist4());
@@ -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 ?? "";
@@ -146419,8 +146575,17 @@ function toYamlStep(step) {
       return {
         rotate: step.selector ? { on: selectorToYaml(step.selector), by: step.by } : { by: step.by }
       };
-    case "snapshot":
-      return step.maxMismatch === void 0 ? { snapshot: step.name } : { snapshot: { name: step.name, maxMismatch: step.maxMismatch } };
+    case "snapshot": {
+      if (step.maxMismatch === void 0 && step.cropOn === void 0) {
+        return { snapshot: step.name };
+      }
+      const body = {
+        name: step.name
+      };
+      if (step.maxMismatch !== void 0) body.maxMismatch = step.maxMismatch;
+      if (step.cropOn !== void 0) body.cropOn = selectorToYaml(step.cropOn);
+      return { snapshot: body };
+    }
     case "tool":
     default: {
       const y = {
@@ -146501,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"}`);
@@ -146511,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`);
     }
@@ -146546,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({
@@ -146702,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") {
@@ -146729,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 }'
@@ -146757,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 }'
@@ -146797,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");
@@ -146864,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 },
@@ -146995,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"),
@@ -147008,7 +147240,12 @@ function fromYamlStep(raw, whenDepth = 0) {
   if ("snapshot" in raw) {
     const body = raw.snapshot;
     if (body !== null && typeof body === "object" && !Array.isArray(body)) {
-      rejectUnknownKeys(raw, body, ["name", "maxMismatch"], "snapshot");
+      rejectUnknownKeys(
+        raw,
+        body,
+        ["name", "maxMismatch", "cropOn"],
+        "snapshot"
+      );
     }
     const b = typeof body === "string" ? { name: body } : body;
     if (!b || typeof b !== "object" || typeof b.name !== "string" || !b.name) {
@@ -147031,6 +147268,9 @@ function fromYamlStep(raw, whenDepth = 0) {
       }
       step.maxMismatch = m;
     }
+    if (b.cropOn !== void 0) {
+      step.cropOn = parseSelector(b.cropOn, "snapshot.cropOn");
+    }
     return step;
   }
   if ("tool" in raw) {
@@ -147985,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 = [];
@@ -148439,9 +148688,11 @@ function assertReason(condition, selector, expectedText, textMatch, matches2) {
 }
 
 // ../tool-server/src/tools/flows/flow-visual.ts
+var import_node_crypto8 = require("node:crypto");
 var fs44 = __toESM(require("node:fs/promises"));
 var os12 = __toESM(require("node:os"));
 var path32 = __toESM(require("node:path"));
+var import_pngjs3 = __toESM(require_png());
 
 // ../tool-server/src/tools/screenshot-diff/screenshot-diff.ts
 var import_promises11 = __toESM(require("fs/promises"));
@@ -150004,7 +150255,7 @@ async function diffPngFiles(options) {
     decodePngFile(options.baselinePath),
     decodePngFile(options.currentPath)
   ]);
-  const normalized = normalizeToCommonSize(decodedBaseline, decodedCurrent);
+  const normalized = options.normalizeSizes === false ? sameDimensionsOrNull(decodedBaseline, decodedCurrent) : normalizeToCommonSize(decodedBaseline, decodedCurrent);
   if (!normalized) {
     return summarizeResult(
       buildDimensionMismatchResult({
@@ -150071,6 +150322,9 @@ function resolveDiffSettings(topMask) {
 function summarizeResult(result) {
   return { ...result, summary: formatScreenshotDiffSummary(result) };
 }
+function sameDimensionsOrNull(baseline, current) {
+  return baseline.width === current.width && baseline.height === current.height ? { baseline, current } : null;
+}
 function buildDimensionMismatchResult(params) {
   return {
     totalPixels: params.baseline.width * params.baseline.height,
@@ -150490,6 +150744,15 @@ async function pngDimensions(file2) {
     await fh.close();
   }
 }
+function cropIdentity(s) {
+  return JSON.stringify([
+    s.text ?? null,
+    s.textMatches ?? null,
+    s.identifier ?? null,
+    s.role ?? null,
+    s.loose ?? false
+  ]);
+}
 function baselineDir(flowsDir, flowName) {
   return path32.join(flowsDir, "__baselines__", flowName);
 }
@@ -150506,80 +150769,153 @@ async function cleanupDiffDir(dir, keep) {
   } catch {
   }
 }
+async function cropPngFile(src, dest, frame) {
+  const png = import_pngjs3.PNG.sync.read(await fs44.readFile(src));
+  const left = Math.max(0, Math.round(frame.x * png.width));
+  const top = Math.max(0, Math.round(frame.y * png.height));
+  const right = Math.min(png.width, Math.round((frame.x + frame.width) * png.width));
+  const bottom = Math.min(png.height, Math.round((frame.y + frame.height) * png.height));
+  const w = right - left;
+  const h = bottom - top;
+  if (w < 1 || h < 1) return null;
+  const out = new import_pngjs3.PNG({ width: w, height: h });
+  import_pngjs3.PNG.bitblt(png, out, left, top, w, h, 0, 0);
+  await fs44.writeFile(dest, import_pngjs3.PNG.sync.write(out));
+  return { w, h };
+}
 async function runSnapshot(env, opts) {
-  try {
-    await settleTree(env);
-  } catch {
+  if (opts.cropOn === void 0) {
+    try {
+      await settleTree(env);
+    } catch {
+    }
   }
   if (env.signal?.aborted) {
     return { status: "skip", reason: "run aborted during snapshot settle" };
   }
+  let cropFrame;
+  if (opts.cropOn !== void 0) {
+    const frame = await waitForFrame(env, opts.cropOn);
+    if (frame === "aborted") {
+      return { status: "skip", reason: "run aborted while resolving cropOn" };
+    }
+    if (frame === void 0) {
+      return { status: "fail", reason: offscreenHint(opts.cropOn) };
+    }
+    cropFrame = frame;
+  }
   const store = requireArtifacts(env.ctx);
   const shot = await invokeOnDevice(env, "screenshot", {
     scale: 1,
     includeImageInContext: false
   });
-  const currentPath = shot.image.hostPath;
-  const { w, h } = await pngDimensions(currentPath);
-  const snapshotKey = `${opts.name}__${env.device.platform}-${w}x${h}`;
+  const { w, h } = await pngDimensions(shot.image.hostPath);
+  const cropSuffix = opts.cropOn === void 0 ? "" : `-crop-${(0, import_node_crypto8.createHash)("sha256").update(cropIdentity(opts.cropOn)).digest("hex").slice(0, 8)}`;
+  const snapshotKey = `${opts.name}__${env.device.platform}-${w}x${h}${cropSuffix}`;
   const key = `${snapshotKey}.png`;
   const dir = baselineDir(opts.flowsDir, opts.flowName);
   const baselinePath = path32.join(dir, key);
-  const exists2 = await fs44.access(baselinePath).then(() => true).catch(() => false);
-  if (opts.updateBaselines) {
-    await fs44.mkdir(dir, { recursive: true });
-    await fs44.copyFile(currentPath, baselinePath);
-    const baseline = await store.register(baselinePath, { mimeType: "image/png" });
-    return {
-      status: "pass",
-      reason: exists2 ? `baseline updated (${key})` : `baseline written (${key})`,
-      snapshotKey,
-      artifacts: { baseline }
-    };
-  }
-  if (!exists2) {
-    return {
-      status: "fail",
-      reason: `no baseline for "${opts.name}" on this device class \u2014 expected ${baselinePath}, nothing was compared. Run with updateBaselines (--update-baselines) to adopt the current screen, then review and commit it`,
-      snapshotKey,
-      artifacts: { current: shot.image }
-    };
-  }
-  const outputDir = await fs44.mkdtemp(path32.join(os12.tmpdir(), "argent-flow-diff-"));
-  let keepInOutputDir;
+  let currentPath = shot.image.hostPath;
+  let cropDir;
+  let keepCropped = false;
+  const currentArtifact = async () => {
+    if (cropDir === void 0) return shot.image;
+    keepCropped = true;
+    return store.register(currentPath, {
+      mimeType: "image/png",
+      filename: `${snapshotKey}-current.png`
+    });
+  };
   try {
-    const result = await diffPngFiles({ baselinePath, currentPath, outputDir });
-    if (result.dimensionMismatch) {
-      const { expected, actual } = result.dimensionMismatch;
+    if (cropFrame !== void 0) {
+      cropDir = await fs44.mkdtemp(path32.join(os12.tmpdir(), "argent-flow-crop-"));
+      const croppedPath = path32.join(cropDir, key);
+      const cropped = await cropPngFile(shot.image.hostPath, croppedPath, cropFrame);
+      if (cropped === null) {
+        return {
+          status: "fail",
+          reason: `cropOn matched ${describeSelector(opts.cropOn)} but its on-screen region is empty at this resolution \u2014 nothing was compared`,
+          snapshotKey,
+          // No crop exists to show, so attach the full capture (already registered).
+          artifacts: { current: shot.image }
+        };
+      }
+      currentPath = croppedPath;
+    }
+    const exists2 = await fs44.access(baselinePath).then(() => true).catch(() => false);
+    if (opts.updateBaselines) {
+      await fs44.mkdir(dir, { recursive: true });
+      await fs44.copyFile(currentPath, baselinePath);
+      const baseline = await store.register(baselinePath, { mimeType: "image/png" });
       return {
-        status: "fail",
-        reason: `baseline is ${expected.width}x${expected.height} but the capture is ${actual.width}x${actual.height} (${key}) \u2014 nothing was compared`,
+        status: "pass",
+        reason: exists2 ? `baseline updated (${key})` : `baseline written (${key})`,
         snapshotKey,
-        artifacts: {
-          baseline: await store.register(baselinePath, { mimeType: "image/png" }),
-          current: shot.image
-        }
+        artifacts: { baseline }
       };
     }
-    const within = result.mismatchPercentage <= opts.maxMismatch;
-    const reason = `diff ${result.mismatchPercentage.toFixed(2)}% ${within ? "\u2264" : ">"} ${opts.maxMismatch}% (${key})`;
-    if (within) {
-      return { status: "pass", reason };
+    if (!exists2) {
+      return {
+        status: "fail",
+        reason: `no baseline for "${opts.name}" on this device class \u2014 expected ${baselinePath}, nothing was compared. Run with updateBaselines (--update-baselines) to adopt the current screen, then review and commit it`,
+        snapshotKey,
+        artifacts: { current: await currentArtifact() }
+      };
     }
-    const artifacts = {
-      baseline: await store.register(baselinePath, { mimeType: "image/png" }),
-      current: shot.image
-    };
-    if (result.contextDiffPath) {
-      artifacts.diff = await store.register(result.contextDiffPath, {
-        mimeType: "image/png",
-        filename: `${snapshotKey}-diff.png`
+    const outputDir = await fs44.mkdtemp(path32.join(os12.tmpdir(), "argent-flow-diff-"));
+    let keepInOutputDir;
+    try {
+      const result = await diffPngFiles({
+        baselinePath,
+        currentPath,
+        outputDir,
+        // A crop compares EVERY pixel of the element's region — no masking,
+        // wherever the crop sits. Masking a crop's overlap with the screen's
+        // top status-bar band would degenerate into comparing nothing for an
+        // element inside the band (a vacuous pass); a crop overlapping the
+        // band leans on best-effort pinStatusBar until frame resolution
+        // asserts the element clears it.
+        topMask: cropFrame === void 0 ? "status-bar" : "none",
+        // Crop dimensions track the element — size drift must hard-fail below
+        // instead of being resampled away like a full-screen scale difference.
+        ...cropFrame !== void 0 && { normalizeSizes: false }
       });
-      keepInOutputDir = result.contextDiffPath;
+      if (result.dimensionMismatch) {
+        const { expected, actual } = result.dimensionMismatch;
+        return {
+          status: "fail",
+          reason: `baseline is ${expected.width}x${expected.height} but the ${opts.cropOn ? "cropOn region" : "capture"} is ${actual.width}x${actual.height} (${key}) \u2014 nothing was compared` + (opts.cropOn ? `. The element's size drifted \u2014 crop a fixed-size container, or re-adopt with updateBaselines` : ""),
+          snapshotKey,
+          artifacts: {
+            baseline: await store.register(baselinePath, { mimeType: "image/png" }),
+            current: await currentArtifact()
+          }
+        };
+      }
+      const within = result.mismatchPercentage <= opts.maxMismatch;
+      const reason = `diff ${result.mismatchPercentage.toFixed(2)}% ${within ? "\u2264" : ">"} ${opts.maxMismatch}% (${key})`;
+      if (within) {
+        return { status: "pass", reason };
+      }
+      const artifacts = {
+        baseline: await store.register(baselinePath, { mimeType: "image/png" }),
+        current: await currentArtifact()
+      };
+      if (result.contextDiffPath) {
+        artifacts.diff = await store.register(result.contextDiffPath, {
+          mimeType: "image/png",
+          filename: `${snapshotKey}-diff.png`
+        });
+        keepInOutputDir = result.contextDiffPath;
+      }
+      return { status: "fail", reason, snapshotKey, artifacts };
+    } finally {
+      await cleanupDiffDir(outputDir, keepInOutputDir);
     }
-    return { status: "fail", reason, snapshotKey, artifacts };
   } finally {
-    await cleanupDiffDir(outputDir, keepInOutputDir);
+    if (cropDir !== void 0) {
+      await cleanupDiffDir(cropDir, keepCropped ? currentPath : void 0);
+    }
   }
 }
 
@@ -150789,14 +151125,21 @@ 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
 when \`on\` is omitted; distinct from the \`rotate\` tool, which changes device orientation); \`await\` waits
 for a UI condition; \`wait\` pauses for a fixed number of milliseconds; \`assert\` checks one now; \`snapshot\`
-diffs a screenshot against a stored baseline (a missing baseline fails the step \u2014 set updateBaselines
-to adopt the current screen); \`echo\` annotates; \`run\` executes a referenced fragment inline.
+diffs a screenshot \u2014 or, with \`cropOn: <selector>\`, one element's cropped region \u2014 against a stored
+baseline (a missing baseline fails the step \u2014 set updateBaselines to adopt the current screen; a
+cropped element whose size drifted fails on dimensions); \`echo\` annotates; \`run\` executes a referenced fragment inline.
 A \`when:\` block (condition + \`steps:\`, no else) runs its steps only if the condition holds \u2014
 checked once with the short assert grace \u2014 for one-sided divergences like interstitials and coach
 marks; a skipped block reports distinctly and failures inside an entered block are real failures.
@@ -150947,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) {
@@ -150987,7 +151335,7 @@ function stepTarget(step) {
       return step.selector ? `${selectorLabel2(step.selector)} (${by})` : by;
     }
     case "snapshot":
-      return `"${step.name}"`;
+      return step.cropOn ? `"${step.name}" cropOn ${selectorLabel2(step.cropOn)}` : `"${step.name}"`;
     default:
       return void 0;
   }
@@ -151191,7 +151539,8 @@ async function execLeafStep(state3, step, index, scope) {
           flowName: state3.topFlowName,
           name: step.name,
           maxMismatch: step.maxMismatch ?? DEFAULT_MAX_MISMATCH,
-          updateBaselines: state3.updateBaselines
+          updateBaselines: state3.updateBaselines,
+          cropOn: step.cropOn
         });
         return {
           ...base,
@@ -151799,7 +152148,7 @@ var dismissUpdateTool = {
 };
 
 // ../tool-server/src/tools/screenshot-diff/index.ts
-var import_node_crypto8 = __toESM(require("node:crypto"));
+var import_node_crypto9 = __toESM(require("node:crypto"));
 var import_promises13 = __toESM(require("fs/promises"));
 var import_node_os13 = __toESM(require("node:os"));
 var import_path10 = __toESM(require("path"));
@@ -151885,7 +152234,7 @@ async function resolveOutputDir(params, options) {
   const dir = import_path10.default.join(
     import_node_os13.default.tmpdir(),
     "argent-screenshot-diff",
-    import_node_crypto8.default.randomBytes(6).toString("hex")
+    import_node_crypto9.default.randomBytes(6).toString("hex")
   );
   await import_promises13.default.mkdir(dir, { recursive: true });
   return dir;
@@ -151962,7 +152311,7 @@ async function captureLiveInput(params) {
   } catch {
     capture = await params.captureScreenshot(params.api, params.rotation, params.signal);
   }
-  const suffix = import_node_crypto8.default.randomBytes(4).toString("hex");
+  const suffix = import_node_crypto9.default.randomBytes(4).toString("hex");
   const destination = import_path10.default.join(params.outputDir, `${params.name}-${suffix}.live.png`);
   await import_promises13.default.mkdir(params.outputDir, { recursive: true });
   await import_promises13.default.copyFile(capture.path, destination);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.17.1-next.1",
+  "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

@@ -32,17 +32,41 @@ Beyond raw `tool:` steps and `echo:`, flows support declarative directives inter
 | `await`      | `- await: { visible: Home }`                                                                                                                                         | wait for a UI condition                                                                                                                                         |
 | `wait`       | `- wait: 500`                                                                                                                                                        | pause for a fixed number of milliseconds (last resort — prefer `await`)                                                                                         |
 | `assert`     | `- assert: { visible: Welcome }`                                                                                                                                     | check a condition, hard-fail if it never holds                                                                                                                  |
-| `snapshot`   | `- snapshot: home` or `- snapshot: { name: home, maxMismatch: 0.5 }`                                                                                                 | diff a screenshot against a stored baseline                                                                                                                     |
+| `snapshot`   | `- snapshot: home` or `- snapshot: { name: home, maxMismatch: 0.5, cropOn: { id: order-summary } }`                                                                  | diff a screenshot — or one element's region — against a stored baseline                                                                                         |
 | `run`        | `- run: login`                                                                                                                                                       | execute another flow's steps inline (fragment or e2e)                                                                                                           |
 | `when`       | `- when: { visible: "What's new" }` + `steps: [...]`                                                                                                                 | run a guarded step block only when the condition holds (no else)                                                                                                |
 
 ### 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,11 @@ 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
+
+`cropOn: <selector>` narrows a snapshot's comparison to one element's region — `- snapshot: { name: cart-total, cropOn: { id: order-summary } }`. The selector resolves like a directive target (settled tree, auto-wait, the standard not-found failure; selector-only, no point form), and the **cropped** image is what gets compared, stored as the baseline, and reported as the `current` artifact; the baseline filename still keys on the full capture's resolution — plus a `-crop-<hash>` selector suffix — so device-class drift is still caught. A cropped comparison never masks any region — every pixel of the crop is compared — so prefer elements clear of the top status-bar band (a crop overlapping it leans on best-effort status-bar pinning, and the clock/battery may diff). Crop **fixed-size containers**, addressed by `id`: a text selector resolves to the smallest matching node — typically the label itself, whose frame tracks text metrics — and the crop tracks the element's frame, so an element that grew or shrank by a pixel fails on dimensions ("nothing was compared") rather than on content. Baseline storage and seeding are covered under _Standalone runner_.
 
 ### TV targets (Vega)