@alpsckr/unitycli 0.4.3 → 0.4.4

package/unitypkg/Editor/Tools/screenshot/screen.cs

@@ -1,6 +1,8 @@
 #if UNITY_EDITOR
 using System;
+using System.Collections.Generic;
 using System.IO;
+using System.Threading;
 using UnityEngine;
 
 namespace UnityCli
@@ -15,7 +17,9 @@ namespace UnityCli
             [UnityCliRequired] public string Path { get; set; }
             public bool Overwrite { get; set; }
             public bool InlineBase64 { get; set; }
-            public int? SuperSize { get; set; }
+            [UnityCliRange(1L, 4L)] public int? SuperSize { get; set; }
+            public ScreenshotBudgetInput Limits { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result : ScreenshotCaptureResult { }
@@ -24,7 +28,7 @@ namespace UnityCli
         {
             Name = "screenshot.screen",
             Summary = "Capture the final composited screen including screen-space UI to a PNG file.",
-            Description = "Capture the final composited frame (including Screen Space Overlay Canvas UI) via ScreenCapture. Resolution follows the Game View size and cannot be set arbitrarily; capture is most reliable in Play Mode and the file is written at the end of the frame.",
+            Description = "Capture the final composited frame including screen-space UI. superSize is 1..4 and the resulting Game View dimensions must each be 1..8192 with at most 16777216 pixels. Before ScreenCapture, the plan must fit default ceilings of 33554432 total pixels, 128 MiB temporary memory and 64 MiB artifacts (public maxima 67108864, 256 MiB and 256 MiB). The file is produced at frame end; available in Edit and Play Mode but most reliable in Play Mode.",
             Group = "screenshot",
             DestructiveHint = true,
             SideEffects = new[] { "asset-write" },
@@ -42,39 +46,195 @@ namespace UnityCli
                 throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_FORMAT_UNSUPPORTED", "screenshot.screen only writes .png output.", "Pass a .png output path.");
             if (File.Exists(outputPath) && !request.Overwrite)
                 throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Screenshot output already exists: " + outputPath, "Pass overwrite=true or choose a different output path.");
+            var requestBudget = ctx.UseReadBudget(request.Budget);
+            var superSize = request.SuperSize ?? 1;
+            if (!requestBudget.TryConsumeGetter() || !requestBudget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(requestBudget.ExhaustedDimension);
+            var width = checked(Screen.width * superSize);
+            var height = checked(Screen.height * superSize);
+            var captureBudget = ScreenshotToolSupport.PrepareCaptureBudget(width, height, 1, false, request.Limits, requestBudget);
             ctx.CommitEffect();
             ScreenshotToolSupport.CreateScreenshotDirectory(outputPath);
-            var superSize = Math.Max(1, request.SuperSize ?? 1);
-
-            // ScreenCapture 抓最终合成画面（含屏幕空间 UI），在帧末异步落盘。
-            ScreenCapture.CaptureScreenshot(outputPath, superSize);
-
-            var written = await ctx.Wait.Until(() => File.Exists(outputPath) && new FileInfo(outputPath).Length > 0, TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct);
-            if (!written)
-                throw new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", "ScreenCapture did not write the screenshot before the deadline.", "Retry with a larger timeout, or use screenshot.game-view for camera-only capture.");
+            captureBudget.BeginCapture(width, height);
+            ScreenshotArtifactProof artifact;
+            using (var publication = new PendingCapturePublication(outputPath))
+            {
+                // ScreenCapture 只写本请求的唯一 pending；旧 final 与并发请求都不能满足 fresh-write proof。
+                publication.BeginWrite();
+                ScreenCapture.CaptureScreenshot(publication.PendingPath, superSize);
+                var written = await ctx.Wait.Until(
+                    () => File.Exists(publication.PendingPath) && new FileInfo(publication.PendingPath).Length > 0,
+                    TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)),
+                    ct);
+                ctx.ReadBudget.ResumeAfterWait();
+                if (!written)
+                {
+                    publication.TryFault();
+                    throw new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", "ScreenCapture did not write the screenshot before the deadline.", "Retry with a larger timeout, or use screenshot.game-view for camera-only capture.");
+                }
 
-            var artifact = ScreenshotToolSupport.VerifyScreenshotArtifact(outputPath, "png");
-            var (width, height) = ReadPngDimensions(outputPath);
+                captureBudget.ChargeArtifact(new FileInfo(publication.PendingPath).Length);
+                artifact = ScreenshotToolSupport.VerifyScreenshotArtifact(publication.PendingPath, "png", captureBudget);
+                publication.Publish();
+                artifact.Path = outputPath;
+            }
+            var dimensions = ReadPngDimensions(outputPath);
             var result = new Result
             {
                 ScreenshotPath = outputPath, ArtifactPath = outputPath, Source = "screen",
-                SizeBytes = artifact.SizeBytes, Sha256 = artifact.Sha256
+                SizeBytes = artifact.SizeBytes, Sha256 = artifact.Sha256, CapturePlan = captureBudget.Plan
             };
-            if (request.InlineBase64)
+            if (request.InlineBase64 && artifact.SizeBytes <= 512 * 1024)
             {
                 var bytes = File.ReadAllBytes(outputPath);
-                ScreenshotToolSupport.MaybeAppendInline(result, bytes, (int)width, (int)height, "image/png", true);
+                ScreenshotToolSupport.MaybeAppendInline(result, bytes, (int)dimensions.width, (int)dimensions.height, "image/png", true, captureBudget);
             }
             return result;
         }
 
