fix(scripting): serialize empty snapshot fields as nil

CHANGELOG.md

@@ -20,6 +20,7 @@
 
 ### Fixed
 
+- **Empty Lua plugin fields are `nil`**: missing values in playback, track, device and other snapshots now match the documented `nil` behavior, so guards such as `if track.release_date then` correctly skip absent values. JSON decoding and plugin storage keep their existing null sentinel ([#736](https://github.com/LargeModGames/spotatui/issues/736)).
 - **Clicking a row in a scrolled Settings list selects that row**: once the Behavior or Keybindings list had scrolled, a click counted rows from the top of the box without the scroll offset, so it selected a row scrolled out of view and the list jumped back to the top; a second click then edited that row. The click now adds the offset the list was drawn with, the way the other lists already do ([#661](https://github.com/LargeModGames/spotatui/issues/661)).
 
 - **Focus keys follow the sidebar position**: with `sidebar_position: right`, the right key still moved focus into the content and the left key did nothing, because the keys assumed a sidebar on the left even though it was drawn on the right. Left and right now move towards and away from the sidebar as it appears on screen. Going back to the sidebar also returns to the panel you left (Library or Playlists) instead of always Library ([#738](https://github.com/LargeModGames/spotatui/issues/738)).

src/infra/scripting/api.rs

@@ -9,6 +9,7 @@ use crate::core::plugin_api::{self, PluginPopup, PopupLine};
 use crate::core::theme::ThemeField;
 use crate::core::user_config::parse_theme_item;
 
+use super::engine::snapshot_to_lua;
 use super::events::VALID_EVENT_NAMES;
 use super::shared::{
   DataRequest, HttpResponseData, HttpResult, NewTimer, ScriptShared, COMMANDS_KEY,
@@ -82,7 +83,7 @@ pub(super) fn install_api(
     let playback = lua.create_function(move |lua, ()| {
       let pb = shared_pb.playback.borrow().clone();
       match pb {
-        Some(state) => lua.to_value(&state),
+        Some(state) => snapshot_to_lua(lua, &state),
         None => Ok(Value::Nil),
       }
     })?;
@@ -92,7 +93,7 @@ pub(super) fn install_api(
     let current_track = lua.create_function(move |lua, ()| {
       let pb = shared_ct.playback.borrow().clone();
       match pb.and_then(|s| s.track) {
-        Some(track) => lua.to_value(&track),
+        Some(track) => snapshot_to_lua(lua, &track),
         None => Ok(Value::Nil),
       }
     })?;
@@ -101,7 +102,7 @@ pub(super) fn install_api(
     let shared_dev = shared.clone();
     let devices = lua.create_function(move |lua, ()| {
       let devices = shared_dev.devices.borrow().clone();
-      lua.to_value(&devices)
+      snapshot_to_lua(lua, &devices)
     })?;
     tbl.set("devices", devices)?;
   }
@@ -385,18 +386,19 @@ pub(super) fn install_api(
   // generation advances.
   {
     let shared_pl = shared.clone();
-    let playlists =
-      lua.create_function(move |lua, ()| lua.to_value(&*shared_pl.playlists_cache.borrow()))?;
+    let playlists = lua
+      .create_function(move |lua, ()| snapshot_to_lua(lua, &*shared_pl.playlists_cache.borrow()))?;
     tbl.set("playlists", playlists)?;
 
     let shared_q = shared.clone();
     let queue =
-      lua.create_function(move |lua, ()| lua.to_value(&*shared_q.queue_cache.borrow()))?;
+      lua.create_function(move |lua, ()| snapshot_to_lua(lua, &*shared_q.queue_cache.borrow()))?;
     tbl.set("queue", queue)?;
 
     let shared_sr = shared.clone();
-    let search_results = lua
-      .create_function(move |lua, ()| lua.to_value(&*shared_sr.search_results_cache.borrow()))?;
+    let search_results = lua.create_function(move |lua, ()| {
+      snapshot_to_lua(lua, &*shared_sr.search_results_cache.borrow())
+    })?;
     tbl.set("search_results", search_results)?;
   }
 
@@ -583,7 +585,7 @@ pub(super) fn install_api(
   {
     let shared = shared.clone();
     let config =
-      lua.create_function(move |lua, ()| lua.to_value(&*shared.config_cache.borrow()))?;
+      lua.create_function(move |lua, ()| snapshot_to_lua(lua, &*shared.config_cache.borrow()))?;
     tbl.set("config", config)?;
   }
 

src/infra/scripting/engine.rs

@@ -477,7 +477,7 @@ impl ScriptEngine {
   fn playback_value(&self) -> Value {
     let pb = self.shared.playback.borrow().clone();
     match pb {
-      Some(state) => self.lua.to_value(&state).unwrap_or(Value::Nil),
+      Some(state) => snapshot_to_lua(&self.lua, &state).unwrap_or(Value::Nil),
       None => Value::Nil,
     }
   }
@@ -1055,18 +1055,28 @@ fn discover_user_scripts(config_dir: &Path) -> Vec<(PathBuf, Option<PathBuf>)> {
   discovered
 }
 
+/// Serialize a plugin snapshot with `None` as Lua `nil`, as the docs promise.
+pub(super) fn snapshot_to_lua<T: serde::Serialize>(lua: &Lua, value: &T) -> mlua::Result<Value> {
+  lua.to_value_with(
+    value,
+    mlua::serde::SerializeOptions::new().serialize_none_to_null(false),
+  )
+}
+
 /// Serialize the plugin-facing snapshot for a data kind from `App` state.
 fn data_value_for(lua: &Lua, kind: PluginDataKind, app: &App) -> mlua::Result<Value> {
   match kind {
-    PluginDataKind::Playlists => lua.to_value(&plugin_api::playlists_snapshot(app)),
-    PluginDataKind::Queue => lua.to_value(&plugin_api::queue_snapshot(app)),
-    PluginDataKind::Search => lua.to_value(&plugin_api::search_results_snapshot(app)),
-    PluginDataKind::SavedTracks => lua.to_value(&plugin_api::saved_tracks_snapshot(app)),
-    PluginDataKind::SavedAlbums => lua.to_value(&plugin_api::saved_albums_snapshot(app)),
-    PluginDataKind::SavedShows => lua.to_value(&plugin_api::saved_shows_snapshot(app)),
-    PluginDataKind::RecentlyPlayed => lua.to_value(&plugin_api::recently_played_snapshot(app)),
-    PluginDataKind::Devices => lua.to_value(&plugin_api::device_list(app)),
-    PluginDataKind::Lyrics => lua.to_value(&plugin_api::lyrics_snapshot(app)),
+    PluginDataKind::Playlists => snapshot_to_lua(lua, &plugin_api::playlists_snapshot(app)),
+    PluginDataKind::Queue => snapshot_to_lua(lua, &plugin_api::queue_snapshot(app)),
+    PluginDataKind::Search => snapshot_to_lua(lua, &plugin_api::search_results_snapshot(app)),
+    PluginDataKind::SavedTracks => snapshot_to_lua(lua, &plugin_api::saved_tracks_snapshot(app)),
+    PluginDataKind::SavedAlbums => snapshot_to_lua(lua, &plugin_api::saved_albums_snapshot(app)),
+    PluginDataKind::SavedShows => snapshot_to_lua(lua, &plugin_api::saved_shows_snapshot(app)),
+    PluginDataKind::RecentlyPlayed => {
+      snapshot_to_lua(lua, &plugin_api::recently_played_snapshot(app))
+    }
+    PluginDataKind::Devices => snapshot_to_lua(lua, &plugin_api::device_list(app)),
+    PluginDataKind::Lyrics => snapshot_to_lua(lua, &plugin_api::lyrics_snapshot(app)),
   }
 }
 

src/infra/scripting/tests.rs

@@ -80,6 +80,50 @@ fn track_change_handler_queues_notify() {
   }
 }
 
+#[test]
+fn empty_playback_fields_reach_lua_as_nil() {
+  let mut engine = ScriptEngine::new().unwrap();
+  *engine.shared.playback.borrow_mut() = Some(playback(Some(track("uri:1", "Song A")), true, 0));
+  engine
+    .load_source(
+      "test",
+      r#"
+        local pb = spotatui.playback()
+        local t = spotatui.current_track()
+        spotatui.notify(tostring(pb.device == nil) .. ":" .. tostring(pb.track.release_date == nil) .. ":" .. tostring(t.id == nil), 1)
+      "#,
+    )
+    .unwrap();
+
+  match one(&engine) {
+    Action::Notify(msg, 1) => assert_eq!(msg, "true:true:true"),
+    other => panic!("unexpected effect: {:?}", std::mem::discriminant(&other)),
+  }
+}
+
+#[test]
+fn empty_fields_in_an_event_playback_reach_lua_as_nil() {
+  let mut engine = ScriptEngine::new().unwrap();
+  engine
+    .load_source(
+      "test",
+      r#"
+        spotatui.on("track_change", function(pb)
+          spotatui.notify(tostring(pb.device == nil), 1)
+        end)
+      "#,
+    )
+    .unwrap();
+
+  *engine.shared.playback.borrow_mut() = Some(playback(Some(track("uri:1", "Song A")), true, 0));
+  engine.emit(ScriptEvent::TrackChange);
+
+  match one(&engine) {
+    Action::Notify(msg, 1) => assert_eq!(msg, "true"),
+    other => panic!("unexpected effect: {:?}", std::mem::discriminant(&other)),
+  }
+}
+
 #[test]
 fn erroring_handler_is_disabled_after_one_strike() {
   let mut engine = ScriptEngine::new().unwrap();