feat(Android): VMI name (#13079) 2a59ec434e
Adds ability to query VMI and VM names.

Includes a new path through the command queue, server, and listeners. Exposed as a suspend function. Includes tests.

Co-authored-by: Erik <erik@rive.app>
Co-authored-by: Miklós Fazekas <mfazekas@szemafor.com>
diff --git a/.rive_head b/.rive_head
index a5f7371..f9a417d 100644
--- a/.rive_head
+++ b/.rive_head
@@ -1 +1 @@
-f564fe7c6101755e6147c1abb672dad51425b304
+2a59ec434e43c9a308c5a99f28ae9008f67ffe52
diff --git a/include/rive/command_queue.hpp b/include/rive/command_queue.hpp
index ebd3d09..6441118 100644
--- a/include/rive/command_queue.hpp
+++ b/include/rive/command_queue.hpp
@@ -310,14 +310,20 @@
                                             ViewModelInstanceHandle>
     {
     public:
+        virtual void onViewModelInstanceError(const ViewModelInstanceHandle,
+                                              uint64_t requestId,
+                                              std::string error)
+        {}
+
         virtual void onViewModelInstanceViewModelNameReceived(
             const ViewModelInstanceHandle,
             uint64_t requestId,
             std::string viewModelName)
         {}
-        virtual void onViewModelInstanceError(const ViewModelInstanceHandle,
-                                              uint64_t requestId,
-                                              std::string error)
+        virtual void onViewModelInstanceNameReceived(
+            const ViewModelInstanceHandle handle,
+            uint64_t requestId,
+            std::string instanceName)
         {}
 
         virtual void onViewModelDeleted(const ViewModelInstanceHandle,
@@ -721,8 +727,16 @@
     // Create unique draw key for draw.
     DrawKey createDrawKey();
 
-    // Executes a one-time callback on the server. This may eventualy become a
-    // testing-only method.
+    /**
+     * Executes a one-time callback directly on the command server.
+     *
+     * This is an escape hatch for tests and runtime-specific operations that
+     * cannot be represented by the shared command and message protocol. Do not
+     * use it to implement capabilities common to multiple runtimes; add a
+     * canonical command, message, and listener callback instead.
+     *
+     * @param callback The callback to execute on the command server.
+     */
     void runOnce(CommandServerCallback);
 
     // Run draw function for given draw key, only the latest function passed
@@ -751,8 +765,6 @@
     void requestGlobalViewModelNames(FileHandle, uint64_t requestId = 0);
     void requestArtboardNames(FileHandle, uint64_t requestId = 0);
     void requestFileAssets(FileHandle, uint64_t requestId = 0);
-    void requestViewModelInstanceViewModelName(ViewModelInstanceHandle,
-                                               uint64_t requestId = 0);
     void requestViewModelEnums(FileHandle, uint64_t requestId = 0);
     void requestViewModelPropertyDefinitions(FileHandle,
                                              std::string viewModelName,
@@ -762,6 +774,12 @@
                                        std::string viewModelName,
                                        uint64_t requestId = 0);
 
+    void requestViewModelInstanceViewModelName(ViewModelInstanceHandle,
+                                               uint64_t requestId = 0);
+
+    void requestViewModelInstanceName(ViewModelInstanceHandle handle,
+                                      uint64_t requestId = 0);
+
     void requestViewModelInstanceBool(ViewModelInstanceHandle,
                                       std::string path,
                                       uint64_t requestId = 0);
@@ -1003,6 +1021,7 @@
         listViewModelProperties,
         listViewModelPropertyValue,
         getViewModelInstanceViewModelName,
+        getViewModelInstanceName,
         getViewModelListSize,
         clearViewModelList,
         listFileAssets,
@@ -1020,6 +1039,7 @@
         stateMachinesListed,
         defaultViewModelReceived,
         viewModelInstanceViewModelNameReceived,
+        viewModelInstanceNameReceived,
         viewModelsListend,
         globalViewModelNamesListed,
         viewModelInstanceNamesListed,
diff --git a/src/command_queue.cpp b/src/command_queue.cpp
index 9560e62..32cfade 100644
--- a/src/command_queue.cpp
+++ b/src/command_queue.cpp
@@ -1063,15 +1063,6 @@
     m_commandStream << requestId;
 }
 
-void CommandQueue::requestViewModelInstanceViewModelName(
-    ViewModelInstanceHandle viewModelInstanceHandle,
-    uint64_t requestId)
-{
-    AutoLockAndNotify lock(m_commandMutex, m_commandConditionVariable);
-    m_commandStream << Command::getViewModelInstanceViewModelName;
-    m_commandStream << viewModelInstanceHandle;
-    m_commandStream << requestId;
-}
 void CommandQueue::requestViewModelEnums(FileHandle fileHandle,
                                          uint64_t requestId)
 {
@@ -1104,6 +1095,26 @@
     m_names << viewModelName;
 }
 
+void CommandQueue::requestViewModelInstanceViewModelName(
+    ViewModelInstanceHandle viewModelInstanceHandle,
+    uint64_t requestId)
+{
+    AutoLockAndNotify lock(m_commandMutex, m_commandConditionVariable);
+    m_commandStream << Command::getViewModelInstanceViewModelName;
+    m_commandStream << viewModelInstanceHandle;
+    m_commandStream << requestId;
+}
+
+void CommandQueue::requestViewModelInstanceName(
+    ViewModelInstanceHandle viewModelInstanceHandle,
+    uint64_t requestId)
+{
+    AutoLockAndNotify lock(m_commandMutex, m_commandConditionVariable);
+    m_commandStream << Command::getViewModelInstanceName;
+    m_commandStream << viewModelInstanceHandle;
+    m_commandStream << requestId;
+}
+
 void CommandQueue::requestViewModelInstanceBool(ViewModelInstanceHandle handle,
                                                 std::string path,
                                                 uint64_t requestId)
@@ -1469,6 +1480,33 @@
                 }
                 break;
             }