+        private static readonly object PublicationLock = new object();
+        private static readonly object PendingLock = new object();
+        private static readonly HashSet<string> LivePending = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        private static readonly HashSet<string> LateWriterPending = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        private const int PendingOwnerLimit = 8;
+        private const int MaximumObservedPendingFiles = 1024;
+
+        /// <summary>每次 capture 都有唯一同目录 pending；迟到 writer 的 owner 不复用，当前启动最多保留8个。</summary>
+        internal sealed class PendingCapturePublication : IDisposable
+        {
+            private readonly string outputPath;
+            private int terminal;
+            private int writerStarted;
+
+            internal PendingCapturePublication(string outputPath)
+            {
+                if (string.IsNullOrWhiteSpace(outputPath)) throw new ArgumentException("Output path is required.", "outputPath");
+                this.outputPath = outputPath;
+                SweepObservedPending(Path.GetDirectoryName(outputPath));
+                PendingPath = outputPath + "." + Guid.NewGuid().ToString("N") + ".unitycli.pending";
+                lock (PendingLock)
+                {
+                    if (LivePending.Count + LateWriterPending.Count >= PendingOwnerLimit)
+                        throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_PENDING_SLOTS_BUSY", "All 8 screenshot pending owners are waiting for capture or late-writer cleanup.", "Wait for prior ScreenCapture writes to settle, then retry.");
+                    LivePending.Add(PendingPath);
+                }
+                try { DeletePendingStrict(PendingPath); }
+                catch
+                {
+                    lock (PendingLock) LivePending.Remove(PendingPath);
+                    throw;
+                }
+            }
+
+            internal string PendingPath { get; private set; }
+
+            internal void BeginWrite()
+            {
+                if (Volatile.Read(ref terminal) != 0) throw new InvalidOperationException("Screenshot pending publication already reached a terminal state.");
+                Volatile.Write(ref writerStarted, 1);
+            }
+
+            internal void Publish()
+            {
+                if (Interlocked.CompareExchange(ref terminal, 1, 0) != 0)
+                    throw new InvalidOperationException("Screenshot pending publication already reached a terminal state.");
+                try { PublishPending(PendingPath, outputPath); }
+                catch
+                {
+                    DeletePendingStrict(PendingPath);
+                    throw;
+                }
+                finally
+                {
+                    lock (PendingLock) LivePending.Remove(PendingPath);
+                }
+            }
+
+            internal bool TryFault()
+            {
+                if (Interlocked.CompareExchange(ref terminal, 2, 0) != 0) return false;
+                DeletePendingStrict(PendingPath);
+                lock (PendingLock)
+                {
+                    LivePending.Remove(PendingPath);
+                    if (Volatile.Read(ref writerStarted) != 0) LateWriterPending.Add(PendingPath);
+                }
+                return true;
+            }
+
+            public void Dispose()
+            {
+                TryFault();
+            }
+        }
+
+        /// <summary>只观察最多1024个产品 pending；迟到文件出现后删除并释放对应 owner。</summary>
+        private static void SweepObservedPending(string directory)
+        {
+            if (string.IsNullOrWhiteSpace(directory) || !Directory.Exists(directory)) return;
+            var observed = 0;
+            foreach (var path in Directory.EnumerateFiles(directory, "*.unitycli.pending", SearchOption.TopDirectoryOnly))
+            {
+                observed++;
+                if (observed > MaximumObservedPendingFiles)
+                    throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_PENDING_SCAN_LIMIT", "Screenshot pending cleanup exceeded the 1024-file observation limit.", "Remove stale *.unitycli.pending files from the output directory and retry.");
+                var lateWriter = false;
+                var delete = false;
+                lock (PendingLock)
+                {
+                    lateWriter = LateWriterPending.Contains(path);
+                    delete = lateWriter || !LivePending.Contains(path);
+                }
+                if (!delete) continue;
+                DeletePendingStrict(path);
+                if (lateWriter)
+                {
+                    lock (PendingLock) LateWriterPending.Remove(path);
+                }
+            }
+        }
+
+        /// <summary>同目录唯一 pending 在进程内串行原子 rename；失败时保留原 final。</summary>
+        internal static void PublishPending(string pendingPath, string outputPath)
+        {
+            lock (PublicationLock)
+            {
+                try
+                {
+                    if (File.Exists(outputPath)) File.Replace(pendingPath, outputPath, null, true);
+                    else File.Move(pendingPath, outputPath);
+                }
+                catch (Exception exception)
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_PUBLISH_FAILED", "Failed to atomically publish screenshot output: " + exception.Message, "Inspect output permissions and retry after the pending file is clean.");
+                }
+            }
+        }
+
+        /// <summary>pending删除失败必须显式终止，不能积累或被后续capture复用。</summary>
+        internal static void DeletePendingStrict(string pendingPath)
+        {
+            try
+            {
+                if (File.Exists(pendingPath)) File.Delete(pendingPath);
+                if (File.Exists(pendingPath)) throw new IOException("pending path still exists after deletion");
+            }
+            catch (Exception exception)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_PENDING_CLEANUP_FAILED", "Failed to clean screenshot pending output: " + exception.Message, "Remove the reported pending file after checking its exact path, then retry.");
+            }
+        }
+
         // 从落盘 PNG 的 IHDR 读取实际宽高（大端），用于报告 Game View 实际分辨率。
         private static (long width, long height) ReadPngDimensions(string path)
         {
             try
             {
-                var bytes = File.ReadAllBytes(path);
-                if (bytes.Length >= 24 && bytes[0] == 0x89 && bytes[1] == 0x50 && bytes[2] == 0x4e && bytes[3] == 0x47)
+                var bytes = new byte[24];
+                using (var stream = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read))
+                {
+                    if (stream.Read(bytes, 0, bytes.Length) < bytes.Length) return (0, 0);
+                }
+                if (bytes[0] == 0x89 && bytes[1] == 0x50 && bytes[2] == 0x4e && bytes[3] == 0x47)
                 {
                     long width = ((long)bytes[16] << 24) | ((long)bytes[17] << 16) | ((long)bytes[18] << 8) | bytes[19];
                     long height = ((long)bytes[20] << 24) | ((long)bytes[21] << 16) | ((long)bytes[22] << 8) | bytes[23];

package/unitypkg/Editor/Tools/screenshot/surround.cs

@@ -6,9 +6,7 @@ using UnityEngine;
 
 namespace UnityCli
 {
-    /// <summary>
-    /// screenshot.surround — 6 角度环绕截图并生成 contact sheet。破坏性(asset-write)。
-    /// </summary>
+    /// <summary>screenshot.surround — 六张逐次释放的捕获与一个 aggregate contact sheet。</summary>
     public class ScreenshotSurroundTool : IUnityCliTool<ScreenshotSurroundTool.Request, ScreenshotSurroundTool.Result>
     {
         public sealed class Request
@@ -16,12 +14,14 @@ namespace UnityCli
             [UnityCliRequired] public string Target { get; set; }
             public string OutputDir { get; set; } = "Assets/Screenshots/Surround";
             public string ContactSheetPath { get; set; }
-            public int? Width { get; set; }
-            public int? Height { get; set; }
+            [UnityCliRange(1L, 8192L)] public int? Width { get; set; }
+            [UnityCliRange(1L, 8192L)] public int? Height { get; set; }
             public float? Radius { get; set; }
             public float? Fov { get; set; }
             public bool Overwrite { get; set; }
             public bool InlineBase64 { get; set; }
+            public ScreenshotBudgetInput Limits { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
@@ -35,6 +35,7 @@ namespace UnityCli
             public long? ImageWidth { get; set; }
             public long? ImageHeight { get; set; }
             public string ImageMimeType { get; set; }
+            public ScreenshotCapturePlan CapturePlan { get; set; }
         }
 
         public sealed class SurroundShot
@@ -47,134 +48,137 @@ namespace UnityCli
         public ToolDescriptor Describe() => new()
         {
             Name = "screenshot.surround",
-            Summary = "Capture six fixed-angle screenshots and compose a 3x2 contact sheet; dry-run supported.",
-            Description = "Capture six fixed angles (front, back, left, right, top, bird_eye) around a GameObject and compose a 3x2 contact sheet PNG. Supports --dry-run to preview planned artifacts. Editor-only.",
-            Group = "screenshot",
-            DestructiveHint = true,
-            SideEffects = new[] { "asset-write" },
-            Target = "editor",
-            PlayModeSupport = "editor-only",
-            SupportsDryRun = true,
-            DefaultTimeoutMs = 30000,
-            MaxTimeoutMs = 600000,
-            Examples = new[] { new ToolExample { Description = "Surround a target (dry-run)", Input = new Request { Target = "Player" }, Execution = new ToolExampleExecution { DryRun = true } } }
+            Summary = "Capture six fixed views and one bounded contact sheet while releasing every tile immediately.",
+            Description = "Capture front/back/left/right/top/bird_eye PNGs plus a 3x2 contact sheet. Tile and contact-sheet dimensions each must satisfy 1..8192 and 16777216 pixels per image. Before dry-run or the first effect, the seven-output aggregate plan must fit default ceilings of 33554432 total pixels, 128 MiB peak temporary memory and 64 MiB artifacts; public maxima are 67108864, 256 MiB and 256 MiB. radius must be positive and fov must be 10..120. Each tile is copied into the sheet, encoded, written and destroyed before the next capture. Editor-only; dry-run returns the same frozen plan without effects.",
+            Group = "screenshot", DestructiveHint = true, SideEffects = new[] { "asset-write" },
+            Target = "editor", PlayModeSupport = "editor-only", SupportsDryRun = true,
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Preview surround artifacts", Input = new Request { Target = "Player" }, Execution = new ToolExampleExecution { DryRun = true } } }
         };
 
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
-            var go = UnityCliBridge.ObjectRefResolver.FindGameObjectByPath(request.Target);
-            if (go == null)
-                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "screenshot.surround requires a target GameObject.", "Pass --target <path>.");
+            var requestBudget = ctx.UseReadBudget(request.Budget);
+            var gameObject = UnityCliBridge.ObjectRefResolver.FindGameObjectByExactPath(request.Target, requestBudget);
+            if (gameObject == null) throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "screenshot.surround requires a target GameObject.", "Pass an exact hierarchy path.");
             var outputDir = request.OutputDir ?? "Assets/Screenshots/Surround";
             var outputFullDir = ScreenshotToolSupport.AssetFullPath(outputDir);
             var contactSheetPath = ScreenshotToolSupport.ResolveScreenshotOutputPath(request.ContactSheetPath ?? Path.Combine(outputDir, "surround_contact_sheet.png"));
-            var width = Math.Max(1, request.Width ?? 512);
-            var height = Math.Max(1, request.Height ?? 512);
-            var bounds = ScreenshotToolSupport.TargetRenderBounds(go);
+            var width = request.Width ?? 512;
+            var height = request.Height ?? 512;
+            var bounds = ScreenshotToolSupport.TargetRenderBounds(gameObject, requestBudget);
             var center = bounds.center;
             var radius = request.Radius ?? Mathf.Max(bounds.extents.magnitude * 2.5f, 5f);
+            var fov = request.Fov ?? 60f;
+            if (float.IsNaN(radius) || float.IsInfinity(radius) || radius <= 0f)
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_LIMIT_INVALID", "radius must be finite and greater than zero.", "Pass a positive finite radius.");
+            if (float.IsNaN(fov) || float.IsInfinity(fov) || fov < 10f || fov > 120f)
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_LIMIT_INVALID", "fov must be finite in 10..120.", "Pass a supported field of view.");
+            var captureBudget = ScreenshotToolSupport.PrepareCaptureBudget(width, height, 6, true, request.Limits, requestBudget);
 
             var labels = new[] { "front", "back", "left", "right", "top", "bird_eye" };
             var positions = new[]
             {
-                center + new Vector3(0, 0, -radius),
-                center + new Vector3(0, 0, radius),
-                center + new Vector3(-radius, 0, 0),
-                center + new Vector3(radius, 0, 0),
-                center + new Vector3(0, radius, 0),
-                center + new Vector3(radius * 0.7f, radius * 0.7f, -radius * 0.7f)
+                center + new Vector3(0, 0, -radius), center + new Vector3(0, 0, radius),
+                center + new Vector3(-radius, 0, 0), center + new Vector3(radius, 0, 0),
+                center + new Vector3(0, radius, 0), center + new Vector3(radius * 0.7f, radius * 0.7f, -radius * 0.7f)
             };
             var shotPaths = new List<string>();
-            for (var i = 0; i < labels.Length; i++)
+            for (var index = 0; index < labels.Length; index++)
             {
-                var path = Path.Combine(outputFullDir, "surround_" + labels[i] + ".png");
-                if (File.Exists(path) && !request.Overwrite)
-                    throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Screenshot output already exists: " + path, "Pass overwrite=true or choose a different output-dir.");
+                var path = Path.Combine(outputFullDir, "surround_" + labels[index] + ".png");
+                if (File.Exists(path) && !request.Overwrite) throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Screenshot output already exists: " + path, "Pass overwrite=true or choose a different outputDir.");
                 shotPaths.Add(path);
             }
-            if (File.Exists(contactSheetPath) && !request.Overwrite)
-                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Contact sheet output already exists: " + contactSheetPath, "Pass overwrite=true or choose a different contactSheetPath.");
-
+            if (File.Exists(contactSheetPath) && !request.Overwrite) throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Contact sheet output already exists: " + contactSheetPath, "Pass overwrite=true or choose another path.");
+            var planned = BuildPlannedShots(labels, shotPaths, width, height, positions);
             if (ctx.DryRun)
             {
                 return new System.Threading.Tasks.ValueTask<Result>(new Result
                 {
-                    DryRun = true,
-                    Center = new double[] { center.x, center.y, center.z },
-                    ContactSheet = new ScreenshotArtifactEntry { Source = "surround-contact-sheet", Path = contactSheetPath, Width = width * 3, Height = height * 2, Format = "png" },
-                    Artifacts = BuildPlannedShots(labels, shotPaths, width, height, positions)
+                    DryRun = true, Center = new[] { (double)center.x, center.y, center.z }, Count = 6,
+                    ContactSheet = new ScreenshotArtifactEntry { Source = "surround-contact-sheet", Path = contactSheetPath, Width = width * 3L, Height = height * 2L, Format = "png" },
+                    Artifacts = planned, CapturePlan = captureBudget.Plan
                 });
             }
 
             ctx.CommitEffect();
             Directory.CreateDirectory(outputFullDir);
             ScreenshotToolSupport.CreateScreenshotDirectory(contactSheetPath);
-            var tempGo = new GameObject("__unitycli_surround_cam__");
-            var cam = tempGo.AddComponent<Camera>();
-            cam.fieldOfView = Mathf.Clamp(request.Fov ?? 60f, 10f, 120f);
-            cam.nearClipPlane = 0.1f;
-            cam.farClipPlane = Mathf.Max(radius * 6f, 100f);
-            cam.clearFlags = CameraClearFlags.SolidColor;
-            cam.backgroundColor = new Color(0.18f, 0.18f, 0.18f, 1f);
-            var tiles = new List<Texture2D>();
+            GameObject cameraObject = null;
+            Camera camera = null;
+            Texture2D sheet = null;
             var artifacts = new List<SurroundShot>();
             byte[] contactBytes = null;
+            ScreenshotArtifactProof contactProof = null;
             try
             {
-                for (var i = 0; i < labels.Length; i++)
+                cameraObject = new GameObject("__unitycli_surround_cam__");
+                camera = cameraObject.AddComponent<Camera>();
+                camera.fieldOfView = fov;
+                camera.nearClipPlane = 0.1f;
+                camera.farClipPlane = Mathf.Max(radius * 6f, 100f);
+                camera.clearFlags = CameraClearFlags.SolidColor;
+                camera.backgroundColor = new Color(0.18f, 0.18f, 0.18f, 1f);
+                sheet = ScreenshotToolSupport.CreateContactSheet(width, height, captureBudget);
+                for (var index = 0; index < labels.Length; index++)
                 {
-                    cam.transform.position = positions[i];
-                    cam.transform.LookAt(center);
-                    var tile = ScreenshotToolSupport.RenderScreenshotTexture(cam, width, height);
-                    tiles.Add(tile);
-                    var proof = ScreenshotToolSupport.WriteScreenshotBytes(shotPaths[i], tile.EncodeToPNG());
-                    artifacts.Add(new SurroundShot
+                    camera.transform.position = positions[index];
+                    camera.transform.LookAt(center);
+                    var tile = ScreenshotToolSupport.RenderScreenshotTexture(camera, width, height, captureBudget);
+                    try
                     {
-                        Angle = labels[i],
-                        Artifact = new ScreenshotArtifactEntry { Source = "surround", Path = shotPaths[i], Camera = "surround:" + labels[i], Width = width, Height = height, Format = "png", SizeBytes = proof.SizeBytes, Sha256 = proof.Sha256 },
-                        CameraPosition = new double[] { positions[i].x, positions[i].y, positions[i].z }
-                    });
+                        ScreenshotToolSupport.CopyContactSheetTile(sheet, tile, index, width, height);
+                        var proof = ScreenshotToolSupport.WriteScreenshotBytes(shotPaths[index], tile.EncodeToPNG(), captureBudget);
+                        artifacts.Add(new SurroundShot
+                        {
+                            Angle = labels[index],
+                            Artifact = new ScreenshotArtifactEntry { Source = "surround", Path = shotPaths[index], Camera = "surround:" + labels[index], Width = width, Height = height, Format = "png", SizeBytes = proof.SizeBytes, Sha256 = proof.Sha256 },
+                            CameraPosition = new[] { (double)positions[index].x, positions[index].y, positions[index].z }
+                        });
+                    }
+                    finally { UnityEngine.Object.DestroyImmediate(tile); }
                 }
-                var contact = ScreenshotToolSupport.ComposeScreenshotContactSheet(tiles, width, height);
-                try { contactBytes = contact.EncodeToPNG(); ScreenshotToolSupport.WriteScreenshotBytes(contactSheetPath, contactBytes); }
-                finally { UnityEngine.Object.DestroyImmediate(contact); }
+                sheet.Apply(false, false);
+                contactBytes = sheet.EncodeToPNG();
+                contactProof = ScreenshotToolSupport.WriteScreenshotBytes(contactSheetPath, contactBytes, captureBudget);
             }
             finally
             {
-                foreach (var tile in tiles) UnityEngine.Object.DestroyImmediate(tile);
-                UnityEngine.Object.DestroyImmediate(tempGo);
+                if (sheet != null) UnityEngine.Object.DestroyImmediate(sheet);
+                if (cameraObject != null) UnityEngine.Object.DestroyImmediate(cameraObject);
             }
 
-            var contactProof = ScreenshotToolSupport.VerifyScreenshotArtifact(contactSheetPath, "png");
             var result = new Result
             {
-                Center = new double[] { center.x, center.y, center.z }, Count = 6,
-                ContactSheet = new ScreenshotArtifactEntry { Source = "surround-contact-sheet", Path = contactSheetPath, Width = width * 3, Height = height * 2, Format = "png", SizeBytes = contactProof.SizeBytes, Sha256 = contactProof.Sha256 },
-                Artifacts = artifacts
+                Center = new[] { (double)center.x, center.y, center.z }, Count = 6,
+                ContactSheet = new ScreenshotArtifactEntry { Source = "surround-contact-sheet", Path = contactSheetPath, Width = width * 3L, Height = height * 2L, Format = "png", SizeBytes = contactProof.SizeBytes, Sha256 = contactProof.Sha256 },
+                Artifacts = artifacts, CapturePlan = captureBudget.Plan
             };
-            if (request.InlineBase64 && contactBytes != null && contactBytes.Length <= 512 * 1024)
+            string encoded;
+            if (request.InlineBase64 && contactBytes != null && contactBytes.Length <= 512 * 1024 && captureBudget.TryCreateInlineBase64(contactBytes, out encoded))
             {
-                result.ImageBase64 = Convert.ToBase64String(contactBytes);
-                result.ImageWidth = width * 3;
-                result.ImageHeight = height * 2;
+                result.ImageBase64 = encoded;
+                result.ImageWidth = width * 3L;
+                result.ImageHeight = height * 2L;
                 result.ImageMimeType = "image/png";
             }
             return new System.Threading.Tasks.ValueTask<Result>(result);
         }
 
