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

package/dist/tool-server.cjs

@@ -144726,6 +144726,28 @@ function textWaitToYaml(selector, expectedText, textMatch) {
     }
   }
 }
+function targetToYaml(step) {
+  const hasPointField = step.x !== void 0 || step.y !== void 0;
+  if (step.selector !== void 0) {
+    if (hasPointField) {
+      throw new Error(
+        "Cannot serialize flow gesture target: use a selector or x/y coordinates, not both"
+      );
+    }
+    return selectorToYaml(step.selector);
+  }
+  if (typeof step.x !== "number" || typeof step.y !== "number") {
+    throw new Error(
+      "Cannot serialize flow gesture target: a coordinate target needs numeric x and y"
+    );
+  }
+  if (!(step.x >= 0 && step.x <= 1) || !(step.y >= 0 && step.y <= 1)) {
+    throw new Error(
+      "Cannot serialize flow gesture target: coordinates are normalized 0\u20131 fractions of the screen, not pixels"
+    );
+  }
+  return { x: step.x, y: step.y };
+}
 function waitToYaml(condition, selector, expectedText, textMatch, timeoutMs) {
   const sel = selectorToYaml(selector);
   let body;
@@ -144755,18 +144777,13 @@ function toYamlStep(step) {
     case "run":
       return { run: step.flow };
     case "tap": {
-      if (step.selector) {
-        const sel = selectorToYaml(step.selector);
-        return { tap: step.times !== void 0 ? { on: sel, times: step.times } : sel };
-      }
-      const body = { x: step.x, y: step.y };
-      if (step.times !== void 0) body.times = step.times;
-      return { tap: body };
+      const target = targetToYaml(step);
+      return { tap: step.times !== void 0 ? { on: target, times: step.times } : target };
     }
     case "long-press": {
-      const sel = selectorToYaml(step.selector);
+      const target = targetToYaml(step);
       return {
-        "long-press": step.duration !== void 0 ? { on: sel, duration: step.duration } : sel
+        "long-press": step.duration !== void 0 ? { on: target, duration: step.duration } : target
       };
     }
     case "type": {
@@ -145079,35 +145096,6 @@ var STEP_DIRECTIVE_KEYS = [
   "scroll-to",
   "snapshot"
 ];
-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) {
-      badEntry(
-        entry,
-        'the long-press options form takes a nested selector \u2014 e.g. long-press: { on: { text: "Row" }, duration: 1200 }'
-      );
-    }
-    if (!Object.keys(obj).every((k) => k === "on" || k === "duration")) {
-      badEntry(entry, "the long-press options form accepts only { on, duration }");
-    }
-    if (obj.on === void 0) {
-      badEntry(entry, 'long-press needs a target \u2014 e.g. long-press: { on: "Row", duration: 1200 }');
-    }
-    const step = { kind: "long-press", selector: parseSelector(obj.on, "long-press.on") };
-    if (obj.duration !== void 0) {
-      if (typeof obj.duration !== "number" || !Number.isFinite(obj.duration) || obj.duration <= 0) {
-        badEntry(
-          entry,
-          "long-press.duration needs a positive number of milliseconds (e.g. `duration: 1200`)"
-        );
-      }
-      step.duration = obj.duration;
-    }
-    return step;
-  }
-  return { kind: "long-press", selector: parseSelector(body, "long-press") };
-}
 function parseTapTimes(raw, entry) {
   if (raw === void 0) return void 0;
   if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1 || raw > 10) {
@@ -145115,23 +145103,32 @@ function parseTapTimes(raw, entry) {
   }
   return raw === 1 ? void 0 : raw;
 }
-function parseTap(body, entry) {
-  const obj = body !== null && typeof body === "object" ? body : {};
-  if (obj.x !== void 0 || obj.y !== void 0) {
-    if (obj.on !== void 0 || obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0) {
-      badEntry(entry, "tap takes a selector or x/y coordinates, not both");
-    }
-    if (typeof obj.x !== "number" || typeof obj.y !== "number") {
-      badEntry(entry, "a coordinate tap needs numeric x and y");
-    }
-    if (!Object.keys(obj).every((k) => k === "x" || k === "y" || k === "times")) {
-      badEntry(entry, "a coordinate tap takes only { x, y, times }");
+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) {
+        badEntry(raw, `${where} takes a selector or x/y coordinates, not both`);
+      }
+      if (typeof obj.x !== "number" || typeof obj.y !== "number") {
+        badEntry(raw, `${where}: a coordinate target needs numeric x and y`);
+      }
+      if (!(obj.x >= 0 && obj.x <= 1) || !(obj.y >= 0 && obj.y <= 1)) {
+        badEntry(
+          raw,
+          `${where}: coordinates are normalized 0\u20131 fractions of the screen, not pixels`
+        );
+      }
+      if (!Object.keys(obj).every((k) => k === "x" || k === "y")) {
+        badEntry(raw, `${where}: a coordinate target takes only { x, y }`);
+      }
+      return { x: obj.x, y: obj.y };
     }
-    const step = { kind: "tap", x: obj.x, y: obj.y };
-    const times = parseTapTimes(obj.times, entry);
-    if (times !== void 0) step.times = times;
-    return step;
   }