+            case Message::viewModelInstanceNameReceived:
+            {
+                ViewModelInstanceHandle handle;
+                uint64_t requestId;
+                std::string instanceName;
+                m_messageStream >> handle;
+                m_messageStream >> requestId;
+                m_messageNames >> instanceName;
+
+                lock.unlock();
+                if (m_globalViewModelListener)
+                {
+                    m_globalViewModelListener->onViewModelInstanceNameReceived(
+                        handle,
+                        requestId,
+                        instanceName);
+                }
+                auto itr = m_viewModelListeners.find(handle);
+                if (itr != m_viewModelListeners.end())
+                {
+                    itr->second->onViewModelInstanceNameReceived(
+                        handle,
+                        requestId,
+                        std::move(instanceName));
+                }
+                break;
+            }
             case Message::viewModelsListend:
             {
                 size_t numViewModels;
diff --git a/src/command_server.cpp b/src/command_server.cpp
index bd1ba3c..4144658 100644
--- a/src/command_server.cpp
+++ b/src/command_server.cpp
@@ -2484,6 +2484,36 @@
                 break;
             }
 
+            case CommandQueue::Command::getViewModelInstanceName:
+            {
+                ViewModelInstanceHandle handle;
+                uint64_t requestId;
+                commandStream >> handle;
+                commandStream >> requestId;
+                lock.unlock();
+                auto viewModelInstance = getViewModelInstance(handle);
+                if (viewModelInstance)
+                {
+                    std::unique_lock<std::mutex> messageLock(
+                        m_commandQueue->m_messageMutex);
+                    messageStream
+                        << CommandQueue::Message::viewModelInstanceNameReceived;
+                    messageStream << handle;
+                    messageStream << requestId;
+                    m_commandQueue->m_messageNames << viewModelInstance->name();
+                }
+                else
+                {
+                    ErrorReporter<ViewModelInstanceHandle>(
+                        this,
+                        handle,
+                        requestId,
+                        CommandQueue::Message::viewModelError)
+                        << "Invalid view model instance handle " << handle;
+                }
+                break;
+            }
+
             case CommandQueue::Command::listViewModelEnums:
             {
                 FileHandle handle;
diff --git a/tests/unit_tests/runtime/command_queue_test.cpp b/tests/unit_tests/runtime/command_queue_test.cpp
index 9599df8..fd31dd3 100644
--- a/tests/unit_tests/runtime/command_queue_test.cpp
+++ b/tests/unit_tests/runtime/command_queue_test.cpp
@@ -3182,23 +3182,44 @@
         m_hasCallback = true;
     }
 
+    virtual void onViewModelInstanceNameReceived(
+        const ViewModelInstanceHandle handle,
+        uint64_t requestId,
+        std::string instanceName) override
+    {
+        CHECK(requestId == m_requestId);
+        CHECK(handle == m_handle);
+        CHECK(instanceName == m_expectedInstanceName);
+        m_hasInstanceNameCallback = true;
+    }
+
     virtual void onViewModelInstanceError(const ViewModelInstanceHandle handle,
                                           uint64_t requestId,
                                           std::string error) override
     {
         CHECK(handle == m_handle);
         CHECK(error.size());
+        if (requestId == m_instanceNameErrorRequestId)
+        {
+            m_hasInstanceNameError = true;
+        }
         ++m_receivedErrors;
     }
 
     uint64_t m_requestId = 0;
     ViewModelInstanceHandle m_handle;
     std::string m_expectedViewModelName;
