fix(screenshot): wait for end-of-frame without PlayerLoop re-entry

Play-mode include_image capture now finishes from WaitForEndOfFrame
instead of reading the current backbuffer, and the capturer destroys
itself on timeout so paused sessions cannot leak or hang the command.

Signed-off-by: Atirna <288419661+atirna@users.noreply.github.com>

Author: atirna

MCPForUnity/Editor/Tools/CommandRegistry.cs

@@ -302,7 +302,18 @@ public static object ExecuteCommand(string commandName, JObject @params, TaskCom
                 throw new InvalidOperationException($"Handler for '{commandName}' does not provide a synchronous implementation");
             }
 
-            return handlerInfo.SyncHandler(@params);
+            object result = handlerInfo.SyncHandler(@params);
+            if (result is Task<object> returnedTask)
+            {
+                ExecuteAsyncHandler(
+                    new HandlerInfo(commandName, null, _ => returnedTask),
+                    @params,
+                    commandName,
+                    tcs);
+                return null;
+            }
+
+            return result;
         }
 
         /// <summary>
@@ -332,6 +343,11 @@ public static Task<object> InvokeCommandAsync(string commandName, JObject @param
             }
 
             object result = handlerInfo.SyncHandler(payload);
+            if (result is Task<object> returnedTask)
+            {
+                return returnedTask;
+            }
+
             return Task.FromResult(result);
         }
 

MCPForUnity/Editor/Tools/ManageScene.cs

@@ -2,6 +2,7 @@
 using System.Collections.Generic;
 using System.IO;
 using System.Linq;
+using System.Threading.Tasks;
 using MCPForUnity.Editor.Helpers; // For Response class
 using MCPForUnity.Runtime.Helpers; // For ScreenshotUtility
 using Newtonsoft.Json.Linq;
@@ -613,18 +614,7 @@ private static object CaptureScreenshot(SceneCommand cmd)
                 if (includeImage && Application.isPlaying)
                 {
                     if (!Application.isBatchMode) EnsureGameView();
-
-                    string folderOverride = ScreenshotPreferences.Resolve(cmd.outputFolder);
-                    ScreenshotCaptureResult result = ScreenshotUtility.CaptureComposited(
-                        fileName, resolvedSuperSize, ensureUniqueFileName: true,
-                        includeImage: true, maxResolution: maxResolution,
-                        folderOverride: folderOverride);
-
-                    if (ScreenshotUtility.IsUnderAssets(result.ProjectRelativePath))
-                        AssetDatabase.ImportAsset(result.ProjectRelativePath, ImportAssetOptions.ForceSynchronousImport);
-                    string cameraName = Camera.main != null ? Camera.main.name : "composited";
-                    string message = $"Screenshot captured to '{result.ProjectRelativePath}' (camera: {cameraName}).";
-                    return new SuccessResponse(message, BuildScreenshotResponseData(result, cameraName, includeImage: true));
+                    return CaptureCompositedScreenshotAsync(cmd, fileName, resolvedSuperSize, maxResolution);
                 }
 
                 if (includeImage)
@@ -756,6 +746,38 @@ private static Dictionary<string, object> BuildScreenshotResponseData(
             return data;
         }
 
+        private static async Task<object> CaptureCompositedScreenshotAsync(
+            SceneCommand cmd,
+            string fileName,
+            int resolvedSuperSize,
+            int maxResolution)
+        {
+            string folderOverride = ScreenshotPreferences.Resolve(cmd.outputFolder);
+            ScreenshotCaptureResult result;
+            try
+            {
+                result = await ScreenshotUtility.CaptureCompositedAsync(
+                    fileName, resolvedSuperSize, ensureUniqueFileName: true,
+                    includeImage: true, maxResolution: maxResolution,
+                    folderOverride: folderOverride).ConfigureAwait(true);
+            }
+            catch (TimeoutException ex)
+            {
+                return new ErrorResponse(ex.Message);
+            }
+            catch (InvalidOperationException ex)
+            {
+                return new ErrorResponse(ex.Message);
+            }
+
+            if (ScreenshotUtility.IsUnderAssets(result.ProjectRelativePath))
+                AssetDatabase.ImportAsset(result.ProjectRelativePath, ImportAssetOptions.ForceSynchronousImport);
+
+            string cameraName = Camera.main != null ? Camera.main.name : "composited";
+            string message = $"Screenshot captured to '{result.ProjectRelativePath}' (camera: {cameraName}).";
+            return new SuccessResponse(message, BuildScreenshotResponseData(result, cameraName, includeImage: true));
+        }
+
         private static object CaptureSceneViewScreenshot(
             SceneCommand cmd,
             string fileName,

MCPForUnity/Editor/Tools/ManageUI.cs

@@ -866,6 +866,14 @@ private static object RenderUI(JObject @params)
                 playFullPath = EnsureUniqueFilePath(playFullPath);
                 string playProjectRelPath = ScreenshotUtility.ToProjectRelativePath(playFullPath);
 
+                if (s_pendingCaptureDone && s_pendingCaptureTex == null)
+                {
+                    s_pendingCaptureDone = false;
+                    s_pendingCaptureStarted = false;
+                    return new ErrorResponse(
+                        "Play-mode screenshot timed out or captured nothing. Keep the Game view visible and the editor unpaused.");
+                }
+
                 // ── Case 1: capture is ready ──────────────────────────────────────
                 if (s_pendingCaptureDone && s_pendingCaptureTex != null)
                 {