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

package/dist/cli-cmds.mjs

@@ -8489,6 +8489,14 @@ function parseRunArgs(argv) {
   }
   return out;
 }
+function renderEchoLine(s) {
+  if (!s.message) return void 0;
+  if (s.status === "skip") {
+    const reason = s.reason ? ` \u2014 ${s.reason}` : "";
+    return `  ${STATUS_GLYPH.skip} \u203A ${s.message}${reason}`;
+  }
+  return `  \u203A ${s.message}`;
+}
 function renderStepLine(s, n2, topFlow) {
   const where = s.flow && s.flow !== topFlow ? ` [${s.flow}]` : "";
   const what = s.tool ?? s.target;
@@ -8576,7 +8584,8 @@ function renderReport(report) {
   let n2 = 0;
   for (const s of report.steps) {
     if (s.kind === "echo") {
-      if (s.message) lines.push(`  \u203A ${s.message}`);
+      const line = renderEchoLine(s);
+      if (line) lines.push(line);
       continue;
     }
     n2++;
@@ -8653,7 +8662,8 @@ async function flow(argv, options) {
     if (liveSteps === 0) console.log(`Flow "${flowName}"`);
     liveSteps++;
     if (s.kind === "echo") {
-      if (s.message) console.log(`  \u203A ${s.message}`);
+      const line = renderEchoLine(s);
+      if (line) console.log(line);
       return;
     }
     liveIndex++;

package/dist/tool-server.cjs

@@ -144776,6 +144776,16 @@ function toYamlStep(step) {
       return { launch: step.app };
     case "run":
       return { run: step.flow };
+    case "when": {
+      const when = step.condition.kind === "platform" ? { platform: step.condition.platform } : waitToYaml(
+        step.condition.condition,
+        step.condition.selector,
+        step.condition.expectedText,
+        step.condition.textMatch,
+        void 0
+      );
+      return { when, steps: step.steps.map(toYamlStep) };
+    }
     case "tap": {
       const target = targetToYaml(step);
       return { tap: step.times !== void 0 ? { on: target, times: step.times } : target };
@@ -144843,7 +144853,13 @@ function toYamlStep(step) {
   }
 }
 function badEntry(raw, detail) {
-  throw new FailureError(`Unrecognized flow entry (${detail}): ${JSON.stringify(raw)}`, {
+  let rendered;
+  try {
+    rendered = JSON.stringify(raw);
+  } catch {
+    rendered = "[cyclic entry]";
+  }
+  throw new FailureError(`Unrecognized flow entry (${detail}): ${rendered}`, {
     error_code: FAILURE_CODES.FLOW_ENTRY_UNRECOGNIZED,
     failure_stage: "flow_file_parse_step",
     failure_area: "tool_server",
@@ -145086,6 +145102,7 @@ var STEP_DIRECTIVE_KEYS = [
   "echo",
   "launch",
   "run",
+  "when",
   "tool",
   "tap",
   "long-press",
@@ -145190,8 +145207,85 @@ function parseLongPress(body, entry) {
   }
   return { kind: "long-press", ...parseTarget(body, "long-press") };
 }
-function fromYamlStep(raw) {
+function parseWhenCondition(raw) {
+  const conditionKeys = `${WAIT_CONDITIONS.join(", ")}, platform`;
+  if (raw === null || typeof raw !== "object") {
+    badEntry({ when: raw }, `when needs exactly one condition key (${conditionKeys})`);
+  }
+  const b = raw;
+  const present = [...WAIT_CONDITIONS, "platform"].filter((c) => c in b);
+  if (present.length !== 1) {
+    badEntry({ when: raw }, `when needs exactly one condition key (${conditionKeys})`);
+  }
+  if ("timeout" in b) {
+    badEntry(
+      { when: raw },
+      "when takes no timeout \u2014 the guard is evaluated with the short assert grace so a skipped block never adds a full await wait"
+    );
+  }
+  if (present[0] === "platform") {
+    if (Object.keys(b).length !== 1) {
+      badEntry({ when: raw }, "when.platform takes no other keys");
+    }
+    const p = b.platform;
+    if (typeof p !== "string" || !LAUNCH_PLATFORMS.includes(p)) {
+      badEntry({ when: raw }, `when.platform must be one of ${LAUNCH_PLATFORMS.join(", ")}`);
+    }
+    return { kind: "platform", platform: p };
+  }
+  const { timeout: _timeout, ...cond } = parseWaitFields(raw, "when");
+  const { selector, expectedText } = cond;
+  for (const s of [
+    expectedText,
+    selector.text,
+    selector.textMatches,
+    selector.identifier,
+    selector.role
+  ]) {
+    if (s !== void 0 && s.includes(SECRET_PLACEHOLDER_MARKER)) {
+      badEntry(
+        { when: raw },
+        "when takes no {{secret:\u2026}} placeholder \u2014 secrets resolve only in text-entry steps (`type:`), never in condition evaluation, so the guard tests literal placeholder text that is never on screen: permanently false (for `hidden`, vacuously true); use the literal on-screen text instead"
+      );
+    }
+  }
+  return { kind: "ui", ...cond };
+}
+var MAX_WHEN_DEPTH = 20;
+function parseWhenStep(raw, depth) {
+  if (depth >= MAX_WHEN_DEPTH) {
+    badEntry(
+      raw,
+      `when blocks nest deeper than ${MAX_WHEN_DEPTH} levels \u2014 check for a cyclic YAML alias (\`steps: &s \u2026 steps: *s\`)`
+    );
+  }
+  if ("else" in raw) {
+    badEntry(
+      raw,
+      "when has no else \u2014 paths may only reconverge, never diverge; two genuinely different paths are two flows"
+    );
+  }
+  if (!Object.keys(raw).every((k) => k === "when" || k === "steps")) {
+    badEntry(raw, "a when step takes exactly { when: <condition>, steps: [...] }");
+  }
+  const condition = parseWhenCondition(raw.when);
+  if (!Array.isArray(raw.steps) || raw.steps.length === 0) {
+    badEntry(raw, "when needs a non-empty steps list to guard");
+  }
+  const steps = raw.steps.map((s) => {
+    if (s !== null && typeof s === "object") return fromYamlStep(s, depth + 1);
+    return badEntry(s, "step must be an object");
+  });
+  return { kind: "when", condition, steps };
+}
+function fromYamlStep(raw, whenDepth = 0) {
   const entry = raw;
+  if ("optional" in raw) {
+    badEntry(
+      raw,
+      "optional is not supported \u2014 guard the step with a when: block instead (`when: { visible: <target> }` + `steps:`)"
+    );
+  }
   const kinds = STEP_DIRECTIVE_KEYS.filter((k) => k in entry);
   if (kinds.length === 0) {
     const hint = Object.keys(entry).map((k) => closestKey(k, STEP_DIRECTIVE_KEYS)).find((h) => h !== null);
@@ -145204,17 +145298,20 @@ function fromYamlStep(raw) {
     );
   }
   const kind = kinds[0];
-  const siblings = kind === "tool" ? ["tool", "args", "delayMs"] : [kind];
-  const extras = Object.keys(entry).filter((k) => !siblings.includes(k));
-  if (extras.length > 0) {
-    badEntry(
-      raw,
-      `a \`${kind}\` step has ${describeUnknownKeys(extras, siblings)}` + (kind === "tool" ? " \u2014 a tool step takes only `tool`, `args`, `delayMs`" : ` \u2014 step options go inside the \`${kind}:\` value, not beside it`)
-    );
+  if (kind !== "when") {
+    const siblings = kind === "tool" ? ["tool", "args", "delayMs"] : [kind];
+    const extras = Object.keys(entry).filter((k) => !siblings.includes(k));
+    if (extras.length > 0) {
+      badEntry(
+        raw,
+        `a \`${kind}\` step has ${describeUnknownKeys(extras, siblings)}` + (kind === "tool" ? " \u2014 a tool step takes only `tool`, `args`, `delayMs`" : ` \u2014 step options go inside the \`${kind}:\` value, not beside it`)
+      );
+    }
   }
   if ("echo" in raw) return { kind: "echo", message: String(raw.echo) };
   if ("launch" in raw) return { kind: "launch", app: parseLaunch(raw.launch) };
   if ("run" in raw) return { kind: "run", flow: String(raw.run) };
+  if ("when" in raw) return parseWhenStep(entry, whenDepth);
   if ("tap" in raw) return parseTap(raw.tap, raw);
   if ("long-press" in raw) {
     return parseLongPress(raw["long-press"], raw);
@@ -146115,6 +146212,11 @@ var fs38 = __toESM(require("node:fs/promises"));
 function selectorLabel(sel) {
   return JSON.stringify(selectorToYaml(sel));
 }
+function textConditionLabel(sel, expectedText, textMatch) {
+  const selector = selectorLabel(sel);
+  const expected = expectedText ?? "";
+  return textMatch === "matches" ? `text ${selector} matches /${expected}/` : textMatch === "equals" ? `text ${selector} == ${JSON.stringify(expected)}` : `text ${selector} contains ${JSON.stringify(expected)}`;
+}
 var zodSchema61 = external_exports.object({});
 var flowFinishRecordingTool = {
   id: "flow-finish-recording",
@@ -146152,18 +146254,20 @@ You can still edit the .yaml file directly afterwards to remove or reorder steps
           return `${n}. type: ${selectorLabel(step.into)} \u2190 "${step.text}"`;
         case "await":
         case "assert": {
-          let tail;
-          if (step.condition !== "text") {
-            tail = `${step.condition} ${selectorLabel(step.selector)}`;
-          } else {
-            const selector = selectorLabel(step.selector);
-            const expected = step.expectedText ?? "";
-            tail = step.textMatch === "matches" ? `text ${selector} matches /${expected}/` : step.textMatch === "equals" ? `text ${selector} == ${JSON.stringify(expected)}` : `text ${selector} contains ${JSON.stringify(expected)}`;
-          }
+          const tail = step.condition === "text" ? textConditionLabel(step.selector, step.expectedText, step.textMatch) : `${step.condition} ${selectorLabel(step.selector)}`;
           return `${n}. ${step.kind}: ${tail}`;
         }
         case "wait":
           return `${n}. wait: ${step.ms}ms`;
+        case "when": {
+          const cond = step.condition.kind === "platform" ? `platform ${step.condition.platform}` : step.condition.condition === "text" ? textConditionLabel(
+            step.condition.selector,
+            step.condition.expectedText,
+            step.condition.textMatch
+          ) : `${step.condition.condition} ${selectorLabel(step.condition.selector)}`;
+          const count = step.steps.length;
+          return `${n}. when: ${cond} (${count} step${count === 1 ? "" : "s"})`;
+        }
         case "scroll-to":
           return `${n}. scroll-to: ${selectorLabel(step.target)} (${step.direction})`;
         case "snapshot":
@@ -146235,6 +146339,10 @@ function axisFullyInside(frame, direction, clip2) {
   return direction === "down" || direction === "right" ? fEnd <= clipEnd - EDGE_EPS && fStart >= clipStart - EDGE_EPS : fStart >= clipStart + EDGE_EPS && fEnd <= clipEnd + EDGE_EPS;
 }
 var DEFAULT_ASSERT_TIMEOUT_MS = 1e3;
+var CONDITION_DARK_TAIL_TOLERANCE_MS = POLL_INTERVAL_MS * 2;
+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];
 }
@@ -146495,7 +146603,8 @@ async function waitForCondition(env, step, timeoutMs) {
   let lastMatches = [];
   let fetchError;
   let everMatched = false;
-  let everTrustedRead = false;
+  let lastTrustedReadAt;
+  let lastReadTrusted;
   let finalPoll = false;
   for (; ; ) {
     if (env.signal?.aborted) return ABORTED_OUTCOME;
@@ -146505,12 +146614,14 @@ async function waitForCondition(env, step, timeoutMs) {
       fetchError = void 0;
       everMatched ||= lastMatches.length > 0;
       const blind = data.tree.children.length === 0 && Boolean(data.hint || data.should_restart || everMatched);
-      everTrustedRead ||= !blind;
+      if (!blind) lastTrustedReadAt = Date.now();
+      lastReadTrusted = !blind;
       if (!blind && evaluateCondition(step.condition, step.expectedText, lastMatches, step.textMatch)) {
         return { ok: true };
       }
     } catch (err) {
       fetchError = err instanceof Error ? err.message : String(err);
+      lastReadTrusted = false;
     }
     if (Date.now() >= deadline) {
       if (finalPoll) break;
@@ -146522,22 +146633,34 @@ async function waitForCondition(env, step, timeoutMs) {
       return ABORTED_OUTCOME;
     }
   }
-  if (fetchError) return { ok: false, reason: `could not read the UI tree: ${fetchError}` };
-  if (step.condition === "hidden" && !everTrustedRead) {
+  if (lastTrustedReadAt === void 0) {
     return {
       ok: false,
-      reason: "could not confirm the element is hidden \u2014 the UI tree was empty or unreadable"
+      indeterminate: true,
+      reason: fetchError ? `could not read the UI tree: ${fetchError}` : "could not evaluate the condition \u2014 every read of the UI tree was empty or degraded"
     };
   }
+  if (!lastReadTrusted) {
+    if (step.condition === "hidden") {
+      return {
+        ok: false,
+        indeterminate: true,
+        reason: fetchError ? `could not confirm the element is hidden \u2014 it was visible earlier, but the last UI read failed: ${fetchError}` : "could not confirm the element is hidden \u2014 it was visible earlier, but the last UI reads were empty"
+      };
+    }
+    const darkTailMs = Date.now() - lastTrustedReadAt;
+    if (darkTailMs > CONDITION_DARK_TAIL_TOLERANCE_MS) {
+      return {
+        ok: false,
+        indeterminate: true,
+        reason: fetchError ? `could not evaluate the condition \u2014 the UI tree was unreadable for the final ${darkTailMs}ms of the window: ${fetchError}` : `could not evaluate the condition \u2014 the UI tree reads were empty or degraded for the final ${darkTailMs}ms of the window`
+      };
+    }
+  }
+  const blipNote = !lastReadTrusted && fetchError ? ` (the final poll could not read the UI tree: ${fetchError})` : "";
   return {
     ok: false,
-    reason: assertReason(
-      step.condition,
-      step.selector,
-      step.expectedText,
-      step.textMatch,
-      lastMatches
-    )
+    reason: assertReason(step.condition, step.selector, step.expectedText, step.textMatch, lastMatches) + blipNote
   };
 }
 function assertReason(condition, selector, expectedText, textMatch, matches2) {
@@ -146548,7 +146671,7 @@ function assertReason(condition, selector, expectedText, textMatch, matches2) {
     case "visible":
       return matches2.length > 0 ? `element(s) matched ${sel} but none was visible (zero-area frame)` : `no element matched selector ${sel}`;
     case "hidden":
-      return matches2.some(isVisible) ? `an element matching ${sel} was still visible` : `could not confirm the element is hidden \u2014 it was visible earlier, but the last UI reads returned an empty tree`;
+      return `an element matching ${sel} was still visible`;
     case "text": {
       const first = firstInReadingOrder(matches2.filter(isVisible)) ?? firstInReadingOrder(matches2);
       if (!first) return `no element matched selector ${sel}`;
@@ -148784,7 +148907,7 @@ var zodSchema62 = external_exports.object({
   device: external_exports.string().optional().describe(
     "Device id to run against (iOS UDID, Android/Vega serial, Chromium id). Auto-detected when omitted."
   ),
-  platform: external_exports.enum(["ios", "android", "chromium", "vega"]).optional().describe("Restrict auto-detection to this platform when several devices are booted."),
+  platform: external_exports.enum(LAUNCH_PLATFORMS).optional().describe("Restrict auto-detection to this platform when several devices are booted."),
   updateBaselines: external_exports.boolean().optional().describe(
     "Write/refresh screenshot baselines for `snapshot` steps instead of diffing against them."
   ),
@@ -148919,6 +149042,9 @@ holds; \`tap\`/\`long-press\` alternatively take a raw normalized point \u2014 b
 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.
+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.
 A flow that begins with a \`launch\` step is a self-contained e2e flow; one that doesn't runs against the
 device's current state. Device id is injected by the runner (flows store none) \u2014 pass \`device\` or
 \`platform\` to pick one, else the single booted device is used. For a Chromium e2e flow the \`launch\`
@@ -148962,13 +149088,15 @@ returns a notice with the prerequisite instead of running.`,
         chromiumLaunched: false,
         ...ctx?.emitProgress ? { onStepReport: ctx.emitProgress } : {}
       };
+      let aborted2;
       try {
         await execSteps(state3, flow.steps, params.name, [params.name]);
       } finally {
+        aborted2 = state3.signal?.aborted === true;
         if (state3.pinned) await restoreStatusBar(device);
         if (resolved.booted) await teardownBootedChromium(registry2, resolved.booted);
       }
-      return summarize(params.name, device.id, flow.executionPrerequisite, state3.reports);
+      return summarize(params.name, device.id, flow.executionPrerequisite, state3.reports, aborted2);
     }
   };
 }
@@ -149024,14 +149152,12 @@ async function frontChromiumPage(registry2, device) {
   } catch {
   }
 }
-function summarize(flowName, deviceId, executionPrerequisite, steps) {
+function summarize(flowName, deviceId, executionPrerequisite, steps, aborted2) {
   let passed = 0;
   let failed = 0;
   let skipped = 0;
   let errored = 0;
-  let hasSkippedReport = false;
   for (const s of steps) {
-    hasSkippedReport ||= s.status === "skip";
     if (s.kind === "echo") continue;
     if (s.status === "pass") passed++;
     else if (s.status === "fail") failed++;
@@ -149042,11 +149168,13 @@ function summarize(flowName, deviceId, executionPrerequisite, steps) {
     flow: flowName,
     device: deviceId,
     executionPrerequisite,
-    // A skip is never a successful omission: the runner only emits skips after
-    // a hard stop or cancellation. The former already has a fail/error report;
-    // the latter may contain skips alone, so include them in the verdict or an
-    // aborted run would be reported as PASS.
-    ok: failed === 0 && errored === 0 && !hasSkippedReport,
+    // A cancelled run must never read as PASS — it may contain skips alone
+    // (no fail/error report), so the verdict folds the abort in directly. A
+    // skip by itself is NOT a failure: an unmet `when:` guard skips its block
+    // as a successful omission, and a hard stop already carries its own
+    // fail/error report.
+    ok: failed === 0 && errored === 0 && !aborted2,
+    ...aborted2 ? { aborted: true } : {},
     passed,
     failed,
     skipped,
@@ -149066,6 +149194,13 @@ function selectorLabel2(sel) {
   if (sel.role) parts.push(`role=${sel.role}`);
   return parts.join(" ");
 }
+function conditionLabel(cond, renderSelector) {
+  const sel = renderSelector(cond.selector);
+  if (cond.condition === "text") {
+    return `${sel} ${describeTextExpectation(cond.expectedText, cond.textMatch)}`;
+  }
+  return `${cond.condition} ${sel}`;
+}
 function stepTarget(step) {
   switch (step.kind) {
     case "tap":
@@ -149076,13 +149211,10 @@ function stepTarget(step) {
     case "type":
       return `into ${selectorLabel2(step.into)}`;
     case "await":
-    case "assert": {
-      const sel = selectorLabel2(step.selector);
-      if (step.condition === "text") {
-        return `${sel} ${describeTextExpectation(step.expectedText, step.textMatch)}`;
-      }
-      return `${step.condition} ${sel}`;
-    }
+    case "assert":
+      return conditionLabel(step, selectorLabel2);
+    case "when":
+      return step.condition.kind === "platform" ? `platform ${step.condition.platform}` : conditionLabel(step.condition, selectorLabel2);
     case "scroll-to": {
       const dir = step.direction !== "down" ? ` (${step.direction})` : "";
       return `${selectorLabel2(step.target)}${dir}`;
@@ -149102,8 +149234,12 @@ async function execSteps(state3, steps, sourceFlow, runStack) {
         kind: step.kind,
         status: "skip",
         flow: sourceFlow,
-        target: stepTarget(step)
+        target: stepTarget(step),
+        // Carry the echo's message so a skipped narration renders as a skip
+        // line rather than vanishing — matching reportBlockSkipped.
+        ...step.kind === "echo" ? { message: step.message } : {}
       });
+      if (step.kind === "when") reportBlockSkipped(state3, step.steps, sourceFlow);
       continue;
     }
     if (state3.signal?.aborted) {
@@ -149114,19 +149250,106 @@ async function execSteps(state3, steps, sourceFlow, runStack) {
         status: "skip",
         reason: "run aborted",
         flow: sourceFlow,
-        target: stepTarget(step)
+        target: stepTarget(step),
+        ...step.kind === "echo" ? { message: step.message } : {}
       });
+      if (step.kind === "when") reportBlockSkipped(state3, step.steps, sourceFlow, "run aborted");
       continue;
     }
     if (step.kind === "run") {
       await execRunStep(state3, step, runStack);
       continue;
     }
+    if (step.kind === "when") {
+      await execWhenStep(state3, step, sourceFlow, runStack);
+      continue;
+    }
     const report = await execLeafStep(state3, step, index, sourceFlow);
     pushReport(state3, report);
     if (report.status === "fail" || report.status === "error") state3.stopped = true;
   }
 }
+function describeWhenCondition(cond) {
+  if (cond.kind === "platform") return `platform ${cond.platform}`;
+  return conditionLabel(cond, describeSelector);
+}
+function reportBlockSkipped(state3, steps, sourceFlow, reason) {
+  for (const step of steps) {
+    pushReport(state3, {
+      index: state3.reports.length,
+      kind: step.kind,
+      status: "skip",
+      reason,
+      // A `run:` line is attributed to the fragment it names, matching the
+      // executed marker in execRunStep; everything else belongs to the
+      // enclosing flow.
+      flow: step.kind === "run" ? step.flow : sourceFlow,
+      target: stepTarget(step),
+      ...step.kind === "echo" ? { message: step.message } : {}
+    });
+    if (step.kind === "when") reportBlockSkipped(state3, step.steps, sourceFlow, reason);
+  }
+}
+async function execWhenStep(state3, step, sourceFlow, runStack) {
+  const index = state3.reports.length;
+  const label = describeWhenCondition(step.condition);
+  const target = stepTarget(step);
+  let met;
+  if (step.condition.kind === "platform") {
+    const platform = state3.device.platform === "ios-remote" ? "ios" : state3.device.platform;
+    met = platform === step.condition.platform;
+  } else {
+    const probe3 = await probeWhenCondition(state3, step.condition);
+    if (probe3.aborted) {
+      pushReport(state3, {
+        index,
+        kind: "when",
+        status: "skip",
+        reason: "run aborted",
+        flow: sourceFlow,
+        target
+      });
+      reportBlockSkipped(state3, step.steps, sourceFlow, "run aborted");
+      return;
+    }
+    if (!probe3.ok && probe3.indeterminate) {
+      pushReport(state3, {
+        index,
+        kind: "when",
+        status: "error",
+        reason: `could not evaluate when guard (${label}): ${probe3.reason}`,
+        flow: sourceFlow,
+        target
+      });
+      state3.stopped = true;
+      reportBlockSkipped(state3, step.steps, sourceFlow, "when guard errored");
+      return;
+    }
+    met = probe3.ok;
+  }
+  if (!met) {
+    const n = step.steps.length;
+    pushReport(state3, {
+      index,
+      kind: "when",
+      status: "skip",
+      reason: `condition not met (${label}) \u2014 block skipped (${n} step${n === 1 ? "" : "s"})`,
+      flow: sourceFlow,
+      target
+    });
+    reportBlockSkipped(state3, step.steps, sourceFlow, "when block skipped");
+    return;
+  }
+  pushReport(state3, {
+    index,
+    kind: "when",
+    status: "pass",
+    reason: `condition met (${label})`,
+    flow: sourceFlow,
+    target
+  });
+  await execSteps(state3, step.steps, sourceFlow, runStack);
+}
 async function execRunStep(state3, step, runStack) {
   const index = state3.reports.length;
   const target = step.flow;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.16.1-next.2",
+  "version": "0.16.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,6 +32,7 @@ Beyond raw `tool:` steps and `echo:`, flows support declarative directives inter
 | `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                                                                                                                     |
 | `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
 
@@ -159,6 +160,7 @@ The top-level is an object with `steps` (array) and — fragments only — `exec
 
 - `- echo: <message>` — a label printed during replay
 - `- tool: <name>` with optional `args:` — a raw tool call. A tool step may also carry `delayMs: <ms>` to sleep that long before it runs. (`await-ui-element` is an ordinary tool step; see _flow-add-step arguments_ and _Making flows resilient_ for when to gate a transition with one.)
+- **`when:` blocks** handle one-sided divergences (interstitials, coach marks): `- when: { visible: "What's new" }` with a sibling `steps: [...]` list runs the block only if the condition holds — checked once with the short assert grace (~1s), so a skipped block barely costs a clean run. Guards are one condition key (`exists`/`visible`/`hidden`/`text`, the await/assert shapes) or `platform: ios|android|chromium|vega`. **No else** (parse-rejected): a block exists to dismiss the divergence and reconverge, never to test two paths — two paths are two flows. Failures inside an entered block are real failures; a skipped block reports `skip` lines. Tap-if-present is a one-step block (`when: { visible: "Got it" }` + `steps: [tap: "Got it"]`); there is NO per-step `optional:` key — it is rejected at parse with a pointer to `when:`.
 
 The polished result of the example session above: