@mflrevan/ucp 0.6.2 → 0.6.3

package/README.md

@@ -1,6 +1,6 @@
 # @mflrevan/ucp
 
-Version `0.6.2` of the Unity Control Protocol CLI.
+Version `0.6.3` of the Unity Control Protocol CLI.
 
 This package installs the `ucp` command, downloads the matching published binary for your platform during `postinstall`, and ships the matching Unity bridge payload inside the npm package.
 

package/bridge/com.ucp.bridge/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [0.6.3] - 2026-09-07
+
+### Added
+
+- Every response produced on the main thread carries an `editor` summary next to `result` or
+  `error` (`EditorStateSummary`): mode, active scene dirtiness, Console badge counts read
+  through `LogEntries.GetCountsByType`, entries logged since the request was dispatched, and
+  conditional flags for compile errors, compiling, importing, building, prefab stage, and
+  recording. The handshake, which is answered off the main thread, reports
+  `mainThreadTickAgeMs` and `compiling` so a client can recognise a blocked main thread or a
+  pending domain reload before sending a request. Added `editor/state`
+  to fetch the summary on its own.
+- Added the `ui/list`, `ui/lint`, `ui/inspect`, `ui/screenshot`, `ui/check`, and `ui/status`
+  RPCs plus the `ui/result` completion notification for UI Toolkit authoring on Unity 6 and
+  newer. On older editors the methods are registered but return an explicit unsupported error.
+- Lint runs the synchronous UXML/USS/TSS importers, reads their import logs and
+  `importedWithErrors`/`importedWithWarnings` flags, follows UI dependencies, and clone-probes
+  each `VisualTreeAsset` under a scoped log capture. Immutable package assets are inspected from
+  their existing import artifacts without a forced reimport.
+- Render operations (`inspect`, `screenshot`, `check`) are queued and ticked on
+  `EditorApplication.update` in a transient `HideAndDontSave` utility window, wait for stable
+  finite geometry and stable pixels, capture through `InternalEditorUtility.CaptureEditorWindow`
+  with DPI compensation, write PNGs under `Library/UCP/UiCaptures`, and restore the previously
+  focused window. A 300-second overall ceiling and per-state settle timeouts bound every run;
+  `BridgeServer.Shutdown` fails in-flight operations with `editor_shutdown` before a reload.
+- Scenario support: strict `.ucp-ui.json` parsing with unknown-field rejection, deep data
+  overlays, an allowlisted `set` block, `repeat` and virtualized `list-view` collections driven
+  by JSON pointers, and automatic rewriting of `DataBinding` paths to dictionary keys through
+  `Unity.Properties`.
+
+### Changed
+
+- Object ids are 64-bit end to end. `UnityObjectCompat.GetId()` returns a `long`
+  (`EntityId.ToULong` on 6000.5+, the instance id below that), `ResolveByInstanceId` takes a
+  `long`, and every controller reads `instanceId` parameters with `Convert.ToInt64`. On
+  6000.5 an `EntityId` carries a per-session upper word, so the previous `int` truncation
+  produced ids that could not be resolved back.
+
+### Fixed
+
+- Fixed the `tests/run` console guard counting log lines emitted inside a test's
+  `LogAssert.ignoreFailingMessages` window; the `IgnoreFailingMessages:true/false` markers the
+  test runner writes now delimit an exclusion range.
+- Fixed the edit-mode test assembly failing to compile on Unity 6000.5 (`GetInstanceID()` is
+  obsolete-as-error there); tests use the `EntityId`-aware `GetId()` helper throughout.
+- Removed the empty `UCP.Bridge.Runtime` assembly definition that logged an "will not be
+  compiled, because it has no scripts associated with it" warning on every import (#4).
+
 ## [0.6.2] - 2026-08-31
 
 ### Added

package/bridge/com.ucp.bridge/Editor/Bridge/BridgeServer.cs

