user_settings.cc

Go to the documentation of this file.

#include "app/editor/system/session/user_settings.h"
 
#include <algorithm>
#include <array>
#include <cmath>
#include <filesystem>
#include <fstream>
#include <sstream>
#include <string_view>
#include <system_error>
 
#include "absl/strings/str_format.h"
#include "app/editor/layout/layout_designer/dock_tree.h"
#include "app/editor/layout/layout_designer/dock_tree_json.h"
#include "app/editor/system/workspace/panel_visibility.h"
#include "app/gui/core/style.h"
#include "imgui/imgui.h"
#include "util/file_util.h"
#include "util/log.h"
#include "util/platform_paths.h"
 
#ifdef YAZE_WITH_JSON
#include "nlohmann/json.hpp"
#endif
 
namespace yaze {
namespace editor {
 
#ifdef YAZE_WITH_JSON
using json = nlohmann::json;
#endif
 
namespace {
 
// Matches the Settings slider and View > Zoom range. A scale of 0 or NaN from a
// hand-edited or truncated file makes every widget too small to use.
constexpr float kMinFontGlobalScale = 0.5f;
constexpr float kMaxFontGlobalScale = 2.0f;
 
float SanitizeFontGlobalScale(float scale) {
  if (!std::isfinite(scale)) {
    return 1.0f;
  }
  return std::clamp(scale, kMinFontGlobalScale, kMaxFontGlobalScale);
}
 
absl::Status EnsureParentDirectory(const std::filesystem::path& path) {
  auto parent = path.parent_path();
  if (parent.empty()) {
    return absl::OkStatus();
  }
  return util::PlatformPaths::EnsureDirectoryExists(parent);
}
 
UserSettings::WorkspaceOverrides CaptureWorkspaceFields(
    const UserSettings::Preferences& prefs) {
  UserSettings::WorkspaceOverrides values;
  values.font_global_scale = prefs.font_global_scale;
  values.autosave_enabled = prefs.autosave_enabled;
  values.autosave_interval = prefs.autosave_interval;
  values.backup_before_save = prefs.backup_before_save;
  return values;
}
 
void WriteWorkspaceFields(const UserSettings::WorkspaceOverrides& values,
                          UserSettings::Preferences* prefs) {
  prefs->font_global_scale = values.font_global_scale;
  prefs->autosave_enabled = values.autosave_enabled;
  prefs->autosave_interval = values.autosave_interval;
  prefs->backup_before_save = values.backup_before_save;
}
 
void EraseTransientPanelVisibility(
    std::unordered_map<std::string, bool>* panel_state) {
  if (!panel_state) {
    return;
  }
  for (auto it = panel_state->begin(); it != panel_state->end();) {
    if (IsTransientPanelVisibilityId(it->first)) {
      it = panel_state->erase(it);
    } else {
      ++it;
    }
  }
}
 
bool IsEmbeddedDungeonUtilityPanelId(const std::string& panel_id) {
  return panel_id == "dungeon.object_editor" ||
         panel_id == "dungeon.settings" || panel_id == "dungeon.dungeon_map";
}
 
void EraseEmbeddedDungeonUtilityPanelVisibility(
    std::unordered_map<std::string, bool>* panel_state) {
  if (!panel_state) {
    return;
  }
  for (auto it = panel_state->begin(); it != panel_state->end();) {
    if (IsEmbeddedDungeonUtilityPanelId(it->first)) {
      it = panel_state->erase(it);
    } else {
      ++it;
    }
  }
}
 
constexpr std::array<const char*, 10> kDungeonWorkbenchDuplicatePanels = {
    "dungeon.room_selector",   "dungeon.room_matrix",
    "dungeon.object_selector", "dungeon.sprite_editor",
    "dungeon.item_editor",     "dungeon.room_graphics",
    "dungeon.door_editor",     "dungeon.palette_editor",
    "dungeon.entrance_list",   "dungeon.entrance_properties",
};
 
constexpr std::array<const char*, 7> kDungeonDemotedUtilityPanels = {
    "dungeon.custom_collision",   "dungeon.water_fill",
    "dungeon.room_tags",          "dungeon.object_coverage",
    "dungeon.object_tile_editor", "dungeon.overlay_manager",
    "dungeon.minecart_tracks",
};
 
void ApplyDungeonWorkbenchVisibilityDefaults(
    std::unordered_map<std::string, bool>* panel_state) {
  if (!panel_state) {
    return;
  }
  (*panel_state)["dungeon.workbench"] = true;
  for (const char* panel_id : kDungeonWorkbenchDuplicatePanels) {
    (*panel_state)[panel_id] = false;
  }
}
 
void ApplyDungeonPanelAdmissionDefaults(
    std::unordered_map<std::string, bool>* panel_state) {
  ApplyDungeonWorkbenchVisibilityDefaults(panel_state);
  if (!panel_state) {
    return;
  }
  for (const char* panel_id : kDungeonDemotedUtilityPanels) {
    (*panel_state)[panel_id] = false;
  }
}
 
// Windows the panel admission policy moved out of the window browser
// (Diagnostic or EmbeddedTool). Each is still openable from its declared host
// and the command palette. Revision 26 closes their persisted live visibility
// so they stop reopening from an old session; pins, saved layouts, and named
// layouts are explicit user customizations and are left alone.
struct DemotedWindow {
  const char* category;
  const char* window_id;
};
 
constexpr DemotedWindow kRevision26DemotedWindows[] = {
    // Agent developer tooling: opened from Tools > Hack Workflows.
    {"Agent", "agent.mesen_debug"},
    {"Agent", "agent.mesen_screenshot"},
    {"Agent", "agent.oracle_states"},
    {"Agent", "agent.feature_flags"},
    {"Agent", "agent.manifest"},
    {"Agent", "agent.sram_viewer"},
    // Oracle validation and inspection tooling: opened from Tools > Hack
    // Workflows.
    {"Agent", "oracle.validation"},
    {"Agent", "oracle.menu_inspector"},
    // Graphics research importer: opened from the welcome screen.
    {"Graphics", "graphics.prototype_viewer"},
    // Stub: draws nothing yet.
    {"Screen", "screen.naming_screen"},
    // Placeholder: shows "Coming Soon".
    {"Emulator", "emulator.save_states"},
};
 
void CloseDemotedWindowVisibility(
    std::unordered_map<std::string, std::unordered_map<std::string, bool>>*
        visibility_state) {
  if (!visibility_state) {
    return;
  }
  for (const DemotedWindow& window : kRevision26DemotedWindows) {
    auto category_it = visibility_state->find(window.category);
    if (category_it == visibility_state->end()) {
      continue;
    }
    auto window_it = category_it->second.find(window.window_id);
    if (window_it != category_it->second.end()) {
      window_it->second = false;
    }
  }
}
 
bool PruneEmbeddedDungeonUtilityPanelsFromDockTreeJson(std::string* json_body) {
  if (!json_body || json_body->empty()) {
    return false;
  }
  auto parsed = nlohmann::json::parse(*json_body, nullptr, false);
  if (parsed.is_discarded() || !parsed.is_object() ||
      !parsed.contains("root")) {
    return false;
  }
 
  bool changed = false;
  auto prune_node = [&changed](auto&& self, nlohmann::json& node) -> void {
    if (!node.is_object()) {
      return;
    }
    const std::string type = node.contains("type") && node["type"].is_string()
                                 ? node["type"].get<std::string>()
                                 : "";
    if (type == "leaf" && node.contains("panels") &&
        node["panels"].is_array()) {
      auto& panels = node["panels"];
      for (auto it = panels.begin(); it != panels.end();) {
        const bool erase = it->is_object() && it->contains("panel_id") &&
                           (*it)["panel_id"].is_string() &&
                           IsEmbeddedDungeonUtilityPanelId(
                               (*it)["panel_id"].get<std::string>());
        if (erase) {
          it = panels.erase(it);
          changed = true;
        } else {
          ++it;
        }
      }
      const int max_active =
          panels.empty() ? 0 : static_cast<int>(panels.size()) - 1;
      const int active_tab_index =
          node.contains("active_tab_index") &&
                  node["active_tab_index"].is_number_integer()
              ? node["active_tab_index"].get<int>()
              : 0;
      const int clamped_active = std::clamp(active_tab_index, 0, max_active);
      if (active_tab_index != clamped_active) {
        node["active_tab_index"] = clamped_active;
        changed = true;
      }
    }
    if (node.contains("child_a")) {
      self(self, node["child_a"]);
    }
    if (node.contains("child_b")) {
      self(self, node["child_b"]);
    }
  };
  prune_node(prune_node, parsed["root"]);
 
  if (changed) {
    *json_body = parsed.dump();
  }
  return changed;
}
 
absl::Status LoadPreferencesFromIni(const std::filesystem::path& path,
                                    UserSettings::Preferences* prefs) {
  if (!prefs) {
    return absl::InvalidArgumentError("prefs is null");
  }
 
  auto data = util::LoadFile(path.string());
  if (data.empty()) {
    return absl::OkStatus();
  }
 
  std::istringstream ss(data);
  std::string line;
  // Tolerate malformed numeric values in a partial or truncated INI: skip the
  // bad value (keep the current default) instead of throwing out of Load(),
  // which would abort before the defaults are written and the file re-saved.
  auto to_float = [](const std::string& s, float fallback) {
    try {
      return std::stof(s);
    } catch (const std::exception&) {
      return fallback;
    }
  };
  auto to_int = [](const std::string& s, int fallback) {
    try {
      return std::stoi(s);
    } catch (const std::exception&) {
      return fallback;
    }
  };
  while (std::getline(ss, line)) {
    size_t eq_pos = line.find('=');
    if (eq_pos == std::string::npos) {
      continue;
    }
 
    std::string key = line.substr(0, eq_pos);
    std::string val = line.substr(eq_pos + 1);
 
    // General
    if (key == "font_global_scale") {
      prefs->font_global_scale =
          SanitizeFontGlobalScale(to_float(val, prefs->font_global_scale));
    } else if (key == "backup_rom") {
      prefs->backup_rom = (val == "1");
    } else if (key == "save_new_auto") {
      prefs->save_new_auto = (val == "1");
    } else if (key == "autosave_enabled") {
      prefs->autosave_enabled = (val == "1");
    } else if (key == "autosave_interval") {
      prefs->autosave_interval = to_float(val, prefs->autosave_interval);
    } else if (key == "recent_files_limit") {
      prefs->recent_files_limit = to_int(val, prefs->recent_files_limit);
    } else if (key == "last_rom_path") {
      prefs->last_rom_path = val;
    } else if (key == "last_project_path") {
      prefs->last_project_path = val;
    } else if (key == "show_welcome_on_startup") {
      prefs->show_welcome_on_startup = (val == "1");
    } else if (key == "test_mode") {
      prefs->test_mode = (val == "1");
    } else if (key == "restore_last_session") {
      prefs->restore_last_session = (val == "1");
    } else if (key == "prefer_hmagic_sprite_names") {
      prefs->prefer_hmagic_sprite_names = (val == "1");
    } else if (key == "feature_hints_enabled") {
      prefs->feature_hints_enabled = (val == "1");
    } else if (constexpr std::string_view kDismissedHintPrefix =
                   "dismissed_feature_hint.";
               key.rfind(kDismissedHintPrefix, 0) == 0) {
      const std::string hint_id = key.substr(kDismissedHintPrefix.size());
      if (!hint_id.empty() && val == "1") {
        prefs->dismissed_feature_hints.insert(hint_id);
      }
    } else if (key == "welcome_triforce_alpha") {
      prefs->welcome_triforce_alpha =
          to_float(val, prefs->welcome_triforce_alpha);
    } else if (key == "welcome_triforce_speed") {
      prefs->welcome_triforce_speed =
          to_float(val, prefs->welcome_triforce_speed);
    } else if (key == "welcome_triforce_size") {
      prefs->welcome_triforce_size =
          to_float(val, prefs->welcome_triforce_size);
    } else if (key == "welcome_particles_enabled") {
      prefs->welcome_particles_enabled = (val == "1");
    } else if (key == "welcome_mouse_repel_enabled") {
      prefs->welcome_mouse_repel_enabled = (val == "1");
    } else if (key == "reduced_motion") {
      prefs->reduced_motion = (val == "1");
    } else if (key == "switch_motion_profile") {
      prefs->switch_motion_profile = to_int(val, prefs->switch_motion_profile);
    } else if (key == "last_theme_name") {
      prefs->last_theme_name = val;
    } else if (key == "language_locale") {
      prefs->language_locale = val;
    } else if (key == "font_family_index") {
      prefs->font_family_index = to_int(val, prefs->font_family_index);
    }
    // Editor Behavior
    else if (key == "backup_before_save") {
      prefs->backup_before_save = (val == "1");
    } else if (key == "default_editor") {
      prefs->default_editor = to_int(val, prefs->default_editor);
    }
    // Performance
    else if (key == "vsync") {
      prefs->vsync = (val == "1");
    } else if (key == "target_fps") {
      prefs->target_fps = to_int(val, prefs->target_fps);
    } else if (key == "cache_size_mb") {
      prefs->cache_size_mb = to_int(val, prefs->cache_size_mb);
    } else if (key == "undo_history_size") {
      prefs->undo_history_size = to_int(val, prefs->undo_history_size);
    }
    // AI Agent
    else if (key == "ai_provider") {
      prefs->ai_provider = to_int(val, prefs->ai_provider);
    } else if (key == "ai_model") {
      prefs->ai_model = val;
    } else if (key == "ollama_url") {
      prefs->ollama_url = val;
    } else if (key == "gemini_api_key") {
      prefs->gemini_api_key = val;
    } else if (key == "openai_api_key") {
      prefs->openai_api_key = val;
    } else if (key == "anthropic_api_key") {
      prefs->anthropic_api_key = val;
    } else if (key == "ai_temperature") {
      prefs->ai_temperature = to_float(val, prefs->ai_temperature);
    } else if (key == "ai_max_tokens") {
      prefs->ai_max_tokens = to_int(val, prefs->ai_max_tokens);
    } else if (key == "ai_proactive") {
      prefs->ai_proactive = (val == "1");
    } else if (key == "ai_auto_learn") {
      prefs->ai_auto_learn = (val == "1");
    } else if (key == "ai_multimodal") {
      prefs->ai_multimodal = (val == "1");
    }
    // CLI Logging
    else if (key == "log_level") {
      prefs->log_level = to_int(val, prefs->log_level);
    } else if (key == "log_to_file") {
      prefs->log_to_file = (val == "1");
    } else if (key == "log_file_path") {
      prefs->log_file_path = val;
    } else if (key == "log_ai_requests") {
      prefs->log_ai_requests = (val == "1");
    } else if (key == "log_rom_operations") {
      prefs->log_rom_operations = (val == "1");
    } else if (key == "log_gui_automation") {
      prefs->log_gui_automation = (val == "1");
    } else if (key == "log_proposals") {
      prefs->log_proposals = (val == "1");
    }
    // Panel Shortcuts (format: panel_shortcut.panel_id=shortcut)
    else if (key.substr(0, 15) == "panel_shortcut.") {
      std::string panel_id = key.substr(15);
      prefs->panel_shortcuts[panel_id] = val;
    }
    // Backward compatibility for card_shortcut
    else if (key.substr(0, 14) == "card_shortcut.") {
      std::string panel_id = key.substr(14);
      prefs->panel_shortcuts[panel_id] = val;
    }
    // Sidebar State
    else if (key == "sidebar_visible") {
      prefs->sidebar_visible = (val == "1");
    } else if (key == "sidebar_panel_expanded") {
      prefs->sidebar_panel_expanded = (val == "1");
    } else if (key == "sidebar_panel_width") {
      prefs->sidebar_panel_width = to_float(val, prefs->sidebar_panel_width);
    } else if (key == "panel_browser_category_width") {
      prefs->panel_browser_category_width =
          to_float(val, prefs->panel_browser_category_width);
    } else if (key == "panel_layout_defaults_revision") {
      prefs->panel_layout_defaults_revision =
          to_int(val, prefs->panel_layout_defaults_revision);
    } else if (key == "sidebar_active_category") {
      prefs->sidebar_active_category = val;
    } else if (key.rfind("sidebar_context_collapsed.", 0) == 0) {
      const std::string category =
          key.substr(std::string("sidebar_context_collapsed.").size());
      if (!category.empty()) {
        if (val == "1") {
          prefs->sidebar_context_collapsed.insert(category);
        } else {
          prefs->sidebar_context_collapsed.erase(category);
        }
      }
    } else if (key == "dungeon_inspector_side") {
      prefs->dungeon_inspector_side =
          (val == "left") ? std::string("left") : std::string("right");
    }
    // Status Bar
    else if (key == "show_status_bar") {
      prefs->show_status_bar = (val == "1");
    } else if (key == "emulator_keep_running_in_background") {
      prefs->emulator_keep_running_in_background = (val == "1");
    } else if (key == "show_experimental_editors") {
      prefs->show_experimental_editors = (val == "1");
    }
    // Panel Visibility State (format: panel_visibility.EditorType.panel_id=1)
    else if (key.substr(0, 17) == "panel_visibility.") {
      std::string rest = key.substr(17);
      size_t dot_pos = rest.find('.');
      if (dot_pos != std::string::npos) {
        std::string editor_type = rest.substr(0, dot_pos);
        std::string panel_id = rest.substr(dot_pos + 1);
        prefs->panel_visibility_state[editor_type][panel_id] = (val == "1");
      }
    }
    // Pinned Panels (format: pinned_panel.panel_id=1)
    else if (key.substr(0, 13) == "pinned_panel.") {
      std::string panel_id = key.substr(13);
      prefs->pinned_panels[panel_id] = (val == "1");
    }
    // Right panel widths (format: right_panel_width.panel_key=420.0)
    else if (key.substr(0, 18) == "right_panel_width.") {
      std::string panel_key = key.substr(18);
      prefs->right_panel_widths[panel_key] = to_float(val, 0.0f);
    }
    // Saved Layouts (format: saved_layout.LayoutName.panel_id=1)
    else if (key.substr(0, 13) == "saved_layout.") {
      std::string rest = key.substr(13);
      size_t dot_pos = rest.find('.');
      if (dot_pos != std::string::npos) {
        std::string layout_name = rest.substr(0, dot_pos);
        std::string panel_id = rest.substr(dot_pos + 1);
        prefs->saved_layouts[layout_name][panel_id] = (val == "1");
      }
    }
    // Named DockTree layouts (format: named_layout.<name>=<compact-json>).
    // Value is a single-line JSON document produced by DockTreeToJson().dump();
    // callers re-parse it through DockTreeFromJson when needed.
    else if (key.substr(0, 13) == "named_layout.") {
      std::string layout_name = key.substr(13);
      prefs->named_layouts[layout_name] = val;
    } else if (key == "last_applied_layout_name") {
      prefs->last_applied_layout_name = val;
    }
    // Remembered ROM load options (format: rom_load_choice=<choice>\t<path>).
    // The choice comes first because it never holds a tab; the path may hold
    // '=' or a tab, so it takes the rest of the line.
    else if (key == "rom_load_choice") {
      const size_t tab = val.find('\t');
      if (tab != std::string::npos && tab + 1 < val.size()) {
        prefs->rom_load_choices[val.substr(tab + 1)] = val.substr(0, tab);
      }
    }
  }
 
  return absl::OkStatus();
}
 
absl::Status SavePreferencesToIni(const std::filesystem::path& path,
                                  const UserSettings::Preferences& prefs) {
  auto ensure_status = EnsureParentDirectory(path);
  if (!ensure_status.ok()) {
    return ensure_status;
  }
 
  std::ostringstream ss;
  // General
  ss << "font_global_scale=" << prefs.font_global_scale << "\n";
  ss << "backup_rom=" << (prefs.backup_rom ? 1 : 0) << "\n";
  ss << "save_new_auto=" << (prefs.save_new_auto ? 1 : 0) << "\n";
  ss << "autosave_enabled=" << (prefs.autosave_enabled ? 1 : 0) << "\n";
  ss << "autosave_interval=" << prefs.autosave_interval << "\n";
  ss << "recent_files_limit=" << prefs.recent_files_limit << "\n";
  ss << "last_rom_path=" << prefs.last_rom_path << "\n";
  ss << "last_project_path=" << prefs.last_project_path << "\n";
  ss << "show_welcome_on_startup=" << (prefs.show_welcome_on_startup ? 1 : 0)
     << "\n";
  ss << "test_mode=" << (prefs.test_mode ? 1 : 0) << "\n";
  ss << "restore_last_session=" << (prefs.restore_last_session ? 1 : 0) << "\n";
  ss << "prefer_hmagic_sprite_names="
     << (prefs.prefer_hmagic_sprite_names ? 1 : 0) << "\n";
  ss << "feature_hints_enabled=" << (prefs.feature_hints_enabled ? 1 : 0)
     << "\n";
  std::vector<std::string> dismissed_hints(
      prefs.dismissed_feature_hints.begin(),
      prefs.dismissed_feature_hints.end());
  std::sort(dismissed_hints.begin(), dismissed_hints.end());
  for (const auto& hint_id : dismissed_hints) {
    ss << "dismissed_feature_hint." << hint_id << "=1\n";
  }
  ss << "welcome_triforce_alpha=" << prefs.welcome_triforce_alpha << "\n";
  ss << "welcome_triforce_speed=" << prefs.welcome_triforce_speed << "\n";
  ss << "welcome_triforce_size=" << prefs.welcome_triforce_size << "\n";
  ss << "welcome_particles_enabled="
     << (prefs.welcome_particles_enabled ? 1 : 0) << "\n";
  ss << "welcome_mouse_repel_enabled="
     << (prefs.welcome_mouse_repel_enabled ? 1 : 0) << "\n";
  ss << "reduced_motion=" << (prefs.reduced_motion ? 1 : 0) << "\n";
  ss << "switch_motion_profile=" << prefs.switch_motion_profile << "\n";
  ss << "last_theme_name=" << prefs.last_theme_name << "\n";
  ss << "language_locale=" << prefs.language_locale << "\n";
  ss << "font_family_index=" << prefs.font_family_index << "\n";
 
  // Editor Behavior
  ss << "backup_before_save=" << (prefs.backup_before_save ? 1 : 0) << "\n";
  ss << "default_editor=" << prefs.default_editor << "\n";
 
  // Performance
  ss << "vsync=" << (prefs.vsync ? 1 : 0) << "\n";
  ss << "target_fps=" << prefs.target_fps << "\n";
  ss << "cache_size_mb=" << prefs.cache_size_mb << "\n";
  ss << "undo_history_size=" << prefs.undo_history_size << "\n";
 
  // AI Agent
  ss << "ai_provider=" << prefs.ai_provider << "\n";
  ss << "ai_model=" << prefs.ai_model << "\n";
  ss << "ollama_url=" << prefs.ollama_url << "\n";
  ss << "gemini_api_key=" << prefs.gemini_api_key << "\n";
  ss << "openai_api_key=" << prefs.openai_api_key << "\n";
  ss << "anthropic_api_key=" << prefs.anthropic_api_key << "\n";
  ss << "ai_temperature=" << prefs.ai_temperature << "\n";
  ss << "ai_max_tokens=" << prefs.ai_max_tokens << "\n";
  ss << "ai_proactive=" << (prefs.ai_proactive ? 1 : 0) << "\n";
  ss << "ai_auto_learn=" << (prefs.ai_auto_learn ? 1 : 0) << "\n";
  ss << "ai_multimodal=" << (prefs.ai_multimodal ? 1 : 0) << "\n";
 
  // CLI Logging
  ss << "log_level=" << prefs.log_level << "\n";
  ss << "log_to_file=" << (prefs.log_to_file ? 1 : 0) << "\n";
  ss << "log_file_path=" << prefs.log_file_path << "\n";
  ss << "log_ai_requests=" << (prefs.log_ai_requests ? 1 : 0) << "\n";
  ss << "log_rom_operations=" << (prefs.log_rom_operations ? 1 : 0) << "\n";
  ss << "log_gui_automation=" << (prefs.log_gui_automation ? 1 : 0) << "\n";
  ss << "log_proposals=" << (prefs.log_proposals ? 1 : 0) << "\n";
 
  // Panel Shortcuts
  for (const auto& [panel_id, shortcut] : prefs.panel_shortcuts) {
    ss << "panel_shortcut." << panel_id << "=" << shortcut << "\n";
  }
 
  // Sidebar State
  ss << "sidebar_visible=" << (prefs.sidebar_visible ? 1 : 0) << "\n";
  ss << "sidebar_panel_expanded=" << (prefs.sidebar_panel_expanded ? 1 : 0)
     << "\n";
  ss << "sidebar_panel_width=" << prefs.sidebar_panel_width << "\n";
  ss << "panel_browser_category_width=" << prefs.panel_browser_category_width
     << "\n";
  ss << "panel_layout_defaults_revision="
     << prefs.panel_layout_defaults_revision << "\n";
  ss << "sidebar_active_category=" << prefs.sidebar_active_category << "\n";
  for (const std::string& category : prefs.sidebar_context_collapsed) {
    ss << "sidebar_context_collapsed." << category << "=1\n";
  }
  ss << "dungeon_inspector_side=" << prefs.dungeon_inspector_side << "\n";
 
  // Status Bar
  ss << "show_status_bar=" << (prefs.show_status_bar ? 1 : 0) << "\n";
  ss << "emulator_keep_running_in_background="
     << (prefs.emulator_keep_running_in_background ? 1 : 0) << "\n";
  ss << "show_experimental_editors="
     << (prefs.show_experimental_editors ? 1 : 0) << "\n";
 
  // Panel Visibility State
  for (const auto& [editor_type, panel_state] : prefs.panel_visibility_state) {
    for (const auto& [panel_id, visible] : panel_state) {
      ss << "panel_visibility." << editor_type << "." << panel_id << "="
         << (visible ? 1 : 0) << "\n";
    }
  }
 
  // Pinned Panels
  for (const auto& [panel_id, pinned] : prefs.pinned_panels) {
    ss << "pinned_panel." << panel_id << "=" << (pinned ? 1 : 0) << "\n";
  }
 
  for (const auto& [panel_key, width] : prefs.right_panel_widths) {
    ss << "right_panel_width." << panel_key << "=" << width << "\n";
  }
 
  // Saved Layouts
  for (const auto& [layout_name, panel_state] : prefs.saved_layouts) {
    for (const auto& [panel_id, visible] : panel_state) {
      ss << "saved_layout." << layout_name << "." << panel_id << "="
         << (visible ? 1 : 0) << "\n";
    }
  }
 
  // Named DockTree layouts (Layout Designer).
  if (!prefs.last_applied_layout_name.empty()) {
    ss << "last_applied_layout_name=" << prefs.last_applied_layout_name << "\n";
  }
  for (const auto& [layout_name, json_body] : prefs.named_layouts) {
    // JSON bodies are expected to be compact (no newlines) — filter just in
    // case the caller handed us an indented dump.
    std::string single_line;
    single_line.reserve(json_body.size());
    for (char c : json_body) {
      if (c == '\n' || c == '\r')
        continue;
      single_line.push_back(c);
    }
    ss << "named_layout." << layout_name << "=" << single_line << "\n";
  }
 
  // Remembered ROM load options. A newline in either part would split the
  // line, and a tab in the choice would move the separator; skip both.
  for (const auto& [rom_path, choice] : prefs.rom_load_choices) {
    if (rom_path.find_first_of("\r\n") != std::string::npos ||
        choice.find_first_of("\t\r\n") != std::string::npos) {
      continue;
    }
    ss << "rom_load_choice=" << choice << "\t" << rom_path << "\n";
  }
 
  std::ofstream file(path);
  if (!file.is_open()) {
    return absl::InternalError(
        absl::StrFormat("Failed to open settings file: %s", path.string()));
  }
  file << ss.str();
  return absl::OkStatus();
}
 
#ifdef YAZE_WITH_JSON
void EnsureDefaultAiHosts(UserSettings::Preferences* prefs) {
  if (!prefs) {
    return;
  }
 
  if (!prefs->ai_hosts.empty()) {
    if (prefs->active_ai_host_id.empty()) {
      prefs->active_ai_host_id = prefs->ai_hosts.front().id;
    }
    return;
  }
 
  if (!prefs->ollama_url.empty()) {
    UserSettings::Preferences::AiHost host;
    host.id = "ollama-local";
    host.label = "Ollama (local)";
    host.base_url = prefs->ollama_url;
    host.api_type = "ollama";
    host.supports_tools = true;
    host.supports_streaming = true;
    prefs->ai_hosts.push_back(host);
  }
 
  // Provide a local OpenAI-compatible host for LM Studio by default.
  UserSettings::Preferences::AiHost lmstudio;
  lmstudio.id = "lmstudio-local";
  lmstudio.label = "LM Studio (local)";
  lmstudio.base_url = "http://localhost:1234";
  lmstudio.api_type = "lmstudio";
  lmstudio.supports_tools = true;
  lmstudio.supports_streaming = true;
  prefs->ai_hosts.push_back(lmstudio);
 
  if (!prefs->ai_hosts.empty() && prefs->active_ai_host_id.empty()) {
    prefs->active_ai_host_id = prefs->ai_hosts.front().id;
  }
}
 
void EnsureDefaultAiProfiles(UserSettings::Preferences* prefs) {
  if (!prefs) {
    return;
  }
  if (!prefs->ai_profiles.empty()) {
    if (prefs->active_ai_profile.empty()) {
      prefs->active_ai_profile = prefs->ai_profiles.front().name;
    }
    return;
  }
  if (!prefs->ai_model.empty()) {
    UserSettings::Preferences::AiModelProfile profile;
    profile.name = "default";
    profile.model = prefs->ai_model;
    profile.temperature = prefs->ai_temperature;
    profile.top_p = 0.95f;
    profile.max_output_tokens = prefs->ai_max_tokens;
    profile.supports_tools = true;
    prefs->ai_profiles.push_back(profile);
    prefs->active_ai_profile = profile.name;
  }
}
 
void EnsureDefaultFilesystemRoots(UserSettings::Preferences* prefs) {
  if (!prefs) {
    return;
  }
 
  auto add_unique_root = [&](const std::filesystem::path& path) {
    if (path.empty()) {
      return;
    }
    const std::string path_str = path.string();
    auto it = std::find(prefs->project_root_paths.begin(),
                        prefs->project_root_paths.end(), path_str);
    if (it == prefs->project_root_paths.end()) {
      prefs->project_root_paths.push_back(path_str);
    }
  };
 
  auto docs_dir = util::PlatformPaths::GetUserDocumentsDirectory();
  if (docs_dir.ok()) {
    add_unique_root(*docs_dir);
  }
 
  if (prefs->use_icloud_sync) {
    auto icloud_dir =
        util::PlatformPaths::GetUserDocumentsSubdirectory("iCloud");
    if (icloud_dir.ok()) {
      add_unique_root(*icloud_dir);
      if (prefs->default_project_root.empty()) {
        prefs->default_project_root = icloud_dir->string();
      }
    }
  }
 
  if (prefs->default_project_root.empty() &&
      !prefs->project_root_paths.empty()) {
    prefs->default_project_root = prefs->project_root_paths.front();
  }
}
 
void EnsureDefaultModelPaths(UserSettings::Preferences* prefs) {
  if (!prefs) {
    return;
  }
  if (!prefs->ai_model_paths.empty()) {
    return;
  }
 
  auto add_unique_path = [&](const std::filesystem::path& path) {
    if (path.empty()) {
      return;
    }
    const std::string path_str = path.string();
    auto it = std::find(prefs->ai_model_paths.begin(),
                        prefs->ai_model_paths.end(), path_str);
    if (it == prefs->ai_model_paths.end()) {
      prefs->ai_model_paths.push_back(path_str);
    }
  };
 
  const auto home_dir = util::PlatformPaths::GetHomeDirectory();
  if (!home_dir.empty() && home_dir != ".") {
    add_unique_path(home_dir / "models");
    add_unique_path(home_dir / ".lmstudio" / "models");
    add_unique_path(home_dir / ".ollama" / "models");
  }
}
 
void LoadStringMap(const json& src,
                   std::unordered_map<std::string, std::string>* target) {
  if (!target || !src.is_object()) {
    return;
  }
  target->clear();
  for (const auto& [key, value] : src.items()) {
    if (value.is_string()) {
      (*target)[key] = value.get<std::string>();
    }
  }
}
 
void LoadBoolMap(const json& src,
                 std::unordered_map<std::string, bool>* target) {
  if (!target || !src.is_object()) {
    return;
  }
  target->clear();
  for (const auto& [key, value] : src.items()) {
    if (value.is_boolean()) {
      (*target)[key] = value.get<bool>();
    }
  }
}
 
void LoadFloatMap(const json& src,
                  std::unordered_map<std::string, float>* target) {
  if (!target || !src.is_object()) {
    return;
  }
  target->clear();
  for (const auto& [key, value] : src.items()) {
    if (value.is_number()) {
      (*target)[key] = value.get<float>();
    }
  }
}
 
void LoadNestedBoolMap(
    const json& src,
    std::unordered_map<std::string, std::unordered_map<std::string, bool>>*
        target) {
  if (!target || !src.is_object()) {
    return;
  }
  target->clear();
  for (const auto& [outer_key, outer_val] : src.items()) {
    if (!outer_val.is_object()) {
      continue;
    }
    auto& inner = (*target)[outer_key];
    inner.clear();
    for (const auto& [inner_key, inner_val] : outer_val.items()) {
      if (inner_val.is_boolean()) {
        inner[inner_key] = inner_val.get<bool>();
      }
    }
  }
}
 
json ToStringMap(const std::unordered_map<std::string, std::string>& map) {
  json obj = json::object();
  for (const auto& [key, value] : map) {
    obj[key] = value;
  }
  return obj;
}
 
json ToBoolMap(const std::unordered_map<std::string, bool>& map) {
  json obj = json::object();
  for (const auto& [key, value] : map) {
    obj[key] = value;
  }
  return obj;
}
 
json ToFloatMap(const std::unordered_map<std::string, float>& map) {
  json obj = json::object();
  for (const auto& [key, value] : map) {
    obj[key] = value;
  }
  return obj;
}
 
json ToNestedBoolMap(const std::unordered_map<
                     std::string, std::unordered_map<std::string, bool>>& map) {
  json obj = json::object();
  for (const auto& [outer_key, inner] : map) {
    obj[outer_key] = ToBoolMap(inner);
  }
  return obj;
}
 
absl::Status LoadPreferencesFromJson(const std::filesystem::path& path,
                                     UserSettings::Preferences* prefs) {
  if (!prefs) {
    return absl::InvalidArgumentError("prefs is null");
  }
 
  std::ifstream file(path);
  if (!file.is_open()) {
    return absl::NotFoundError(
        absl::StrFormat("Settings file not found: %s", path.string()));
  }
 
  json root;
  try {
    file >> root;
  } catch (const std::exception& e) {
    return absl::InternalError(
        absl::StrFormat("Failed to parse settings.json: %s", e.what()));
  }
 
  if (root.contains("general")) {
    const auto& g = root["general"];
    prefs->font_global_scale = SanitizeFontGlobalScale(
        g.value("font_global_scale", prefs->font_global_scale));
    prefs->backup_rom = g.value("backup_rom", prefs->backup_rom);
    prefs->save_new_auto = g.value("save_new_auto", prefs->save_new_auto);
    prefs->autosave_enabled =
        g.value("autosave_enabled", prefs->autosave_enabled);
    prefs->autosave_interval =
        g.value("autosave_interval", prefs->autosave_interval);
    prefs->recent_files_limit =
        g.value("recent_files_limit", prefs->recent_files_limit);
    prefs->last_rom_path = g.value("last_rom_path", prefs->last_rom_path);
    prefs->last_project_path =
        g.value("last_project_path", prefs->last_project_path);
    prefs->show_welcome_on_startup =
        g.value("show_welcome_on_startup", prefs->show_welcome_on_startup);
    prefs->test_mode = g.value("test_mode", prefs->test_mode);
    prefs->restore_last_session =
        g.value("restore_last_session", prefs->restore_last_session);
    prefs->prefer_hmagic_sprite_names = g.value(
        "prefer_hmagic_sprite_names", prefs->prefer_hmagic_sprite_names);
    prefs->welcome_triforce_alpha =
        g.value("welcome_triforce_alpha", prefs->welcome_triforce_alpha);
    prefs->welcome_triforce_speed =
        g.value("welcome_triforce_speed", prefs->welcome_triforce_speed);
    prefs->welcome_triforce_size =
        g.value("welcome_triforce_size", prefs->welcome_triforce_size);
    prefs->welcome_particles_enabled =
        g.value("welcome_particles_enabled", prefs->welcome_particles_enabled);
    prefs->welcome_mouse_repel_enabled = g.value(
        "welcome_mouse_repel_enabled", prefs->welcome_mouse_repel_enabled);
  }
 
  if (root.contains("onboarding")) {
    const auto& onboarding = root["onboarding"];
    prefs->feature_hints_enabled =
        onboarding.value("feature_hints_enabled", prefs->feature_hints_enabled);
    if (onboarding.contains("dismissed_feature_hints") &&
        onboarding["dismissed_feature_hints"].is_array()) {
      prefs->dismissed_feature_hints.clear();
      for (const auto& item : onboarding["dismissed_feature_hints"]) {
        if (item.is_string()) {
          prefs->dismissed_feature_hints.insert(item.get<std::string>());
        }
      }
    }
  }
 
  if (root.contains("appearance")) {
    const auto& appearance = root["appearance"];
    prefs->reduced_motion =
        appearance.value("reduced_motion", prefs->reduced_motion);
    prefs->switch_motion_profile =
        appearance.value("switch_motion_profile", prefs->switch_motion_profile);
    prefs->last_theme_name =
        appearance.value("last_theme_name", prefs->last_theme_name);
    prefs->language_locale =
        appearance.value("language_locale", prefs->language_locale);
    prefs->font_family_index =
        appearance.value("font_family_index", prefs->font_family_index);
  }
 
  if (root.contains("editor")) {
    const auto& e = root["editor"];
    prefs->backup_before_save =
        e.value("backup_before_save", prefs->backup_before_save);
    prefs->default_editor = e.value("default_editor", prefs->default_editor);
    {
      std::string side =
          e.value("dungeon_inspector_side", prefs->dungeon_inspector_side);
      prefs->dungeon_inspector_side = (side == "left") ? "left" : "right";
    }
  }
 
  if (root.contains("performance")) {
    const auto& p = root["performance"];
    prefs->vsync = p.value("vsync", prefs->vsync);
    prefs->target_fps = p.value("target_fps", prefs->target_fps);
    prefs->cache_size_mb = p.value("cache_size_mb", prefs->cache_size_mb);
    prefs->undo_history_size =
        p.value("undo_history_size", prefs->undo_history_size);
  }
 
  if (root.contains("ai")) {
    const auto& ai = root["ai"];
    prefs->ai_provider = ai.value("provider", prefs->ai_provider);
    prefs->ai_model = ai.value("model", prefs->ai_model);
    prefs->ollama_url = ai.value("ollama_url", prefs->ollama_url);
    prefs->gemini_api_key = ai.value("gemini_api_key", prefs->gemini_api_key);
    prefs->openai_api_key = ai.value("openai_api_key", prefs->openai_api_key);
    prefs->anthropic_api_key =
        ai.value("anthropic_api_key", prefs->anthropic_api_key);
    std::string google_key = ai.value("google_api_key", std::string());
    if (prefs->gemini_api_key.empty() && !google_key.empty()) {
      prefs->gemini_api_key = google_key;
    }
    prefs->ai_temperature = ai.value("temperature", prefs->ai_temperature);
    prefs->ai_max_tokens = ai.value("max_tokens", prefs->ai_max_tokens);
    prefs->ai_proactive = ai.value("proactive", prefs->ai_proactive);
    prefs->ai_auto_learn = ai.value("auto_learn", prefs->ai_auto_learn);
    prefs->ai_multimodal = ai.value("multimodal", prefs->ai_multimodal);
    prefs->active_ai_host_id =
        ai.value("active_host_id", prefs->active_ai_host_id);
    prefs->active_ai_profile =
        ai.value("active_profile", prefs->active_ai_profile);
    prefs->remote_build_host_id =
        ai.value("remote_build_host_id", prefs->remote_build_host_id);
    if (ai.contains("model_paths") && ai["model_paths"].is_array()) {
      prefs->ai_model_paths.clear();
      for (const auto& item : ai["model_paths"]) {
        if (item.is_string()) {
          prefs->ai_model_paths.push_back(item.get<std::string>());
        }
      }
    }
 
    if (ai.contains("hosts") && ai["hosts"].is_array()) {
      prefs->ai_hosts.clear();
      for (const auto& host : ai["hosts"]) {
        if (!host.is_object()) {
          continue;
        }
        UserSettings::Preferences::AiHost entry;
        entry.id = host.value("id", "");
        entry.label = host.value("label", "");
        entry.base_url = host.value("base_url", "");
        entry.api_type = host.value("api_type", "");
        entry.supports_vision =
            host.value("supports_vision", entry.supports_vision);
        entry.supports_tools =
            host.value("supports_tools", entry.supports_tools);
        entry.supports_streaming =
            host.value("supports_streaming", entry.supports_streaming);
        entry.allow_insecure =
            host.value("allow_insecure", entry.allow_insecure);
        entry.api_key = host.value("api_key", "");
        entry.credential_id = host.value("credential_id", "");
        prefs->ai_hosts.push_back(entry);
      }
    }
 
    if (ai.contains("profiles") && ai["profiles"].is_array()) {
      prefs->ai_profiles.clear();
      for (const auto& profile : ai["profiles"]) {
        if (!profile.is_object()) {
          continue;
        }
        UserSettings::Preferences::AiModelProfile entry;
        entry.name = profile.value("name", "");
        entry.model = profile.value("model", "");
        entry.temperature = profile.value("temperature", entry.temperature);
        entry.top_p = profile.value("top_p", entry.top_p);
        entry.max_output_tokens =
            profile.value("max_output_tokens", entry.max_output_tokens);
        entry.supports_vision =
            profile.value("supports_vision", entry.supports_vision);
        entry.supports_tools =
            profile.value("supports_tools", entry.supports_tools);
        prefs->ai_profiles.push_back(entry);
      }
    }
  }
 
  if (root.contains("logging")) {
    const auto& log = root["logging"];
    prefs->log_level = log.value("level", prefs->log_level);
    prefs->log_to_file = log.value("to_file", prefs->log_to_file);
    prefs->log_file_path = log.value("file_path", prefs->log_file_path);
    prefs->log_ai_requests = log.value("ai_requests", prefs->log_ai_requests);
    prefs->log_rom_operations =
        log.value("rom_operations", prefs->log_rom_operations);
    prefs->log_gui_automation =
        log.value("gui_automation", prefs->log_gui_automation);
    prefs->log_proposals = log.value("proposals", prefs->log_proposals);
  }
 
  if (root.contains("shortcuts")) {
    const auto& shortcuts = root["shortcuts"];
    if (shortcuts.contains("panel")) {
      LoadStringMap(shortcuts["panel"], &prefs->panel_shortcuts);
    }
    if (shortcuts.contains("global")) {
      LoadStringMap(shortcuts["global"], &prefs->global_shortcuts);
    }
    if (shortcuts.contains("editor")) {
      LoadStringMap(shortcuts["editor"], &prefs->editor_shortcuts);
    }
  }
 
  if (root.contains("sidebar")) {
    const auto& sidebar = root["sidebar"];
    prefs->sidebar_visible = sidebar.value("visible", prefs->sidebar_visible);
    prefs->sidebar_panel_expanded =
        sidebar.value("panel_expanded", prefs->sidebar_panel_expanded);
    prefs->sidebar_panel_width =
        sidebar.value("panel_width", prefs->sidebar_panel_width);
    prefs->panel_browser_category_width = sidebar.value(
        "panel_browser_category_width", prefs->panel_browser_category_width);
    prefs->sidebar_active_category =
        sidebar.value("active_category", prefs->sidebar_active_category);
 
    if (sidebar.contains("order") && sidebar["order"].is_array()) {
      prefs->sidebar_order.clear();
      for (const auto& item : sidebar["order"]) {
        if (item.is_string()) {
          prefs->sidebar_order.push_back(item.get<std::string>());
        }
      }
    }
    if (sidebar.contains("hidden") && sidebar["hidden"].is_array()) {
      prefs->sidebar_hidden.clear();
      for (const auto& item : sidebar["hidden"]) {
        if (item.is_string()) {
          prefs->sidebar_hidden.insert(item.get<std::string>());
        }
      }
    }
    if (sidebar.contains("pinned") && sidebar["pinned"].is_array()) {
      prefs->sidebar_pinned.clear();
      for (const auto& item : sidebar["pinned"]) {
        if (item.is_string()) {
          prefs->sidebar_pinned.insert(item.get<std::string>());
        }
      }
    }
    if (sidebar.contains("context_collapsed") &&
        sidebar["context_collapsed"].is_array()) {
      prefs->sidebar_context_collapsed.clear();
      for (const auto& item : sidebar["context_collapsed"]) {
        if (item.is_string()) {
          prefs->sidebar_context_collapsed.insert(item.get<std::string>());
        }
      }
    }
  }
 
  if (root.contains("status_bar")) {
    const auto& status_bar = root["status_bar"];
    prefs->show_status_bar =
        status_bar.value("visible", prefs->show_status_bar);
  }
 
  if (root.contains("emulator")) {
    const auto& emulator = root["emulator"];
    prefs->emulator_keep_running_in_background =
        emulator.value("keep_running_in_background",
                       prefs->emulator_keep_running_in_background);
  }
 
  if (root.contains("editors")) {
    const auto& editors = root["editors"];
    prefs->show_experimental_editors =
        editors.value("show_experimental", prefs->show_experimental_editors);
  }
 
  if (root.contains("layouts")) {
    const auto& layouts = root["layouts"];
    prefs->panel_layout_defaults_revision = layouts.value(
        "defaults_revision", prefs->panel_layout_defaults_revision);
    if (layouts.contains("panel_visibility")) {
      LoadNestedBoolMap(layouts["panel_visibility"],
                        &prefs->panel_visibility_state);
    }
    if (layouts.contains("pinned_panels")) {
      LoadBoolMap(layouts["pinned_panels"], &prefs->pinned_panels);
    }
    if (layouts.contains("right_panel_widths")) {
      LoadFloatMap(layouts["right_panel_widths"], &prefs->right_panel_widths);
    }
    if (layouts.contains("saved_layouts")) {
      LoadNestedBoolMap(layouts["saved_layouts"], &prefs->saved_layouts);
    }
    if (layouts.contains("named_layouts") &&
        layouts["named_layouts"].is_object()) {
      prefs->named_layouts.clear();
      for (auto it = layouts["named_layouts"].begin();
           it != layouts["named_layouts"].end(); ++it) {
        if (it.value().is_string()) {
          prefs->named_layouts[it.key()] = it.value().get<std::string>();
        } else if (it.value().is_object() || it.value().is_array()) {
          // Preferred shape: embed the DockTree as a nested JSON object for
          // human-readability. Re-serialize to compact string for storage.
          prefs->named_layouts[it.key()] = it.value().dump();
        }
      }
    }
    prefs->last_applied_layout_name = layouts.value(
        "last_applied_layout_name", prefs->last_applied_layout_name);
  }
 
  if (root.contains("rom_load_choices")) {
    LoadStringMap(root["rom_load_choices"], &prefs->rom_load_choices);
  }
 
  if (root.contains("filesystem")) {
    const auto& fs = root["filesystem"];
    if (fs.contains("project_root_paths") &&
        fs["project_root_paths"].is_array()) {
      prefs->project_root_paths.clear();
      for (const auto& item : fs["project_root_paths"]) {
        if (item.is_string()) {
          prefs->project_root_paths.push_back(item.get<std::string>());
        }
      }
    }
    prefs->default_project_root =
        fs.value("default_project_root", prefs->default_project_root);
    prefs->use_files_app = fs.value("use_files_app", prefs->use_files_app);
    prefs->use_icloud_sync =
        fs.value("use_icloud_sync", prefs->use_icloud_sync);
  }
 
  EnsureDefaultAiHosts(prefs);
  EnsureDefaultAiProfiles(prefs);
  EnsureDefaultFilesystemRoots(prefs);
 
  return absl::OkStatus();
}
 
absl::Status SavePreferencesToJson(const std::filesystem::path& path,
                                   const UserSettings::Preferences& prefs) {
  auto ensure_status = EnsureParentDirectory(path);
  if (!ensure_status.ok()) {
    return ensure_status;
  }
 
  json root;
  root["version"] = 1;
  root["general"] = {
      {"font_global_scale", prefs.font_global_scale},
      {"backup_rom", prefs.backup_rom},
      {"save_new_auto", prefs.save_new_auto},
      {"autosave_enabled", prefs.autosave_enabled},
      {"autosave_interval", prefs.autosave_interval},
      {"recent_files_limit", prefs.recent_files_limit},
      {"last_rom_path", prefs.last_rom_path},
      {"last_project_path", prefs.last_project_path},
      {"show_welcome_on_startup", prefs.show_welcome_on_startup},
      {"test_mode", prefs.test_mode},
      {"restore_last_session", prefs.restore_last_session},
      {"prefer_hmagic_sprite_names", prefs.prefer_hmagic_sprite_names},
      {"welcome_triforce_alpha", prefs.welcome_triforce_alpha},
      {"welcome_triforce_speed", prefs.welcome_triforce_speed},
      {"welcome_triforce_size", prefs.welcome_triforce_size},
      {"welcome_particles_enabled", prefs.welcome_particles_enabled},
      {"welcome_mouse_repel_enabled", prefs.welcome_mouse_repel_enabled},
  };
 
  {
    auto set_to_sorted_vec = [](const std::unordered_set<std::string>& s)
        -> std::vector<std::string> {
      std::vector<std::string> v(s.begin(), s.end());
      std::sort(v.begin(), v.end());
      return v;
    };
    root["onboarding"] = {
        {"feature_hints_enabled", prefs.feature_hints_enabled},
        {"dismissed_feature_hints",
         set_to_sorted_vec(prefs.dismissed_feature_hints)},
    };
  }
 
  root["appearance"] = {
      {"reduced_motion", prefs.reduced_motion},
      {"switch_motion_profile", prefs.switch_motion_profile},
      {"last_theme_name", prefs.last_theme_name},
      {"language_locale", prefs.language_locale},
      {"font_family_index", prefs.font_family_index},
  };
 
  root["editor"] = {
      {"backup_before_save", prefs.backup_before_save},
      {"default_editor", prefs.default_editor},
      {"dungeon_inspector_side", prefs.dungeon_inspector_side},
  };
 
  root["performance"] = {
      {"vsync", prefs.vsync},
      {"target_fps", prefs.target_fps},
      {"cache_size_mb", prefs.cache_size_mb},
      {"undo_history_size", prefs.undo_history_size},
  };
 
  json ai_hosts = json::array();
  for (const auto& host : prefs.ai_hosts) {
    ai_hosts.push_back({
        {"id", host.id},
        {"label", host.label},
        {"base_url", host.base_url},
        {"api_type", host.api_type},
        {"supports_vision", host.supports_vision},
        {"supports_tools", host.supports_tools},
        {"supports_streaming", host.supports_streaming},
        {"allow_insecure", host.allow_insecure},
        {"api_key", host.api_key},
        {"credential_id", host.credential_id},
    });
  }
 
  json ai_profiles = json::array();
  for (const auto& profile : prefs.ai_profiles) {
    ai_profiles.push_back({
        {"name", profile.name},
        {"model", profile.model},
        {"temperature", profile.temperature},
        {"top_p", profile.top_p},
        {"max_output_tokens", profile.max_output_tokens},
        {"supports_vision", profile.supports_vision},
        {"supports_tools", profile.supports_tools},
    });
  }
 
  root["ai"] = {
      {"provider", prefs.ai_provider},
      {"model", prefs.ai_model},
      {"ollama_url", prefs.ollama_url},
      {"gemini_api_key", prefs.gemini_api_key},
      {"google_api_key", prefs.gemini_api_key},
      {"openai_api_key", prefs.openai_api_key},
      {"anthropic_api_key", prefs.anthropic_api_key},
      {"temperature", prefs.ai_temperature},
      {"max_tokens", prefs.ai_max_tokens},
      {"proactive", prefs.ai_proactive},
      {"auto_learn", prefs.ai_auto_learn},
      {"multimodal", prefs.ai_multimodal},
      {"hosts", ai_hosts},
      {"active_host_id", prefs.active_ai_host_id},
      {"profiles", ai_profiles},
      {"active_profile", prefs.active_ai_profile},
      {"remote_build_host_id", prefs.remote_build_host_id},
      {"model_paths", prefs.ai_model_paths},
  };
 
  root["logging"] = {
      {"level", prefs.log_level},
      {"to_file", prefs.log_to_file},
      {"file_path", prefs.log_file_path},
      {"ai_requests", prefs.log_ai_requests},
      {"rom_operations", prefs.log_rom_operations},
      {"gui_automation", prefs.log_gui_automation},
      {"proposals", prefs.log_proposals},
  };
 
  root["shortcuts"] = {
      {"panel", ToStringMap(prefs.panel_shortcuts)},
      {"global", ToStringMap(prefs.global_shortcuts)},
      {"editor", ToStringMap(prefs.editor_shortcuts)},
  };
 
  auto set_to_sorted_vec =
      [](const std::unordered_set<std::string>& s) -> std::vector<std::string> {
    std::vector<std::string> v(s.begin(), s.end());
    std::sort(v.begin(), v.end());
    return v;
  };
 
  root["sidebar"] = {
      {"visible", prefs.sidebar_visible},
      {"panel_expanded", prefs.sidebar_panel_expanded},
      {"panel_width", prefs.sidebar_panel_width},
      {"panel_browser_category_width", prefs.panel_browser_category_width},
      {"active_category", prefs.sidebar_active_category},
      {"order", prefs.sidebar_order},
      {"hidden", set_to_sorted_vec(prefs.sidebar_hidden)},
      {"pinned", set_to_sorted_vec(prefs.sidebar_pinned)},
      {"context_collapsed", set_to_sorted_vec(prefs.sidebar_context_collapsed)},
  };
 
  root["status_bar"] = {
      {"visible", prefs.show_status_bar},
  };
 
  root["emulator"] = {
      {"keep_running_in_background", prefs.emulator_keep_running_in_background},
  };
 
  root["editors"] = {
      {"show_experimental", prefs.show_experimental_editors},
  };
 
  // Emit named_layouts as an object of parsed JSON objects so the settings
  // file stays human-readable. Malformed or non-object bodies are stored as
  // the raw string so the next load can try to recover them.
  nlohmann::json named_layouts_json = nlohmann::json::object();
  for (const auto& [layout_name, json_body] : prefs.named_layouts) {
    nlohmann::json parsed = nlohmann::json::parse(json_body, nullptr, false);
    if (parsed.is_discarded() || !parsed.is_object()) {
      named_layouts_json[layout_name] = json_body;
    } else {
      named_layouts_json[layout_name] = std::move(parsed);
    }
  }
 
  root["layouts"] = {
      {"defaults_revision", prefs.panel_layout_defaults_revision},
      {"panel_visibility", ToNestedBoolMap(prefs.panel_visibility_state)},
      {"pinned_panels", ToBoolMap(prefs.pinned_panels)},
      {"right_panel_widths", ToFloatMap(prefs.right_panel_widths)},
      {"saved_layouts", ToNestedBoolMap(prefs.saved_layouts)},
      {"named_layouts", std::move(named_layouts_json)},
      {"last_applied_layout_name", prefs.last_applied_layout_name},
  };
 
  root["rom_load_choices"] = ToStringMap(prefs.rom_load_choices);
 
  root["filesystem"] = {
      {"project_root_paths", prefs.project_root_paths},
      {"default_project_root", prefs.default_project_root},
      {"use_files_app", prefs.use_files_app},
      {"use_icloud_sync", prefs.use_icloud_sync},
  };
 
  std::ofstream file(path);
  if (!file.is_open()) {
    return absl::InternalError(
        absl::StrFormat("Failed to open settings file: %s", path.string()));
  }
 
  file << root.dump(2) << "\n";
  return absl::OkStatus();
}
#endif  // YAZE_WITH_JSON
 
}  // namespace
 
UserSettings::UserSettings() {
  auto docs_dir_status = util::PlatformPaths::GetUserDocumentsDirectory();
  auto config_dir_status = util::PlatformPaths::GetConfigDirectory();
  if (docs_dir_status.ok()) {
    settings_file_path_ = (*docs_dir_status / "settings.json").string();
  } else if (config_dir_status.ok()) {
    settings_file_path_ = (*config_dir_status / "settings.json").string();
  } else {
    LOG_WARN("UserSettings",
             "Could not determine user documents or config directory. Using "
             "local settings.json.");
    settings_file_path_ = "settings.json";
  }
 
  if (config_dir_status.ok()) {
    legacy_settings_file_path_ =
        (*config_dir_status / "yaze_settings.ini").string();
  } else {
    legacy_settings_file_path_ = "yaze_settings.ini";
  }
}
 
absl::Status UserSettings::Load() {
  try {
    bool loaded = false;
#ifdef YAZE_WITH_JSON
    bool json_exists = util::PlatformPaths::Exists(settings_file_path_);
    if (json_exists) {
      auto status = LoadPreferencesFromJson(settings_file_path_, &prefs_);
      if (status.ok()) {
        loaded = true;
      } else {
        LOG_WARN("UserSettings", "Failed to load settings.json: %s",
                 status.ToString().c_str());
        // Preserve the unreadable file as settings.json.bak before the defaults
        // below overwrite it via Save(), so the user can recover it.
        std::error_code ec;
        std::filesystem::rename(settings_file_path_,
                                settings_file_path_ + ".bak", ec);
        if (ec) {
          LOG_WARN("UserSettings", "Could not back up settings.json: %s",
                   ec.message().c_str());
        }
      }
    }
#endif
 
    if (!loaded && util::PlatformPaths::Exists(legacy_settings_file_path_)) {
      auto status = LoadPreferencesFromIni(legacy_settings_file_path_, &prefs_);
      if (!status.ok()) {
        return status;
      }
      loaded = true;
#ifdef YAZE_WITH_JSON
      if (!util::PlatformPaths::Exists(settings_file_path_)) {
        (void)SavePreferencesToJson(settings_file_path_, prefs_);
      }
#endif
    }
 
    if (!loaded) {
#if defined(__APPLE__) && \
    (TARGET_OS_IPHONE == 1 || TARGET_IPHONE_SIMULATOR == 1)
      prefs_.sidebar_visible = false;
      prefs_.sidebar_panel_expanded = false;
#endif
      LOG_INFO("UserSettings", "Settings not found, creating defaults at: %s",
               settings_file_path_.c_str());
      return Save();
    }
 
#ifdef YAZE_WITH_JSON
    EnsureDefaultAiHosts(&prefs_);
    EnsureDefaultAiProfiles(&prefs_);
    EnsureDefaultFilesystemRoots(&prefs_);
    EnsureDefaultModelPaths(&prefs_);
#endif
 
    prefs_.switch_motion_profile =
        std::clamp(prefs_.switch_motion_profile, 0, 2);
 
    if (ImGui::GetCurrentContext() != nullptr) {
      ImGui::GetIO().FontGlobalScale = prefs_.font_global_scale;
    } else {
      LOG_WARN("UserSettings",
               "ImGui context not available; skipping FontGlobalScale update");
    }
  } catch (const std::exception& e) {
    return absl::InternalError(
        absl::StrFormat("Failed to load user settings: %s", e.what()));
  }
  return absl::OkStatus();
}
 
bool UserSettings::ApplyPanelLayoutDefaultsRevision(int target_revision) {
  if (target_revision <= 0) {
    return false;
  }
 
  bool applied = false;
 
  if (prefs_.panel_layout_defaults_revision < 4 && target_revision >= 4) {
    prefs_.sidebar_visible = true;
    prefs_.sidebar_panel_expanded = true;
    prefs_.sidebar_panel_width = 0.0f;
    prefs_.panel_browser_category_width = 260.0f;
    prefs_.sidebar_active_category.clear();
 
    prefs_.panel_visibility_state.clear();
    prefs_.pinned_panels.clear();
    prefs_.right_panel_widths.clear();
    prefs_.saved_layouts.clear();
 
    prefs_.panel_layout_defaults_revision = 4;
    applied = true;
  }
 
  if (prefs_.panel_layout_defaults_revision < 5 && target_revision >= 5) {
    auto overworld_it = prefs_.panel_visibility_state.find("Overworld");
    if (overworld_it != prefs_.panel_visibility_state.end()) {
      overworld_it->second["overworld.tile16_editor"] = false;
    }
    prefs_.panel_layout_defaults_revision = 5;
    applied = true;
  }
 
  if (prefs_.panel_layout_defaults_revision < 6 && target_revision >= 6) {
    auto overworld_it = prefs_.panel_visibility_state.find("Overworld");
    if (overworld_it != prefs_.panel_visibility_state.end()) {
      auto& overworld_windows = overworld_it->second;
      overworld_windows["overworld.canvas"] = true;
      overworld_windows["overworld.tile16_selector"] = true;
      overworld_windows["overworld.properties"] = true;
      overworld_windows["overworld.tile16_editor"] = false;
      overworld_windows["overworld.tile8_selector"] = false;
      overworld_windows["overworld.area_graphics"] = false;
      overworld_windows["overworld.item_list"] = false;
    }
    prefs_.panel_layout_defaults_revision = 6;
    applied = true;
  }
 
  // Revision 7: WindowLifecycle::Persistent collapsed into CrossEditor.
  // Force-pin the two former-Persistent panels on upgrade so always-visible
  // behavior carries through. We must overwrite an existing pinned=false
  // entry here: under the old Persistent regime that value was a silent no-op
  // (the draw loop ignored pin state for Persistent panels), so treating it
  // as a "user choice" post-collapse would be a regression, not preservation.
  // After the migration runs once, subsequent unpin actions ARE load-bearing
  // and persist normally.
  if (prefs_.panel_layout_defaults_revision < 7 && target_revision >= 7) {
    prefs_.pinned_panels["agent.oracle_ram"] = true;
    prefs_.pinned_panels["workflow.output"] = true;
    prefs_.panel_layout_defaults_revision = 7;
    applied = true;
  }
 
  if (prefs_.panel_layout_defaults_revision < 8 && target_revision >= 8) {
    auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
    if (dungeon_it != prefs_.panel_visibility_state.end()) {
      auto& dungeon_windows = dungeon_it->second;
      dungeon_windows["dungeon.workbench"] = true;
      dungeon_windows["dungeon.room_selector"] = false;
      dungeon_windows["dungeon.room_matrix"] = true;
      dungeon_windows["dungeon.object_editor"] = true;
      dungeon_windows["dungeon.room_graphics"] = true;
      dungeon_windows["dungeon.palette_editor"] = true;
    }
    prefs_.panel_layout_defaults_revision = 8;
    applied = true;
  }
 
  if (prefs_.panel_layout_defaults_revision < 9 && target_revision >= 9) {
    auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
    if (dungeon_it != prefs_.panel_visibility_state.end()) {
      auto& dungeon_windows = dungeon_it->second;
      dungeon_windows["dungeon.door_editor"] = true;
    }
    prefs_.panel_layout_defaults_revision = 9;
    applied = true;
  }
 
  if (prefs_.panel_layout_defaults_revision < 10 && target_revision >= 10) {
    auto graphics_it = prefs_.panel_visibility_state.find("Graphics");
    if (graphics_it != prefs_.panel_visibility_state.end()) {
      auto& graphics_windows = graphics_it->second;
      graphics_windows["graphics.prototype_viewer"] = true;
    }
    prefs_.panel_layout_defaults_revision = 10;
    applied = true;
  }
 
  if (prefs_.panel_layout_defaults_revision < 11 && target_revision >= 11) {
    auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
    if (dungeon_it != prefs_.panel_visibility_state.end()) {
      auto& dungeon_windows = dungeon_it->second;
      const bool legacy_object_surface =
          dungeon_windows.contains("dungeon.object_editor")
              ? dungeon_windows["dungeon.object_editor"]
              : true;
      dungeon_windows["dungeon.object_selector"] = legacy_object_surface;
    }
    prefs_.panel_layout_defaults_revision = 11;
    applied = true;
  }
 
  if (prefs_.panel_layout_defaults_revision < 12 && target_revision >= 12) {
    auto graphics_it = prefs_.panel_visibility_state.find("Graphics");
    if (graphics_it != prefs_.panel_visibility_state.end()) {
      auto& graphics_windows = graphics_it->second;
      graphics_windows["graphics.polyhedral"] = false;
    }
    prefs_.panel_layout_defaults_revision = 12;
    applied = true;
  }
 
  if (prefs_.panel_layout_defaults_revision < 13 && target_revision >= 13) {
    auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
    if (dungeon_it != prefs_.panel_visibility_state.end()) {
      auto& dungeon_windows = dungeon_it->second;
      dungeon_windows["dungeon.workbench"] = true;
      dungeon_windows["dungeon.room_selector"] = false;
      dungeon_windows["dungeon.object_selector"] = true;
      dungeon_windows["dungeon.object_editor"] = true;
      dungeon_windows["dungeon.room_graphics"] = true;
      dungeon_windows["dungeon.room_matrix"] = true;
      dungeon_windows["dungeon.palette_editor"] = true;
      dungeon_windows["dungeon.door_editor"] = false;
    }
    prefs_.panel_layout_defaults_revision = 13;
    applied = true;
  }
 
  if (prefs_.panel_layout_defaults_revision < 14 && target_revision >= 14) {
    if (prefs_.last_theme_name == "YAZE Tre") {
      prefs_.last_theme_name = "Classic YAZE";
    }
 
    auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
    if (dungeon_it != prefs_.panel_visibility_state.end()) {
      auto& dungeon_windows = dungeon_it->second;
      dungeon_windows["dungeon.object_tile_editor"] = false;
      dungeon_windows["dungeon.settings"] = false;
      dungeon_windows["dungeon.dungeon_map"] = false;
    }
 
    prefs_.panel_layout_defaults_revision = 14;
    applied = true;
  }
 
  if (prefs_.panel_layout_defaults_revision < 15 && target_revision >= 15) {
    auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
    if (dungeon_it != prefs_.panel_visibility_state.end()) {
      auto& dungeon_windows = dungeon_it->second;
      dungeon_windows["dungeon.object_selector"] = true;
      dungeon_windows["dungeon.room_graphics"] = false;
    }
    prefs_.panel_layout_defaults_revision = 15;
    applied = true;
  }
 
  // Revision 16: best-effort lift each visibility-only `saved_layouts` entry
  // into a flat single-leaf DockTree under `named_layouts`. Users who want
  // a custom dock arrangement re-author it in the Layout Designer; this
  // migration only preserves which panels were in the set, not where they
  // were docked (that information never existed in the old format).
  if (prefs_.panel_layout_defaults_revision < 16 && target_revision >= 16) {
    for (const auto& [layout_name, panel_state] : prefs_.saved_layouts) {
      if (prefs_.named_layouts.count(layout_name) != 0) {
        continue;  // Don't overwrite a DockTree the user already has.
      }
      layout_designer::DockTree tree(layout_name);
      std::vector<layout_designer::PanelEntry> panels;
      panels.reserve(panel_state.size());
      for (const auto& [panel_id, visible] : panel_state) {
        if (!visible)
          continue;
        panels.push_back({panel_id, /*display_name=*/"", /*icon=*/""});
      }
      tree.root = layout_designer::DockNode::MakeLeaf(std::move(panels));
      prefs_.named_layouts[layout_name] =
          layout_designer::DockTreeToJson(tree).dump();
    }
    prefs_.panel_layout_defaults_revision = 16;
    applied = true;
  }
 
  // Revision 17: default-pin the Layout Designer so "Show: Layout Designer"
  // from the command palette is drawable from any editor context, not just
  // when the active_category matches. Mirrors the rev-7 pattern for
  // former-Persistent panels (agent.oracle_ram, workflow.output). A user
  // who later unpins the panel keeps that choice — the block only runs
  // once on upgrade.
  if (prefs_.panel_layout_defaults_revision < 17 && target_revision >= 17) {
    prefs_.pinned_panels["layout.designer"] = true;
    prefs_.panel_layout_defaults_revision = 17;
    applied = true;
  }
 
  // Revision 18: stop carrying standalone dungeon room windows across app
  // launches. Workbench mode is now the default dungeon workflow; stale
  // `dungeon.room_*` visibility entries can resurrect dozens of room panels
  // and make the UI look broken immediately after switching to Dungeon.
  if (prefs_.panel_layout_defaults_revision < 18 && target_revision >= 18) {
    if (auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
        dungeon_it != prefs_.panel_visibility_state.end()) {
      EraseTransientPanelVisibility(&dungeon_it->second);
    }
    for (auto it = prefs_.pinned_panels.begin();
         it != prefs_.pinned_panels.end();) {
      if (IsTransientPanelVisibilityId(it->first)) {
        it = prefs_.pinned_panels.erase(it);
      } else {
        ++it;
      }
    }
    prefs_.panel_layout_defaults_revision = 18;
    applied = true;
  }
 
  // Revision 19: Selection Inspector, Dungeon Settings, and Dungeon Map are no
  // longer high-level dungeon panels. Their controls live in the Workbench
  // inspector or its transient map popup, so stale persisted panel IDs should
  // not resurrect empty/missing windows.
  if (prefs_.panel_layout_defaults_revision < 19 && target_revision >= 19) {
    if (auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
        dungeon_it != prefs_.panel_visibility_state.end()) {
      dungeon_it->second["dungeon.workbench"] = true;
      EraseEmbeddedDungeonUtilityPanelVisibility(&dungeon_it->second);
    }
    for (auto it = prefs_.pinned_panels.begin();
         it != prefs_.pinned_panels.end();) {
      if (IsEmbeddedDungeonUtilityPanelId(it->first)) {
        it = prefs_.pinned_panels.erase(it);
      } else {
        ++it;
      }
    }
    for (auto& [layout_name, panel_state] : prefs_.saved_layouts) {
      (void)layout_name;
      EraseEmbeddedDungeonUtilityPanelVisibility(&panel_state);
    }
    for (auto& [layout_name, json_body] : prefs_.named_layouts) {
      (void)layout_name;
      (void)PruneEmbeddedDungeonUtilityPanelsFromDockTreeJson(&json_body);
    }
    prefs_.panel_layout_defaults_revision = 19;
    applied = true;
  }
 
  // Revision 20: keep the Overworld editor selector-first on startup. Earlier
  // migrations hid Tile16 Editor from defaults, but persisted visibility state
  // from affected sessions can still reopen it before the user asks for it.
  if (prefs_.panel_layout_defaults_revision < 20 && target_revision >= 20) {
    if (auto overworld_it = prefs_.panel_visibility_state.find("Overworld");
        overworld_it != prefs_.panel_visibility_state.end()) {
      overworld_it->second["overworld.tile16_editor"] = false;
    }
    prefs_.panel_layout_defaults_revision = 20;
    applied = true;
  }
 
  // Revision 21: Layout C (ZScream-style) defaults for the Dungeon editor.
  // Open the three left-stack selectors (Object/Sprite/Item) plus the Room
  // Browser/Entrances surface (`dungeon.room_selector`) and Room Matrix in
  // addition to the workbench so a first-run / migrated user lands on a
  // ZScream-shaped layout. The actual L/R placement is decided by the
  // workbench window itself (it inspects `dungeon_inspector_side` at draw
  // time) and by ImGui's docking — no `left_panel_widths` map exists, and
  // adding one is out of scope for this slice. The inspector-pane width hint
  // is seeded into `right_panel_widths` for the workbench window so users see
  // a sensibly-sized inspector before they drag.
  if (prefs_.panel_layout_defaults_revision < 21 && target_revision >= 21) {
    if (auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
        dungeon_it != prefs_.panel_visibility_state.end()) {
      auto& dungeon_windows = dungeon_it->second;
      dungeon_windows["dungeon.workbench"] = true;
      dungeon_windows["dungeon.object_selector"] = true;
      dungeon_windows["dungeon.sprite_editor"] = true;
      dungeon_windows["dungeon.item_editor"] = true;
      dungeon_windows["dungeon.room_selector"] = true;
      dungeon_windows["dungeon.room_matrix"] = true;
    }
 
    // Default Layout C placement is selectors-left / inspector-right. Only
    // seed the value when the user has not already chosen one (empty string
    // from a pre-rev-21 settings file) so a future preference flip isn't
    // clobbered by the migration.
    if (prefs_.dungeon_inspector_side.empty()) {
      prefs_.dungeon_inspector_side = "right";
    }
 
    // Seed sensible widths for the workbench inspector pane. These are hints;
    // the user's drag persists through `right_panel_widths` once they adjust.
    if (!prefs_.right_panel_widths.contains("dungeon.workbench")) {
      prefs_.right_panel_widths["dungeon.workbench"] = 320.0f;
    }
 
    prefs_.panel_layout_defaults_revision = 21;
    applied = true;
  }
 
  // Revision 22: make the Dungeon Workbench the single default surface.
  // These standalone panels duplicate tools already embedded in the
  // Workbench and collectively squeeze the room canvas. Close only the live
  // Dungeon visibility entries; pinned panels and saved/named layouts are
  // explicit user customizations and must remain untouched.
  if (prefs_.panel_layout_defaults_revision < 22 && target_revision >= 22) {
    if (auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
        dungeon_it != prefs_.panel_visibility_state.end()) {
      ApplyDungeonWorkbenchVisibilityDefaults(&dungeon_it->second);
    }
 
    prefs_.panel_layout_defaults_revision = 22;
    applied = true;
  }
 
  // Revision 23: keep the global activity rail available, but collapse its
  // wide tool catalog when Dungeon is the active/default workspace. The
  // Workbench already embeds the useful room browser, canvas, and inspector;
  // showing both left panes steals enough width for responsive layout to hide
  // the room browser. Re-assert the revision-22 visibility set because an older
  // concurrently-running build can persist those duplicate windows again.
  if (prefs_.panel_layout_defaults_revision < 23 && target_revision >= 23) {
    if (auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
        dungeon_it != prefs_.panel_visibility_state.end()) {
      ApplyDungeonWorkbenchVisibilityDefaults(&dungeon_it->second);
    }
    if (prefs_.sidebar_active_category.empty() ||
        prefs_.sidebar_active_category == "Dungeon") {
      prefs_.sidebar_panel_expanded = false;
    }
 
    prefs_.panel_layout_defaults_revision = 23;
    applied = true;
  }
 
  // Revision 24: ActivityBar-only left chrome. Keep the thin category rail, but
  // collapse WindowSidebar by default so Tile16 / canvas editors reclaim width.
  if (prefs_.panel_layout_defaults_revision < 24 && target_revision >= 24) {
    prefs_.sidebar_panel_expanded = false;
    prefs_.panel_layout_defaults_revision = 24;
    applied = true;
  }
 
  // Revision 25: utility and diagnostic dungeon surfaces are hosted by the
  // Workbench first. Close only persisted live visibility; explicit pins and
  // user-authored named layouts remain untouched.
  if (prefs_.panel_layout_defaults_revision < 25 && target_revision >= 25) {
    if (auto dungeon_it = prefs_.panel_visibility_state.find("Dungeon");
        dungeon_it != prefs_.panel_visibility_state.end()) {
      ApplyDungeonPanelAdmissionDefaults(&dungeon_it->second);
    }
    prefs_.panel_layout_defaults_revision = 25;
    applied = true;
  }
 
  // Revision 26: panel admission demotions (see kRevision26DemotedWindows).
  // Only persisted live visibility changes; the windows stay reachable from
  // their hosts and the command palette.
  if (prefs_.panel_layout_defaults_revision < 26 && target_revision >= 26) {
    CloseDemotedWindowVisibility(&prefs_.panel_visibility_state);
    prefs_.panel_layout_defaults_revision = 26;
    applied = true;
  }
 
  // Revision 27: overworld area graphics opens in the right column. The
  // workspace reset that follows this revision rebuilds the dock so a saved
  // bottom strip does not keep covering the maps.
  if (prefs_.panel_layout_defaults_revision < 27 && target_revision >= 27) {
    if (auto overworld_it = prefs_.panel_visibility_state.find("Overworld");
        overworld_it != prefs_.panel_visibility_state.end()) {
      overworld_it->second["overworld.area_graphics"] = true;
      overworld_it->second["overworld.tile16_selector"] = true;
    }
    prefs_.panel_layout_defaults_revision = 27;
    applied = true;
  }
 
  // Revision 28: host Objects/Entrance above the room matrix on the right.
  // This changes only the pane side; named layouts, pins, and workspace docks
  // survive. The user's subsequent side-swap choice remains authoritative.
  if (prefs_.panel_layout_defaults_revision < 28 && target_revision >= 28) {
    prefs_.dungeon_inspector_side = "left";
    prefs_.panel_layout_defaults_revision = 28;
    applied = true;
  }
 
  // Revision 29: the Workbench owns navigation; an old live visibility
  // snapshot must not steal its embedded matrix or entrance selector. Explicit
  // named layouts and pins remain available for standalone workflows.
  if (prefs_.panel_layout_defaults_revision < 29 && target_revision >= 29) {
    auto close_unpinned = [this](const char* category, const char* id) {
      auto it = prefs_.panel_visibility_state.find(category);
      if (it == prefs_.panel_visibility_state.end())
        return;
      const auto pin = prefs_.pinned_panels.find(id);
      if (pin == prefs_.pinned_panels.end() || !pin->second) {
        it->second[id] = false;
      }
    };
    auto dungeon = prefs_.panel_visibility_state.find("Dungeon");
    if (dungeon != prefs_.panel_visibility_state.end() &&
        dungeon->second["dungeon.workbench"]) {
      close_unpinned("Dungeon", "dungeon.room_matrix");
      close_unpinned("Dungeon", "dungeon.room_selector");
      close_unpinned("Dungeon", "dungeon.entrance_list");
      close_unpinned("Dungeon", "dungeon.entrance_properties");
    }
    close_unpinned("Graphics", "graphics.link_sprite_editor");
    close_unpinned("Overworld", "overworld.cutscene_camera");
    prefs_.panel_layout_defaults_revision = 29;
    applied = true;
  }
 
  // Revision 30 consolidates ordinary Palette navigation in one workspace.
  // Preserve explicit comparison pins and named layouts; migrate only live state.
  if (prefs_.panel_layout_defaults_revision < 30 && target_revision >= 30) {
    auto palettes = prefs_.panel_visibility_state.find("Palette");
    if (palettes != prefs_.panel_visibility_state.end()) {
      for (auto& [id, visible] : palettes->second) {
        const auto pin = prefs_.pinned_panels.find(id);
        if (id != "palette.control_panel" &&
            (pin == prefs_.pinned_panels.end() || !pin->second))
          visible = false;
      }
      palettes->second["palette.control_panel"] = true;
    }
    prefs_.panel_layout_defaults_revision = 30;
    applied = true;
  }
 
  return applied;
}
 
std::string UserSettings::GetDungeonInspectorSide() const {
  const std::string& side = prefs_.dungeon_inspector_side;
  if (side == "left") {
    return "left";
  }
  return "right";
}
 
void UserSettings::SetDungeonInspectorSide(std::string side) {
  prefs_.dungeon_inspector_side = (side == "left") ? "left" : "right";
}
 
void UserSettings::ApplyWorkspaceOverrides(
    const WorkspaceOverrides& overrides) {
  if (!workspace_baseline_.has_value()) {
    workspace_baseline_ = CaptureWorkspaceFields(prefs_);
  }
  WorkspaceOverrides values = overrides;
  // Project files are hand-editable too; keep the font scale usable.
  values.font_global_scale = SanitizeFontGlobalScale(values.font_global_scale);
  WriteWorkspaceFields(values, &prefs_);
}
 
void UserSettings::ClearWorkspaceOverrides() {
  if (!workspace_baseline_.has_value()) {
    return;
  }
  WriteWorkspaceFields(*workspace_baseline_, &prefs_);
  workspace_baseline_.reset();
}
 
absl::Status UserSettings::Save() {
  try {
    // A project overlay stays out of the settings files: write the user's own
    // values for the fields it replaced.
    std::optional<Preferences> without_overlay;
    if (workspace_baseline_.has_value()) {
      without_overlay = prefs_;
      WriteWorkspaceFields(*workspace_baseline_, &*without_overlay);
    }
    const Preferences& to_write =
        without_overlay.has_value() ? *without_overlay : prefs_;
    absl::Status status = absl::OkStatus();
#ifdef YAZE_WITH_JSON
    status = SavePreferencesToJson(settings_file_path_, to_write);
    if (!status.ok()) {
      return status;
    }
#endif
    status = SavePreferencesToIni(legacy_settings_file_path_, to_write);
    if (!status.ok()) {
      return status;
    }
  } catch (const std::exception& e) {
    return absl::InternalError(
        absl::StrFormat("Failed to save user settings: %s", e.what()));
  }
  return absl::OkStatus();
}
 
}  // namespace editor
}  // namespace yaze