-        private static List<SurroundShot> BuildPlannedShots(string[] labels, List<string> shotPaths, int width, int height, Vector3[] positions)
+        private static List<SurroundShot> BuildPlannedShots(string[] labels, List<string> paths, int width, int height, Vector3[] positions)
         {
-            var shots = new List<SurroundShot>();
-            for (var i = 0; i < labels.Length; i++)
+            var result = new List<SurroundShot>();
+            for (var index = 0; index < labels.Length; index++)
             {
-                shots.Add(new SurroundShot
+                result.Add(new SurroundShot
                 {
-                    Angle = labels[i],
-                    Artifact = new ScreenshotArtifactEntry { Source = "surround", Path = shotPaths[i], Camera = "surround:" + labels[i], Width = width, Height = height, Format = "png" },
-                    CameraPosition = new double[] { positions[i].x, positions[i].y, positions[i].z }
+                    Angle = labels[index],
+                    Artifact = new ScreenshotArtifactEntry { Source = "surround", Path = paths[index], Camera = "surround:" + labels[index], Width = width, Height = height, Format = "png" },
+                    CameraPosition = new[] { (double)positions[index].x, positions[index].y, positions[index].z }
                 });
             }
-            return shots;
+            return result;
         }
     }
 }

package/unitypkg/Editor/Tools/ui/render-preview.cs

