@swmansion/argent 0.17.0 → 0.17.1-next.0

package/dist/tool-server.cjs

@@ -126894,6 +126894,7 @@ Use when you need to zoom in or out on a map, image, or zoomable view. Returns {
 
 // ../tool-server/src/tools/gesture-rotate/index.ts
 init_zod();
+init_src();
 var zodSchema22 = external_exports.object({
   udid: external_exports.string().describe("Target device id from `list-devices` (iOS UDID or Android serial)."),
   centerX: external_exports.number().describe(
@@ -126902,13 +126903,33 @@ var zodSchema22 = external_exports.object({
   centerY: external_exports.number().describe(
     "Center of rotation, vertical: normalized 0.0\u20131.0 (fraction of screen height, not pixels)"
   ),
-  radius: external_exports.number().describe(
-    "Distance from center to each finger: normalized 0.0\u20131.0 (fraction of screen, not pixels). E.g. 0.15 = fingers placed 15% of screen away from center."
+  radius: external_exports.number().optional().describe(
+    "Distance from center to each finger: normalized 0.0\u20131.0 (fraction of screen, not pixels). E.g. 0.15 = fingers placed 15% of screen away from center. One value for both axes, so on a non-square screen the orbit is a physical ellipse \u2014 pass radiusX+radiusY instead for a true circle. Required unless radiusX and radiusY are given."
+  ),
+  radiusX: external_exports.number().optional().describe(
+    "Per-axis finger distance, horizontal: normalized 0.0\u20131.0 fraction of screen WIDTH. Give both radiusX and radiusY (they override radius) with radiusX\xB7screenWidth = radiusY\xB7screenHeight for a physically circular orbit \u2014 constant finger separation, no pinch coupled into the turn."
+  ),
+  radiusY: external_exports.number().optional().describe(
+    "Per-axis finger distance, vertical: normalized 0.0\u20131.0 fraction of screen HEIGHT. Always paired with radiusX \u2014 see radiusX."
   ),
   startAngle: external_exports.number().describe("Starting angle in degrees (0 = right, 90 = down)"),
   endAngle: external_exports.number().describe("Ending angle in degrees. endAngle > startAngle = clockwise."),
   durationMs: external_exports.number().optional().describe("Total gesture duration in milliseconds (default 300)")
-});
+}).refine((p) => p.radiusX === void 0 === (p.radiusY === void 0), {
+  message: "radiusX and radiusY must be given together (one physical radius, two normalizations)"
+}).refine((p) => p.radius !== void 0 || p.radiusX !== void 0, {
+  message: "Pass radius, or both radiusX and radiusY."
+});
+var inputSchema = {
+  ...zodObjectToJsonSchema(zodSchema22),
+  anyOf: [
+    { required: ["radiusX", "radiusY"] },
+    {
+      required: ["radius"],
+      not: { anyOf: [{ required: ["radiusX"] }, { required: ["radiusY"] }] }
+    }
+  ]
+};
 var capability14 = {
   apple: { simulator: true, device: true },
   appleRemote: { simulator: true },
@@ -126916,32 +126937,51 @@ var capability14 = {
 };
 var gestureRotateTool = {
   id: "gesture-rotate",
-  description: `Send a two-finger circular arc gesture to rotate on-screen content by a specified angle. Two fingers are placed opposite each other at a fixed radius from the center, then swept from startAngle to endAngle degrees. All positions and radius are normalized 0.0\u20131.0 (fractions of screen width/height, not pixels)\u2014same coordinate space as gesture-tap and gesture-swipe.
-endAngle > startAngle = clockwise rotation. Typical values: radius 0.15, startAngle 0, endAngle 90 for a 90\xB0 clockwise turn.
+  description: `Send a two-finger circular arc gesture to rotate on-screen content by a specified angle. Two fingers are placed opposite each other at a fixed radius from the center, then swept from startAngle to endAngle degrees. All positions and radii are normalized 0.0\u20131.0 (fractions of screen width/height, not pixels)\u2014same coordinate space as gesture-tap and gesture-swipe.
+endAngle > startAngle = clockwise rotation. Typical values: radius 0.15, startAngle 0, endAngle 90 for a 90\xB0 clockwise turn. A single radius applies to both axes, so on a non-square screen it traces a physical ellipse (finger separation varies through the turn); pass radiusX+radiusY (fractions of width/height with radiusX\xB7width = radiusY\xB7height) for a physically circular orbit instead.
 Auto-generates interpolated frames at ~60fps.
 Unlike gesture-pinch which moves fingers linearly to zoom, this orbits fingers in an arc to change orientation.
 Use when you need to rotate a map, image picker, or any rotateable UI element. Returns { rotated: true, timestampMs }. Fails if the simulator-server / emulator backend is not reachable for the given device.`,
   zodSchema: zodSchema22,
+  inputSchema,
   capability: capability14,
   services: (params) => ({
     simulatorServer: simulatorServerRef(resolveDevice(params.udid))
   }),
-  async execute(services, params) {
+  async execute(services, params, ctx) {
     const api = services.simulatorServer;
     const duration3 = params.durationMs ?? 300;
     const steps = Math.max(1, Math.round(duration3 / 16));
+    const radiusX = params.radiusX ?? params.radius;
+    const radiusY = params.radiusY ?? params.radius;
     let timestampMs = 0;
+    let lastX1 = 0;
+    let lastY1 = 0;
+    let lastX2 = 0;
+    let lastY2 = 0;
     for (let i = 0; i <= steps; i++) {
+      if (ctx?.signal?.aborted) {
+        if (i > 0) sendTouchEvent(api, "Up", lastX1, lastY1, lastX2, lastY2);
+        const err = new Error(
+          `gesture-rotate aborted \u2014 cancelled mid-gesture after ${i} of ${steps + 1} frames`
+        );
+        err.name = "AbortError";
+        throw err;
+      }
       const t = i / steps;
       const angleDeg = params.startAngle + (params.endAngle - params.startAngle) * t;
       const angleRad = angleDeg * Math.PI / 180;
-      const x1 = params.centerX + params.radius * Math.cos(angleRad);
-      const y1 = params.centerY + params.radius * Math.sin(angleRad);
-      const x2 = params.centerX - params.radius * Math.cos(angleRad);
-      const y2 = params.centerY - params.radius * Math.sin(angleRad);
+      const x1 = params.centerX + radiusX * Math.cos(angleRad);
+      const y1 = params.centerY + radiusY * Math.sin(angleRad);
+      const x2 = params.centerX - radiusX * Math.cos(angleRad);
+      const y2 = params.centerY - radiusY * Math.sin(angleRad);
       const type = i === 0 ? "Down" : i === steps ? "Up" : "Move";
       if (i === 0) timestampMs = Date.now();
       sendTouchEvent(api, type, x1, y1, x2, y2);
+      lastX1 = x1;
+      lastY1 = y1;
+      lastX2 = x2;
+      lastY2 = y2;
       if (i < steps) await sleep(16);
     }
     return { rotated: true, timestampMs };
@@ -134019,7 +134059,7 @@ Allowed tools and their args (udid is auto-injected, do NOT include it in args):
   gesture-drag:   { fromX: number, fromY: number, toX: number, toY: number, durationMs?: number }                       [chromium only]
   gesture-custom: { events: [{ type: "Down"|"Move"|"Up", x: number, y: number, x2?: number, y2?: number, delayMs?: number }], interpolate?: number }  [ios/android]
   gesture-pinch:  { centerX: number, centerY: number, startDistance: number, endDistance: number, endCenterX?: number, endCenterY?: number, angle?: number, durationMs?: number }  [ios/android]
-  gesture-rotate: { centerX: number, centerY: number, radius: number, startAngle: number, endAngle: number, durationMs?: number }                    [ios/android]
+  gesture-rotate: { centerX: number, centerY: number, radius?: number, radiusX?: number, radiusY?: number, startAngle: number, endAngle: number, durationMs?: number }  [ios/android]
   button:         { button: "home"|"back"|"power"|"volumeUp"|"volumeDown"|"appSwitch"|"actionButton" }                  [ios/android]
   keyboard:       { text?: string, key?: string, delayMs?: number }  (key pressed after text; TV: text only)            [ios/android/chromium/vega/tv]
                   text supports {{secret:<NAME>}} placeholders, resolved server-side from ARGENT_SECRET_<NAME> env vars (prefix mandatory) \u2014 credentials never enter agent context
@@ -145949,6 +145989,123 @@ var fs39 = __toESM(require("node:fs/promises"));
 init_src();
 var import_yaml = __toESM(require_dist5());
 init_src();
+
+// ../tool-server/src/tools/flows/flow-pinch-geometry.ts
+var PINCH_RATIO_PER_GESTURE = 4;
+var PINCH_SETTLE_MS = 250;
+var TARGET_START_FRACTION = 0.82;
+var SCREEN_EDGE_INSET = 0.02;
+var MIN_VIABLE_TRAVEL = 0.03;
+function systemEdgeGuards(device) {
+  return device.platform === "android" ? { left: 0.13, right: 0.13, top: 0.08, bottom: 0.08 } : { left: 0.08, right: 0.08, top: 0.08, bottom: 0.08 };
+}
+function decomposePinch(scale) {
+  const n = Math.max(
+    1,
+    Math.ceil(Math.abs(Math.log(scale)) / Math.log(PINCH_RATIO_PER_GESTURE) - 1e-9)
+  );
+  return { n, per: scale ** (1 / n) };
+}
+function clamp2(v, lo, hi) {
+  return v < lo ? lo : v > hi ? hi : v;
+}
+function buildAxisCandidate(input) {
+  const { angle, center, targetSpan, per, guards } = input;
+  const c = angle === 0 ? center.x : center.y;
+  const gLow = angle === 0 ? guards.left : guards.top;
+  const gHigh = angle === 0 ? guards.right : guards.bottom;
+  const p = angle === 0 ? center.y : center.x;
+  const pLow = angle === 0 ? guards.top : guards.left;
+  const pHigh = angle === 0 ? guards.bottom : guards.right;
+  const screenEndSpan = 1 - 2 * SCREEN_EDGE_INSET;
+  const edgeSafeStartSpan = 2 * Math.max(0, Math.min(c - gLow, 1 - gHigh - c));
+  const insetStartSpan = 2 * Math.max(0, Math.min(c - SCREEN_EDGE_INSET, 1 - SCREEN_EDGE_INSET - c));
+  const screenStartLimit = edgeSafeStartSpan > 0 ? Math.min(screenEndSpan, edgeSafeStartSpan) : Math.min(screenEndSpan, insetStartSpan);
+  const startLimit = targetSpan !== void 0 ? Math.min(screenStartLimit, targetSpan * TARGET_START_FRACTION) : screenStartLimit;
+  const start2 = per > 1 ? Math.min(startLimit, screenEndSpan / per) : startLimit;
+  const end = Math.min(screenEndSpan, start2 * per);
+  const travel = Math.abs(end - start2);
+  if (!(travel > 0)) return void 0;
+  const endCenter = clamp2(c, SCREEN_EDGE_INSET + end / 2, 1 - SCREEN_EDGE_INSET - end / 2);
+  const downLow = c - start2 / 2;
+  const downHigh = c + start2 / 2;
+  const axisSafe = downLow >= gLow && downHigh <= 1 - gHigh;
+  const perpSafe = p >= pLow && p <= 1 - pHigh;
+  const clearance = Math.min(downLow - gLow, 1 - gHigh - downHigh, p - pLow, 1 - pHigh - p);
+  return {
+    angle,
+    start: start2,
+    end,
+    endCenter,
+    travel,
+    viable: travel >= MIN_VIABLE_TRAVEL,
+    axisSafe,
+    fullyEdgeSafe: axisSafe && perpSafe,
+    clearance
+  };
+}
+function selectPinchCandidate(candidates) {
+  if (candidates.length === 0) return void 0;
+  const rank2 = (c) => c.fullyEdgeSafe ? 0 : c.axisSafe ? 1 : 2;
+  return [...candidates].sort((a, b) => {
+    const byViable = Number(b.viable) - Number(a.viable);
+    if (byViable !== 0) return byViable;
+    const byRank = rank2(a) - rank2(b);
+    if (byRank !== 0) return byRank;
+    if (a.fullyEdgeSafe && b.fullyEdgeSafe) return b.travel - a.travel;
+    return b.clearance - a.clearance || b.travel - a.travel;
+  })[0];
+}
+
+// ../tool-server/src/tools/flows/flow-rotate-geometry.ts
+var ROTATE_MS_PER_90_DEG = 300;
+var MAX_DERIVED_ROTATE_MS = 1e4;
+var MAX_ROTATE_BY_DEG = MAX_DERIVED_ROTATE_MS / ROTATE_MS_PER_90_DEG * 90;
+function deriveRotateDurationMs(by) {
+  return Math.round(ROTATE_MS_PER_90_DEG * Math.max(1, Math.abs(by) / 90));
+}
+function buildRotateCandidate(input) {
+  const { startAngle, center, targetSpan, guards, aspect } = input;
+  const xClear = Math.min(center.x - SCREEN_EDGE_INSET, 1 - SCREEN_EDGE_INSET - center.x);
+  const yClear = Math.min(center.y - SCREEN_EDGE_INSET, 1 - SCREEN_EDGE_INSET - center.y);
+  const screenRx = Math.min(xClear, yClear / aspect);
+  const targetRx = targetSpan === void 0 ? Infinity : startAngle === 0 ? targetSpan * TARGET_START_FRACTION / 2 : targetSpan * TARGET_START_FRACTION / 2 / aspect;
+  const radiusX = Math.min(screenRx, targetRx);
+  if (!(radiusX > 0)) return void 0;
+  const radiusY = radiusX * aspect;
+  const c = startAngle === 0 ? center.x : center.y;
+  const half = startAngle === 0 ? radiusX : radiusY;
+  const gLow = startAngle === 0 ? guards.left : guards.top;
+  const gHigh = startAngle === 0 ? guards.right : guards.bottom;
+  const p = startAngle === 0 ? center.y : center.x;
+  const pLow = startAngle === 0 ? guards.top : guards.left;
+  const pHigh = startAngle === 0 ? guards.bottom : guards.right;
+  const downLow = c - half;
+  const downHigh = c + half;
+  const axisSafe = downLow >= gLow && downHigh <= 1 - gHigh;
+  const perpSafe = p >= pLow && p <= 1 - pHigh;
+  const clearance = Math.min(downLow - gLow, 1 - gHigh - downHigh, p - pLow, 1 - pHigh - p);
+  return {
+    startAngle,
+    radiusX,
+    radiusY,
+    axisSafe,
+    fullyEdgeSafe: axisSafe && perpSafe,
+    clearance
+  };
+}
+function selectRotateCandidate(candidates) {
+  if (candidates.length === 0) return void 0;
+  const rank2 = (c) => c.fullyEdgeSafe ? 0 : c.axisSafe ? 1 : 2;
+  return [...candidates].sort((a, b) => {
+    const byRank = rank2(a) - rank2(b);
+    if (byRank !== 0) return byRank;
+    if (a.fullyEdgeSafe && b.fullyEdgeSafe) return b.radiusX - a.radiusX;
+    return b.clearance - a.clearance || b.radiusX - a.radiusX;
+  })[0];
+}
+
+// ../tool-server/src/tools/flows/flow-utils.ts
 var FLOWS_DIR_NAME = path29.join(".argent", "flows");
 var activeFlowName = null;
 var activeProjectRoot = null;
@@ -146258,6 +146415,10 @@ function toYamlStep(step) {
       return {
         pinch: step.selector ? { on: selectorToYaml(step.selector), scale: step.scale } : { scale: step.scale }
       };
+    case "rotate":
+      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 "tool":
@@ -146531,6 +146692,7 @@ var STEP_DIRECTIVE_KEYS = [
   "wait",
   "scroll-to",
   "pinch",
+  "rotate",
   "snapshot"
 ];
 function parseTapTimes(raw, entry) {
@@ -146649,6 +146811,31 @@ function parsePinch(body, entry) {
   if (obj.on !== void 0) step.selector = parseSelector(obj.on, "pinch.on");
   return step;
 }
+function parseRotate(body, entry) {
+  if (body === null || typeof body !== "object") {
+    badEntry(
+      entry,
+      'rotate takes an options map \u2014 e.g. rotate: { on: "Map", by: 90 } (an angle is required)'
+    );
+  }
+  const obj = body;
+  if (obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0) {
+    badEntry(entry, 'rotate takes a nested selector \u2014 e.g. rotate: { on: "Map", by: 90 }');
+  }
+  rejectUnknownKeys(entry, obj, ["on", "by"], "rotate");
+  if (typeof obj.by !== "number" || !Number.isFinite(obj.by) || obj.by === 0) {
+    badEntry(entry, "rotate.by must be a finite non-zero number of degrees (+CW, \u2212CCW)");
+  }
+  if (Math.abs(obj.by) > MAX_ROTATE_BY_DEG) {
+    badEntry(
+      entry,
+      `rotate.by must be within \xB1${MAX_ROTATE_BY_DEG}\xB0 \u2014 one continuous gesture at ~300\xB0/s (10 s max)`
+    );
+  }
+  const step = { kind: "rotate", by: obj.by };
+  if (obj.on !== void 0) step.selector = parseSelector(obj.on, "rotate.on");
+  return step;
+}
 function parseWhenCondition(raw) {
   const conditionKeys = `${WAIT_CONDITIONS.join(", ")}, platform`;
   if (raw === null || typeof raw !== "object") {
@@ -146817,6 +147004,7 @@ function fromYamlStep(raw, whenDepth = 0) {
     return step;
   }
   if ("pinch" in raw) return parsePinch(raw.pinch, raw);
+  if ("rotate" in raw) return parseRotate(raw.rotate, raw);
   if ("snapshot" in raw) {
     const body = raw.snapshot;
     if (body !== null && typeof body === "object" && !Array.isArray(body)) {
@@ -147221,7 +147409,7 @@ function projectIosNode(node, screenW, screenH) {
     scrolls: role === "AXScrollArea"
   };
 }
-function adaptFullHierarchyToDescribeResult(raw) {
+function adaptFullHierarchy(raw) {
   const windows = typeof raw === "object" && raw !== null && Array.isArray(raw.windows) ? raw.windows.map(asViewNode).filter((n) => n !== null) : [];
   let screenW = 0;
   let screenH = 0;
@@ -147238,11 +147426,12 @@ function adaptFullHierarchyToDescribeResult(raw) {
       flattenHoisting(win, (n) => projectIosNode(n, screenW, screenH), children);
     }
   }
-  return parseDescribeResult({
+  const tree = parseDescribeResult({
     role: "AXGroup",
     frame: { x: 0, y: 0, width: 1, height: 1 },
     children
   });
+  return screenW > 0 && screenH > 0 ? { tree, screen: { width: screenW, height: screenH } } : { tree };
 }
 var FULL_HIERARCHY_FIELDS = [
   "className",
@@ -147284,7 +147473,8 @@ async function queryFullHierarchyTree(registry2, device) {
   if (rawResult.error) {
     throw new Error(`getFullHierarchy failed for ${target.bundleId}: ${rawResult.error}`);
   }
-  return { tree: adaptFullHierarchyToDescribeResult(rawResult), source: "native-devtools" };
+  const { tree, screen } = adaptFullHierarchy(rawResult);
+  return { tree, source: "native-devtools", ...screen ? { screen } : {} };
 }
 function errMsg(err) {
   return err instanceof Error ? err.message : String(err);
@@ -147407,7 +147597,11 @@ async function queryAndroidFullHierarchy(registry2, device) {
     devtools.getScreenSize()
   ]);
   const tree = adaptFullAndroidHierarchyToDescribeResult(xml, size.width, size.height);
-  return { tree, source: "android-devtools" };
+  return {
+    tree,
+    source: "android-devtools",
+    ...size.width > 0 && size.height > 0 ? { screen: { width: size.width, height: size.height } } : {}
+  };
 }
 
 // ../tool-server/src/tools/flows/flow-chromium-tree.ts
@@ -147715,6 +147909,8 @@ You can still edit the .yaml file directly afterwards to remove or reorder steps
           return `${n}. scroll-to: ${selectorLabel(step.target)} (${step.direction})`;
         case "pinch":
           return `${n}. pinch: scale ${step.scale}${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
+        case "rotate":
+          return `${n}. rotate: by ${step.by}\xB0${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
         case "snapshot":
           return `${n}. snapshot: ${step.name}`;
         case "tool":
@@ -147741,73 +147937,6 @@ var fs45 = __toESM(require("node:fs/promises"));
 var path33 = __toESM(require("node:path"));
 init_src();
 
-// ../tool-server/src/tools/flows/flow-pinch-geometry.ts
-var PINCH_RATIO_PER_GESTURE = 4;
-var PINCH_SETTLE_MS = 250;
-var TARGET_START_FRACTION = 0.82;
-var SCREEN_EDGE_INSET = 0.02;
-var MIN_VIABLE_TRAVEL = 0.03;
-function systemEdgeGuards(device) {
-  return device.platform === "android" ? { left: 0.13, right: 0.13, top: 0.08, bottom: 0.08 } : { left: 0.08, right: 0.08, top: 0.08, bottom: 0.08 };
-}
-function decomposePinch(scale) {
-  const n = Math.max(
-    1,
-    Math.ceil(Math.abs(Math.log(scale)) / Math.log(PINCH_RATIO_PER_GESTURE) - 1e-9)
-  );
-  return { n, per: scale ** (1 / n) };
-}
-function clamp2(v, lo, hi) {
-  return v < lo ? lo : v > hi ? hi : v;
-}
-function buildAxisCandidate(input) {
-  const { angle, center, targetSpan, per, guards } = input;
-  const c = angle === 0 ? center.x : center.y;
-  const gLow = angle === 0 ? guards.left : guards.top;
-  const gHigh = angle === 0 ? guards.right : guards.bottom;
-  const p = angle === 0 ? center.y : center.x;
-  const pLow = angle === 0 ? guards.top : guards.left;
-  const pHigh = angle === 0 ? guards.bottom : guards.right;
-  const screenEndSpan = 1 - 2 * SCREEN_EDGE_INSET;
-  const edgeSafeStartSpan = 2 * Math.max(0, Math.min(c - gLow, 1 - gHigh - c));
-  const insetStartSpan = 2 * Math.max(0, Math.min(c - SCREEN_EDGE_INSET, 1 - SCREEN_EDGE_INSET - c));
-  const screenStartLimit = edgeSafeStartSpan > 0 ? Math.min(screenEndSpan, edgeSafeStartSpan) : Math.min(screenEndSpan, insetStartSpan);
-  const startLimit = targetSpan !== void 0 ? Math.min(screenStartLimit, targetSpan * TARGET_START_FRACTION) : screenStartLimit;
-  const start2 = per > 1 ? Math.min(startLimit, screenEndSpan / per) : startLimit;
-  const end = Math.min(screenEndSpan, start2 * per);
-  const travel = Math.abs(end - start2);
-  if (!(travel > 0)) return void 0;
-  const endCenter = clamp2(c, SCREEN_EDGE_INSET + end / 2, 1 - SCREEN_EDGE_INSET - end / 2);
-  const downLow = c - start2 / 2;
-  const downHigh = c + start2 / 2;
-  const axisSafe = downLow >= gLow && downHigh <= 1 - gHigh;
-  const perpSafe = p >= pLow && p <= 1 - pHigh;
-  const clearance = Math.min(downLow - gLow, 1 - gHigh - downHigh, p - pLow, 1 - pHigh - p);
-  return {
-    angle,
-    start: start2,
-    end,
-    endCenter,
-    travel,
-    viable: travel >= MIN_VIABLE_TRAVEL,
-    axisSafe,
-    fullyEdgeSafe: axisSafe && perpSafe,
-    clearance
-  };
-}
-function selectPinchCandidate(candidates) {
-  if (candidates.length === 0) return void 0;
-  const rank2 = (c) => c.fullyEdgeSafe ? 0 : c.axisSafe ? 1 : 2;
-  return [...candidates].sort((a, b) => {
-    const byViable = Number(b.viable) - Number(a.viable);
-    if (byViable !== 0) return byViable;
-    const byRank = rank2(a) - rank2(b);
-    if (byRank !== 0) return byRank;
-    if (a.fullyEdgeSafe && b.fullyEdgeSafe) return b.travel - a.travel;
-    return b.clearance - a.clearance || b.travel - a.travel;
-  })[0];
-}
-
 // ../tool-server/src/tools/flows/flow-actions.ts
 var ABORTED_OUTCOME = {
   ok: false,
@@ -148021,16 +148150,16 @@ function offscreenHint(sel) {
   return `no visible element matched selector ${describeSelector(sel)} \u2014 if it is off-screen, add a scroll-to step before this one`;
 }
 async function runDirective(env, step) {
-  if (env.device.platform === "vega" && (step.kind === "tap" || step.kind === "long-press" || step.kind === "type" || step.kind === "scroll-to" || step.kind === "pinch")) {
+  if (env.device.platform === "vega" && (step.kind === "tap" || step.kind === "long-press" || step.kind === "type" || step.kind === "scroll-to" || step.kind === "pinch" || step.kind === "rotate")) {
     return {
       ok: false,
       reason: `${step.kind} is a touch directive and Vega is remote-driven \u2014 move focus with \`tool: tv-remote\` steps (and type via \`tool: keyboard\`) instead`
     };
   }
-  if (step.kind === "pinch" && env.device.platform === "chromium") {
+  if ((step.kind === "pinch" || step.kind === "rotate") && env.device.platform === "chromium") {
     return {
       ok: false,
-      reason: "pinch is unsupported on chromium \u2014 desktop apps have no uniform pinch-zoom mapping (they zoom via ctrl+wheel or their own controls); drive the app's zoom UI with tap/keyboard instead"
+      reason: step.kind === "pinch" ? "pinch is unsupported on chromium \u2014 desktop apps have no uniform pinch-zoom mapping (they zoom via ctrl+wheel or their own controls); drive the app's zoom UI with tap/keyboard instead" : "rotate is unsupported on chromium \u2014 desktop apps have no rotate-gesture idiom; drive the app's rotate controls with tap/keyboard instead"
     };
   }
   switch (step.kind) {
@@ -148051,6 +148180,8 @@ async function runDirective(env, step) {
     }
     case "pinch":
       return runPinch(env, step);
+    case "rotate":
+      return runRotate(env, step);
   }
 }
 async function resolveTargetPoint(env, target) {
@@ -148140,6 +148271,66 @@ async function runPinch(env, step) {
   }
   return { ok: true };
 }
+async function fetchScreenAspect(env) {
+  try {
+    const { screen } = await fetchFlowTree(env.registry, env.device);
+    return screen && screen.width > 0 && screen.height > 0 ? screen.width / screen.height : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function runRotate(env, step) {
+  let center = { x: 0.5, y: 0.5 };
+  let frame;
+  if (step.selector) {
+    const resolved = await waitForFrame(env, step.selector);
+    if (resolved === "aborted") return ABORTED_OUTCOME;
+    if (!resolved) return { ok: false, reason: offscreenHint(step.selector) };
+    frame = resolved;
+    center = getDescribeTapPoint(resolved);
+  }
+  const aspect = await fetchScreenAspect(env);
+  const guards = systemEdgeGuards(env.device);
+  const candidates = [
+    buildRotateCandidate({
+      startAngle: 0,
+      center,
+      targetSpan: frame?.width,
+      guards,
+      aspect: aspect ?? 1
+    }),
+    buildRotateCandidate({
+      startAngle: 90,
+      center,
+      targetSpan: frame?.height,
+      guards,
+      aspect: aspect ?? 1
+    })
+  ].filter((c) => c !== void 0);
+  const selected = selectRotateCandidate(candidates);
+  if (!selected) {
+    return {
+      ok: false,
+      reason: `rotate found no on-screen orbit radius around (${center.x}, ${center.y})`
+    };
+  }
+  if (env.signal?.aborted) return ABORTED_OUTCOME;
+  try {
+    await invokeOnDevice(env, "gesture-rotate", {
+      centerX: center.x,
+      centerY: center.y,
+      ...aspect === void 0 ? { radius: selected.radiusX } : { radiusX: selected.radiusX, radiusY: selected.radiusY },
+      startAngle: selected.startAngle,
+      // endAngle > startAngle = clockwise in the tool, matching +by.
+      endAngle: selected.startAngle + step.by,
+      durationMs: deriveRotateDurationMs(step.by)
+    });
+  } catch (err) {
+    if (env.signal?.aborted) return ABORTED_OUTCOME;
+    throw err;
+  }
+  return { ok: true };
+}
 async function runType(env, step) {
   const frame = await waitForFrame(env, step.into);
   if (frame === "aborted") return ABORTED_OUTCOME;
@@ -150600,7 +150791,9 @@ ready; \`tool\` calls dispatch through the registry; \`tap\`/\`long-press\`/\`ty
 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; \`pinch\` zooms
-(\`pinch: { on?, scale }\` \u2014 scale > 1 in, < 1 out; screen center when \`on\` is omitted); \`await\` waits
+(\`pinch: { on?, scale }\` \u2014 scale > 1 in, < 1 out; screen center when \`on\` is omitted); \`rotate\` is the
+two-finger rotation gesture (\`rotate: { on?, by }\` \u2014 degrees, + clockwise, within \xB13000\xB0; screen center
+when \`on\` is omitted; distinct from the \`rotate\` tool, which changes device orientation); \`await\` waits
 for a UI condition; \`wait\` pauses for a fixed number of milliseconds; \`assert\` checks one now; \`snapshot\`
 diffs a screenshot against a stored baseline (a missing baseline fails the step \u2014 set updateBaselines
 to adopt the current screen); \`echo\` annotates; \`run\` executes a referenced fragment inline.
@@ -150789,6 +150982,10 @@ function stepTarget(step) {
       const scale = `scale ${step.scale}`;
       return step.selector ? `${selectorLabel2(step.selector)} (${scale})` : scale;
     }
+    case "rotate": {
+      const by = `by ${step.by}\xB0`;
+      return step.selector ? `${selectorLabel2(step.selector)} (${by})` : by;
+    }
     case "snapshot":
       return `"${step.name}"`;
     default:
@@ -150971,7 +151168,8 @@ async function execLeafStep(state3, step, index, scope) {
     case "await":
     case "assert":
     case "scroll-to":
-    case "pinch": {
+    case "pinch":
+    case "rotate": {
       try {
         const r = await runDirective(state3, step);
         if (r.aborted) return { ...base, status: "skip", reason: r.reason };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.17.0",
+  "version": "0.17.1-next.0",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",
   "repository": {

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

@@ -28,6 +28,7 @@ Beyond raw `tool:` steps and `echo:`, flows support declarative directives inter
 | `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                                                                                                                |
 | `pinch`      | `- pinch: { on: "Map", scale: 3 }` or `- pinch: { scale: 0.5 }`                                                                                                      | two-finger zoom in (`scale` > 1) or out (`< 1`); big scales chain gestures; `on` optional — defaults to screen center; open-loop — assert the visible result    |
+| `rotate`     | `- rotate: { on: "Map", by: 90 }` or `- rotate: { by: -45 }`                                                                                                         | two-finger rotation by degrees (+ CW, − CCW, within ±3000°; options map only); `on` optional — screen center default; not `tool: rotate` (orientation)          |
 | `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                                                                                                                  |
@@ -68,7 +69,7 @@ Never record a real credential into a flow — the YAML is committed to the repo
 
 ### 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`) 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).
+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).
 
 ```yaml
 steps:
@@ -130,6 +131,7 @@ Record an `await-ui-element` step to **gate** the next step on a screen transiti
    - `tool: await-ui-element` gating a transition → `await: { visible: "…" }` / `{ hidden: … }` / `{ text: { in: …, equals: … } }`, carrying a custom `timeoutMs` over as a `timeout` sibling key. Converting also upgrades the wait from the trimmed `describe` tree to the flow's full-hierarchy tree (see Selectors). Keep the raw `tool: await-ui-element` step only when it sets a custom `pollIntervalMs`/`bundleId` the directive can't express.
    - A scroll-to-reach-an-element — a `tool: gesture-swipe` (or its chromium analog, `gesture-scroll`) used to bring a specific element on screen before interacting with it (a `tap`, `type`, `assert`, …) → `scroll-to: { target: "<that element>", direction: … }`, dropping the swipe. This is far more robust than a fixed-distance swipe: it scrolls momentum-free and stops exactly when the target appears, so it survives layout and content changes. (`tap`/`type` do not scroll, so a raw swipe whose fling lands differently on another device leaves the following tap unresolved — always prefer the `scroll-to` rewrite.) Keep a `gesture-swipe` as a raw `tool:` step when it isn't scrolling toward a specific element — especially a velocity-dependent gesture like swipe-to-dismiss, edge-swipe-back, or swipe-to-reveal a row action, which a momentum-free `scroll-to` would not reproduce.
    - `tool: gesture-pinch` → `pinch: { on: "<target>", scale: … }`, deriving `scale` as `endDistance / startDistance`. Set `on:` to the element under the pinch center when the pinch was aimed at one (the map or image being zoomed); omit it for a screen-center pinch. Don't carry the recorded distances/angle over — the directive re-derives the geometry (finger placement, system-edge avoidance, chaining of large scales) at run time, so the conversion swaps device-specific coordinates for a portable selector with auto-wait. Keep the raw `tool: gesture-pinch` step when the pinch is anchored at a specific point _inside_ a large element (zooming toward a particular map location, not the map's center) or deliberately pans via `endCenterX`/`endCenterY` — `on:` takes only a selector and re-centers the pinch on the element's frame center, so converting would silently move the zoom anchor.
+   - `tool: gesture-rotate` → `rotate: { on: "<target>", by: … }`, deriving `by` as `endAngle − startAngle` (the tool's `endAngle` > `startAngle` turns clockwise, matching the directive's positive `by`). Set `on:` to the element under the rotation center when the rotation was aimed at one (the map or image being rotated); omit it for a screen-center rotation. Don't carry the recorded `centerX`/`centerY`, radii (`radius` or `radiusX`/`radiusY`), `startAngle`, or `durationMs` over — the directive re-derives the geometry (finger placement, physical-circle radius, system-edge avoidance) and runs at a fixed pace (~90° per 300 ms), so the conversion swaps device-specific coordinates for a portable selector with auto-wait. Keep the raw `tool: gesture-rotate` step when the rotation is anchored at a specific point _inside_ a large element rather than its center (the directive re-centers on the element's frame center, so converting would silently move the pivot), when the gesture's speed itself matters (the directive's pace is fixed), or when the sweep exceeds the directive's ±3000° bound.
 
 Every other recorded tool (a velocity-dependent `gesture-swipe`, a fixed-distance `gesture-scroll` not aimed at an element, `button`, `screenshot`, …) has no directive form — leave it as a `tool:` step. The recorder already handles the rest: coordinate `gesture-tap`s are captured as portable `tap:` selector steps, a `restart-app` is captured as a `launch:` step, a `flow-execute` of a sibling fragment is captured as a `run: <name>` composition directive, and device ids are stripped. Captured selectors are emitted in the strict map form (`tap: { text: General }`), never as a loose bare string — the recorder verified the exact element the tap hit, and a bare string would re-parse as loose and route through the identifier-first fallback it was never checked against. After editing, re-run with `flow-execute` to confirm the cleaned flow still passes.
 

package/skills/argent-device-interact/SKILL.md

@@ -149,7 +149,7 @@ All values are normalized 0.0–1.0 (fractions of screen, not pixels) — same a
 }
 ```
 
-All positions and radius are normalized 0.0–1.0 (fractions of screen, not pixels). `radius: 0.15` means each finger is 15% of the screen away from center. `endAngle > startAngle` = clockwise. Default duration: 300ms. Optional: `"durationMs": 500` for slower rotation.
+All positions and radii are normalized 0.0–1.0 (fractions of screen, not pixels). `radius: 0.15` means each finger is 15% of the screen away from center. `endAngle > startAngle` = clockwise. Default duration: 300ms. Optional: `"durationMs": 500` for slower rotation, and `"radiusX"`/`"radiusY"` (fractions of screen width/height; give both — they override `radius`) with `radiusX·width = radiusY·height` for a physically circular orbit — a single `radius` traces a physical ellipse on a non-square screen, coupling a slight pinch into the turn.
 
 ### gesture-custom — Custom touch sequence