+    std::string m_expectedInstanceName;
     bool m_hasCallback = false;
+    bool m_hasInstanceNameCallback = false;
+    uint64_t m_instanceNameErrorRequestId = 0;
+    bool m_hasInstanceNameError = false;
     int m_receivedErrors = 0;
 };
 
-TEST_CASE("requestViewModelInstanceViewModelName", "[CommandQueue]")
+TEST_CASE("requestViewModelInstanceViewModelName and "
+          "requestViewModelInstanceName",
+          "[CommandQueue]")
 {
     auto commandQueue = make_rcp<CommandQueue>();
     std::thread serverThread(server_thread, commandQueue);
@@ -3219,15 +3240,19 @@
 
     vmListener.m_handle = vmHandle;
     vmListener.m_expectedViewModelName = "Test All";
+    vmListener.m_expectedInstanceName = "Test Default";
     vmListener.m_requestId = 0x50;
 
     commandQueue->requestViewModelInstanceViewModelName(vmHandle,
                                                         vmListener.m_requestId);
+    commandQueue->requestViewModelInstanceName(vmHandle,
+                                               vmListener.m_requestId);
 
     wait_for_server(commandQueue.get());
     commandQueue->processMessages();
 
     CHECK(vmListener.m_hasCallback);
+    CHECK(vmListener.m_hasInstanceNameCallback);
 
     // A handle that resolves to a null instance on the server (invalid view
     // model name) should not trigger the success callback but should produce
@@ -3239,14 +3264,20 @@
                                                         "Blah",
                                                         &badListener);
     badListener.m_handle = badHandle;
+    badListener.m_instanceNameErrorRequestId = 0x52;
 
-    commandQueue->requestViewModelInstanceViewModelName(badHandle);
+    commandQueue->requestViewModelInstanceViewModelName(badHandle, 0x51);
+    commandQueue->requestViewModelInstanceName(
+        badHandle,
+        badListener.m_instanceNameErrorRequestId);
 
     wait_for_server(commandQueue.get());
 
     commandQueue->processMessages();
 
     CHECK(!badListener.m_hasCallback);
+    CHECK(!badListener.m_hasInstanceNameCallback);
+    CHECK(badListener.m_hasInstanceNameError);
     CHECK(badListener.m_receivedErrors >= 1);
 
     commandQueue->disconnect();
@@ -5084,9 +5115,16 @@
                                    std::string,
                                    viewModelName);
 
+    DEFINE_TEST_CALLBACK_ONE_PARAM(onViewModelInstanceNameReceived,
+                                   ViewModelInstanceHandle,
+                                   19,
+                                   std::string,
+                                   instanceName);
+
     size_t m_size = 2;
     std::string m_path = "Test List";
     std::string m_viewModelName = "Test All";
+    std::string m_instanceName = "Test Default";
     ViewModelInstanceHandle m_handle;
     CommandQueue::ViewModelInstanceData m_instanceData = {
         .metaData = PropertyData{DataType::boolean, "Test Bool"},
@@ -5178,6 +5216,7 @@
     commandQueue->requestViewModelInstanceBool(viewModel, "Test Bool", 13);
     commandQueue->requestViewModelInstanceListSize(viewModel, "Test List", 14);
     commandQueue->requestViewModelInstanceViewModelName(viewModel, 18);
+    commandQueue->requestViewModelInstanceName(viewModel, 19);
     commandQueue->advanceStateMachine(stateMachineHandle, 1, 16);
     commandQueue->advanceStateMachine(stateMachineHandle, 1, 16);
     commandQueue->advanceStateMachine(stateMachineHandle, 1, 16);
@@ -5202,6 +5241,8 @@
                    onViewModelListSizeReceived);
     CHECK_CALLBACK(globalViewModelInstanceListener,
                    onViewModelInstanceViewModelNameReceived);
+    CHECK_CALLBACK(globalViewModelInstanceListener,
+                   onViewModelInstanceNameReceived);
 
     CHECK_CALLBACK(globalArtboardListener, onArtboardDeleted);
     CHECK_CALLBACK(globalArtboardListener, onStateMachineInstantiated);