@@ -15,9 +15,11 @@ namespace UnityCli
         {
             public string Target { get; set; }
             public string Output { get; set; }
-            public int? Width { get; set; }
-            public int? Height { get; set; }
+            [UnityCliRange(1L, 8192L)] public int? Width { get; set; }
+            [UnityCliRange(1L, 8192L)] public int? Height { get; set; }
             public bool Overwrite { get; set; }
+            public ScreenshotBudgetInput Limits { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
@@ -67,12 +69,13 @@ namespace UnityCli
             var document = go.GetComponent<UIDocument>();
             if (document == null) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_NOT_FOUND", "No UIDocument on target.", "Pass a GameObject containing UIDocument.");
 
-            var width = Mathf.Max(1, request.Width ?? 1280);
-            var height = Mathf.Max(1, request.Height ?? 720);
+            var width = request.Width ?? 1280;
+            var height = request.Height ?? 720;
             var outputPath = ScreenshotToolSupport.ResolveScreenshotOutputPath(request.Output ?? "Assets/UI/preview.png");
             if (File.Exists(outputPath) && !request.Overwrite)
                 throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "UI preview output already exists: " + outputPath, "Pass overwrite=true or choose a different output path.");
 
+            var captureBudget = ScreenshotToolSupport.PrepareCaptureBudget(width, height, 1, false, request.Limits, ctx.UseReadBudget(request.Budget));
             var effects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.render-preview", Target = request.Target, Path = outputPath } };
             if (ctx.DryRun)
             {
@@ -80,20 +83,24 @@ namespace UnityCli
             }
 
             ctx.CommitEffect();
+            captureBudget.BeginCapture(width, height);
             var originalPanelSettings = document.panelSettings;
             var originalEnabled = document.enabled;
-            var renderTexture = new RenderTexture(width, height, 24, RenderTextureFormat.ARGB32);
-            var panelSettings = ScriptableObject.CreateInstance<PanelSettings>();
+            RenderTexture renderTexture = null;
+            PanelSettings panelSettings = null;
             Texture2D texture = null;
             var previousActive = RenderTexture.active;
             try
             {
+                renderTexture = new RenderTexture(width, height, 24, RenderTextureFormat.ARGB32);
+                panelSettings = ScriptableObject.CreateInstance<PanelSettings>();
                 renderTexture.Create();
                 panelSettings.targetTexture = renderTexture;
                 panelSettings.scaleMode = PanelScaleMode.ConstantPixelSize;
                 document.panelSettings = panelSettings;
                 document.enabled = true;
                 await ctx.Wait.NextFrame(2, ct);
+                ctx.ReadBudget.ResumeAfterWait();
                 ct.ThrowIfCancellationRequested();
 
                 RenderTexture.active = renderTexture;
@@ -101,8 +108,7 @@ namespace UnityCli
                 texture.ReadPixels(new Rect(0, 0, width, height), 0, 0, false);
                 texture.Apply(false, false);
                 var bytes = texture.EncodeToPNG();
-                ScreenshotToolSupport.WriteScreenshotBytes(outputPath, bytes);
-                var artifact = ScreenshotToolSupport.VerifyScreenshotArtifact(outputPath, "png");
+                var artifact = ScreenshotToolSupport.WriteScreenshotBytes(outputPath, bytes, captureBudget);
                 return new Result
                 {
                     DryRun = false,
@@ -118,9 +124,8 @@ namespace UnityCli
                 document.panelSettings = originalPanelSettings;
                 document.enabled = originalEnabled;
                 if (texture != null) Object.DestroyImmediate(texture);
-                renderTexture.Release();
-                Object.DestroyImmediate(renderTexture);
-                Object.DestroyImmediate(panelSettings);
+                if (renderTexture != null) { renderTexture.Release(); Object.DestroyImmediate(renderTexture); }
+                if (panelSettings != null) Object.DestroyImmediate(panelSettings);
             }
         }
     }