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

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

@@ -121584,6 +121584,10 @@ var zodSchema2 = external_exports.object({
 var nativeDevtoolsStatusTool = {
   id: "native-devtools-status",
   capability: { apple: { simulator: true, device: true }, appleRemote: { simulator: true } },
+  // The "injectable is false" recovery sentence inlines NON_INJECTABLE_RECOVERY
+  // verbatim: the description must stay a plain literal so scripts/extract-tools.mjs
+  // can read it statically for the spidershield scan. The verbatim match is pinned
+  // by native-devtools-status.test.ts.
   description: `Check whether native devtools are connected to a specific app and whether the next launch is prepared for injection.
 Use when you need to verify native devtools readiness before calling native-full-hierarchy, native-describe-screen, or native-network-logs.
 
@@ -121596,7 +121600,7 @@ Returns { envSetup, appRunning, connected, requiresRestart, nextLaunchWillBeInje
 - injectable: whether native devtools can ever be injected into this app. Apple system apps (bundle ids under com.apple.) are platform binaries with library validation, so the dylib can never load into them.
 
 Call this before using app-scoped native hierarchy tools or native-network-logs.
-If injectable is false: this is a TERMINAL state \u2014 the app can never be injected. Do NOT restart/retry. ${NON_INJECTABLE_RECOVERY}
+If injectable is false: this is a TERMINAL state \u2014 the app can never be injected. Do NOT restart/retry. Use the standard \`describe\` tool (its accessibility path reads the screen without injection) or \`screenshot\` (then interact by coordinate). Do not fall back to the native-devtools feature tools (native-describe-screen, native-find-views, native-full-hierarchy, native-network-logs, native-view-at-point, native-user-interactable-view-at-point) \u2014 they run the same injection precheck and fail with the same non-injectable error.
 If appRunning is false and nextLaunchWillBeInjected is true: use launch-app normally.
 If requiresRestart is true: call restart-app, then proceed with the native feature.
 Returns { status: "init_failed", message, attempts } instead when the simulator's native-devtools environment failed to initialize.
@@ -144776,6 +144780,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 +144857,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 +145106,7 @@ var STEP_DIRECTIVE_KEYS = [
   "echo",
   "launch",
   "run",
+  "when",
   "tool",
   "tap",
   "long-press",
@@ -145190,8 +145211,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 +145302,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 +146216,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 +146258,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 +146343,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 +146607,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 +146618,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 +146637,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 +146675,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 +148911,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 +149046,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 +149092,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 +149156,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 +149172,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 +149198,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 +149215,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 +149238,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 +149254,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.4",
   "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: