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

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);
     };
   }
 });
@@ -146419,8 +146419,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 = {
@@ -147008,7 +147017,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 +147045,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) {
@@ -148439,9 +148456,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 +150023,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 +150090,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 +150512,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 +150537,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);
+    }
   }
 }
 
@@ -150795,8 +150899,9 @@ holds; \`tap\`/\`long-press\` alternatively take a raw normalized point \u2014 b
 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.
@@ -150987,7 +151092,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 +151296,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 +151905,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 +151991,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 +152068,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.0",
+  "version": "0.17.1-next.2",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",
   "repository": {

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

@@ -32,7 +32,7 @@ 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)                                                                                                |
 
@@ -67,6 +67,10 @@ Never record a real credential into a flow — the YAML is committed to the repo
 
 `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.
 
+### `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)
 
 A Vega (Fire TV) device is remote-driven — there is no touch input, so the touch directives (`tap`, `long-press`, `type`, `scroll-to`, `pinch`, `rotate`) fail on it with guidance. Drive focus with `tool: tv-remote` steps and type with `tool: keyboard` instead; everything else (`launch`, `await`, `assert`, `wait`, `snapshot`, `echo`, `run`, selectors) works unchanged — the tree comes from the on-device automation toolkit, which attaches at app launch (the `launch` step waits for it, so a leading `launch` also guarantees selectors resolve).