@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/scene/validate.cs

@@ -0,0 +1,115 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.validate — 校验场景:缺失脚本、null 引用、Build Settings 包含。
+    /// </summary>
+    public class SceneValidateTool : IUnityCliTool<SceneValidateTool.Request, SceneValidateTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string Scene { get; set; }
+            public bool Valid { get; set; }
+            public long MissingScriptCount { get; set; }
+            public long NullReferenceCount { get; set; }
+            public bool InBuildSettings { get; set; }
+            public List<string> Issues { get; set; }
+            public List<string> NextActions { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.validate",
+            Summary = "Validate a scene for missing scripts, null references, and Build Settings inclusion.",
+            Description = "Validate the active scene (or --path scene) for common issues: missing script components (null components from missing assemblies), null references, and whether the scene is included in Editor Build Settings scenes. Returns valid flag, issue counts, and nextActions to fix.",
+            Group = "scene",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Validate the active scene", Input = new Request { } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var scene = SceneManager.GetActiveScene();
+            var path = request.Path;
+            if (!string.IsNullOrEmpty(path))
+            {
+                scene = SceneManager.GetSceneByPath(path);
+                if (!scene.IsValid())
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_SCENE_NOT_OPEN", "Scene is not loaded: " + path, "Load the scene first or run tools run scene.list-opened.");
+                }
+            }
+            var issues = new List<string>();
+            var missingScriptCount = 0;
+            var nullReferenceCount = 0;
+            foreach (var root in scene.GetRootGameObjects())
+            {
+                foreach (var t in root.GetComponentsInChildren<Transform>(true))
+                {
+                    foreach (var c in t.GetComponents<Component>())
+                    {
+                        // 缺失脚本(MonoBehaviour 引用的程序集丢失)表现为 null 组件。
+                        if (c == null)
+                        {
+                            missingScriptCount++;
+                            issues.Add(t.gameObject.name + ": missing script component");
+                            continue;
+                        }
+                    }
+                }
+            }
+            // 构建 scenes 配置校验:当前场景是否在 EditorBuildSettings.scenes。
+            var inBuildSettings = false;
+            foreach (var bs in EditorBuildSettings.scenes ?? new EditorBuildSettingsScene[0])
+            {
+                if (string.Equals(bs.path, scene.path, System.StringComparison.OrdinalIgnoreCase))
+                {
+                    inBuildSettings = true;
+                    break;
+                }
+            }
+            if (!string.IsNullOrEmpty(scene.path) && !inBuildSettings)
+            {
+                issues.Add("scene not in Build Settings scenes: " + scene.path);
+            }
+            var ok = missingScriptCount == 0 && nullReferenceCount == 0;
+            var nextActions = new List<string>();
+            if (!ok)
+            {
+                nextActions.Add("Fix missing scripts/null references before building.");
+            }
+            if (!inBuildSettings && !string.IsNullOrEmpty(scene.path))
+            {
+                nextActions.Add("Add the scene to Build Settings with build.scene.add using path " + scene.path);
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Scene = scene.name,
+                Valid = ok,
+                MissingScriptCount = missingScriptCount,
+                NullReferenceCount = nullReferenceCount,
+                InBuildSettings = inBuildSettings,
+                Issues = issues,
+                NextActions = nextActions
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scene/view-frame.cs

@@ -0,0 +1,218 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.view-frame — 将 Editor SceneView 对准目标 GameObject 或 frame all。
+    /// </summary>
+    public class SceneViewFrameTool : IUnityCliTool<SceneViewFrameTool.Request, SceneViewFrameTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public string Path { get; set; }
+            public bool? FrameAll { get; set; }
+        }
+
+        public sealed class ViewReadback
+        {
+            public Vector3Data Pivot { get; set; }
+            public Vector3Data Rotation { get; set; }
+            public float Size { get; set; }
+            public bool Orthographic { get; set; }
+            public Vector3Data BoundsCenter { get; set; }
+            public Vector3Data BoundsSize { get; set; }
+            public bool BoundsContained { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool Framed { get; set; }
+            public bool Changed { get; set; }
+            public string NoOpReason { get; set; }
+            public ViewReadback View { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.view-frame",
+            Summary = "Frame the Editor SceneView on a target GameObject or frame all.",
+            Description = "Frame the Editor SceneView on a target GameObject or frame all. Changes Editor selection and viewport state without modifying scene data. target resolves by name, hierarchy path or instance id.",
+            Group = "scene",
+            DestructiveHint = false,
+            SideEffects = new[] { "editor-selection", "scene-view-state" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Frame all objects", Input = new Request { FrameAll = true } }
+            }
+        };
+
+        /// <summary>执行一次 SceneView.Frame，等待 repaint 稳定后用 camera frustum 与完整 viewport 状态证明终态。</summary>
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var target = request.Target ?? request.Path;
+            var frameAll = request.FrameAll == true;
+            var sceneView = SceneView.lastActiveSceneView;
+            if (sceneView == null || sceneView.camera == null)
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_VIEW_NOT_AVAILABLE", "No active SceneView with a camera is open.", "Open a SceneView window in the Unity Editor.");
+            GameObject go = null;
+            if (!string.IsNullOrEmpty(target))
+            {
+                go = SceneToolSupport.ResolveGameObjectByPath(target);
+                if (go == null)
+                    throw new UnityCliBridge.BridgeCommandException("E_GAME_OBJECT_NOT_FOUND", "SceneView frame target was not found: " + target, "Pass an existing hierarchy path, name, or instance id.");
+            }
+            else if (!frameAll)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_VIEW_TARGET_REQUIRED", "scene.view-frame requires target/path or frameAll=true.", "Pass a GameObject target or set frameAll=true.");
+            }
+
+            var instanceId = go == null ? 0 : go.GetInstanceID();
+            var globalId = go == null ? null : GlobalObjectId.GetGlobalObjectIdSlow(go).ToString();
+            var sceneHandle = go == null ? 0 : go.scene.handle;
+            var bounds = go == null ? ReadAllBounds() : ReadTargetBounds(go);
+            var before = ReadView(sceneView, bounds);
+            if (before != null && before.BoundsContained)
+                return new Result { Framed = true, Changed = false, NoOpReason = "target-bounds-already-contained", View = before };
+
+            ctx.CommitEffect();
+            try
+            {
+                if (go != null) Selection.activeGameObject = go;
+                if (!sceneView.Frame(bounds, true))
+                    throw new InvalidOperationException("SceneView rejected the resolved finite bounds.");
+                SynchronizeSceneCamera(sceneView);
+                sceneView.Repaint();
+            }
+            catch (System.Exception exception)
+            {
+                throw Unknown("invoke", exception.Message);
+            }
+
+            await ctx.Wait.NextFrame(1, ct);
+            var stable = await ctx.Wait.UntilStable(() => SceneView.lastActiveSceneView == sceneView && ReadView(sceneView, bounds)?.BoundsContained == true,
+                System.TimeSpan.FromMilliseconds(ctx.TimeoutMs), minimumFrames: 2, ct: ct);
+            if (!stable) throw Unknown("postcondition", "SceneView did not stably contain the requested bounds before the deadline.");
+
+            if (instanceId != 0)
+            {
+                var fresh = EditorUtility.InstanceIDToObject(instanceId) as GameObject;
+                if (fresh == null || fresh.scene.handle != sceneHandle
+                    || !string.Equals(GlobalObjectId.GetGlobalObjectIdSlow(fresh).ToString(), globalId, StringComparison.Ordinal))
+                    throw Unknown("readback", "SceneView target identity changed while framing.");
+                var freshBounds = ReadTargetBounds(fresh);
+                if (!SameBounds(bounds, freshBounds)) throw Unknown("readback", "SceneView target bounds changed while framing.");
+            }
+            var readback = ReadView(sceneView, bounds);
+            if (readback == null || !readback.BoundsContained) throw Unknown("postcondition", "Fresh SceneView readback does not contain the requested bounds.");
+            return new Result { Framed = true, Changed = true, View = readback };
+        }
+
+        /// <summary>合并目标及子层级 Renderer bounds；无 Renderer 时回退到 Transform 原点。</summary>
+        private static Bounds ReadTargetBounds(GameObject go)
+        {
+            var renderers = go.GetComponentsInChildren<Renderer>(true);
+            if (renderers.Length == 0) return new Bounds(go.transform.position, Vector3.one);
+            var bounds = renderers[0].bounds;
+            for (var index = 1; index < renderers.Length; index++) bounds.Encapsulate(renderers[index].bounds);
+            return bounds;
+        }
+
+        /// <summary>frameAll 使用当前已加载 scene 的真实 Renderer 集合，不使用固定虚构范围。</summary>
+        private static Bounds ReadAllBounds()
+        {
+            var renderers = Resources.FindObjectsOfTypeAll<Renderer>();
+            var found = false;
+            var bounds = new Bounds(Vector3.zero, Vector3.one);
+            foreach (var renderer in renderers)
+            {
+                if (renderer == null || !renderer.gameObject.scene.IsValid() || !renderer.gameObject.scene.isLoaded) continue;
+                if (!found) { bounds = renderer.bounds; found = true; }
+                else bounds.Encapsulate(renderer.bounds);
+            }
+            return bounds;
+        }
+
+        /// <summary>读取完整 viewport 并用 camera frustum 检查 AABB 八角范围。</summary>
+        private static ViewReadback ReadView(SceneView sceneView, Bounds bounds)
+        {
+            if (sceneView == null || sceneView.camera == null || !Finite(sceneView.pivot) || !Finite(sceneView.rotation.eulerAngles)
+                || sceneView.size <= 0f || float.IsNaN(sceneView.size) || float.IsInfinity(sceneView.size)) return null;
+            var contained = GeometryUtility.TestPlanesAABB(GeometryUtility.CalculateFrustumPlanes(sceneView.camera), bounds);
+            return new ViewReadback {
+                Pivot = Vector(sceneView.pivot), Rotation = Vector(sceneView.rotation.eulerAngles), Size = sceneView.size,
+                Orthographic = sceneView.orthographic, BoundsCenter = Vector(bounds.center), BoundsSize = Vector(bounds.size), BoundsContained = contained
+            };
+        }
+
+        /// <summary>后台或被遮挡的 SceneView 不执行 OnGUI；按 Unity 2022.3 SetupCamera 公式同步其隐藏 camera，确保读回不依赖窗口可见性。</summary>
+        private static void SynchronizeSceneCamera(SceneView sceneView)
+        {
+            var camera = sceneView.camera;
+            var settings = sceneView.cameraSettings;
+            if (camera == null || settings == null)
+                throw new InvalidOperationException("SceneView camera settings are unavailable.");
+
+            var size = Mathf.Abs(sceneView.size);
+            var aspect = camera.aspect;
+            if (float.IsNaN(aspect) || float.IsInfinity(aspect) || aspect <= 0f) aspect = 1f;
+
+            var rotation = sceneView.rotation;
+            float distance;
+            if (sceneView.orthographic)
+            {
+                camera.orthographic = true;
+                camera.orthographicSize = aspect < 1f ? size / aspect : size;
+                distance = size * 2f;
+            }
+            else
+            {
+                var aspectNeutralFov = settings.fieldOfView;
+                var halfFovRadians = aspectNeutralFov * 0.5f * Mathf.Deg2Rad;
+                var halfFovSin = Mathf.Sin(halfFovRadians);
+                if (float.IsNaN(aspectNeutralFov) || float.IsInfinity(aspectNeutralFov) || halfFovSin <= Mathf.Epsilon)
+                    throw new InvalidOperationException("SceneView field of view is not finite and positive.");
+
+                var verticalMultiplier = aspect < 1f ? 1f / aspect : 1f;
+                var verticalHalfFov = Mathf.Atan(Mathf.Tan(halfFovRadians) * verticalMultiplier);
+                camera.orthographic = false;
+                camera.fieldOfView = verticalHalfFov * 2f * Mathf.Rad2Deg;
+                distance = size / halfFovSin;
+            }
+
+            camera.transform.rotation = rotation;
+            camera.transform.position = sceneView.pivot + rotation * new Vector3(0f, 0f, -distance);
+            if (settings.dynamicClip)
+            {
+                var farClip = Mathf.Clamp(2000f * size, 1000f, 1.844674E+19f);
+                camera.nearClipPlane = Mathf.Max(0.00001f, farClip * 0.000005f);
+                camera.farClipPlane = farClip;
+            }
+            else
+            {
+                camera.nearClipPlane = settings.nearClip;
+                camera.farClipPlane = settings.farClip;
+            }
+            camera.ResetWorldToCameraMatrix();
+            camera.ResetProjectionMatrix();
+        }
+
+        private static bool SameBounds(Bounds left, Bounds right) { return (left.center - right.center).sqrMagnitude <= 0.000001f && (left.size - right.size).sqrMagnitude <= 0.000001f; }
+        private static bool Finite(Vector3 value) { return !(float.IsNaN(value.x) || float.IsInfinity(value.x) || float.IsNaN(value.y) || float.IsInfinity(value.y) || float.IsNaN(value.z) || float.IsInfinity(value.z)); }
+        private static Vector3Data Vector(Vector3 value) { return new Vector3Data { X = value.x, Y = value.y, Z = value.z }; }
+        private static UnityCliBridge.BridgeCommandException Unknown(string stage, string cause)
+        {
+            return new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", "SceneView framing result cannot be confirmed; inspect the business state before deciding whether to retry.",
+                new Dictionary<string, object> { { "stage", stage }, { "cause", cause } }, new[] { "Inspect the SceneView before submitting a new request." });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,181 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using UnityEditor;
+using UnityEngine;
+#if UNITY_6000_7_OR_NEWER
+using UnityEngine.UIElements;
+#endif
+
+namespace UnityCli
+{
+    /// <summary>Unity 6000.7+ UI Toolkit element解析、bounded capture和artifact proof owner。</summary>
+    internal static class EditorElementCaptureToolSupport
+    {
+        internal const int MaxDimension = 4096;
+        internal const long MaxArtifactBytes = 32L * 1024L * 1024L;
+
+        internal sealed class Plan
+        {
+#if UNITY_6000_7_OR_NEWER
+            internal VisualElement Element;
+#endif
+            internal string WindowType, WindowTitle, Selector, ElementType, ElementName;
+            internal List<string> ElementClasses;
+            internal long WindowInstanceId, MaxBytes;
+            internal int Width, Height;
+        }
+
+        internal static Plan Prepare(EditorElementCaptureRequest request)
+        {
+#if !UNITY_6000_7_OR_NEWER
+            throw Unavailable();
+#else
+            EditorToolSupport.EnsureEditorNotBusy("screenshot.editor-element");
+            if (request == null || string.IsNullOrWhiteSpace(request.Window)) throw Error("E_EDITOR_ELEMENT_WINDOW_REQUIRED", "window is required.");
+            if (string.IsNullOrWhiteSpace(request.Selector) || request.Selector.Length > 1024) throw Error("E_EDITOR_ELEMENT_SELECTOR_INVALID", "selector must contain 1..1024 characters.");
+            var maxWidth = request.MaxWidth ?? 2048L;
+            var maxHeight = request.MaxHeight ?? 2048L;
+            var maxBytes = request.MaxBytes ?? (8L * 1024L * 1024L);
+            if (maxWidth < 1 || maxWidth > MaxDimension || maxHeight < 1 || maxHeight > MaxDimension || maxBytes < 1024 || maxBytes > MaxArtifactBytes)
+                throw Error("E_EDITOR_ELEMENT_LIMIT_INVALID", "maxWidth/maxHeight must be 1..4096 and maxBytes must be 1024..33554432.");
+            var candidates = Resources.FindObjectsOfTypeAll<EditorWindow>()
+                .Where(value => value != null && value.rootVisualElement != null && value.rootVisualElement.panel != null)
+                .Where(value => string.Equals(value.GetType().Name, request.Window, StringComparison.Ordinal) || string.Equals(value.titleContent == null ? null : value.titleContent.text, request.Window, StringComparison.Ordinal))
+                .OrderBy(value => value.GetInstanceID()).Take(257).ToList();
+            if (candidates.Count == 0) throw Error("E_EDITOR_ELEMENT_WINDOW_NOT_FOUND", "No attached EditorWindow exactly matches '" + request.Window + "'.");
+            if (candidates.Count > 256) throw Error("E_EDITOR_ELEMENT_LIMIT_EXCEEDED", "More than 256 EditorWindow candidates matched the bounded scan.");
+            var window = candidates[0];
+            var element = Resolve(window.rootVisualElement, request.Selector);
+            if (element == null) throw Error("E_EDITOR_ELEMENT_NOT_FOUND", "No UI Toolkit element matched selector '" + request.Selector + "'.");
+            var width = Mathf.CeilToInt(element.worldBound.width);
+            var height = Mathf.CeilToInt(element.worldBound.height);
+            if (width < 1 || height < 1 || width > maxWidth || height > maxHeight || (long)width * height > 16777216L)
+                throw Error("E_EDITOR_ELEMENT_LIMIT_EXCEEDED", "Resolved element dimensions " + width + "x" + height + " exceed the requested capture bounds.");
+            return new Plan { Element = element, WindowType = window.GetType().Name, WindowTitle = window.titleContent == null ? null : window.titleContent.text, WindowInstanceId = window.GetInstanceID(), Selector = request.Selector, ElementType = element.GetType().Name, ElementName = element.name, ElementClasses = element.GetClasses().Take(128).Select(Bound).ToList(), Width = width, Height = height, MaxBytes = maxBytes };
+#endif
+        }
+
+        /// <summary>调用方必须先跨barrier；render state和temporary texture总在finally恢复。</summary>
+        internal static EditorElementCaptureResult Capture(Plan plan, UnityCliProjectToolContext ctx)
+        {
+#if !UNITY_6000_7_OR_NEWER
+            throw Unavailable();
+#else
+            if (plan == null || plan.Element == null || plan.Element.panel == null) throw Error("E_EDITOR_ELEMENT_TARGET_CHANGED", "The frozen UI Toolkit element is no longer attached.");
+            RenderTexture texture = null;
+            Texture2D readable = null;
+            var previous = RenderTexture.active;
+            byte[] png;
+            try
+            {
+                texture = plan.Element.CaptureToRenderTexture();
+                if (texture == null || texture.width != plan.Width || texture.height != plan.Height) throw Error("E_EDITOR_ELEMENT_TARGET_CHANGED", "The captured element dimensions changed after the effect barrier.");
+                RenderTexture.active = texture;
+                readable = new Texture2D(texture.width, texture.height, TextureFormat.RGBA32, false);
+                readable.ReadPixels(new Rect(0, 0, texture.width, texture.height), 0, 0, false);
+                readable.Apply(false, false);
+                png = readable.EncodeToPNG();
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (Exception exception) { throw Error("E_EDITOR_ELEMENT_CAPTURE_FAILED", "UI Toolkit capture failed: " + exception.GetType().Name + "."); }
+            finally
+            {
+                RenderTexture.active = previous;
+                if (texture != null) { texture.Release(); UnityEngine.Object.DestroyImmediate(texture); }
+                if (readable != null) UnityEngine.Object.DestroyImmediate(readable);
+            }
+            if (png == null || png.LongLength < 8 || png.LongLength > plan.MaxBytes) throw Error("E_EDITOR_ELEMENT_LIMIT_EXCEEDED", "Encoded PNG is empty or exceeds maxBytes.");
+            if (string.IsNullOrWhiteSpace(ctx.ArtifactDir)) throw Error("E_EDITOR_ELEMENT_ARTIFACT_UNAVAILABLE", "The request artifact directory is unavailable.");
+            Directory.CreateDirectory(ctx.ArtifactDir);
+            var output = Path.Combine(ctx.ArtifactDir, "editor-element.png");
+            var artifact = ScreenshotToolSupport.WriteScreenshotBytes(output, png);
+            if (artifact.SizeBytes > plan.MaxBytes || artifact.SizeBytes != png.LongLength)
+            {
+                try { File.Delete(output); } catch { }
+                throw Error("E_EDITOR_ELEMENT_ARTIFACT_INVALID", "The persisted PNG does not match the bounded encoded artifact.");
+            }
+            return Result(plan, false, artifact);
+#endif
+        }
+
+        internal static EditorElementCaptureResult Preview(Plan plan) => Result(plan, true, null);
+
+        private static EditorElementCaptureResult Result(Plan plan, bool dryRun, ScreenshotArtifactProof artifact)
+        {
+            return new EditorElementCaptureResult { Available = true, Element = new EditorElementIdentity { Selector = plan.Selector, Type = plan.ElementType, Name = plan.ElementName, Classes = plan.ElementClasses }, Width = plan.Width, Height = plan.Height, Artifact = artifact, DryRun = dryRun, PlannedEffects = new List<EditorElementCapturePlannedEffect> { new EditorElementCapturePlannedEffect { Type = "screenshot.editor-element", WindowInstanceId = plan.WindowInstanceId, Width = plan.Width, Height = plan.Height, MaxBytes = plan.MaxBytes } } };
+        }
+
+#if UNITY_6000_7_OR_NEWER
+        /// <summary>实现type/#id/.class与descendant/child链；全查询最多16段、10000候选。</summary>
+        private static VisualElement Resolve(VisualElement root, string selector)
+        {
+            var tokens = selector.Replace(">", " > ").Split(new[] { ' ' }, StringSplitOptions.RemoveEmptyEntries);
+            var segments = tokens.Count(token => token != ">");
+            if (segments < 1 || segments > 16) throw Error("E_EDITOR_ELEMENT_SELECTOR_INVALID", "selector must contain 1..16 simple segments.");
+            var current = new List<VisualElement> { root };
+            var direct = false;
+            var visited = 0;
+            foreach (var token in tokens)
+            {
+                if (token == ">") { direct = true; continue; }
+                var next = new List<VisualElement>();
+                foreach (var parent in current)
+                {
+                    var values = direct ? parent.Children() : Descendants(parent, ref visited);
+                    foreach (var value in values)
+                    {
+                        if (++visited > 10000) throw Error("E_EDITOR_ELEMENT_LIMIT_EXCEEDED", "selector scan exceeded 10000 UI elements.");
+                        if (Matches(value, token)) next.Add(value);
+                        if (next.Count > 256) throw Error("E_EDITOR_ELEMENT_LIMIT_EXCEEDED", "selector produced more than 256 intermediate matches.");
+                    }
+                }
+                current = next;
+                direct = false;
+                if (current.Count == 0) return null;
+            }
+            return current.FirstOrDefault();
+        }
+
+        private static IEnumerable<VisualElement> Descendants(VisualElement root, ref int visited)
+        {
+            var result = new List<VisualElement>();
+            var stack = new Stack<VisualElement>(root.Children().Reverse());
+            while (stack.Count > 0)
+            {
+                var value = stack.Pop();
+                result.Add(value);
+                if (result.Count + visited > 10000) break;
+                foreach (var child in value.Children().Reverse()) stack.Push(child);
+            }
+            return result;
+        }
+
+        private static bool Matches(VisualElement value, string simple)
+        {
+            var typeEnd = simple.IndexOfAny(new[] { '#', '.' });
+            var type = typeEnd < 0 ? simple : simple.Substring(0, typeEnd);
+            if (!string.IsNullOrEmpty(type) && type != "*" && !string.Equals(value.GetType().Name, type, StringComparison.Ordinal)) return false;
+            var position = Math.Max(0, typeEnd);
+            while (position < simple.Length)
+            {
+                var marker = simple[position++];
+                var next = simple.IndexOfAny(new[] { '#', '.' }, position);
+                var name = simple.Substring(position, (next < 0 ? simple.Length : next) - position);
+                if (string.IsNullOrEmpty(name)) return false;
+                if (marker == '#' && !string.Equals(value.name, name, StringComparison.Ordinal)) return false;
+                if (marker == '.' && !value.ClassListContains(name)) return false;
+                position = next < 0 ? simple.Length : next;
+            }
+            return true;
+        }
+#endif
+
+        private static string Bound(string value) => value == null || value.Length <= 1024 ? value : value.Substring(0, 1024);
+        private static UnityCliBridge.BridgeCommandException Error(string code, string message) => new UnityCliBridge.BridgeCommandException(code, message, "Inspect the target Editor window and tighten the bounded selector before retrying.");
+        private static UnityCliBridge.BridgeCommandException Unavailable() => new UnityCliBridge.BridgeCommandException("E_EDITOR_ELEMENT_CAPTURE_UNAVAILABLE", "screenshot.editor-element requires Unity 6000.7 or newer.", "Use a Unity 6000.7+ Editor instance.");
+    }
+}
+#endif