feat(plugins): add noctalia.appIconPath icon resolution binding (#3356)

* feat(plugins): add noctalia.appIconPath icon resolution binding

Resolves an app id (or raw icon name) to an icon file path using the
same components the native taskbar uses: the shared desktop-entry
index via app_identity::findDesktopEntry, then IconResolver with the
caller's target size. The desktop-entry cache gains a mutex-guarded
non-refreshing snapshot accessor so script worker threads read it
race-free; the resolver instance is thread_local.

Assisted with AI tooling.

* fix(plugins): make appIconPath icon-theme state thread-safe and snapshots copy-free

---------

Co-authored-by: Lemmy <studio@quadbyte.net>

Author: gegnep

src/scripting/luau_host.cpp

@@ -13,6 +13,9 @@
 #include "scripting/plugin_bindings.h"
 #include "scripting/plugin_state_store.h"
 #include "scripting/script_api_context.h"
+#include "system/app_identity.h"
+#include "system/desktop_entry.h"
+#include "system/icon_resolver.h"
 #include "system/terminal_launch.h"
 #include "time/time_format.h"
 #include "util/file_utils.h"
@@ -321,6 +324,37 @@ namespace {
     return 1;
   }
 
+  // appIconPath(appIdOrIconName, sizePx?) -> absolute icon file path or nil.
+  // Same resolution the native taskbar uses: desktop-entry lookup (id /
+  // StartupWMClass) for the icon name, then the XDG icon-theme resolver.
+  // Unmatched inputs are treated as raw icon names so plugins can also
+  // resolve themed icons directly.
+  int luau_appIconPath(lua_State* L) {
+    size_t len = 0;
+    const char* appId = luaL_checklstring(L, 1, &len);
+    const int targetSize = luaL_optinteger(L, 2, 0);
+
+    std::string iconName;
+    const auto entries = desktopEntriesSnapshot();
+    if (const auto entry = app_identity::findDesktopEntry(std::string_view(appId, len), *entries);
+        entry.has_value() && !entry->icon.empty()) {
+      iconName = entry->icon;
+    } else {
+      iconName.assign(appId, len);
+    }
+
+    // One resolver (and icon-path cache) per script worker thread; the theme
+    // plan it reads is shared across threads and mutex-guarded in IconResolver.
+    static thread_local IconResolver resolver;
+    const std::string& path = resolver.resolve(iconName, targetSize);
+    if (path.empty()) {
+      lua_pushnil(L);
+      return 1;
+    }
+    lua_pushlstring(L, path.data(), path.size());
+    return 1;
+  }
+
   int luau_setWallpaperEnabled(lua_State* L) {
     size_t len = 0;
     const char* connector = luaL_checklstring(L, 1, &len);
@@ -1137,6 +1171,7 @@ namespace {
       {"portalAvailable", luau_portalAvailable},
       {"focusedOutputName", luau_focusedOutputName},
       {"outputs", luau_outputs},
+      {"appIconPath", luau_appIconPath},
       {"setWallpaperEnabled", luau_setWallpaperEnabled},
       {"setWallpaper", luau_setWallpaper},
       {"togglePanel", luau_togglePanel},

src/system/desktop_entry.cpp

@@ -7,6 +7,8 @@
 #include <cstdlib>
 #include <filesystem>
 #include <fstream>
+#include <memory>
+#include <mutex>
 #include <ranges>
 #include <string_view>
 #include <sys/inotify.h>
@@ -389,6 +391,14 @@ namespace {
 
     const std::vector<DesktopEntry>& entries() {
       refreshIfNeeded();
+      return *m_entries;
+    }
+
+    // Worker-thread-safe shared snapshot. Deliberately non-refreshing:
+    // freshness stays driven by the main thread's poll/reload path; this only
+    // synchronizes against the reload swap.
+    std::shared_ptr<const std::vector<DesktopEntry>> entriesSnapshot() const {
+      std::scoped_lock lock(m_entriesMutex);
       return m_entries;
     }
 
@@ -448,7 +458,11 @@ namespace {
         return;
       }
 
-      m_entries = scanDesktopEntries();
+      auto scanned = std::make_shared<const std::vector<DesktopEntry>>(scanDesktopEntries());
+      {
+        std::scoped_lock lock(m_entriesMutex);
+        m_entries = std::move(scanned);
+      }
       rebuildWatches();
       m_sourceSignature = computeSourceSignature();
       m_dirty = false;
@@ -554,7 +568,8 @@ namespace {
       m_watches[wd] = key;
     }
 
-    std::vector<DesktopEntry> m_entries;
+    std::shared_ptr<const std::vector<DesktopEntry>> m_entries = std::make_shared<std::vector<DesktopEntry>>();
+    mutable std::mutex m_entriesMutex; // guards the m_entries swap against entriesSnapshot() readers
     std::uint64_t m_version = 0;
     int m_inotifyFd = -1;
     bool m_dirty = true;
@@ -610,6 +625,8 @@ std::vector<DesktopEntry> scanDesktopEntries() {
 
 const std::vector<DesktopEntry>& desktopEntries() { return cache().entries(); }
 
+std::shared_ptr<const std::vector<DesktopEntry>> desktopEntriesSnapshot() { return cache().entriesSnapshot(); }
+
 std::uint64_t desktopEntriesVersion() { return cache().version(); }
 
 int desktopEntryWatchFd() noexcept { return cache().watchFd(); }

src/system/desktop_entry.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <cstdint>
+#include <memory>
 #include <string>
 #include <vector>
 
@@ -42,6 +43,12 @@ struct DesktopEntry {
 std::vector<DesktopEntry> scanDesktopEntries();
 
 const std::vector<DesktopEntry>& desktopEntries();
+
+// Shared snapshot of the current entry list, safe to call from non-main
+// threads (e.g. plugin script workers). Does not trigger a refresh —
+// freshness is owned by the main thread's reload path.
+std::shared_ptr<const std::vector<DesktopEntry>> desktopEntriesSnapshot();
+
 std::uint64_t desktopEntriesVersion();
 int desktopEntryWatchFd() noexcept;
 void checkDesktopEntryReload();

src/system/desktop_entry_poll_source.h

@@ -5,9 +5,15 @@
 
 class DesktopEntryPollSource final : public PollSource {
 public:
+  // Prime the cache on the main thread and refresh it eagerly on change, so
+  // worker-thread desktopEntriesSnapshot() readers see a populated, current
+  // list even when no main-thread widget consumes desktopEntries().
+  DesktopEntryPollSource() { desktopEntries(); }
+
   void dispatch(const std::vector<pollfd>& fds, std::size_t startIdx) override {
     if (desktopEntryWatchFd() >= 0 && (fds[startIdx].revents & POLLIN) != 0) {
       checkDesktopEntryReload();
+      desktopEntries();
     }
   }
 

src/system/icon_resolver.cpp

@@ -8,6 +8,7 @@
 #include <fstream>
 #include <gio/gio.h>
 #include <memory>
+#include <mutex>
 #include <optional>
 #include <set>
 #include <string_view>
@@ -50,7 +51,10 @@ namespace {
     return size;
   }
 
+  // Shared across all IconResolver instances, including thread_local ones on
+  // script worker threads; every access goes through `mutex`.
   struct IconThemeState {
+    std::mutex mutex;
     bool initialized = false;
     std::uint64_t generation = 1;
     IconThemePlan plan;
@@ -409,8 +413,8 @@ namespace {
     return plan;
   }
 
-  void ensureThemeState() {
-    auto& state = iconThemeState();
+  // Requires state.mutex to be held.
+  void ensureThemeStateLocked(IconThemeState& state) {
     if (!state.initialized) {
       state.plan = buildThemePlan();
       state.initialized = true;
@@ -423,6 +427,7 @@ IconResolver::IconResolver() { rebuild(); }
 
 bool IconResolver::checkThemeChanged() {
   auto& state = iconThemeState();
+  std::scoped_lock lock(state.mutex);
   IconThemePlan next = buildThemePlan();
   if (!state.initialized) {
     state.plan = std::move(next);
@@ -439,13 +444,16 @@ bool IconResolver::checkThemeChanged() {
 }
 
 std::uint64_t IconResolver::themeGeneration() {
-  ensureThemeState();
-  return iconThemeState().generation;
+  auto& state = iconThemeState();
+  std::scoped_lock lock(state.mutex);
+  ensureThemeStateLocked(state);
+  return state.generation;
 }
 
 void IconResolver::rebuild() {
-  ensureThemeState();
-  const auto& state = iconThemeState();
+  auto& state = iconThemeState();
+  std::scoped_lock lock(state.mutex);
+  ensureThemeStateLocked(state);
   m_baseDirs = state.plan.baseDirs;
   m_searchDirs = state.plan.searchDirs;
   m_pixmapDirs = state.plan.pixmapDirs;