@@ -26,7 +26,7 @@ namespace UCP.Bridge
         private const int DefaultPort = 21342;
         private const int MaxPort = 21352;
         private const int MaxConnections = 4;
-        private const string ProtocolVersion = "0.6.2";
+        private const string ProtocolVersion = "0.6.3";
 
         private static TcpListener s_listener;
         private static CancellationTokenSource s_cts;
@@ -45,6 +45,14 @@ namespace UCP.Bridge
 
         // Main-thread action queue
         private static readonly ConcurrentQueue<Action> s_mainThreadQueue = new();
+        // UTC ticks of the last EditorApplication.update we saw. Written by the main thread,
+        // read by the socket thread in the handshake so a client can tell "the editor's main
+        // thread is stalled" (modal dialog, synchronous import, domain reload) apart from "busy".
+        private static long s_lastMainThreadTick;
+        // EditorApplication.isCompiling as of the last pump, so the off-thread handshake can warn
+        // a client that a domain reload is imminent instead of letting its request race it.
+        private static int s_compiling;
+        private static bool s_summaryFailureLogged;
 
         // Command router
         private static readonly CommandRouter s_router = new();
@@ -120,7 +128,9 @@ namespace UCP.Bridge
                     protocolVersion = ProtocolVersion,
                     unityVersion = s_unityVersion,
                     projectName = s_projectName,
-                    projectPath = s_projectPath
+                    projectPath = s_projectPath,
+                    mainThreadTickAgeMs = MainThreadTickAgeMs(),
+                    compiling = System.Threading.Volatile.Read(ref s_compiling) == 1
                 };
             });
 
@@ -145,6 +155,9 @@ namespace UCP.Bridge
             // Lightweight video recording
             RecordingController.Register(s_router);
 
+            // UI Toolkit authoring, inspection, linting, and capture
+            UiController.Register(s_router);
+
             // Logs
             LogsController.Register(s_router);
 
@@ -435,16 +448,25 @@ namespace UCP.Bridge
             // Dispatch on main thread
             s_mainThreadQueue.Enqueue(() =>
             {
+                var logCursor = LogsController.GetLatestId();
                 var response = s_router.Dispatch(capturedMethod, capturedId, capturedParams);
-                SendResponse(capturedWs, response);
+                SendResponse(capturedWs, response, logCursor);
             });
         }
 