+  return { selector: parseSelector(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) {
       badEntry(
@@ -145139,18 +145136,59 @@ function parseTap(body, entry) {
         'the tap options form takes a nested selector \u2014 e.g. tap: { on: { text: "Photo" }, times: 2 }'
       );
     }
+    if (obj.x !== void 0 || obj.y !== void 0) {
+      badEntry(
+        entry,
+        "the tap options form takes a nested point \u2014 e.g. tap: { on: { x: 0.5, y: 0.5 }, times: 2 }"
+      );
+    }
     if (!Object.keys(obj).every((k) => k === "on" || k === "times")) {
       badEntry(entry, "the tap options form accepts only { on, times }");
     }
     if (obj.on === void 0) {
       badEntry(entry, 'tap with times needs a target \u2014 e.g. tap: { on: "Photo", times: 2 }');
     }
-    const step = { kind: "tap", selector: parseSelector(obj.on, "tap.on") };
+    const step = { kind: "tap", ...parseTarget(obj.on, "tap.on") };
     const times = parseTapTimes(obj.times, entry);
     if (times !== void 0) step.times = times;
     return step;
   }
-  return { kind: "tap", selector: parseSelector(body, "tap") };
+  return { kind: "tap", ...parseTarget(body, "tap") };
+}
+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) {
+      badEntry(
+        entry,
+        'the long-press options form takes a nested selector \u2014 e.g. long-press: { on: { text: "Row" }, duration: 1200 }'
+      );
+    }
+    if (obj.x !== void 0 || obj.y !== void 0) {
+      badEntry(
+        entry,
+        "the long-press options form takes a nested point \u2014 e.g. long-press: { on: { x: 0.5, y: 0.5 }, duration: 1200 }"
+      );
+    }
+    if (!Object.keys(obj).every((k) => k === "on" || k === "duration")) {
+      badEntry(entry, "the long-press options form accepts only { on, duration }");
+    }
+    if (obj.on === void 0) {
+      badEntry(entry, 'long-press needs a target \u2014 e.g. long-press: { on: "Row", duration: 1200 }');
+    }
+    const step = { kind: "long-press", ...parseTarget(obj.on, "long-press.on") };
+    if (obj.duration !== void 0) {
+      if (typeof obj.duration !== "number" || !Number.isFinite(obj.duration) || obj.duration <= 0) {
+        badEntry(
+          entry,
+          "long-press.duration needs a positive number of milliseconds (e.g. `duration: 1200`)"
+        );
+      }
+      step.duration = obj.duration;
+    }
+    return step;
+  }
+  return { kind: "long-press", ...parseTarget(body, "long-press") };
 }
 function fromYamlStep(raw) {
   const entry = raw;
@@ -145980,12 +146018,7 @@ async function captureRunTarget(session, args) {
   try {
     assertSafeFlowName(name);
     const fragPath = path28.join(path28.dirname(session.filePath), `${name}.yaml`);
-    const fragment = parseFlow(await fs37.readFile(fragPath, "utf8"));
-    if (isE2eFlow(fragment)) {
-      return {
-        warning: `"${name}" is an e2e flow (starts with a launch step); only fragments compose via run: \u2014 kept the raw flow-execute step`
-      };
-    }
+    parseFlow(await fs37.readFile(fragPath, "utf8"));
     return { flow: name };
   } catch (err) {
     return {
@@ -146113,9 +146146,8 @@ You can still edit the .yaml file directly afterwards to remove or reorder steps
         case "run":
           return `${n}. run: ${step.flow}`;
         case "tap":
-          return `${n}. tap: ${step.selector ? selectorLabel(step.selector) : `(${step.x}, ${step.y})`}`;
         case "long-press":
-          return `${n}. long-press: ${selectorLabel(step.selector)}`;
+          return `${n}. ${step.kind}: ${step.selector ? selectorLabel(step.selector) : `(${step.x}, ${step.y})`}`;
         case "type":
           return `${n}. type: ${selectorLabel(step.into)} \u2190 "${step.text}"`;
         case "await":
@@ -146393,20 +146425,23 @@ async function runDirective(env, step) {
     }
   }
 }
-async function runTap(env, target) {
-  let point;
+async function resolveTargetPoint(env, target) {
   if (target.selector) {
     const frame = await waitForFrame(env, target.selector);
-    if (frame === "aborted") return ABORTED_OUTCOME;
+    if (frame === "aborted") return { fail: ABORTED_OUTCOME };
     if (!frame) {
-      return { ok: false, reason: offscreenHint(target.selector) };
+      return { fail: { ok: false, reason: offscreenHint(target.selector) } };
     }
-    point = getDescribeTapPoint(frame);
-  } else if (typeof target.x === "number" && typeof target.y === "number") {
-    point = { x: target.x, y: target.y };
-  } else {
-    return { ok: false, reason: "tap needs a selector or x/y coordinates" };
+    return getDescribeTapPoint(frame);
+  }
+  if (typeof target.x === "number" && typeof target.y === "number") {
+    return { x: target.x, y: target.y };
   }
+  return { fail: { ok: false, reason: "gesture needs a selector or x/y coordinates" } };
+}
+async function runTap(env, target) {
+  const point = await resolveTargetPoint(env, target);
+  if ("fail" in point) return point.fail;
   await invokeOnDevice(env, "gesture-tap", {
     ...point,
     ...target.times !== void 0 ? { clickCount: target.times } : {}
@@ -146415,12 +146450,8 @@ async function runTap(env, target) {
 }
 var DEFAULT_LONG_PRESS_MS = 800;
 async function runLongPress(env, step) {
-  const frame = await waitForFrame(env, step.selector);
-  if (frame === "aborted") return ABORTED_OUTCOME;
-  if (!frame) {
-    return { ok: false, reason: offscreenHint(step.selector) };
-  }
-  const point = getDescribeTapPoint(frame);
+  const point = await resolveTargetPoint(env, step);
+  if ("fail" in point) return point.fail;
   const duration3 = step.duration ?? DEFAULT_LONG_PRESS_MS;
   if (env.device.platform === "chromium") {
     await invokeOnDevice(env, "gesture-drag", {
@@ -148830,6 +148861,13 @@ async function treeSourceGate(registry2, device, bundleId, signal) {
 async function runLaunch(state3, app) {
   const { registry: registry2, device, signal } = state3;
   if (device.platform === "chromium") {
+    if (state3.chromiumLaunched) {
+      return {
+        ok: false,
+        reason: `chromium launches only the top-level flow's app, once per run \u2014 a nested launch can't boot its own instance and would run against the already-launched app. Nested chromium e2e flows aren't supported: run this flow at the top level, or drop its launch step to make it a fragment.`
+      };
+    }
+    state3.chromiumLaunched = true;
     if (state3.chromiumBooted) {
       if (!await sleepOrAbort(POST_LAUNCH_SETTLE_MS, signal)) return ABORTED_OUTCOME;
       return { ok: true };
@@ -148875,8 +148913,9 @@ function createRunFlowTool(registry2) {
     description: `Run a saved flow from the .argent/flows/ directory.
 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 (\`long-press: { on, duration }\` presses and holds); \`scroll-to\` scrolls
-(momentum-free) until a target is visible; \`await\` waits for a UI
+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 }\`);
+\`scroll-to\` scrolls (momentum-free) until a target is visible; \`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.
@@ -148920,6 +148959,7 @@ returns a notice with the prerequisite instead of running.`,
         stopped: false,
         pinned: statusBarPinned,
         chromiumBooted: resolved.booted !== null,
+        chromiumLaunched: false,
         ...ctx?.emitProgress ? { onStepReport: ctx.emitProgress } : {}
       };
       try {
@@ -149029,11 +149069,10 @@ function selectorLabel2(sel) {
 function stepTarget(step) {
   switch (step.kind) {
     case "tap":
+    case "long-press":
       if (step.selector) return selectorLabel2(step.selector);
       if (step.x !== void 0 && step.y !== void 0) return `(${step.x}, ${step.y})`;
       return void 0;
-    case "long-press":
-      return selectorLabel2(step.selector);
     case "type":
       return `into ${selectorLabel2(step.into)}`;
     case "await":
@@ -149109,11 +149148,6 @@ async function execRunStep(state3, step, runStack) {
   } catch (err) {
     return fail(`could not load fragment "${target}": ${errMsg2(err)}`);
   }
-  if (isE2eFlow(fragment)) {
-    return fail(
-      `"${target}" is an e2e flow (starts with a launch step); only fragments can be run from another flow`
-    );
-  }
   pushReport(state3, { index, kind: "run", status: "pass", flow: target });
   await execSteps(state3, fragment.steps, target, [...runStack, target]);
 }

package/package.json

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

@@ -11,7 +11,7 @@ Flows store **no device id**: the runner binds a device (the single booted one,
 
 **Two flow types**
 
-- **e2e** — begins with a `launch:` step, which starts that app from scratch (terminate + relaunch), so the flow controls its own start state. No `executionPrerequisite`. May `run:` fragments; cannot itself be a `run:` target. Record one by adding a `restart-app` of the app under test as the **first** step — it is captured as the `launch` step.
+- **e2e** — begins with a `launch:` step, which starts that app from scratch (terminate + relaunch), so the flow controls its own start state. No `executionPrerequisite`. May `run:` other flows, and (on iOS/Android) may itself be a `run:` target — when nested, its `launch` runs inline, restarting the app for that sub-scenario. **Chromium is the exception:** the runner boots one Electron app per run (the top-level flow's), so a nested chromium e2e flow's `launch` can't boot its own instance and fails the run — keep chromium e2e flows top-level. Record one by adding a `restart-app` of the app under test as the **first** step — it is captured as the `launch` step.
 - **fragment** — doesn't begin with a launch; runs against the device's current state. May declare an `executionPrerequisite` (a documented entry-state contract). Invoked from other flows via a `run:` step, or directly by you at any time.
 
 Both run via `argent flow run <name>` — a fragment simply runs against whatever is on screen (its prerequisite is printed as a reminder). Only e2e flows are meaningful CI/suite entries, since only they give a deterministic verdict from a clean start.
@@ -20,18 +20,18 @@ Both run via `argent flow run <name>` — a fragment simply runs against whateve
 
 Beyond raw `tool:` steps and `echo:`, flows support declarative directives interpreted by the runner (they are **not** agent-callable tools). **Every directive hard-stops the flow on failure**; later steps are reported `skip`.
 
-| Directive    | YAML                                                                                                     | Meaning                                                                 |
-| ------------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| `launch`     | `- launch: com.acme.app` or `- launch: { ios: …, android: … }`                                           | start the app from scratch (terminate + relaunch) and wait until ready  |
-| `tap`        | `- tap: Login`, `- tap: { x: 0.5, y: 0.57 }`, `- tap: { on: Login, times: 2 }`                           | tap by selector (auto-waits) or raw point; `times: 2` = double-tap      |
-| `long-press` | `- long-press: Row 3` or `- long-press: { on: <sel>, duration: 1200 }`                                   | press and hold an element (default 800ms; Chromium: mouse press-hold)   |
-| `type`       | `- type: { into: email, text: "a@b.com" }`                                                               | focus a field, type, then press Enter to submit + dismiss the keyboard  |
-| `scroll-to`  | `- scroll-to: "Order #1234"` (scrolls down) or `- scroll-to: { target: …, direction: right, within: … }` | momentum-free scroll until the target is visible                        |
-| `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                             |
-| `run`        | `- run: login`                                                                                           | execute a fragment's steps inline                                       |
+| Directive    | YAML                                                                                                                                                                 | Meaning                                                                                                                                                         |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `launch`     | `- launch: com.acme.app` or `- launch: { ios: …, android: … }`                                                                                                       | start the app from scratch (terminate + relaunch) and wait until ready                                                                                          |
+| `tap`        | `- tap: Login`, `- tap: { x: 0.5, y: 0.57 }`, `- tap: { on: Login, times: 2 }`, `- tap: { on: { x: 0.5, y: 0.57 }, times: 2 }`                                       | tap by selector (auto-waits) or raw point; `times` (2 = double-tap) needs the target nested under `on:` — a selector or a point (`{ x, y, times }` is rejected) |
+| `long-press` | `- long-press: Row 3`, `- long-press: { x: 0.5, y: 0.6 }`, `- long-press: { on: <sel>, duration: 1200 }`, `- long-press: { on: { x: 0.5, y: 0.6 }, duration: 1200 }` | press and hold an element or raw point (default 800ms; Chromium: mouse press-hold); `duration` needs the target nested under `on:` — a selector or a point      |
+| `type`       | `- type: { into: email, text: "a@b.com" }`                                                                                                                           | focus a field, type, then press Enter to submit + dismiss the keyboard                                                                                          |
+| `scroll-to`  | `- scroll-to: "Order #1234"` (scrolls down) or `- scroll-to: { target: …, direction: right, within: … }`                                                             | momentum-free scroll until the target is visible                                                                                                                |
+| `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                                                                                                                     |
+| `run`        | `- run: login`                                                                                                                                                       | execute another flow's steps inline (fragment or e2e)                                                                                                           |
 
 ### Selectors