-        private static void SendResponse(WebSocket ws, JsonRpcResponse response)
+        /// <summary>Milliseconds since the main thread last pumped; -1 before the first pump.</summary>
+        internal static long MainThreadTickAgeMs()
+        {
+            var last = System.Threading.Volatile.Read(ref s_lastMainThreadTick);
+            if (last == 0) return -1;
+            return (DateTime.UtcNow.Ticks - last) / TimeSpan.TicksPerMillisecond;
+        }
+
+        private static void SendResponse(WebSocket ws, JsonRpcResponse response, long? logCursor = null)
         {
             try
             {
-                var json = MiniJson.Serialize(ResponseToDict(response));
+                var json = MiniJson.Serialize(ResponseToDict(response, logCursor));
                 var bytes = Encoding.UTF8.GetBytes(json);
                 _ = ws.SendAsync(new ArraySegment<byte>(bytes),
                     WebSocketMessageType.Text, true, CancellationToken.None);
@@ -521,6 +543,8 @@ namespace UCP.Bridge
 
         private static void PumpMainThread()
         {
+            System.Threading.Volatile.Write(ref s_lastMainThreadTick, DateTime.UtcNow.Ticks);
+            System.Threading.Volatile.Write(ref s_compiling, EditorApplication.isCompiling ? 1 : 0);
             int processed = 0;
             while (s_mainThreadQueue.TryDequeue(out var action) && processed < 50)
             {
@@ -574,6 +598,9 @@ namespace UCP.Bridge
 
         private static void Shutdown()
         {
+#if UNITY_6000_0_OR_NEWER
+            UiOperationManager.Shutdown();
+#endif
             if (!s_running) return;
             s_running = false;
 
@@ -608,7 +635,12 @@ namespace UCP.Bridge
             Application.logMessageReceivedThreaded -= OnLogMessage;
         }
 
-        private static Dictionary<string, object> ResponseToDict(JsonRpcResponse r)
+        /// <param name="logCursor">
+        /// Present for responses produced on the main thread: the log id captured before dispatch.
+        /// The editor-state summary is attached as a sibling of result/error, and only then --
+        /// the handshake is answered off-thread where none of the editor APIs may be touched.
+        /// </param>
+        internal static Dictionary<string, object> ResponseToDict(JsonRpcResponse r, long? logCursor = null)
         {
             var dict = new Dictionary<string, object>
             {
@@ -616,6 +648,23 @@ namespace UCP.Bridge
                 ["id"] = r.id
             };
 
+            if (logCursor.HasValue)
+            {
+                try
+                {
+                    dict["editor"] = EditorStateSummary.Capture(logCursor.Value);
+                }
+                catch (Exception ex)
+                {
+                    // Never let awareness break a response; note the failure once per domain.
+                    if (!s_summaryFailureLogged)
+                    {
+                        s_summaryFailureLogged = true;
+                        Debug.LogWarning($"[UCP] editor state summary unavailable: {ex.Message}");
+                    }
+                }
+            }
+
             if (r.error != null)
             {
                 dict["error"] = new Dictionary<string, object>

package/bridge/com.ucp.bridge/Editor/Bridge/EditorStateSummary.cs

@@ -0,0 +1,165 @@
+using System;
+using System.Collections.Generic;
+using System.Reflection;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UCP.Bridge
+{
+    /// <summary>
+    /// The compact editor state that rides on every main-thread response, so an agent is told
+    /// whether the console is red, whether the editor is playing or compiling, and whether the
+    /// scene is dirty without spending a request on it.
+    ///
+    /// Budget: this runs once per response on the main thread, so it may only use O(1) editor
+    /// queries and cached reflection. It must never allocate more than a few small dictionaries,
+    /// never touch the asset database, and never throw -- a summary failure is swallowed by the
+    /// caller so it can never break a response.
+    /// </summary>
+    public static class EditorStateSummary
+    {
+        private delegate void GetCountsByType(ref int errors, ref int warnings, ref int logs);
+
+        private static GetCountsByType s_getCountsByType;
+        private static bool s_countsLookedUp;
+
+        /// <param name="logsSinceId">
+        /// The log history cursor captured before the request was dispatched; entries after it
+        /// were produced by this request and are reported as "new".
+        /// </param>
+        public static Dictionary<string, object> Capture(long logsSinceId)
+        {
+            var summary = new Dictionary<string, object>(8);
+
+            var playing = EditorApplication.isPlaying;
+            summary["mode"] = playing
+                ? (EditorApplication.isPaused ? "paused" : "play")
+                : "edit";
+            if (EditorApplication.isPlayingOrWillChangePlaymode != playing)
+                summary["modeChanging"] = true;
+            if (EditorApplication.isCompiling)
+                summary["compiling"] = true;
+            if (EditorApplication.isUpdating)
+                summary["importing"] = true;
+            if (EditorUtility.scriptCompilationFailed)
+                summary["compileErrors"] = true;
+            if (BuildPipeline.isBuildingPlayer)
+                summary["building"] = true;
+
+            summary["scene"] = DescribeScenes();
+
+            var stage = PrefabStageUtility.GetCurrentPrefabStage();
+            if (stage != null)
+                summary["prefabStage"] = stage.assetPath;
+
+            summary["console"] = DescribeConsole(logsSinceId);
+
+            var recording = RecordingController.StateForSummary();
+            if (recording != null)
+                summary["recording"] = recording;
+
+            return summary;
+        }
+
+        private static Dictionary<string, object> DescribeScenes()
+        {
+            var active = SceneManager.GetActiveScene();
+            var scene = new Dictionary<string, object>(4)
+            {
+                ["name"] = active.name,
+                ["dirty"] = active.isDirty
+            };
+            if (string.IsNullOrEmpty(active.path))
+                scene["untitled"] = true;
+
+            var count = SceneManager.sceneCount;
+            if (count > 1)
+            {
+                var otherDirty = 0;
+                for (var index = 0; index < count; index++)
+                {
+                    var candidate = SceneManager.GetSceneAt(index);
+                    if (candidate != active && candidate.isDirty)
+                        otherDirty++;
+                }
+                scene["loaded"] = count;
+                if (otherDirty > 0)
+                    scene["otherDirty"] = otherDirty;
+            }
+
+            return scene;
+        }
+
+        private static Dictionary<string, object> DescribeConsole(long logsSinceId)
+        {
+            var console = new Dictionary<string, object>(4);
+            if (TryReadConsoleCounts(out var errors, out var warnings))
+            {
+                console["errors"] = errors;
+                console["warnings"] = warnings;
+            }
+            else
+            {
+                // Reflection into UnityEditor.LogEntries failed on this editor build; fall back to
+                // the bridge's own history, which at least covers everything since the bridge loaded.
+                LogsController.CountLevels(0, out errors, out warnings);
+                console["errors"] = errors;
+                console["warnings"] = warnings;
+                console["source"] = "bridge";
+            }
+
+            LogsController.CountLevels(logsSinceId, out var newErrors, out var newWarnings);
+            if (newErrors > 0)
+                console["newErrors"] = newErrors;
+            if (newWarnings > 0)
+                console["newWarnings"] = newWarnings;
+            return console;
+        }
+
+        /// <summary>
+        /// The counts the Console window's toolbar badges show, read through the same internal
+        /// API the window uses. Cached after the first lookup; the call itself is native and cheap.
+        /// </summary>
+        internal static bool TryReadConsoleCounts(out int errors, out int warnings)
+        {
+            errors = 0;
+            warnings = 0;
+            if (!s_countsLookedUp)
+            {
+                s_countsLookedUp = true;
+                try
+                {
+                    var type = typeof(Editor).Assembly.GetType("UnityEditor.LogEntries");
+                    var method = type?.GetMethod(
+                        "GetCountsByType",
+                        BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static);
+                    if (method != null)
+                    {
+                        s_getCountsByType = (GetCountsByType)Delegate.CreateDelegate(
+                            typeof(GetCountsByType), method, false);
+                    }
+                }
+                catch
+                {
+                    s_getCountsByType = null;
+                }
+            }
+
+            if (s_getCountsByType == null)
+                return false;
+
+            try
+            {
+                var logs = 0;
+                s_getCountsByType(ref errors, ref warnings, ref logs);
+                return true;
+            }
+            catch
+            {
+                return false;
+            }
+        }
+    }
+}

package/bridge/com.ucp.bridge/Editor/Bridge/EditorStateSummary.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 81e4ee8b39d34106904926156faa3bfe
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/bridge/com.ucp.bridge/Editor/Compatibility/UnityObjectCompat.cs

@@ -4,17 +4,30 @@ using UnityEngine.SceneManagement;
 
 namespace UCP.Bridge
 {
+    /// <summary>
+    /// Object identity across the Unity 6 line. Up to 6000.4 an object is identified by a 32-bit
+    /// instance id; from 6000.5 it is a 64-bit <c>EntityId</c> whose upper word is a session
+    /// stamp and whose lower word is the classic id, and neither sign- nor zero-extending the
+    /// lower word resolves the object again. The wire protocol therefore carries ids as 64-bit
+    /// integers everywhere. On older editors the values are the same numbers they always were.
+    /// </summary>
     internal static class UnityObjectCompat
     {
-        public static int GetId(this Object obj)
+        public static long GetId(this Object obj)
         {
 #if UNITY_6000_5_OR_NEWER
-            return unchecked((int)EntityId.ToULong(obj.GetEntityId()));
+            return unchecked((long)EntityId.ToULong(obj.GetEntityId()));
 #else
             return obj.GetInstanceID();
 #endif
         }
 
+        /// <summary>Reads an id parameter from a parsed JSON payload (int, long, or numeric string).</summary>
+        public static long ReadId(object value)
+        {
+            return System.Convert.ToInt64(value);
+        }
+
         public static long GetSceneHandle(Scene scene)
         {
 #if UNITY_6000_5_OR_NEWER
@@ -27,16 +40,20 @@ namespace UCP.Bridge
 #endif
         }
 
-        public static Object ResolveByInstanceId(int instanceId)
+        public static Object ResolveByInstanceId(long instanceId)
         {
 #if UNITY_6000_5_OR_NEWER
             return EditorUtility.EntityIdToObject(EntityId.FromULong(unchecked((ulong)instanceId)));
 #else
-            return EditorUtility.InstanceIDToObject(instanceId);
+            // 32-bit editors cannot have handed out anything wider; treat an out-of-range id as
+            // "no such object" rather than truncating it into a different object's id.
+            if (instanceId < int.MinValue || instanceId > int.MaxValue)
+                return null;
+            return EditorUtility.InstanceIDToObject((int)instanceId);
 #endif
         }
 
-        public static T ResolveByInstanceId<T>(int instanceId) where T : Object
+        public static T ResolveByInstanceId<T>(long instanceId) where T : Object
         {
             return ResolveByInstanceId(instanceId) as T;
         }

package/bridge/com.ucp.bridge/Editor/Controllers/EditorController.cs

@@ -7,6 +7,7 @@ namespace UCP.Bridge
         public static void Register(CommandRouter router)
         {
             router.Register("editor/status", HandleStatus);
+            router.Register("editor/state", _ => EditorStateSummary.Capture(LogsController.GetLatestId()));
             router.Register("editor/quit", HandleQuit);
         }
 

package/bridge/com.ucp.bridge/Editor/Controllers/HierarchyController.cs

@@ -44,7 +44,7 @@ namespace UCP.Bridge
             // Optional parent
             if (p != null && p.TryGetValue("parent", out var parentObj))
             {
-                int parentId = Convert.ToInt32(parentObj);
+                long parentId = Convert.ToInt64(parentObj);
                 var parent = FindGameObject(parentId);
                 go.transform.SetParent(parent.transform, false);
             }
@@ -84,7 +84,7 @@ namespace UCP.Bridge
             if (p == null || !p.TryGetValue("instanceId", out var idObj))
                 throw new ArgumentException("Missing 'instanceId' parameter");
 
-            int instanceId = Convert.ToInt32(idObj);
+            long instanceId = Convert.ToInt64(idObj);
             var go = FindGameObject(instanceId);
             string name = go.name;
             var scene = go.scene;
@@ -107,14 +107,14 @@ namespace UCP.Bridge
             if (p == null || !p.TryGetValue("instanceId", out var idObj))
                 throw new ArgumentException("Missing 'instanceId' parameter");
 
-            int instanceId = Convert.ToInt32(idObj);
+            long instanceId = Convert.ToInt64(idObj);
             var go = FindGameObject(instanceId);
 
             Undo.SetTransformParent(go.transform, null, "UCP Reparent");
 
             if (p.TryGetValue("parent", out var parentObj) && parentObj != null)
             {
-                int parentId = Convert.ToInt32(parentObj);
+                long parentId = Convert.ToInt64(parentObj);
                 var parent = FindGameObject(parentId);
                 Undo.SetTransformParent(go.transform, parent.transform, "UCP Reparent");
             }
@@ -163,7 +163,7 @@ namespace UCP.Bridge
             // Instantiate from existing scene object (clone)
             else if (p.TryGetValue("sourceId", out var srcObj))
             {
-                int srcId = Convert.ToInt32(srcObj);
+                long srcId = Convert.ToInt64(srcObj);
                 source = FindGameObject(srcId);
             }
             else
@@ -183,7 +183,7 @@ namespace UCP.Bridge
             // Optional parent
             if (p.TryGetValue("parent", out var parentObj) && parentObj != null)
             {
-                int parentId = Convert.ToInt32(parentObj);
+                long parentId = Convert.ToInt64(parentObj);
                 var parent = FindGameObject(parentId);
                 instance.transform.SetParent(parent.transform, false);
             }
@@ -222,7 +222,7 @@ namespace UCP.Bridge
             if (!p.TryGetValue("type", out var typeObj) || typeObj == null)
                 throw new ArgumentException("Missing 'type' parameter");
 
-            int instanceId = Convert.ToInt32(idObj);
+            long instanceId = Convert.ToInt64(idObj);
             var go = FindGameObject(instanceId);
             string typeName = typeObj.ToString();
 
@@ -252,7 +252,7 @@ namespace UCP.Bridge
             if (!p.TryGetValue("type", out var typeObj) || typeObj == null)
                 throw new ArgumentException("Missing 'type' parameter");
 
-            int instanceId = Convert.ToInt32(idObj);
+            long instanceId = Convert.ToInt64(idObj);
             var go = FindGameObject(instanceId);
             string typeName = typeObj.ToString();
 
@@ -344,7 +344,7 @@ namespace UCP.Bridge
             return null;
         }
 
-        private static GameObject FindGameObject(int instanceId)
+        private static GameObject FindGameObject(long instanceId)
         {
             var obj = UnityObjectCompat.ResolveByInstanceId<GameObject>(instanceId);
             if (obj != null) return obj;
@@ -363,7 +363,7 @@ namespace UCP.Bridge
             throw new ArgumentException($"GameObject not found: {instanceId}");
         }
 
-        private static GameObject FindInHierarchy(GameObject go, int instanceId)
+        private static GameObject FindInHierarchy(GameObject go, long instanceId)
         {
             if (go.GetId() == instanceId) return go;
             for (int i = 0; i < go.transform.childCount; i++)

package/bridge/com.ucp.bridge/Editor/Controllers/LogsController.cs

@@ -109,6 +109,30 @@ namespace UCP.Bridge
             }
         }
 
+        /// <summary>
+        /// Error/exception and warning counts in the bridge history after <paramref name="afterId"/>.
+        /// Walks back from the newest entry and stops at the cursor, so the cost is proportional to
+        /// what the current request logged, not to the history size.
+        /// </summary>
+        public static void CountLevels(long afterId, out int errors, out int warnings)
+        {
+            errors = 0;
+            warnings = 0;
+            lock (s_historyLock)
+            {
+                for (var index = s_history.Count - 1; index >= 0; index--)
+                {
+                    var entry = s_history[index];
+                    if (entry.Id <= afterId)
+                        break;
+                    if (entry.Level == "error" || entry.Level == "exception")
+                        errors++;
+                    else if (entry.Level == "warning")
+                        warnings++;
+                }
+            }
+        }
+
         public static long GetLatestId()
         {
             SeedHistoryFromConsole();
@@ -132,6 +156,53 @@ namespace UCP.Bridge
             }
         }
 
+        /// <summary>
+        /// Status summary for the test-run console guard. Unity's test runner writes
+        /// "IgnoreFailingMessages:true" / "IgnoreFailingMessages:false" log lines whenever a test
+        /// toggles <c>LogAssert.ignoreFailingMessages</c>; everything logged inside such a window is
+        /// noise the test declared as expected, so it must not fail the guard. The markers
+        /// themselves are dropped as well.
+        /// </summary>
+        public static Dictionary<string, object> BuildTestGuardSummary(long afterId)
+        {
+            SeedHistoryFromConsole();
+            lock (s_historyLock)
+            {
+                var ordered = s_history
+                    .Where(entry => entry.Id > afterId)
+                    .OrderBy(entry => entry.Id)
+                    .ToList();
+
+                return BuildStatusResult(ExcludeExpectedNoise(ordered, entry => entry.Message), afterId);
+            }
+        }
+
+        internal const string IgnoreFailingMessagesOnMarker = "IgnoreFailingMessages:true";
+        internal const string IgnoreFailingMessagesOffMarker = "IgnoreFailingMessages:false";
+
+        internal static List<T> ExcludeExpectedNoise<T>(IEnumerable<T> entries, Func<T, string> message)
+        {
+            var result = new List<T>();
+            var ignoring = false;
+            foreach (var entry in entries)
+            {
+                var text = (message(entry) ?? string.Empty).Trim();
+                if (text == IgnoreFailingMessagesOnMarker)
+                {
+                    ignoring = true;
+                    continue;
+                }
+                if (text == IgnoreFailingMessagesOffMarker)
+                {
+                    ignoring = false;
+                    continue;
+                }
+                if (!ignoring)
+                    result.Add(entry);
+            }
+            return result;
+        }
+
         private static object HandleTail(string paramsJson)
         {
             var query = ParseQuery(paramsJson, includePattern: false);

package/bridge/com.ucp.bridge/Editor/Controllers/MaterialController.cs

@@ -227,7 +227,7 @@ namespace UCP.Bridge
             // Resolve by instanceId (scene object's renderer material)
             if (p.TryGetValue("instanceId", out var idObj))
             {
-                int instanceId = Convert.ToInt32(idObj);
+                long instanceId = Convert.ToInt64(idObj);
                 var obj = UnityObjectCompat.ResolveByInstanceId(instanceId);
 
                 if (obj is Material directMat)
@@ -330,7 +330,7 @@ namespace UCP.Bridge
                         }
                         else if (texDict.TryGetValue("instanceId", out var tid))
                         {
-                            var tex = UnityObjectCompat.ResolveByInstanceId<Texture>(Convert.ToInt32(tid));
+                            var tex = UnityObjectCompat.ResolveByInstanceId<Texture>(Convert.ToInt64(tid));
                             mat.SetTexture(propName, tex);
                         }
                     }

package/bridge/com.ucp.bridge/Editor/Controllers/ObjectLocator.cs

@@ -9,7 +9,7 @@ namespace UCP.Bridge
     /// Shared GameObject resolution for the spatial/visual controllers.
     ///
     /// A target may be addressed three ways, tried in priority order:
-    ///   1. instanceId (int)   — canonical, survives nothing but a domain reload; preferred.
+    ///   1. instanceId (64-bit integer)   — canonical, survives nothing but a domain reload; preferred.
     ///   2. path (string)      — hierarchy path "Root/Child/Leaf" (leading '/' optional),
     ///                           resolved across all loaded scenes; survives reloads.
     ///   3. name (string)      — first GameObject whose name matches; ambiguous under
@@ -32,7 +32,7 @@ namespace UCP.Bridge
 
             if ((p.TryGetValue("instanceId", out var idObj) || p.TryGetValue("id", out idObj)) && idObj != null)
             {
-                var id = Convert.ToInt32(idObj);
+                var id = Convert.ToInt64(idObj);
                 var byId = FindByInstanceId(id);
                 if (byId != null)
                     return byId;
@@ -60,7 +60,7 @@ namespace UCP.Bridge
             throw new ArgumentException("Missing target: provide 'instanceId', 'path', or 'name'");
         }
 
-        internal static GameObject FindByInstanceId(int instanceId)
+        internal static GameObject FindByInstanceId(long instanceId)
         {
             var direct = UnityObjectCompat.ResolveByInstanceId<GameObject>(instanceId);
             if (direct != null)
@@ -82,7 +82,7 @@ namespace UCP.Bridge
             return null;
         }
 
-        private static GameObject FindInHierarchyById(GameObject go, int instanceId)
+        private static GameObject FindInHierarchyById(GameObject go, long instanceId)
         {
             if (go.GetId() == instanceId)
                 return go;