project.cc

Go to the documentation of this file.

#include "core/project.h"
#include "core/project_sections.h"
#include "core/sprite_asset_json.h"
 
#include <algorithm>
#include <atomic>
#include <cctype>
#include <cerrno>
#include <chrono>
#include <cstdint>
#include <cstdio>
#include <filesystem>
#include <fstream>
#include <iomanip>
#include <iterator>
#include <sstream>
#include <stdexcept>
 
#include "absl/strings/match.h"
#include "absl/strings/str_format.h"
#include "absl/strings/str_join.h"
#include "absl/strings/str_split.h"
#include "absl/strings/strip.h"
#include "app/gui/core/icons.h"
#include "core/lyra_terrain_document.h"
#include "core/native_save_receipt.h"
#include "core/source_artifact_publisher.h"
#include "imgui/imgui.h"
#include "util/file_util.h"
#include "util/json.h"
#include "util/log.h"
#include "util/macro.h"
#include "util/platform_paths.h"
#include "yaze_config.h"
#include "zelda3/resource_labels.h"
 
#if defined(YAZE_WITH_Z3DK) && __has_include("z3dk_core/config.h")
#include "z3dk_core/config.h"
#endif
 
#ifdef __EMSCRIPTEN__
#include "app/platform/wasm/wasm_storage.h"
#elif defined(_WIN32)
#include <windows.h>
#else
#include <unistd.h>
#endif
 
// #ifdef YAZE_ENABLE_JSON_PROJECT_FORMAT
// #include "nlohmann/json.hpp"
// using json = nlohmann::json;
// #endif
 
namespace yaze {
namespace project {
 
namespace {
std::string ToLowerCopy(std::string value) {
  std::transform(
      value.begin(), value.end(), value.begin(),
      [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
  return value;
}
 
// Helper functions for parsing key-value pairs
std::pair<std::string, std::string> ParseKeyValue(const std::string& line) {
  size_t eq_pos = line.find('=');
  if (eq_pos == std::string::npos)
    return {"", ""};
 
  std::string key = line.substr(0, eq_pos);
  std::string value = line.substr(eq_pos + 1);
 
  // Trim whitespace
  key.erase(0, key.find_first_not_of(" \t"));
  key.erase(key.find_last_not_of(" \t") + 1);
  value.erase(0, value.find_first_not_of(" \t"));
  value.erase(value.find_last_not_of(" \t") + 1);
 
  return {key, value};
}
 
bool ParseBool(const std::string& value) {
  return value == "true" || value == "1" || value == "yes";
}
 
float ParseFloat(const std::string& value) {
  try {
    return std::stof(value);
  } catch (...) {
    return 0.0f;
  }
}
 
std::vector<std::string> ParseStringList(const std::string& value) {
  std::vector<std::string> result;
  if (value.empty())
    return result;
 
  std::vector<std::string> parts = absl::StrSplit(value, ',');
  for (const auto& part : parts) {
    std::string trimmed = std::string(part);
    trimmed.erase(0, trimmed.find_first_not_of(" \t"));
    trimmed.erase(trimmed.find_last_not_of(" \t") + 1);
    if (!trimmed.empty()) {
      result.push_back(trimmed);
    }
  }
  return result;
}
 
std::vector<std::string> ParsePositionalStringList(const std::string& value) {
  std::vector<std::string> result;
  if (value.empty())
    return result;
 
  std::vector<std::string> parts = absl::StrSplit(value, ',');
  result.reserve(parts.size());
  for (const auto& part : parts) {
    std::string trimmed = part;
    trimmed.erase(0, trimmed.find_first_not_of(" \t"));
    trimmed.erase(trimmed.find_last_not_of(" \t") + 1);
    result.push_back(std::move(trimmed));
  }
  return result;
}
 
std::vector<uint16_t> ParseHexUintList(const std::string& value) {
  std::vector<uint16_t> result;
  if (value.empty()) {
    return result;
  }
 
  auto parts = ParseStringList(value);
  result.reserve(parts.size());
  for (const auto& part : parts) {
    std::string token = part;
    if (token.rfind("0x", 0) == 0 || token.rfind("0X", 0) == 0) {
      token = token.substr(2);
      try {
        result.push_back(static_cast<uint16_t>(std::stoul(token, nullptr, 16)));
      } catch (...) {
        // Ignore malformed entries
      }
    } else {
      try {
        result.push_back(static_cast<uint16_t>(std::stoul(token, nullptr, 10)));
      } catch (...) {
        // Ignore malformed entries
      }
    }
  }
  return result;
}
 
std::optional<uint32_t> ParseHexUint32(const std::string& value) {
  if (value.empty()) {
    return std::nullopt;
  }
  std::string token = value;
  if (token.rfind("0x", 0) == 0 || token.rfind("0X", 0) == 0) {
    token = token.substr(2);
    try {
      return static_cast<uint32_t>(std::stoul(token, nullptr, 16));
    } catch (...) {
      return std::nullopt;
    }
  }
  try {
    return static_cast<uint32_t>(std::stoul(token, nullptr, 10));
  } catch (...) {
    return std::nullopt;
  }
}
 
std::string FormatHexUintList(const std::vector<uint16_t>& values) {
  return absl::StrJoin(values, ",", [](std::string* out, uint16_t value) {
    out->append(absl::StrFormat("0x%02X", value));
  });
}
 
// Before 2026-09-25 the gfx group editor keyed blockset, roomset and
// spriteset labels as "0x" + decimal digits (spriteset 12 -> "0x12", which the
// label resolver reads as hex 18); the paletteset editor did the same until
// 2026-09-26. Canonical keys are decimal. On load:
// existing decimal keys win; "0x" + only decimal digits is that old format and
// is read as decimal; other hex keys ("0x0C") are read as hex.
void MigrateGfxGroupLabelKeys(
    std::unordered_map<std::string,
                       std::unordered_map<std::string, std::string>>& labels) {
  auto all_of = [](absl::string_view text, auto predicate) {
    return !text.empty() && std::all_of(text.begin(), text.end(), predicate);
  };
  auto is_decimal = [](char c) {
    return c >= '0' && c <= '9';
  };
  auto is_hex = [](char c) {
    return std::isxdigit(static_cast<unsigned char>(c)) != 0;
  };
  for (const char* type : {"blockset", "roomset", "spriteset", "paletteset"}) {
    auto found = labels.find(type);
    if (found == labels.end()) {
      continue;
    }
    std::unordered_map<std::string, std::string> migrated;
    // Pass 0: canonical decimal keys. Pass 1: old "0x"+decimal. Pass 2: hex.
    for (int pass = 0; pass < 3; ++pass) {
      for (const auto& [key, value] : found->second) {
        absl::string_view digits = key;
        const bool prefixed = absl::ConsumePrefix(&digits, "0x") ||
                              absl::ConsumePrefix(&digits, "0X");
        std::string canonical;
        if (pass == 0 && !prefixed && all_of(digits, is_decimal)) {
          canonical = std::string(digits);
        } else if (pass == 1 && prefixed && all_of(digits, is_decimal)) {
          canonical =
              std::to_string(std::stoul(std::string(digits), nullptr, 10));
        } else if (pass == 2 && !all_of(digits, is_decimal)) {
          // Real hex keys become decimal; anything else is kept as written.
          canonical =
              prefixed && all_of(digits, is_hex)
                  ? std::to_string(std::stoul(std::string(digits), nullptr, 16))
                  : key;
        }
        if (!canonical.empty()) {
          migrated.emplace(canonical, value);
        }
      }
    }
    found->second = std::move(migrated);
  }
}
 
// "0x55:0,1,2;0x54:3" -> {0x55: {0, 1, 2}, 0x54: {3}}
std::map<uint16_t, std::vector<uint16_t>> ParseHexUintListMap(
    const std::string& value) {
  std::map<uint16_t, std::vector<uint16_t>> result;
  for (absl::string_view entry : absl::StrSplit(value, ';')) {
    const size_t colon = entry.find(':');
    if (colon == absl::string_view::npos) {
      continue;
    }
    const auto keys = ParseHexUintList(std::string(entry.substr(0, colon)));
    if (keys.size() != 1) {
      continue;
    }
    result[keys.front()] =
        ParseHexUintList(std::string(entry.substr(colon + 1)));
  }
  return result;
}
 
std::string FormatHexUintListMap(
    const std::map<uint16_t, std::vector<uint16_t>>& values) {
  return absl::StrJoin(values, ";", [](std::string* out, const auto& entry) {
    out->append(absl::StrFormat("0x%02X:", entry.first));
    out->append(absl::StrJoin(entry.second, ","));
  });
}
 
std::string FormatHexUint32(uint32_t value) {
  return absl::StrFormat("0x%06X", value);
}
 
std::string SanitizeStorageKey(absl::string_view input) {
  std::string key(input);
  for (char& c : key) {
    if (!std::isalnum(static_cast<unsigned char>(c))) {
      c = '_';
    }
  }
  if (key.empty()) {
    key = "project";
  }
  return key;
}
 
std::pair<std::string, std::string> ParseDefineToken(const std::string& value) {
  auto [key, parsed_value] = ParseKeyValue(value);
  if (key.empty()) {
    return {value, "1"};
  }
  return {key, parsed_value.empty() ? "1" : parsed_value};
}
 
std::string ResolveOptionalPath(const std::filesystem::path& base_dir,
                                const std::string& value) {
  if (value.empty()) {
    return {};
  }
  std::filesystem::path path(value);
  if (path.is_absolute()) {
    return path.lexically_normal().string();
  }
  return (base_dir / path).lexically_normal().string();
}
 
std::string BasenameLower(const std::string& path) {
  return ToLowerCopy(std::filesystem::path(path).filename().string());
}
 
uint64_t CurrentProcessIdForProjectSave() {
#if defined(_WIN32)
  return static_cast<uint64_t>(::GetCurrentProcessId());
#elif defined(__EMSCRIPTEN__)
  return 0;
#else
  return static_cast<uint64_t>(::getpid());
#endif
}
 
std::filesystem::path MakeProjectSaveTempPath(
    const std::filesystem::path& target_path) {
  static std::atomic<uint64_t> next_temp_id{0};
  std::filesystem::path temp_path = target_path;
  temp_path +=
      ".tmp." + std::to_string(CurrentProcessIdForProjectSave()) + "." +
      std::to_string(next_temp_id.fetch_add(1, std::memory_order_relaxed));
  return temp_path;
}
 
void RemoveProjectSaveTempFile(const std::filesystem::path& temp_path) {
  std::error_code remove_error;
  std::filesystem::remove(temp_path, remove_error);
}
 
absl::Status WriteProjectFileAtomicallyImpl(
    const std::filesystem::path& target_path, absl::string_view contents,
    bool replace_existing) {
#ifdef __EMSCRIPTEN__
  if (!replace_existing) {
    // MEMFS/IDBFS do not support hard links. Exclusive fopen keeps the existing
    // synchronous virtual-filesystem workflow without replacing a destination.
    FILE* file = std::fopen(target_path.c_str(), "wbx");
    if (file == nullptr) {
      if (errno == EEXIST) {
        return absl::AlreadyExistsError(absl::StrFormat(
            "Project file already exists: %s", target_path.string()));
      }
      return absl::InternalError(absl::StrFormat(
          "Cannot create project file: %s", target_path.string()));
    }
    const bool written = std::fwrite(contents.data(), 1, contents.size(),
                                     file) == contents.size();
    const bool closed = std::fclose(file) == 0;
    if (!written || !closed) {
      RemoveProjectSaveTempFile(target_path);
      return absl::InternalError(absl::StrFormat(
          "Failed to write project file: %s", target_path.string()));
    }
    return absl::OkStatus();
  }
#endif
  const std::filesystem::path temp_path = MakeProjectSaveTempPath(target_path);
#if defined(_WIN32)
  HANDLE file = CreateFileW(temp_path.c_str(), GENERIC_WRITE, 0, nullptr,
                            CREATE_NEW, FILE_ATTRIBUTE_NORMAL, nullptr);
  if (file == INVALID_HANDLE_VALUE) {
    return absl::InvalidArgumentError(absl::StrFormat(
        "Cannot create temporary project file: %s", temp_path.string()));
  }
 
  size_t written_total = 0;
  while (written_total < contents.size()) {
    const DWORD chunk = static_cast<DWORD>(
        std::min<size_t>(contents.size() - written_total, 1024 * 1024));
    DWORD written = 0;
    if (!WriteFile(file, contents.data() + written_total, chunk, &written,
                   nullptr) ||
        written == 0) {
      CloseHandle(file);
      RemoveProjectSaveTempFile(temp_path);
      return absl::InternalError(absl::StrFormat(
          "Failed to write temporary project file: %s", temp_path.string()));
    }
    written_total += written;
  }
  if (!FlushFileBuffers(file)) {
    CloseHandle(file);
    RemoveProjectSaveTempFile(temp_path);
    return absl::InternalError(absl::StrFormat(
        "Failed to write temporary project file: %s", temp_path.string()));
  }
  if (!CloseHandle(file)) {
    RemoveProjectSaveTempFile(temp_path);
    return absl::InternalError(absl::StrFormat(
        "Failed to close temporary project file: %s", temp_path.string()));
  }
#else
  // Exclusive creation establishes ownership; never reopen the staging path.
  FILE* file = std::fopen(temp_path.c_str(), "wbx");
  if (file == nullptr) {
    return absl::InvalidArgumentError(absl::StrFormat(
        "Cannot create temporary project file: %s", temp_path.string()));
  }
  const bool written =
      std::fwrite(contents.data(), 1, contents.size(), file) == contents.size();
  const bool flushed = std::fflush(file) == 0;
  const bool closed = std::fclose(file) == 0;
  if (!written || !flushed) {
    RemoveProjectSaveTempFile(temp_path);
    return absl::InternalError(absl::StrFormat(
        "Failed to write temporary project file: %s", temp_path.string()));
  }
  if (!closed) {
    RemoveProjectSaveTempFile(temp_path);
    return absl::InternalError(absl::StrFormat(
        "Failed to close temporary project file: %s", temp_path.string()));
  }
#endif
 
  std::error_code rename_error;
#if defined(_WIN32)
  const DWORD move_flags =
      MOVEFILE_WRITE_THROUGH |
      (replace_existing ? MOVEFILE_REPLACE_EXISTING : static_cast<DWORD>(0));
  if (!::MoveFileExW(temp_path.c_str(), target_path.c_str(), move_flags)) {
    rename_error = std::error_code(static_cast<int>(::GetLastError()),
                                   std::system_category());
  }
#elif defined(__EMSCRIPTEN__)
  std::filesystem::rename(temp_path, target_path, rename_error);
#else
  if (replace_existing) {
    std::filesystem::rename(temp_path, target_path, rename_error);
  } else if (::link(temp_path.c_str(), target_path.c_str()) != 0) {
    rename_error = std::error_code(errno, std::generic_category());
  } else {
    RemoveProjectSaveTempFile(temp_path);
  }
#endif
  if (rename_error) {
    RemoveProjectSaveTempFile(temp_path);
    bool target_already_exists = rename_error == std::errc::file_exists;
#if defined(_WIN32)
    target_already_exists = target_already_exists ||
                            rename_error.value() == ERROR_FILE_EXISTS ||
                            rename_error.value() == ERROR_ALREADY_EXISTS;
#endif
    if (!replace_existing && target_already_exists) {
      return absl::AlreadyExistsError(absl::StrFormat(
          "Project file already exists: %s", target_path.string()));
    }
    return absl::InternalError(
        absl::StrFormat("Failed to replace project file %s: %s",
                        target_path.string(), rename_error.message()));
  }
 
  return absl::OkStatus();
}
}  // namespace
 
absl::Status WriteProjectFileAtomically(absl::string_view target_path,
                                        absl::string_view contents,
                                        bool replace_existing) {
  return WriteProjectFileAtomicallyImpl(
      std::filesystem::path(std::string(target_path)), contents,
      replace_existing);
}
 
std::string RomRoleToString(RomRole role) {
  switch (role) {
    case RomRole::kBase:
      return "base";
    case RomRole::kPatched:
      return "patched";
    case RomRole::kRelease:
      return "release";
    case RomRole::kDev:
    default:
      return "dev";
  }
}
 
RomRole ParseRomRole(absl::string_view value) {
  std::string lower = ToLowerCopy(std::string(value));
  if (lower == "base") {
    return RomRole::kBase;
  }
  if (lower == "patched") {
    return RomRole::kPatched;
  }
  if (lower == "release") {
    return RomRole::kRelease;
  }
  return RomRole::kDev;
}
 
std::string RomWritePolicyToString(RomWritePolicy policy) {
  switch (policy) {
    case RomWritePolicy::kAllow:
      return "allow";
    case RomWritePolicy::kBlock:
      return "block";
    case RomWritePolicy::kReadOnly:
      return "read_only";
    case RomWritePolicy::kWarn:
    default:
      return "warn";
  }
}
 
RomWritePolicy ParseRomWritePolicy(absl::string_view value) {
  std::string lower = ToLowerCopy(std::string(value));
  if (lower == "allow") {
    return RomWritePolicy::kAllow;
  }
  if (lower == "block") {
    return RomWritePolicy::kBlock;
  }
  if (lower == "read_only") {
    return RomWritePolicy::kReadOnly;
  }
  return RomWritePolicy::kWarn;
}
 
// YazeProject Implementation
YazeProject::~YazeProject() {
  auto& provider = zelda3::GetResourceLabels();
  if (provider.hack_manifest() == &hack_manifest) {
    provider.SetHackManifest(nullptr);
  }
  if (provider.GetAllProjectLabels() == &resource_labels) {
    provider.SetProjectLabels(nullptr);
  }
}
 
absl::Status YazeProject::Create(const std::string& project_name,
                                 const std::string& base_path) {
  name = project_name;
  filepath = base_path + "/" + project_name + ".yaze";
 
  // Initialize metadata
  auto now = std::chrono::system_clock::now();
  auto time_t = std::chrono::system_clock::to_time_t(now);
  std::stringstream ss;
  ss << std::put_time(std::localtime(&time_t), "%Y-%m-%d %H:%M:%S");
 
  metadata.created_date = ss.str();
  metadata.last_modified = ss.str();
  metadata.yaze_version = YAZE_VERSION_STRING;
  metadata.version = "2.0";
  metadata.created_by = "YAZE";
  metadata.project_id = GenerateProjectId();
 
  InitializeDefaults();
 
#ifndef __EMSCRIPTEN__
  // Create project directory structure
  std::filesystem::path project_dir(base_path + "/" + project_name);
  std::filesystem::create_directories(project_dir);
  std::filesystem::create_directories(project_dir / "code");
  std::filesystem::create_directories(project_dir / "assets");
  std::filesystem::create_directories(project_dir / "patches");
  std::filesystem::create_directories(project_dir / "backups");
  std::filesystem::create_directories(project_dir / "output");
 
  // Set folder paths
  code_folder = (project_dir / "code").string();
  assets_folder = (project_dir / "assets").string();
  patches_folder = (project_dir / "patches").string();
  rom_backup_folder = (project_dir / "backups").string();
  output_folder = (project_dir / "output").string();
  labels_filename = (project_dir / "labels.txt").string();
  symbols_filename = (project_dir / "symbols.txt").string();
#else
  // WASM: keep paths relative; persistence handled by WasmStorage/IDBFS
  code_folder = "code";
  assets_folder = "assets";
  patches_folder = "patches";
  rom_backup_folder = "backups";
  output_folder = "output";
  labels_filename = "labels.txt";
  symbols_filename = "symbols.txt";
#endif
 
  return Save();
}
 
// static
std::string YazeProject::ResolveBundleRoot(const std::string& path) {
  if (path.empty()) {
    return {};
  }
 
  // Walk up the path hierarchy looking for a directory whose filename
  // (extension) is ".yazeproj". The first match from the leaf upward wins.
  std::error_code ec;
  auto current = std::filesystem::path(path).lexically_normal();
 
  for (; !current.empty(); current = current.parent_path()) {
    if (current.extension() == ".yazeproj") {
      // Must be an existing directory to count as a valid bundle root.
      if (std::filesystem::is_directory(current, ec) && !ec) {
        return current.string();
      }
    }
    // Guard against infinite loop at the filesystem root.
    if (current == current.parent_path()) {
      break;
    }
  }
 
  return {};
}
 
absl::Status YazeProject::Open(const std::string& project_path) {
  // Resolve bundle root: if the user opened a file *inside* a .yazeproj
  // bundle, normalize to the bundle root directory so the existing
  // .yazeproj handling takes over.
  std::string resolved_path = project_path;
  const std::string bundle_root = ResolveBundleRoot(project_path);
  if (!bundle_root.empty() && bundle_root != project_path) {
    // The user pointed at a file inside a bundle; redirect to the root.
    resolved_path = bundle_root;
  }
 
#ifndef __EMSCRIPTEN__
  // Keep the project root stable even when a caller supplies a relative path.
  // All project-relative files and registry fallbacks must resolve beside the
  // project, not against whichever working directory happens to be active
  // later in the session.
  std::error_code absolute_ec;
  const auto absolute_path =
      std::filesystem::absolute(resolved_path, absolute_ec).lexically_normal();
  if (!absolute_ec) {
    resolved_path = absolute_path.string();
  }
#endif
 
  filepath = resolved_path;
 
#ifdef __EMSCRIPTEN__
  // Prefer persistent storage in WASM builds
  auto storage_key = MakeStorageKey("project");
  auto storage_or = platform::WasmStorage::LoadProject(storage_key);
  if (storage_or.ok()) {
    return ParseFromString(storage_or.value());
  }
#endif
 
  // Determine format and load accordingly
  absl::Status load_status;
  if (resolved_path.ends_with(".yazeproj")) {
    format = ProjectFormat::kYazeNative;
 
    const std::filesystem::path bundle_path(resolved_path);
    std::error_code ec;
    if (!std::filesystem::exists(bundle_path, ec) || ec ||
        !std::filesystem::is_directory(bundle_path, ec) || ec) {
      return absl::InvalidArgumentError(
          absl::StrFormat("Project bundle does not exist: %s", resolved_path));
    }
 
    // Bundle convention: store the actual project config at the root so both
    // desktop and iOS can open the same `.yazeproj` directory.
    const std::filesystem::path project_file = bundle_path / "project.yaze";
    filepath = project_file.string();
 
    if (!std::filesystem::exists(project_file, ec) || ec) {
      // Create a minimal portable project file for the bundle if missing.
      InitializeDefaults();
      name = bundle_path.stem().string();
 
      // Initialize metadata timestamps (Create() normally does this).
      auto now = std::chrono::system_clock::now();
      auto time_t = std::chrono::system_clock::to_time_t(now);
      std::stringstream ss;
      ss << std::put_time(std::localtime(&time_t), "%Y-%m-%d %H:%M:%S");
      if (metadata.created_date.empty()) {
        metadata.created_date = ss.str();
      }
      metadata.last_modified = ss.str();
      if (metadata.yaze_version.empty()) {
        metadata.yaze_version = YAZE_VERSION_STRING;
      }
      if (metadata.version.empty()) {
        metadata.version = "2.0";
      }
      if (metadata.created_by.empty()) {
        metadata.created_by = "YAZE";
      }
      if (metadata.project_id.empty()) {
        metadata.project_id = GenerateProjectId();
      }
 
      // Bundle layout defaults (paths stored as absolute; serializer writes
      // relative values for portability).
      const std::filesystem::path rom_candidate = bundle_path / "rom";
      // Always set the expected bundle ROM path even if the file is not yet
      // present on disk (e.g. still downloading from iCloud). The load
      // attempt in LoadProjectWithRom() handles the missing-file case without
      // corrupting the project by saving a temporary path.
      rom_filename = rom_candidate.string();
 
      const std::filesystem::path project_dir = bundle_path / "project";
      const std::filesystem::path code_dir = bundle_path / "code";
      if (std::filesystem::exists(project_dir, ec) &&
          std::filesystem::is_directory(project_dir, ec) && !ec) {
        code_folder = project_dir.string();
      } else if (std::filesystem::exists(code_dir, ec) &&
                 std::filesystem::is_directory(code_dir, ec) && !ec) {
        code_folder = code_dir.string();
      }
 
      assets_folder = (bundle_path / "assets").string();
      patches_folder = (bundle_path / "patches").string();
      rom_backup_folder = (bundle_path / "backups").string();
      output_folder = (bundle_path / "output").string();
      labels_filename = (bundle_path / "labels.txt").string();
      symbols_filename = (bundle_path / "symbols.txt").string();
 
      load_status = SaveToYazeFormat();
    } else {
      load_status = LoadFromYazeFormat(project_file.string());
    }
  } else if (resolved_path.ends_with(".yaze")) {
    format = ProjectFormat::kYazeNative;
 
    // Try to detect if it's JSON format by peeking at first character
    std::ifstream file(resolved_path);
    if (file.is_open()) {
      std::stringstream buffer;
      buffer << file.rdbuf();
      std::string content = buffer.str();
 
#ifdef YAZE_ENABLE_JSON_PROJECT_FORMAT
      if (!content.empty() && content.front() == '{') {
        LOG_DEBUG("Project", "Detected JSON format project file");
        load_status = LoadFromJsonFormat(resolved_path);
      } else {
        load_status = ParseFromString(content);
      }
#else
      load_status = ParseFromString(content);
#endif
    } else {
      return absl::InvalidArgumentError(
          absl::StrFormat("Cannot open project file: %s", resolved_path));
    }
  } else if (resolved_path.ends_with(".zsproj")) {
    format = ProjectFormat::kZScreamCompat;
    load_status = ImportFromZScreamFormat(resolved_path);
  } else {
    return absl::InvalidArgumentError("Unsupported project file format");
  }
 
  if (!load_status.ok()) {
    return load_status;
  }
 
  // Normalize project-relative paths so downstream code never depends on the
  // process working directory (important for iOS and portable bundles).
  NormalizePathsToAbsolute();
 
  // Auto-load z3dk project config if discoverable.
  TryLoadZ3dkConfig();
 
  // Auto-load hack manifest if configured or discoverable
  TryLoadHackManifest();
 
  return absl::OkStatus();
}
 
absl::Status YazeProject::Save() {
  return SaveToYazeFormat();
}
 
absl::Status YazeProject::SaveNew() {
  return SaveToYazeFormat(false);
}
 
absl::Status YazeProject::LoadFromString(const std::string& content,
                                         const std::string& project_path) {
  if (project_path.empty()) {
    return absl::InvalidArgumentError("Project file path cannot be empty");
  }
 
  *this = YazeProject();
 
#ifndef __EMSCRIPTEN__
  std::error_code ec;
  const auto absolute_path =
      std::filesystem::absolute(project_path, ec).lexically_normal();
  filepath =
      ec ? std::filesystem::path(project_path).lexically_normal().string()
         : absolute_path.string();
#else
  filepath = project_path;
#endif
  format = ProjectFormat::kYazeNative;
  try {
    RETURN_IF_ERROR(ParseFromString(content));
  } catch (const std::exception& error) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Invalid project file value: %s", error.what()));
  }
  NormalizePathsToAbsolute();
  TryLoadZ3dkConfig();
  TryLoadHackManifest();
  return absl::OkStatus();
}
 
absl::Status YazeProject::ValidateSavedSourceBindings(
    const std::string& content) const {
  YazeProject saved;
  saved.filepath = filepath;
  try {
    RETURN_IF_ERROR(saved.ParseFromString(content));
    saved.NormalizePathsToAbsolute();
  } catch (const std::exception& error) {
    return absl::InvalidArgumentError(
        std::string("Invalid saved project bindings: ") + error.what());
  }
  ASSIGN_OR_RETURN(const auto live_text, SerializeToString());
  ASSIGN_OR_RETURN(const auto saved_text, saved.SerializeToString());
  const auto bindings = [](const std::string& text) {
    std::map<std::pair<std::string, std::string>, std::string> values;
    std::istringstream input(text);
    std::string line, section;
    while (std::getline(input, line)) {
      const auto trimmed = absl::StripAsciiWhitespace(line);
      if (trimmed.empty() || trimmed.front() == '#')
        continue;
      if (trimmed.front() == '[' && trimmed.back() == ']') {
        section = std::string(trimmed.substr(1, trimmed.size() - 2));
        continue;
      }
      // These sections are transient application preferences, not sources.
      if (section == "workspace" || section == "keybindings" ||
          section == "editor_visibility" || section == "agent_settings")
        continue;
      const auto [key, value] = ParseKeyValue(std::string(trimmed));
      if (key.empty() || (section == "project" &&
                          (key == "last_modified" || key == "created_date")))
        continue;
      values[{section, key}] = value;
    }
    return values;
  };
  const auto live_bindings = bindings(live_text);
  const auto saved_bindings = bindings(saved_text);
  const auto mismatch = [](const auto& key) {
    return absl::FailedPreconditionError(
        "Saved project source bindings differ from the active project: [" +
        key.first + "] " + key.second);
  };
  for (const auto& [key, value] : live_bindings) {
    const auto saved = saved_bindings.find(key);
    if (saved == saved_bindings.end() || saved->second != value)
      return mismatch(key);
  }
  for (const auto& [key, value] : saved_bindings) {
    if (live_bindings.find(key) == live_bindings.end())
      return mismatch(key);
  }
  return absl::OkStatus();
}
 
namespace {
#if defined(YAZE_WITH_JSON) && !defined(__EMSCRIPTEN__)
absl::Status ExpandedRunError(const std::string& message) {
  return absl::FailedPreconditionError("Expanded run target unavailable: " +
                                       message);
}
absl::Status ExpandedRunRequire(bool valid, const std::string& message) {
  return valid ? absl::OkStatus() : ExpandedRunError(message);
}
std::string ExpandedRunPathText(const std::filesystem::path& path) {
  const auto text = path.generic_u8string();
  return std::string(text.begin(), text.end());
}
absl::StatusOr<std::string> ExpandedRunCanonical(const std::string& text) {
  const auto path = std::filesystem::u8path(text);
  if (text.empty() || !path.is_absolute()) {
    return ExpandedRunError("an absolute evidence path is required");
  }
  std::error_code error;
  const auto canonical = std::filesystem::weakly_canonical(path, error);
  if (error) {
    return ExpandedRunError("cannot resolve evidence path: " + text);
  }
  return ExpandedRunPathText(canonical);
}
#endif
}  // namespace
 
absl::StatusOr<std::optional<std::string>>
YazeProject::ResolveExpandedBuildRunTarget(
    const std::string& editing_source_path) const {
  if (lyra_build_request_file.empty()) {
    return std::optional<std::string>{};
  }
#if !defined(YAZE_WITH_JSON) || defined(__EMSCRIPTEN__)
  return absl::UnimplementedError(
      "Expanded run target verification requires desktop JSON support");
#else
  namespace fs = std::filesystem;
  if (!project_opened() || native_save_producer_file.empty() ||
      native_save_transfer_proof_file.empty() || lyra_terrain_file.empty() ||
      build_target.empty() || code_folder.empty() ||
      editing_source_path.empty()) {
    return ExpandedRunError("complete saved expanded references are required");
  }
  try {
    ASSIGN_OR_RETURN(const auto descriptor, ExpandedRunCanonical(filepath));
    const auto resolve = [&](const std::string& ref) {
      return ExpandedRunCanonical(GetAbsolutePath(ref));
    };
    ASSIGN_OR_RETURN(const auto rom, resolve(rom_filename));
    ASSIGN_OR_RETURN(const auto terrain, resolve(lyra_terrain_file));
    ASSIGN_OR_RETURN(const auto request_path, resolve(lyra_build_request_file));
    ASSIGN_OR_RETURN(const auto producer_path,
                     resolve(native_save_producer_file));
    ASSIGN_OR_RETURN(const auto future_proof,
                     resolve(native_save_transfer_proof_file));
    ASSIGN_OR_RETURN(const auto candidate, resolve(build_target));
    ASSIGN_OR_RETURN(const auto engine, resolve(code_folder));
    ASSIGN_OR_RETURN(
        const auto authority,
        core::GetNativeSaveContext(editing_source_path, descriptor));
    const fs::path target = fs::u8path(candidate);
    const auto relative =
        target.lexically_relative(fs::u8path(engine) / "Roms");
    RETURN_IF_ERROR(ExpandedRunRequire(
        target.filename() == "oos168x.sfc" && !relative.empty() &&
            !relative.is_absolute() && *relative.begin() != ".." &&
            !relative.parent_path().empty(),
        "build_target must name a generation under the project engine"));
 
    // These are freshness joins for artifacts already authenticated by Oracle's
    // compiler. They do not reproduce allocation or native-verifier policy.
    uint64_t remaining = 8ULL * 1024 * 1024 * 1024;
    std::vector<Json> observed;
    const auto check_file = [&](const Json& row) -> absl::Status {
      ASSIGN_OR_RETURN(const auto name,
                       ExpandedRunCanonical(row.at("path").get<std::string>()));
      const auto path = fs::u8path(name);
      const auto expected = row.at("sha256").get<std::string>();
      std::error_code file_error;
      const auto size = fs::file_size(path, file_error);
      RETURN_IF_ERROR(ExpandedRunRequire(
          !file_error && fs::is_regular_file(path, file_error) && !file_error &&
              fs::u8path(row.at("path").get<std::string>()) == path &&
              expected.size() == 64 && size <= 1024ULL * 1024 * 1024 &&
              size <= remaining,
          "an evidence file is missing, changed, or exceeds its bounds"));
      remaining -= size;
      for (const char* key : {"size", "bytes"}) {
        if (row.contains(key)) {
          RETURN_IF_ERROR(
              ExpandedRunRequire(row.at(key).is_number_unsigned() &&
                                     row.at(key).get<uint64_t>() == size,
                                 "an evidence byte count differs"));
        }
      }
      ASSIGN_OR_RETURN(const auto actual,
                       core::ComputeSourceArtifactFileSha256(path));
      return ExpandedRunRequire(actual == expected,
                                "evidence changed: " + name);
    };
    const auto check = [&](const Json& row) -> absl::Status {
      RETURN_IF_ERROR(ExpandedRunRequire(observed.size() < 8192,
                                         "too many evidence bindings"));
      RETURN_IF_ERROR(check_file(row));
      observed.push_back(row);
      return absl::OkStatus();
    };
    const auto rows = [&](const Json& values) -> absl::Status {
      RETURN_IF_ERROR(ExpandedRunRequire(
          (values.is_array() || values.is_object()) && values.size() <= 4096,
          "an evidence binding collection is malformed"));
      for (const auto& row : values)
        RETURN_IF_ERROR(check(row));
      return absl::OkStatus();
    };
    const auto read_text =
        [&](const std::string& name) -> absl::StatusOr<std::string> {
      std::error_code file_error;
      const auto path = fs::u8path(name);
      const auto size = fs::file_size(path, file_error);
      RETURN_IF_ERROR(
          ExpandedRunRequire(!file_error && size <= 16 * 1024 * 1024,
                             "metadata is missing or too large"));
      std::ifstream stream(path, std::ios::binary);
      std::string raw(static_cast<size_t>(size), '\0');
      stream.read(raw.data(), static_cast<std::streamsize>(raw.size()));
      char extra;
      RETURN_IF_ERROR(ExpandedRunRequire(
          stream.gcount() == static_cast<std::streamsize>(raw.size()) &&
              !stream.get(extra) && !stream.bad(),
          "metadata changed while reading"));
      RETURN_IF_ERROR(check(Json{
          {"path", name}, {"sha256", core::ComputeSourceArtifactSha256(raw)}}));
      return raw;
    };
    const auto load = [&](const std::string& name) -> absl::StatusOr<Json> {
      ASSIGN_OR_RETURN(const auto raw, read_text(name));
      auto document =
          Json::parse(raw, [](int depth, Json::parse_event_t, Json&) {
            if (depth > 64)
              throw std::runtime_error("evidence nesting is too deep");
            return true;
          });
      RETURN_IF_ERROR(ExpandedRunRequire(document.is_object(),
                                         "evidence JSON must be an object"));
      return document;
    };
    const auto same_path = [&](const Json& value,
                               const std::string& expected) -> absl::Status {
      ASSIGN_OR_RETURN(const auto path,
                       ExpandedRunCanonical(value.get<std::string>()));
      return ExpandedRunRequire(path == expected,
                                "evidence belongs to another path");
    };
    const auto sibling = [&](const char* name) {
      return ExpandedRunPathText(target.parent_path() / name);
    };
    ASSIGN_OR_RETURN(const auto build, load(sibling("oos168x.build.json")));
    RETURN_IF_ERROR(ExpandedRunRequire(
        build.at("schema_version") == 1 &&
            (build.at("state") == "completed" ||
             build.at("state") == "completed_with_gaps") &&
            build.at("finish").at("exit_code") == 0 &&
            build.at("finish").at("required_gaps") == Json::array(),
        "the selected build is incomplete or failed"));
    RETURN_IF_ERROR(same_path(build.at("root"), engine));
    const auto& artifacts = build.at("artifacts");
    for (const char* key :
         {"output_rom", "symbols", "lyra_prepare", "lyra_verification"}) {
      RETURN_IF_ERROR(
          ExpandedRunRequire(artifacts.at(key).contains("size"),
                             "a build artifact byte count is absent"));
      RETURN_IF_ERROR(check(artifacts.at(key)));
    }
    RETURN_IF_ERROR(check(build.at("base_rom")));
    RETURN_IF_ERROR(same_path(build.at("base_rom").at("path"), rom));
    RETURN_IF_ERROR(
        same_path(artifacts.at("output_rom").at("path"), candidate));
    RETURN_IF_ERROR(
        ExpandedRunRequire(artifacts.at("output_rom").at("size") == 0x400000,
                           "the expanded output must be exactly 4 MiB"));
    RETURN_IF_ERROR(
        same_path(artifacts.at("symbols").at("path"), sibling("oos168x.sym")));
    RETURN_IF_ERROR(same_path(artifacts.at("lyra_verification").at("path"),
                              sibling("oos168x.lyra-verification.json")));
    ASSIGN_OR_RETURN(
        const auto prepared,
        load(artifacts.at("lyra_prepare").at("path").get<std::string>()));
    ASSIGN_OR_RETURN(
        const auto verified,
        load(artifacts.at("lyra_verification").at("path").get<std::string>()));
    RETURN_IF_ERROR(ExpandedRunRequire(
        prepared.at("kind") == "lyra.current_build_prepare.v1" &&
            verified.at("kind") == "lyra.current_build_verification.v1" &&
            verified.at("compiled_consumers_verified") == true &&
            verified.at("prepared_sha256") ==
                artifacts.at("lyra_prepare").at("sha256") &&
            verified.at("compiled_rom_sha256") ==
                artifacts.at("output_rom").at("sha256") &&
            verified.at("symbols_sha256") ==
                artifacts.at("symbols").at("sha256") &&
            verified.at("saved_rom_sha256") ==
                build.at("base_rom").at("sha256") &&
            prepared.at("saved_rom_sha256") == verified.at("saved_rom_sha256"),
        "compiled verification does not bind this build"));
    for (const char* flag :
         {"selected", "allocation_granted", "producer_enforcement_verified",
          "runtime_admission", "ordinary_build_ready"}) {
      RETURN_IF_ERROR(ExpandedRunRequire(
          prepared.at(flag).is_boolean() && prepared.at(flag).get<bool>(),
          "expanded build admission is incomplete"));
    }
    RETURN_IF_ERROR(
        ExpandedRunRequire(!prepared.contains("runtime_scope"),
                           "a private preview is not an ordinary run target"));
    RETURN_IF_ERROR(same_path(prepared.at("project"), descriptor));
    RETURN_IF_ERROR(same_path(prepared.at("base_rom"), rom));
    RETURN_IF_ERROR(same_path(prepared.at("request"), request_path));
    RETURN_IF_ERROR(rows(prepared.at("inputs")));
    const Json* request_binding = nullptr;
    for (const auto& row : prepared.at("inputs")) {
      ASSIGN_OR_RETURN(const auto path,
                       ExpandedRunCanonical(row.at("path").get<std::string>()));
      if (path == request_path)
        request_binding = &row;
    }
    RETURN_IF_ERROR(
        ExpandedRunRequire(request_binding != nullptr,
                           "the preparation omits its request binding"));
    RETURN_IF_ERROR(check(*request_binding));
    ASSIGN_OR_RETURN(const auto request, load(request_path));
    const auto& live = request.at("live");
    const auto& plan = prepared.at("terrain_plan");
    RETURN_IF_ERROR(ExpandedRunRequire(
        request.at("kind") == "lyra.current_save_transfer_request.v1" &&
            plan.at("target") == request.at("target") &&
            plan.at("transfer_id") == request.at("transfer_id") &&
            plan.at("generation") == live.at("generation") &&
            plan.at("operation_id") == live.at("operation_id") &&
            plan.at("save_context") == live.at("save_context"),
        "the prepared transfer or saved generation differs"));
    RETURN_IF_ERROR(same_path(request.at("target").at("path"), candidate));
    RETURN_IF_ERROR(same_path(live.at("project"), descriptor));
    RETURN_IF_ERROR(same_path(live.at("producer").at("path"), producer_path));
    RETURN_IF_ERROR(same_path(live.at("enforcement_receipt"), future_proof));
    RETURN_IF_ERROR(same_path(live.at("inputs").at("rom").at("path"), rom));
    RETURN_IF_ERROR(
        same_path(live.at("inputs").at("project").at("path"), descriptor));
    RETURN_IF_ERROR(
        same_path(live.at("inputs").at("terrain").at("path"), terrain));
    RETURN_IF_ERROR(rows(live.at("inputs")));
    RETURN_IF_ERROR(rows(request.at("inputs")));
    for (const char* key : {"producer", "save_receipt", "save_context"})
      RETURN_IF_ERROR(check(live.at(key)));
    for (const char* key : {"observation", "save_snapshot", "producer_snapshot",
                            "context_snapshot"})
      RETURN_IF_ERROR(check(request.at(key)));
    const auto& producer = live.at("producer_identity");
    RETURN_IF_ERROR(check(producer.at("editor")));
    RETURN_IF_ERROR(check(producer.at("verifier")));
    RETURN_IF_ERROR(rows(producer.at("source_bindings")));
    RETURN_IF_ERROR(check(plan.at("enforcement_receipt")));
    if (request.contains("native_verification"))
      RETURN_IF_ERROR(check(request.at("native_verification")));
    if (plan.at("enforcement_owner") == "oracle.current_builder") {
      RETURN_IF_ERROR(ExpandedRunRequire(
          plan.at("enforcement_receipt") == request.at("native_verification"),
          "the builder enforcement binding differs"));
    } else {
      RETURN_IF_ERROR(
          ExpandedRunRequire(plan.at("enforcement_owner") == "legacy_producer",
                             "the enforcement owner is unsupported"));
      RETURN_IF_ERROR(
          same_path(plan.at("enforcement_receipt").at("path"), future_proof));
    }
 
    const auto receipt_path = descriptor + ".native-save.json";
    RETURN_IF_ERROR(
        same_path(live.at("save_receipt").at("path"), receipt_path));
    RETURN_IF_ERROR(same_path(live.at("save_context").at("path"),
                              ExpandedRunPathText(authority.path)));
    ASSIGN_OR_RETURN(const auto receipt, load(receipt_path));
    ASSIGN_OR_RETURN(const auto context,
                     load(ExpandedRunPathText(authority.path)));
    RETURN_IF_ERROR(ExpandedRunRequire(
        receipt.at("kind") == "yaze.native_save.v1" &&
            receipt.at("bindings_complete") == true &&
            receipt.at("binding_errors") == Json::array() &&
            live.at("generation").is_number_unsigned() &&
            live.at("generation").get<uint64_t>() > 0 &&
            live.at("operation_id").is_string() &&
            !live.at("operation_id").get_ref<const std::string&>().empty() &&
            receipt.at("generation") == live.at("generation") &&
            receipt.at("operation_id") == live.at("operation_id") &&
            context.at("kind") == "yaze.native_save_context.v1" &&
            context.at("state") == "committed" &&
            context.at("native_commit").at("generation") ==
                live.at("generation") &&
            context.at("native_commit").at("operation_id") ==
                live.at("operation_id"),
        "native Save completion or current context differs"));
    RETURN_IF_ERROR(same_path(receipt.at("receipt_path"), receipt_path));
    RETURN_IF_ERROR(same_path(context.at("native_commit").at("receipt_path"),
                              receipt_path));
    RETURN_IF_ERROR(same_path(context.at("editing_source_path"),
                              authority.editing_source_path));
    RETURN_IF_ERROR(same_path(context.at("project_path"), descriptor));
    RETURN_IF_ERROR(same_path(context.at("rom_path"), rom));
    const Json* saved_producer = nullptr;
    for (const auto& row : receipt.at("artifacts")) {
      if (row.at("role") == "producer")
        saved_producer = &row;
    }
    RETURN_IF_ERROR(ExpandedRunRequire(
        saved_producer != nullptr &&
            context.at("producer") == *saved_producer &&
            saved_producer->at("sha256") == producer.at("editor").at("sha256"),
        "native Save and context producers differ"));
    ASSIGN_OR_RETURN(const auto editor_path,
                     ExpandedRunCanonical(
                         producer.at("editor").at("path").get<std::string>()));
    RETURN_IF_ERROR(same_path(saved_producer->at("path"), editor_path));
    ASSIGN_OR_RETURN(const auto saved_descriptor, read_text(descriptor));
    RETURN_IF_ERROR(ValidateSavedSourceBindings(saved_descriptor));
    for (const auto& binding : observed)
      RETURN_IF_ERROR(check_file(binding));
    return std::optional<std::string>(candidate);
  } catch (const std::exception& error) {
    return ExpandedRunError(
        std::string("invalid or incomplete build evidence: ") + error.what());
  }
#endif
}
absl::Status YazeProject::SaveAs(const std::string& new_path) {
  std::string old_filepath = filepath;
  filepath = new_path;
 
  auto status = Save();
  if (!status.ok()) {
    filepath = old_filepath;  // Restore on failure
  }
 
  return status;
}
 
bool YazeProject::IsOracleCompatible() const {
  return hack_manifest.loaded() &&
         (hack_manifest.oracle_progression_state().has_value() ||
          ToLowerCopy(hack_manifest.hack_name()).find("oracle") !=
              std::string::npos);
}
 
absl::Status YazeProject::SaveAsWithLyraTerrain(
    const std::string& new_path, const core::LyraTerrainDocument& terrain,
    const std::optional<std::string>& expected_source_bytes) {
#ifdef __EMSCRIPTEN__
  return absl::UnimplementedError(
      "Saving an independent Lyra project copy requires filesystem storage");
#else
  namespace fs = std::filesystem;
  if (!project_opened() || lyra_terrain_file.empty() || new_path.empty()) {
    return absl::FailedPreconditionError(
        "An open project and Lyra terrain are required for Save As");
  }
  auto read =
      [](const fs::path& path) -> absl::StatusOr<std::optional<std::string>> {
    std::error_code ec;
    if (!fs::exists(path, ec) && !ec) {
      return std::nullopt;
    }
    if (ec || !fs::is_regular_file(path, ec) || ec ||
        fs::file_size(path, ec) > 16 * 1024 * 1024 || ec) {
      return absl::FailedPreconditionError(
          "Project Save As source or destination is not a readable file");
    }
    std::ifstream stream(path, std::ios::binary);
    if (!stream) {
      return absl::PermissionDeniedError("Cannot read project Save As file");
    }
    std::string bytes{std::istreambuf_iterator<char>(stream), {}};
    if (stream.bad()) {
      return absl::DataLossError(
          "Could not finish reading project Save As file");
    }
    return std::optional<std::string>(std::move(bytes));
  };
 
  auto candidate = *this;
  // Preserve the original meaning of every relative asset before relocating.
  candidate.NormalizePathsToAbsolute();
  std::error_code ec;
  const fs::path source_project = fs::absolute(candidate.filepath, ec);
  if (ec) {
    return absl::InvalidArgumentError("Cannot resolve the source project path");
  }
  const fs::path source_terrain = candidate.lyra_terrain_file;
  const fs::path destination = fs::absolute(new_path, ec).lexically_normal();
  if (ec) {
    return absl::InvalidArgumentError(
        "Cannot resolve the project Save As path");
  }
  fs::path destination_terrain = destination;
  destination_terrain.replace_extension(".lyra-terrain.json");
  candidate.filepath = destination.string();
  candidate.lyra_terrain_file = destination_terrain.string();
 
  const std::vector<fs::path> targets = {destination, destination_terrain};
  std::vector<fs::path> read_only_targets = {source_project, source_terrain};
  if (!candidate.rom_filename.empty()) {
    read_only_targets.push_back(candidate.rom_filename);
  }
  if (!candidate.lyra_build_request_file.empty()) {
    read_only_targets.push_back(candidate.lyra_build_request_file);
  }
  for (const auto& reference : {candidate.native_save_producer_file,
                                candidate.native_save_transfer_proof_file,
                                candidate.native_save_receipt_file}) {
    if (!reference.empty()) {
      read_only_targets.push_back(reference);
    }
  }
  ASSIGN_OR_RETURN(
      auto lock,
      core::AcquireSourceArtifactPublicationLock(
          targets, {"Lyra project", "Lyra project files"}, read_only_targets));
  ASSIGN_OR_RETURN(auto original_project, read(source_project));
  if (!original_project) {
    return absl::NotFoundError("The original project file is missing");
  }
  ASSIGN_OR_RETURN(auto original_terrain, read(source_terrain));
  if (original_terrain != expected_source_bytes) {
    return absl::FailedPreconditionError(
        "Lyra terrain changed on disk; refusing stale Save As");
  }
  ASSIGN_OR_RETURN(auto previous_destination, read(destination));
  ASSIGN_OR_RETURN(auto previous_terrain, read(destination_terrain));
  if (previous_terrain) {
    return absl::AlreadyExistsError(
        "The destination project already owns Lyra terrain; choose another "
        "project name");
  }
  auto now =
      std::chrono::system_clock::to_time_t(std::chrono::system_clock::now());
  std::stringstream timestamp;
  timestamp << std::put_time(std::localtime(&now), "%Y-%m-%d %H:%M:%S");
  candidate.metadata.last_modified = timestamp.str();
  if (candidate.music_persistence.storage_key.empty()) {
    candidate.music_persistence.storage_key = candidate.MakeStorageKey("music");
  }
  ASSIGN_OR_RETURN(auto descriptor, candidate.SerializeToString());
  const std::string terrain_bytes = terrain.Serialize();
  RETURN_IF_ERROR(core::PublishSourceArtifacts(
      *lock,
      {{source_project, original_project, *original_project},
       {destination, previous_destination, descriptor},
       {destination_terrain, std::nullopt, terrain_bytes}},
      core::ComputeSourceArtifactSha256(*original_project),
      [&]() -> absl::Status {
        ASSIGN_OR_RETURN(auto source_after, read(source_terrain));
        if (source_after != expected_source_bytes) {
          return absl::FailedPreconditionError(
              "Lyra terrain changed during Save As");
        }
        ASSIGN_OR_RETURN(auto saved, read(destination_terrain));
        if (!saved) {
          return absl::DataLossError("Saved Lyra terrain is missing");
        }
        return core::LyraTerrainDocument::Parse(*saved, terrain.profile())
            .status();
      }));
  *this = std::move(candidate);
  return absl::OkStatus();
#endif
}
 
std::string YazeProject::MakeStorageKey(absl::string_view suffix) const {
  std::string base;
  if (!metadata.project_id.empty()) {
    base = metadata.project_id;
  } else if (!name.empty()) {
    base = name;
  } else if (!filepath.empty()) {
    base = std::filesystem::path(filepath).stem().string();
  }
  base = SanitizeStorageKey(base);
  if (suffix.empty()) {
    return base;
  }
  return absl::StrFormat("%s_%s", base, suffix);
}
 
namespace {
// A '\r' not followed by '\n' is a classic-Mac line ending. The parser can
// normalize CRLF, but a lone CR would split a line somewhere it does not
// expect, so both directions refuse it.
bool ContainsLoneCarriageReturn(const std::string& content) {
  for (size_t i = 0; i < content.size(); ++i) {
    if (content[i] == '\r' &&
        (i + 1 >= content.size() || content[i + 1] != '\n')) {
      return true;
    }
  }
  return false;
}
 
constexpr absl::string_view kProjectFileFooter = "# End of YAZE Project File";
 
// Sections ParseFromString models. Everything else is passed through.
bool IsKnownProjectSection(absl::string_view name) {
  static constexpr absl::string_view kKnown[] = {"project",
                                                 "files",
                                                 "sprite_assets",
                                                 "rom",
                                                 "feature_flags",
                                                 "workspace",
                                                 "dungeon_overlay",
                                                 "graphics_sheets",
                                                 "atlas",
                                                 "planning",
                                                 "rom_addresses",
                                                 "custom_objects",
                                                 "agent_settings",
                                                 "build",
                                                 "keybindings",
                                                 "editor_visibility",
                                                 "zscream_compatibility",
                                                 "music"};
  if (absl::StartsWith(name, "labels_")) {
    return true;
  }
  return std::find(std::begin(kKnown), std::end(kKnown), name) !=
         std::end(kKnown);
}
 
// Comments SerializeToString writes itself; keeping them would duplicate
// them on every save.
bool IsGeneratedProjectComment(absl::string_view line, bool before_sections) {
  if (line == kProjectFileFooter) {
    return true;
  }
  if (!before_sections) {
    return false;
  }
  return absl::StartsWith(line, "# yaze Project File") ||
         absl::StartsWith(line, "# Format Version:") ||
         absl::StartsWith(line, "# Generated by YAZE") ||
         absl::StartsWith(line, "# Last Modified:");
}
 
ProjectFilePassthrough::Section& PassthroughSection(
    ProjectFilePassthrough& passthrough, const std::string& name) {
  for (auto& section : passthrough.sections) {
    if (section.name == name) {
      return section;
    }
  }
  passthrough.sections.push_back({name, false, {}});
  return passthrough.sections.back();
}
 
bool IsKeyLine(absl::string_view line) {
  return !line.empty() && line.front() != '#' &&
         line.find('=') != absl::string_view::npos;
}
 
// Writes `canonical` (SerializeToString's own output) with the passthrough
// lines put back. See ProjectFilePassthrough for the placement rules.
std::string MergeProjectFilePassthrough(
    const std::string& canonical, const ProjectFilePassthrough& passthrough) {
  if (passthrough.empty()) {
    return canonical;
  }
  using Kind = ProjectFilePassthrough::Line::Kind;
 
  struct CanonicalSection {
    std::string header;
    std::string name;
    std::vector<std::string> lines;
  };
  std::vector<std::string> preamble;
  std::vector<CanonicalSection> canonical_sections;
  bool has_footer = false;
  for (absl::string_view line : absl::StrSplit(canonical, '\n')) {
    if (line == kProjectFileFooter) {
      has_footer = true;
      continue;
    }
    if (line.size() >= 2 && line.front() == '[' && line.back() == ']') {
      canonical_sections.push_back(
          {std::string(line),
           std::string(line.substr(1, line.size() - 2)),
           {}});
      continue;
    }
    if (line.empty()) {
      continue;
    }
    (canonical_sections.empty() ? preamble : canonical_sections.back().lines)
        .push_back(std::string(line));
  }
 
  auto find_section =
      [&](absl::string_view name) -> const ProjectFilePassthrough::Section* {
    for (const auto& section : passthrough.sections) {
      if (section.name == name) {
        return &section;
      }
    }
    return nullptr;
  };
 
  std::ostringstream out;
  // Every comment and unknown line of `section`, in file order.
  auto write_all = [&](const ProjectFilePassthrough::Section& section) {
    for (const auto& line : section.lines) {
      if (line.kind != Kind::kKnownKey) {
        out << line.text << "\n";
      }
    }
  };
 
  for (const auto& line : preamble) {
    out << line << "\n";
  }
  out << "\n";
  if (const auto* before = find_section(""); before != nullptr) {
    write_all(*before);
    if (!before->lines.empty()) {
      out << "\n";
    }
  }
 
  std::vector<const ProjectFilePassthrough::Section*> merged;
  for (const auto& section : canonical_sections) {
    out << section.header << "\n";
    const auto* kept = find_section(section.name);
    if (kept == nullptr) {
      for (const auto& line : section.lines) {
        out << line << "\n";
      }
      out << "\n";
      continue;
    }
    merged.push_back(kept);
 
    // Comments belong to the next key line after them in the file.
    std::vector<std::pair<std::string, std::vector<std::string>>> anchored;
    std::vector<std::string> pending;
    std::vector<std::pair<std::string, std::vector<std::string>>> unknown;
    for (const auto& line : kept->lines) {
      if (line.kind == Kind::kComment) {
        pending.push_back(line.text);
      } else if (line.kind == Kind::kUnknownLine) {
        unknown.push_back({line.text, std::move(pending)});
        pending.clear();
      } else if (!pending.empty()) {
        anchored.push_back({line.key, std::move(pending)});
        pending.clear();
      }
    }
    std::vector<bool> anchor_written(anchored.size(), false);
    for (const auto& line : section.lines) {
      if (IsKeyLine(line)) {
        const std::string key = ParseKeyValue(line).first;
        for (size_t i = 0; i < anchored.size(); ++i) {
          if (!anchor_written[i] && anchored[i].first == key) {
            for (const auto& comment : anchored[i].second) {
              out << comment << "\n";
            }
            anchor_written[i] = true;
          }
        }
      }
      out << line << "\n";
    }
    for (const auto& [text, comments] : unknown) {
      for (const auto& comment : comments) {
        out << comment << "\n";
      }
      out << text << "\n";
    }
    // Comments whose key this build no longer writes, then trailing ones.
    for (size_t i = 0; i < anchored.size(); ++i) {
      if (!anchor_written[i]) {
        for (const auto& comment : anchored[i].second) {
          out << comment << "\n";
        }
      }
    }
    for (const auto& comment : pending) {
      out << comment << "\n";
    }
    out << "\n";
  }
 
  // Unknown sections, and known sections this build left out (for example
  // an emptied [graphics_sheets]) that still carry comments or unknown keys.
  for (const auto& section : passthrough.sections) {
    if (section.name.empty() ||
        std::find(merged.begin(), merged.end(), &section) != merged.end()) {
      continue;
    }
    const bool has_content = std::any_of(
        section.lines.begin(), section.lines.end(),
        [](const auto& line) { return line.kind != Kind::kKnownKey; });
    if (!has_content) {
      continue;
    }
    out << "[" << section.name << "]\n";
    write_all(section);
    out << "\n";
  }
 
  if (has_footer) {
    out << kProjectFileFooter << "\n";
  }
  return out.str();
}
}  // namespace
 
bool IsKnownProjectFileSection(absl::string_view name) {
  return IsKnownProjectSection(name);
}
 
absl::StatusOr<std::string> YazeProject::SerializeToString() const {
  std::ostringstream file;
 
  // Write header comment
  file << "# yaze Project File\n";
  file << "# Format Version: 2.0\n";
  file << "# Generated by YAZE " << metadata.yaze_version << "\n";
  file << "# Last Modified: " << metadata.last_modified << "\n\n";
 
  // Project section
  file << "[project]\n";
  file << "name=" << name << "\n";
  file << "description=" << metadata.description << "\n";
  file << "author=" << metadata.author << "\n";
  file << "license=" << metadata.license << "\n";
  file << "version=" << metadata.version << "\n";
  file << "created_date=" << metadata.created_date << "\n";
  file << "last_modified=" << metadata.last_modified << "\n";
  file << "yaze_version=" << metadata.yaze_version << "\n";
  file << "created_by=" << metadata.created_by << "\n";
  file << "project_id=" << metadata.project_id << "\n";
  file << "tags=" << absl::StrJoin(metadata.tags, ",") << "\n\n";
 
  // Files section
  file << "[files]\n";
  file << "rom_filename=" << GetRelativePath(rom_filename) << "\n";
  file << "rom_backup_folder=" << GetRelativePath(rom_backup_folder) << "\n";
  file << "code_folder=" << GetRelativePath(code_folder) << "\n";
  file << "assets_folder=" << GetRelativePath(assets_folder) << "\n";
  file << "patches_folder=" << GetRelativePath(patches_folder) << "\n";
  file << "labels_filename=" << GetRelativePath(labels_filename) << "\n";
  file << "symbols_filename=" << GetRelativePath(symbols_filename) << "\n";
  if (!overworld_graphics_preview.empty()) {
    file << "overworld_graphics_preview="
         << GetRelativePath(overworld_graphics_preview) << "\n";
  }
  if (!dungeon_tile_patterns.empty()) {
    file << "dungeon_tile_patterns="
         << GetRelativePath(GetAbsolutePath(dungeon_tile_patterns)) << "\n";
  }
  if (!cutscene_shots.empty()) {
    file << "cutscene_shots="
         << GetRelativePath(GetAbsolutePath(cutscene_shots)) << "\n";
  }
  if (!custom_collision_json.empty()) {
    file << "custom_collision_json="
         << GetRelativePath(GetAbsolutePath(custom_collision_json)) << "\n";
  }
  file << "output_folder=" << GetRelativePath(output_folder) << "\n";
  file << "custom_objects_folder=" << GetRelativePath(custom_objects_folder)
       << "\n";
  file << "palette_catalog_file="
       << GetRelativePath(GetAbsolutePath(palette_catalog_file)) << "\n";
  file << "terrain_catalog_file="
       << GetRelativePath(GetAbsolutePath(terrain_catalog_file)) << "\n";
  file << "lyra_terrain_file="
       << GetRelativePath(GetAbsolutePath(lyra_terrain_file)) << "\n";
  file << "lyra_build_request_file="
       << GetRelativePath(GetAbsolutePath(lyra_build_request_file)) << "\n";
  if (!native_save_producer_file.empty()) {
    file << "native_save_producer_file="
         << GetRelativePath(GetAbsolutePath(native_save_producer_file)) << "\n";
  }
  if (!native_save_transfer_proof_file.empty()) {
    file << "native_save_transfer_proof_file="
         << GetRelativePath(GetAbsolutePath(native_save_transfer_proof_file))
         << "\n";
  }
  if (!native_save_receipt_file.empty()) {
    file << "native_save_receipt_file="
         << GetRelativePath(GetAbsolutePath(native_save_receipt_file)) << "\n";
  }
  file << "hack_manifest_file=" << GetRelativePath(hack_manifest_file) << "\n";
  file << "sprite_catalog_file="
       << GetRelativePath(GetAbsolutePath(sprite_catalog_file)) << "\n";
  file << "sprite_source_root="
       << GetRelativePath(GetAbsolutePath(sprite_source_root)) << "\n";
  file << "additional_roms=" << absl::StrJoin(additional_roms, ",") << "\n\n";
 
  file << "[sprite_assets]\n";
  for (size_t i = 0; i < sprite_assets.size(); ++i) {
    auto asset = sprite_assets[i];
    asset.zsm_path = GetRelativePath(GetAbsolutePath(asset.zsm_path));
    for (auto& source : asset.graphics_sources) {
      if (source.kind == "bin") {
        source.path = GetRelativePath(GetAbsolutePath(source.path));
      }
    }
    file << "asset_" << i << "=" << SpriteAssetToJson(asset).dump() << "\n";
  }
  file << "\n";
 
  // ROM metadata section
  file << "[rom]\n";
  file << "role=" << RomRoleToString(rom_metadata.role) << "\n";
  file << "expected_hash=" << rom_metadata.expected_hash << "\n";
  file << "write_policy=" << RomWritePolicyToString(rom_metadata.write_policy)
       << "\n\n";
 
  // Feature flags section
  file << "[feature_flags]\n";
  file << "load_custom_overworld="
       << (feature_flags.overworld.kLoadCustomOverworld ? "true" : "false")
       << "\n";
  file << "apply_zs_custom_overworld_asm="
       << (feature_flags.overworld.kApplyZSCustomOverworldASM ? "true"
                                                              : "false")
       << "\n";
  file << "enable_special_world_expansion="
       << (feature_flags.overworld.kEnableSpecialWorldExpansion ? "true"
                                                                : "false")
       << "\n";
  file << "save_with_change_queue="
       << (feature_flags.kSaveWithChangeQueue ? "true" : "false") << "\n";
  file << "save_dungeon_maps="
       << (feature_flags.kSaveDungeonMaps ? "true" : "false") << "\n";
  file << "save_overworld_maps="
       << (feature_flags.overworld.kSaveOverworldMaps ? "true" : "false")
       << "\n";
  file << "save_overworld_entrances="
       << (feature_flags.overworld.kSaveOverworldEntrances ? "true" : "false")
       << "\n";
  file << "save_overworld_exits="
       << (feature_flags.overworld.kSaveOverworldExits ? "true" : "false")
       << "\n";
  file << "save_overworld_items="
       << (feature_flags.overworld.kSaveOverworldItems ? "true" : "false")
       << "\n";
  file << "save_overworld_sprites="
       << (feature_flags.overworld.kSaveOverworldSprites ? "true" : "false")
       << "\n";
  file << "save_overworld_properties="
       << (feature_flags.overworld.kSaveOverworldProperties ? "true" : "false")
       << "\n";
  file << "save_dungeon_objects="
       << (feature_flags.dungeon.kSaveObjects ? "true" : "false") << "\n";
  file << "save_dungeon_sprites="
       << (feature_flags.dungeon.kSaveSprites ? "true" : "false") << "\n";
  file << "save_dungeon_room_headers="
       << (feature_flags.dungeon.kSaveRoomHeaders ? "true" : "false") << "\n";
  file << "save_dungeon_torches="
       << (feature_flags.dungeon.kSaveTorches ? "true" : "false") << "\n";
  file << "save_dungeon_pits="
       << (feature_flags.dungeon.kSavePits ? "true" : "false") << "\n";
  file << "save_dungeon_blocks="
       << (feature_flags.dungeon.kSaveBlocks ? "true" : "false") << "\n";
  file << "save_dungeon_collision="
       << (feature_flags.dungeon.kSaveCollision ? "true" : "false") << "\n";
  file << "save_dungeon_water_fill_zones="
       << (feature_flags.dungeon.kSaveWaterFillZones ? "true" : "false")
       << "\n";
  file << "save_dungeon_chests="
       << (feature_flags.dungeon.kSaveChests ? "true" : "false") << "\n";
  file << "save_dungeon_pot_items="
       << (feature_flags.dungeon.kSavePotItems ? "true" : "false") << "\n";
  file << "save_dungeon_entrances="
       << (feature_flags.dungeon.kSaveEntrances ? "true" : "false") << "\n";
  file << "save_dungeon_palettes="
       << (feature_flags.dungeon.kSavePalettes ? "true" : "false") << "\n";
  file << "save_graphics_sheet="
       << (feature_flags.kSaveGraphicsSheet ? "true" : "false") << "\n";
  file << "save_all_palettes="
       << (feature_flags.kSaveAllPalettes ? "true" : "false") << "\n";
  file << "save_gfx_groups="
       << (feature_flags.kSaveGfxGroups ? "true" : "false") << "\n";
  file << "save_messages=" << (feature_flags.kSaveMessages ? "true" : "false")
       << "\n";
  file << "enable_custom_objects="
       << (feature_flags.kEnableCustomObjects ? "true" : "false") << "\n\n";
 
  // Workspace settings section
  file << "[workspace]\n";
  file << "font_global_scale=" << workspace_settings.font_global_scale << "\n";
  file << "dark_mode=" << (workspace_settings.dark_mode ? "true" : "false")
       << "\n";
  file << "ui_theme=" << workspace_settings.ui_theme << "\n";
  file << "autosave_enabled="
       << (workspace_settings.autosave_enabled ? "true" : "false") << "\n";
  file << "autosave_interval_secs=" << workspace_settings.autosave_interval_secs
       << "\n";
  file << "backup_on_save="
       << (workspace_settings.backup_on_save ? "true" : "false") << "\n";
  file << "backup_retention_count=" << workspace_settings.backup_retention_count
       << "\n";
  file << "backup_keep_daily="
       << (workspace_settings.backup_keep_daily ? "true" : "false") << "\n";
  file << "backup_keep_daily_days=" << workspace_settings.backup_keep_daily_days
       << "\n";
  file << "show_grid=" << (workspace_settings.show_grid ? "true" : "false")
       << "\n";
  file << "show_collision="
       << (workspace_settings.show_collision ? "true" : "false") << "\n";
  file << "prefer_hmagic_names="
       << (workspace_settings.prefer_hmagic_names ? "true" : "false") << "\n";
  file << "last_layout_preset=" << workspace_settings.last_layout_preset
       << "\n";
  file << "saved_layouts="
       << absl::StrJoin(workspace_settings.saved_layouts, ",") << "\n";
  file << "recent_files=" << absl::StrJoin(workspace_settings.recent_files, ",")
       << "\n\n";
 
  // Dungeon overlay settings section
  auto track_tiles = dungeon_overlay.track_tiles;
  if (track_tiles.empty()) {
    for (uint16_t tile = 0xB0; tile <= 0xBE; ++tile) {
      track_tiles.push_back(tile);
    }
  }
  auto track_stop_tiles = dungeon_overlay.track_stop_tiles;
  if (track_stop_tiles.empty()) {
    track_stop_tiles = {0xB7, 0xB8, 0xB9, 0xBA};
  }
  auto track_switch_tiles = dungeon_overlay.track_switch_tiles;
  if (track_switch_tiles.empty()) {
    track_switch_tiles = {0xD0, 0xD1, 0xD2, 0xD3};
  }
  auto track_object_ids = dungeon_overlay.track_object_ids;
  if (track_object_ids.empty()) {
    track_object_ids = {0x31};
  }
  auto minecart_sprite_ids = dungeon_overlay.minecart_sprite_ids;
  if (minecart_sprite_ids.empty()) {
    minecart_sprite_ids = {0xA3};
  }
  file << "[dungeon_overlay]\n";
  file << "track_tiles=" << FormatHexUintList(track_tiles) << "\n";
  file << "track_stop_tiles=" << FormatHexUintList(track_stop_tiles) << "\n";
  file << "track_switch_tiles=" << FormatHexUintList(track_switch_tiles)
       << "\n";
  file << "track_object_ids=" << FormatHexUintList(track_object_ids) << "\n";
  file << "minecart_sprite_ids=" << FormatHexUintList(minecart_sprite_ids)
       << "\n\n";
 
  if (!graphics_sheets.empty()) {
    file << "[graphics_sheets]\n";
    file << "reserved_sheets="
         << FormatHexUintList(graphics_sheets.reserved_sheets) << "\n";
    file << "flagged_sheets="
         << FormatHexUintList(graphics_sheets.flagged_sheets) << "\n";
    file << "reserved_blocks="
         << FormatHexUintListMap(graphics_sheets.reserved_blocks) << "\n\n";
  }
 
  if (atlas.section_present || !atlas.IsDefault()) {
    file << "[atlas]\n";
    file << "annotations=" << absl::StrJoin(atlas.annotations, ",") << "\n";
    file << "defaults=" << atlas.defaults << "\n";
    file << "symbols=" << atlas.symbols << "\n";
    file << "export_folder=" << atlas.export_folder << "\n\n";
  }
 
  if (planning.section_present || !planning.IsDefault()) {
    file << "[planning]\n";
    file << "file=" << planning.file << "\n\n";
  }
 
  if (!rom_address_overrides.addresses.empty()) {
    file << "[rom_addresses]\n";
    for (const auto& [key, value] : rom_address_overrides.addresses) {
      file << key << "=" << FormatHexUint32(value) << "\n";
    }
    file << "\n";
  }
 
  if (!custom_object_files.empty()) {
    file << "[custom_objects]\n";
    for (const auto& [object_id, files] : custom_object_files) {
      file << absl::StrFormat("object_0x%X", object_id) << "="
           << absl::StrJoin(files, ",") << "\n";
    }
    file << "\n";
  }
 
  // AI Agent settings section
  file << "[agent_settings]\n";
  file << "ai_provider=" << agent_settings.ai_provider << "\n";
  file << "ai_model=" << agent_settings.ai_model << "\n";
  file << "ollama_host=" << agent_settings.ollama_host << "\n";
  file << "gemini_api_key=" << agent_settings.gemini_api_key << "\n";
  file << "custom_system_prompt="
       << GetRelativePath(GetAbsolutePath(agent_settings.custom_system_prompt))
       << "\n";
  file << "use_custom_prompt="
       << (agent_settings.use_custom_prompt ? "true" : "false") << "\n";
  file << "show_reasoning="
       << (agent_settings.show_reasoning ? "true" : "false") << "\n";
  file << "verbose=" << (agent_settings.verbose ? "true" : "false") << "\n";
  file << "max_tool_iterations=" << agent_settings.max_tool_iterations << "\n";
  file << "max_retry_attempts=" << agent_settings.max_retry_attempts << "\n";
  file << "temperature=" << agent_settings.temperature << "\n";
  file << "top_p=" << agent_settings.top_p << "\n";
  file << "max_output_tokens=" << agent_settings.max_output_tokens << "\n";
  file << "stream_responses="
       << (agent_settings.stream_responses ? "true" : "false") << "\n";
  file << "favorite_models="
       << absl::StrJoin(agent_settings.favorite_models, ",") << "\n";
  file << "model_chain=" << absl::StrJoin(agent_settings.model_chain, ",")
       << "\n";
  file << "chain_mode=" << agent_settings.chain_mode << "\n";
  file << "enable_tool_resources="
       << (agent_settings.enable_tool_resources ? "true" : "false") << "\n";
  file << "enable_tool_dungeon="
       << (agent_settings.enable_tool_dungeon ? "true" : "false") << "\n";
  file << "enable_tool_overworld="
       << (agent_settings.enable_tool_overworld ? "true" : "false") << "\n";
  file << "enable_tool_messages="
       << (agent_settings.enable_tool_messages ? "true" : "false") << "\n";
  file << "enable_tool_dialogue="
       << (agent_settings.enable_tool_dialogue ? "true" : "false") << "\n";
  file << "enable_tool_gui="
       << (agent_settings.enable_tool_gui ? "true" : "false") << "\n";
  file << "enable_tool_music="
       << (agent_settings.enable_tool_music ? "true" : "false") << "\n";
  file << "enable_tool_sprite="
       << (agent_settings.enable_tool_sprite ? "true" : "false") << "\n";
  file << "enable_tool_emulator="
       << (agent_settings.enable_tool_emulator ? "true" : "false") << "\n";
  file << "enable_tool_memory_inspector="
       << (agent_settings.enable_tool_memory_inspector ? "true" : "false")
       << "\n";
  file << "builder_blueprint_path=" << agent_settings.builder_blueprint_path
       << "\n\n";
 
  // Custom keybindings section
  if (!workspace_settings.custom_keybindings.empty()) {
    file << "[keybindings]\n";
    for (const auto& [key, value] : workspace_settings.custom_keybindings) {
      file << key << "=" << value << "\n";
    }
    file << "\n";
  }
 
  // Editor visibility section
  if (!workspace_settings.editor_visibility.empty()) {
    file << "[editor_visibility]\n";
    for (const auto& [key, value] : workspace_settings.editor_visibility) {
      file << key << "=" << (value ? "true" : "false") << "\n";
    }
    file << "\n";
  }
 
  // Resource labels sections
  for (const auto& [type, labels] : resource_labels) {
    if (!labels.empty()) {
      file << "[labels_" << type << "]\n";
      for (const auto& [key, value] : labels) {
        file << key << "=" << value << "\n";
      }
      file << "\n";
    }
  }
 
  // Build settings section
  file << "[build]\n";
  file << "build_script=" << build_script << "\n";
  file << "output_folder=" << GetRelativePath(output_folder) << "\n";
  file << "git_repository=" << git_repository << "\n";
  file << "track_changes=" << (track_changes ? "true" : "false") << "\n";
  file << "build_configurations=" << absl::StrJoin(build_configurations, ",")
       << "\n";
  file << "build_target=" << build_target << "\n";
  file << "asm_entry_point=" << asm_entry_point << "\n";
  file << "asm_sources=" << absl::StrJoin(asm_sources, ",") << "\n";
  file << "last_build_hash=" << last_build_hash << "\n";
  file << "build_number=" << build_number << "\n\n";
 
  // Music persistence section (for WASM/offline state)
  file << "[music]\n";
  file << "persist_custom_music="
       << (music_persistence.persist_custom_music ? "true" : "false") << "\n";
  file << "storage_key=" << music_persistence.storage_key << "\n";
  file << "last_saved_at=" << music_persistence.last_saved_at << "\n\n";
 
  // ZScream compatibility section
  if (!zscream_project_file.empty()) {
    file << "[zscream_compatibility]\n";
    file << "original_project_file=" << zscream_project_file << "\n";
    for (const auto& [key, value] : zscream_mappings) {
      file << key << "=" << value << "\n";
    }
    file << "\n";
  }
 
  file << "# End of YAZE Project File\n";
 
  // Refuse to WRITE what ParseFromString refuses to READ. Values are streamed
  // verbatim — metadata.description and resource labels injected from
  // hack_manifest.json among them — so a lone CR pasted from an old-Mac
  // source would round-trip through Save() and leave the project permanently
  // unopenable, with the previous good file already overwritten. Failing here
  // keeps that file intact.
  std::string serialized =
      MergeProjectFilePassthrough(file.str(), file_passthrough);
  if (ContainsLoneCarriageReturn(serialized)) {
    return absl::InvalidArgumentError(
        "Project contains a lone carriage return in a value; refusing to "
        "write a descriptor that could not be read back");
  }
  return serialized;
}
 
absl::Status YazeProject::ParseFromString(const std::string& content) {
  if (ContainsLoneCarriageReturn(content)) {
    return absl::InvalidArgumentError(
        "Project file contains unsupported lone carriage returns");
  }
 
  rom_metadata.write_policy = RomWritePolicy::kWarn;
  feature_flags.overworld.kSaveOverworldSprites = true;
  feature_flags.overworld.kEnableSpecialWorldExpansion = false;
  feature_flags.kSaveWithChangeQueue = false;
  sprite_catalog_file.clear();
  sprite_source_root.clear();
  sprite_assets.clear();
  terrain_catalog_file.clear();
  lyra_terrain_file.clear();
  lyra_build_request_file.clear();
  native_save_producer_file.clear();
  native_save_transfer_proof_file.clear();
  native_save_receipt_file.clear();
  palette_catalog_file.clear();
  dungeon_tile_patterns.clear();
  file_passthrough = ProjectFilePassthrough{};
  atlas = AtlasSettings{};
  planning = PlanningSettings{};
  std::istringstream stream(content);
  std::string line;
  std::string current_section;
  ProjectFilePassthrough::Section* passthrough_section =
      &PassthroughSection(file_passthrough, "");
 
  while (std::getline(stream, line)) {
    // std::getline() consumes '\n' but preserves the '\r' in CRLF input.
    // Normalize that line ending before comment, section, or value parsing so
    // project safety flags have identical behavior across platforms.
    if (!line.empty() && line.back() == '\r') {
      line.pop_back();
    }
 
    if (line.find_first_not_of(" \t") == std::string::npos)
      continue;
 
    if (line[0] == '#') {
      if (!IsGeneratedProjectComment(line, current_section.empty())) {
        passthrough_section->lines.push_back(
            {ProjectFilePassthrough::Line::Kind::kComment, "", line});
      }
      continue;
    }
 
    if (line.front() == '[' && line.back() == ']') {
      current_section = line.substr(1, line.length() - 2);
      passthrough_section =
          &PassthroughSection(file_passthrough, current_section);
      passthrough_section->known = IsKnownProjectSection(current_section);
      if (current_section == "atlas") {
        atlas.section_present = true;
      } else if (current_section == "planning") {
        planning.section_present = true;
      }
      continue;
    }
 
    auto [key, value] = ParseKeyValue(line);
    // False when this build does not model the line; it is then kept verbatim
    // and written back on save.
    bool understood = !key.empty();
    if (key.empty()) {
      // No "key=value": nothing to parse.
    } else if (current_section == "project") {
      if (key == "name")
        name = value;
      else if (key == "description")
        metadata.description = value;
      else if (key == "author")
        metadata.author = value;
      else if (key == "license")
        metadata.license = value;
      else if (key == "version")
        metadata.version = value;
      else if (key == "created_date")
        metadata.created_date = value;
      else if (key == "last_modified")
        metadata.last_modified = value;
      else if (key == "yaze_version")
        metadata.yaze_version = value;
      else if (key == "created_by")
        metadata.created_by = value;
      else if (key == "tags")
        metadata.tags = ParseStringList(value);
      else if (key == "project_id")
        metadata.project_id = value;
      else
        understood = false;
    } else if (current_section == "files") {
      if (key == "rom_filename")
        rom_filename = value;
      else if (key == "rom_backup_folder")
        rom_backup_folder = value;
      else if (key == "code_folder")
        code_folder = value;
      else if (key == "assets_folder")
        assets_folder = value;
      else if (key == "patches_folder")
        patches_folder = value;
      else if (key == "labels_filename")
        labels_filename = value;
      else if (key == "symbols_filename")
        symbols_filename = value;
      else if (key == "overworld_graphics_preview")
        overworld_graphics_preview = value;
      else if (key == "dungeon_tile_patterns")
        dungeon_tile_patterns = value;
      else if (key == "cutscene_shots")
        cutscene_shots = value;
      else if (key == "custom_collision_json")
        custom_collision_json = value;
      else if (key == "output_folder")
        output_folder = value;
      else if (key == "custom_objects_folder")
        custom_objects_folder = value;
      else if (key == "palette_catalog_file")
        palette_catalog_file = value;
      else if (key == "terrain_catalog_file")
        terrain_catalog_file = value;
      else if (key == "lyra_terrain_file")
        lyra_terrain_file = value;
      else if (key == "lyra_build_request_file")
        lyra_build_request_file = value;
      else if (key == "native_save_producer_file")
        native_save_producer_file = value;
      else if (key == "native_save_transfer_proof_file")
        native_save_transfer_proof_file = value;
      else if (key == "native_save_receipt_file")
        native_save_receipt_file = value;
      else if (key == "hack_manifest_file")
        hack_manifest_file = value;
      else if (key == "sprite_catalog_file")
        sprite_catalog_file = value;
      else if (key == "sprite_source_root")
        sprite_source_root = value;
      else if (key == "additional_roms")
        additional_roms = ParseStringList(value);
      else
        understood = false;
    } else if (current_section == "sprite_assets") {
      if (key.rfind("asset_", 0) != 0 || value.size() > 65536 ||
          sprite_assets.size() >= 4096)
        return absl::InvalidArgumentError("Invalid sprite_assets section");
      auto asset = ParseSpriteAssetBinding(value);
      if (!asset.ok())
        return asset.status();
      for (const auto& prior : sprite_assets)
        if (prior.zsm_path == asset->zsm_path)
          return absl::InvalidArgumentError("Duplicate sprite asset path");
      sprite_assets.push_back(std::move(*asset));
    } else if (current_section == "rom") {
      if (key == "role")
        rom_metadata.role = ParseRomRole(value);
      else if (key == "expected_hash")
        rom_metadata.expected_hash = value;
      else if (key == "write_policy")
        rom_metadata.write_policy = ParseRomWritePolicy(value);
      else
        understood = false;
    } else if (current_section == "feature_flags") {
      if (key == "load_custom_overworld")
        feature_flags.overworld.kLoadCustomOverworld = ParseBool(value);
      else if (key == "apply_zs_custom_overworld_asm")
        feature_flags.overworld.kApplyZSCustomOverworldASM = ParseBool(value);
      else if (key == "enable_special_world_expansion")
        feature_flags.overworld.kEnableSpecialWorldExpansion = ParseBool(value);
      else if (key == "save_with_change_queue")
        feature_flags.kSaveWithChangeQueue = ParseBool(value);
      else if (key == "save_dungeon_maps")
        feature_flags.kSaveDungeonMaps = ParseBool(value);
      else if (key == "save_overworld_maps")
        feature_flags.overworld.kSaveOverworldMaps = ParseBool(value);
      else if (key == "save_overworld_entrances")
        feature_flags.overworld.kSaveOverworldEntrances = ParseBool(value);
      else if (key == "save_overworld_exits")
        feature_flags.overworld.kSaveOverworldExits = ParseBool(value);
      else if (key == "save_overworld_items")
        feature_flags.overworld.kSaveOverworldItems = ParseBool(value);
      else if (key == "save_overworld_sprites")
        feature_flags.overworld.kSaveOverworldSprites = ParseBool(value);
      else if (key == "save_overworld_properties")
        feature_flags.overworld.kSaveOverworldProperties = ParseBool(value);
      else if (key == "save_dungeon_objects")
        feature_flags.dungeon.kSaveObjects = ParseBool(value);
      else if (key == "save_dungeon_sprites")
        feature_flags.dungeon.kSaveSprites = ParseBool(value);
      else if (key == "save_dungeon_room_headers")
        feature_flags.dungeon.kSaveRoomHeaders = ParseBool(value);
      else if (key == "save_dungeon_torches")
        feature_flags.dungeon.kSaveTorches = ParseBool(value);
      else if (key == "save_dungeon_pits")
        feature_flags.dungeon.kSavePits = ParseBool(value);
      else if (key == "save_dungeon_blocks")
        feature_flags.dungeon.kSaveBlocks = ParseBool(value);
      else if (key == "save_dungeon_collision")
        feature_flags.dungeon.kSaveCollision = ParseBool(value);
      else if (key == "save_dungeon_water_fill_zones")
        feature_flags.dungeon.kSaveWaterFillZones = ParseBool(value);
      else if (key == "save_dungeon_chests")
        feature_flags.dungeon.kSaveChests = ParseBool(value);
      else if (key == "save_dungeon_pot_items")
        feature_flags.dungeon.kSavePotItems = ParseBool(value);
      else if (key == "save_dungeon_entrances")
        feature_flags.dungeon.kSaveEntrances = ParseBool(value);
      else if (key == "save_dungeon_palettes")
        feature_flags.dungeon.kSavePalettes = ParseBool(value);
      else if (key == "save_graphics_sheet")
        feature_flags.kSaveGraphicsSheet = ParseBool(value);
      else if (key == "save_all_palettes")
        feature_flags.kSaveAllPalettes = ParseBool(value);
      else if (key == "save_gfx_groups")
        feature_flags.kSaveGfxGroups = ParseBool(value);
      else if (key == "save_messages")
        feature_flags.kSaveMessages = ParseBool(value);
      else if (key == "enable_custom_objects")
        feature_flags.kEnableCustomObjects = ParseBool(value);
      else
        understood = false;
    } else if (current_section == "workspace") {
      if (key == "font_global_scale")
        workspace_settings.font_global_scale = ParseFloat(value);
      else if (key == "dark_mode")
        workspace_settings.dark_mode = ParseBool(value);
      else if (key == "ui_theme")
        workspace_settings.ui_theme = value;
      else if (key == "autosave_enabled")
        workspace_settings.autosave_enabled = ParseBool(value);
      else if (key == "autosave_interval_secs")
        workspace_settings.autosave_interval_secs = ParseFloat(value);
      else if (key == "backup_on_save")
        workspace_settings.backup_on_save = ParseBool(value);
      else if (key == "backup_retention_count")
        workspace_settings.backup_retention_count = std::stoi(value);
      else if (key == "backup_keep_daily")
        workspace_settings.backup_keep_daily = ParseBool(value);
      else if (key == "backup_keep_daily_days")
        workspace_settings.backup_keep_daily_days = std::stoi(value);
      else if (key == "show_grid")
        workspace_settings.show_grid = ParseBool(value);
      else if (key == "show_collision")
        workspace_settings.show_collision = ParseBool(value);
      else if (key == "prefer_hmagic_names")
        workspace_settings.prefer_hmagic_names = ParseBool(value);
      else if (key == "last_layout_preset")
        workspace_settings.last_layout_preset = value;
      else if (key == "saved_layouts")
        workspace_settings.saved_layouts = ParseStringList(value);
      else if (key == "recent_files")
        workspace_settings.recent_files = ParseStringList(value);
      else
        understood = false;
    } else if (current_section == "dungeon_overlay") {
      if (key == "track_tiles")
        dungeon_overlay.track_tiles = ParseHexUintList(value);
      else if (key == "track_stop_tiles")
        dungeon_overlay.track_stop_tiles = ParseHexUintList(value);
      else if (key == "track_switch_tiles")
        dungeon_overlay.track_switch_tiles = ParseHexUintList(value);
      else if (key == "track_object_ids")
        dungeon_overlay.track_object_ids = ParseHexUintList(value);
      else if (key == "minecart_sprite_ids")
        dungeon_overlay.minecart_sprite_ids = ParseHexUintList(value);
      else
        understood = false;
    } else if (current_section == "graphics_sheets") {
      if (key == "reserved_sheets")
        graphics_sheets.reserved_sheets = ParseHexUintList(value);
      else if (key == "flagged_sheets")
        graphics_sheets.flagged_sheets = ParseHexUintList(value);
      else if (key == "reserved_blocks")
        graphics_sheets.reserved_blocks = ParseHexUintListMap(value);
      else
        understood = false;
    } else if (current_section == "atlas") {
      if (key == "annotations")
        atlas.annotations = ParseStringList(value);
      else if (key == "defaults")
        atlas.defaults = value.empty() ? "vanilla" : value;
      else if (key == "symbols")
        atlas.symbols = value;
      else if (key == "export_folder")
        atlas.export_folder = value;
      else
        understood = false;
    } else if (current_section == "planning") {
      if (key == "file")
        planning.file = value;
      else
        understood = false;
    } else if (current_section == "rom_addresses") {
      auto parsed = ParseHexUint32(value);
      if (parsed.has_value()) {
        rom_address_overrides.addresses[key] = *parsed;
      } else {
        understood = false;
      }
    } else if (current_section == "custom_objects") {
      std::string id_token = key;
      if (absl::StartsWith(id_token, "object_")) {
        id_token = id_token.substr(7);
      }
      auto parsed = ParseHexUint32(id_token);
      if (parsed.has_value()) {
        custom_object_files[static_cast<int>(*parsed)] =
            ParsePositionalStringList(value);
      } else {
        understood = false;
      }
    } else if (current_section == "agent_settings") {
      if (key == "ai_provider")
        agent_settings.ai_provider = value;
      else if (key == "ai_model")
        agent_settings.ai_model = value;
      else if (key == "ollama_host")
        agent_settings.ollama_host = value;
      else if (key == "gemini_api_key")
        agent_settings.gemini_api_key = value;
      else if (key == "custom_system_prompt")
        agent_settings.custom_system_prompt = value;
      else if (key == "use_custom_prompt")
        agent_settings.use_custom_prompt = ParseBool(value);
      else if (key == "show_reasoning")
        agent_settings.show_reasoning = ParseBool(value);
      else if (key == "verbose")
        agent_settings.verbose = ParseBool(value);
      else if (key == "max_tool_iterations")
        agent_settings.max_tool_iterations = std::stoi(value);
      else if (key == "max_retry_attempts")
        agent_settings.max_retry_attempts = std::stoi(value);
      else if (key == "temperature")
        agent_settings.temperature = ParseFloat(value);
      else if (key == "top_p")
        agent_settings.top_p = ParseFloat(value);
      else if (key == "max_output_tokens")
        agent_settings.max_output_tokens = std::stoi(value);
      else if (key == "stream_responses")
        agent_settings.stream_responses = ParseBool(value);
      else if (key == "favorite_models")
        agent_settings.favorite_models = ParseStringList(value);
      else if (key == "model_chain")
        agent_settings.model_chain = ParseStringList(value);
      else if (key == "chain_mode")
        agent_settings.chain_mode = std::stoi(value);
      else if (key == "enable_tool_resources")
        agent_settings.enable_tool_resources = ParseBool(value);
      else if (key == "enable_tool_dungeon")
        agent_settings.enable_tool_dungeon = ParseBool(value);
      else if (key == "enable_tool_overworld")
        agent_settings.enable_tool_overworld = ParseBool(value);
      else if (key == "enable_tool_messages")
        agent_settings.enable_tool_messages = ParseBool(value);
      else if (key == "enable_tool_dialogue")
        agent_settings.enable_tool_dialogue = ParseBool(value);
      else if (key == "enable_tool_gui")
        agent_settings.enable_tool_gui = ParseBool(value);
      else if (key == "enable_tool_music")
        agent_settings.enable_tool_music = ParseBool(value);
      else if (key == "enable_tool_sprite")
        agent_settings.enable_tool_sprite = ParseBool(value);
      else if (key == "enable_tool_emulator")
        agent_settings.enable_tool_emulator = ParseBool(value);
      else if (key == "enable_tool_memory_inspector")
        agent_settings.enable_tool_memory_inspector = ParseBool(value);
      else if (key == "builder_blueprint_path")
        agent_settings.builder_blueprint_path = value;
      else
        understood = false;
    } else if (current_section == "build") {
      if (key == "build_script")
        build_script = value;
      else if (key == "output_folder")
        output_folder = value;
      else if (key == "git_repository")
        git_repository = value;
      else if (key == "track_changes")
        track_changes = ParseBool(value);
      else if (key == "build_configurations")
        build_configurations = ParseStringList(value);
      else if (key == "build_target")
        build_target = value;
      else if (key == "asm_entry_point")
        asm_entry_point = value;
      else if (key == "asm_sources")
        asm_sources = ParseStringList(value);
      else if (key == "last_build_hash")
        last_build_hash = value;
      else if (key == "build_number")
        build_number = std::stoi(value);
      else
        understood = false;
    } else if (current_section.rfind("labels_", 0) == 0) {
      std::string label_type = current_section.substr(7);
      resource_labels[label_type][key] = value;
    } else if (current_section == "keybindings") {
      workspace_settings.custom_keybindings[key] = value;
    } else if (current_section == "editor_visibility") {
      workspace_settings.editor_visibility[key] = ParseBool(value);
    } else if (current_section == "zscream_compatibility") {
      if (key == "original_project_file")
        zscream_project_file = value;
      else
        zscream_mappings[key] = value;
    } else if (current_section == "music") {
      if (key == "persist_custom_music")
        music_persistence.persist_custom_music = ParseBool(value);
      else if (key == "storage_key")
        music_persistence.storage_key = value;
      else if (key == "last_saved_at")
        music_persistence.last_saved_at = value;
      else
        understood = false;
    } else {
      understood = false;  // A section this build does not know.
    }
    passthrough_section->lines.push_back(
        understood
            ? ProjectFilePassthrough::
                  Line{ProjectFilePassthrough::Line::Kind::kKnownKey, key, ""}
            : ProjectFilePassthrough::Line{
                  ProjectFilePassthrough::Line::Kind::kUnknownLine, key, line});
  }
 
  MigrateGfxGroupLabelKeys(resource_labels);
 
  if (metadata.project_id.empty()) {
    metadata.project_id = GenerateProjectId();
  }
  if (metadata.created_by.empty()) {
    metadata.created_by = "YAZE";
  }
  if (music_persistence.storage_key.empty()) {
    music_persistence.storage_key = MakeStorageKey("music");
  }
 
  return absl::OkStatus();
}
 
absl::Status YazeProject::LoadFromYazeFormat(const std::string& project_path) {
#ifdef __EMSCRIPTEN__
  auto storage_key = MakeStorageKey("project");
  auto storage_or = platform::WasmStorage::LoadProject(storage_key);
  if (storage_or.ok()) {
    return ParseFromString(storage_or.value());
  }
#endif  // __EMSCRIPTEN__
 
  std::ifstream file(project_path);
  if (!file.is_open()) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Cannot open project file: %s", project_path));
  }
 
  std::stringstream buffer;
  buffer << file.rdbuf();
  file.close();
  return ParseFromString(buffer.str());
}
 
absl::Status YazeProject::SaveToYazeFormat(bool replace_existing) {
  // Update last modified timestamp
  auto now = std::chrono::system_clock::now();
  auto time_t = std::chrono::system_clock::to_time_t(now);
  std::stringstream ss;
  ss << std::put_time(std::localtime(&time_t), "%Y-%m-%d %H:%M:%S");
  metadata.last_modified = ss.str();
  if (music_persistence.storage_key.empty()) {
    music_persistence.storage_key = MakeStorageKey("music");
  }
 
  // Ensure we serialize clean relative paths even if the user edited fields
  // into relative form (and avoid relying on cwd when opening later).
  NormalizePathsToAbsolute();
 
  ASSIGN_OR_RETURN(auto serialized, SerializeToString());
 
#ifdef __EMSCRIPTEN__
  auto storage_status = platform::WasmStorage::SaveProject(
      MakeStorageKey("project"), serialized, replace_existing);
  if (!storage_status.ok()) {
    return storage_status;
  }
#else
  if (!filepath.empty()) {
    RETURN_IF_ERROR(
        WriteProjectFileAtomically(filepath, serialized, replace_existing));
  }
#endif
 
  return absl::OkStatus();
}
 
absl::Status YazeProject::ImportZScreamProject(
    const std::string& zscream_project_path) {
  // Basic ZScream project import (to be expanded based on ZScream format)
  zscream_project_file = zscream_project_path;
  format = ProjectFormat::kZScreamCompat;
 
  // Extract project name from path
  std::filesystem::path zs_path(zscream_project_path);
  name = zs_path.stem().string() + "_imported";
 
  // Set up basic mapping for common fields
  zscream_mappings["rom_file"] = "rom_filename";
  zscream_mappings["source_code"] = "code_folder";
  zscream_mappings["project_name"] = "name";
 
  InitializeDefaults();
 
  // TODO: Implement actual ZScream format parsing when format is known
  // For now, just create a project structure that can be manually configured
 
  return absl::OkStatus();
}
 
absl::Status YazeProject::ExportForZScream(const std::string& target_path) {
  // Create a simplified project file that ZScream might understand
  std::ofstream file(target_path);
  if (!file.is_open()) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Cannot create ZScream project file: %s", target_path));
  }
 
  // Write in a simple format that ZScream might understand
  file << "# ZScream Compatible Project File\n";
  file << "# Exported from YAZE " << metadata.yaze_version << "\n\n";
  file << "name=" << name << "\n";
  file << "rom_file=" << rom_filename << "\n";
  file << "source_code=" << code_folder << "\n";
  file << "description=" << metadata.description << "\n";
  file << "author=" << metadata.author << "\n";
  file << "created_with=YAZE " << metadata.yaze_version << "\n";
 
  file.close();
  return absl::OkStatus();
}
 
absl::Status YazeProject::LoadAllSettings() {
  // Consolidated loading of all settings from project file
  // This replaces scattered config loading throughout the application
  return LoadFromYazeFormat(filepath);
}
 
absl::Status YazeProject::SaveAllSettings() {
  // Consolidated saving of all settings to project file
  return SaveToYazeFormat();
}
 
absl::Status YazeProject::ResetToDefaults() {
  InitializeDefaults();
  return Save();
}
 
absl::Status YazeProject::Validate() const {
  std::vector<std::string> errors;
 
  if (name.empty())
    errors.push_back("Project name is required");
  if (filepath.empty())
    errors.push_back("Project file path is required");
  if (rom_filename.empty())
    errors.push_back("ROM file is required");
 
#ifndef __EMSCRIPTEN__
  // Check if files exist
  if (!rom_filename.empty() &&
      !std::filesystem::exists(GetAbsolutePath(rom_filename))) {
    errors.push_back("ROM file does not exist: " + rom_filename);
  }
 
  if (!code_folder.empty() &&
      !std::filesystem::exists(GetAbsolutePath(code_folder))) {
    errors.push_back("Code folder does not exist: " + code_folder);
  }
 
  if (!labels_filename.empty() &&
      !std::filesystem::exists(GetAbsolutePath(labels_filename))) {
    errors.push_back("Labels file does not exist: " + labels_filename);
  }
 
  if (!hack_manifest_file.empty()) {
    if (!std::filesystem::exists(GetAbsolutePath(hack_manifest_file))) {
      errors.push_back("Hack manifest file does not exist: " +
                       hack_manifest_file);
    } else if (!hack_manifest.loaded()) {
      errors.push_back("Hack manifest file failed to load: " +
                       hack_manifest_file);
    }
  }
#endif  // __EMSCRIPTEN__
 
  if (!errors.empty()) {
    return absl::InvalidArgumentError(absl::StrJoin(errors, "; "));
  }
 
  return absl::OkStatus();
}
 
std::vector<std::string> YazeProject::GetMissingFiles() const {
  std::vector<std::string> missing;
 
#ifndef __EMSCRIPTEN__
  if (!rom_filename.empty() &&
      !std::filesystem::exists(GetAbsolutePath(rom_filename))) {
    missing.push_back(rom_filename);
  }
  if (!labels_filename.empty() &&
      !std::filesystem::exists(GetAbsolutePath(labels_filename))) {
    missing.push_back(labels_filename);
  }
  if (!symbols_filename.empty() &&
      !std::filesystem::exists(GetAbsolutePath(symbols_filename))) {
    missing.push_back(symbols_filename);
  }
  if (!hack_manifest_file.empty() &&
      !std::filesystem::exists(GetAbsolutePath(hack_manifest_file))) {
    missing.push_back(hack_manifest_file);
  }
#endif  // __EMSCRIPTEN__
 
  return missing;
}
 
absl::Status YazeProject::RepairProject() {
#ifdef __EMSCRIPTEN__
  // In the web build, filesystem layout is virtual; nothing to repair eagerly.
  return absl::OkStatus();
#else
  // Create missing directories
  std::vector<std::string> folders = {code_folder, assets_folder,
                                      patches_folder, rom_backup_folder,
                                      output_folder};
 
  for (const auto& folder : folders) {
    if (!folder.empty()) {
      std::filesystem::path abs_path = GetAbsolutePath(folder);
      if (!std::filesystem::exists(abs_path)) {
        std::filesystem::create_directories(abs_path);
      }
    }
  }
 
  // Create missing files with defaults
  if (!labels_filename.empty()) {
    std::filesystem::path abs_labels = GetAbsolutePath(labels_filename);
    if (!std::filesystem::exists(abs_labels)) {
      std::ofstream labels_file(abs_labels);
      labels_file << "# yaze Resource Labels\n";
      labels_file << "# Format: [type] key=value\n\n";
      labels_file.close();
    }
  }
 
  return absl::OkStatus();
#endif
}
 
std::string YazeProject::GetDisplayName() const {
  if (!metadata.description.empty()) {
    return metadata.description;
  }
  return name.empty() ? "Untitled Project" : name;
}
 
std::string YazeProject::GetRelativePath(
    const std::string& absolute_path) const {
  if (absolute_path.empty() || filepath.empty())
    return absolute_path;
 
  std::filesystem::path project_dir =
      std::filesystem::path(filepath).parent_path();
  std::filesystem::path abs_path(absolute_path);
 
  try {
    std::filesystem::path relative =
        std::filesystem::relative(abs_path.lexically_normal(), project_dir);
    // Persist relative paths in a platform-neutral format for project files.
    return relative.generic_string();
  } catch (...) {
    // Return normalized absolute path if relative conversion fails.
    return abs_path.lexically_normal().generic_string();
  }
}
 
std::string YazeProject::GetAbsolutePath(
    const std::string& relative_path) const {
  if (relative_path.empty() || filepath.empty())
    return relative_path;
 
  std::filesystem::path project_dir =
      std::filesystem::path(filepath).parent_path();
  std::filesystem::path abs_path(relative_path);
  if (abs_path.is_absolute()) {
    abs_path = abs_path.lexically_normal();
    abs_path.make_preferred();
    return abs_path.string();
  }
  abs_path = (project_dir / abs_path).lexically_normal();
  abs_path.make_preferred();
 
  return abs_path.string();
}
 
void YazeProject::NormalizePathsToAbsolute() {
#ifdef __EMSCRIPTEN__
  // Web builds rely on a virtual filesystem and often use relative paths.
  return;
#endif
  if (filepath.empty()) {
    return;
  }
 
  auto normalize = [this](std::string* path) {
    if (!path || path->empty()) {
      return;
    }
    *path = GetAbsolutePath(*path);
  };
 
  normalize(&rom_filename);
  normalize(&rom_backup_folder);
  normalize(&code_folder);
  normalize(&assets_folder);
  normalize(&patches_folder);
  normalize(&labels_filename);
  normalize(&symbols_filename);
  normalize(&custom_objects_folder);
  normalize(&hack_manifest_file);
  normalize(&sprite_catalog_file);
  normalize(&sprite_source_root);
  normalize(&overworld_graphics_preview);
  normalize(&dungeon_tile_patterns);
  normalize(&terrain_catalog_file);
  normalize(&lyra_terrain_file);
  normalize(&lyra_build_request_file);
  normalize(&native_save_producer_file);
  normalize(&native_save_transfer_proof_file);
  normalize(&native_save_receipt_file);
  normalize(&palette_catalog_file);
  for (auto& asset : sprite_assets) {
    normalize(&asset.zsm_path);
    for (auto& source : asset.graphics_sources) {
      if (source.kind == "bin") {
        normalize(&source.path);
      }
    }
  }
  normalize(&output_folder);
 
  for (auto& rom_path : additional_roms) {
    if (!rom_path.empty()) {
      rom_path = GetAbsolutePath(rom_path);
    }
  }
}
 
std::vector<std::string> YazeProject::AtlasAnnotationPaths() const {
  std::vector<std::string> paths;
  paths.reserve(atlas.annotations.size());
  for (const auto& path : atlas.annotations) {
    paths.push_back(GetAbsolutePath(path));
  }
  return paths;
}
 
std::string YazeProject::AtlasSymbolsPath() const {
  return GetAbsolutePath(atlas.symbols);
}
 
std::string YazeProject::PlanningFilePath() const {
  return GetAbsolutePath(planning.file);
}
 
bool YazeProject::IsEmpty() const {
  return name.empty() && rom_filename.empty() && code_folder.empty();
}
 
absl::Status YazeProject::ImportFromZScreamFormat(
    const std::string& project_path) {
  // TODO: Implement ZScream format parsing when format specification is
  // available For now, create a basic project that can be manually configured
 
  std::filesystem::path zs_path(project_path);
  name = zs_path.stem().string() + "_imported";
  zscream_project_file = project_path;
 
  InitializeDefaults();
 
  return absl::OkStatus();
}
 
void YazeProject::ReloadHackManifest() {
  TryLoadHackManifest();
}
 
void YazeProject::ReloadZ3dkSettings() {
  TryLoadZ3dkConfig();
}
 
std::string YazeProject::GetZ3dkArtifactPath(
    absl::string_view artifact_name) const {
  std::filesystem::path base_dir;
  if (!output_folder.empty()) {
    base_dir = output_folder;
  } else if (!z3dk_settings.config_path.empty()) {
    base_dir = std::filesystem::path(z3dk_settings.config_path).parent_path();
  } else if (!code_folder.empty()) {
    base_dir = code_folder;
  } else if (!filepath.empty()) {
    base_dir = std::filesystem::path(filepath).parent_path();
  }
 
  if (base_dir.empty()) {
    return std::string(artifact_name);
  }
  return (base_dir / std::string(artifact_name)).lexically_normal().string();
}
 
void YazeProject::TryLoadZ3dkConfig() {
  z3dk_settings = Z3dkSettings{};
 
#if defined(YAZE_WITH_Z3DK) && __has_include("z3dk_core/config.h")
  std::vector<std::filesystem::path> candidates;
  auto add_candidate = [&candidates](const std::filesystem::path& candidate) {
    if (candidate.empty()) {
      return;
    }
    auto normalized = candidate.lexically_normal();
    if (std::find(candidates.begin(), candidates.end(), normalized) ==
        candidates.end()) {
      candidates.push_back(normalized);
    }
  };
 
  if (!code_folder.empty()) {
    std::filesystem::path code_path(code_folder);
    if (!std::filesystem::is_directory(code_path)) {
      code_path = code_path.parent_path();
    }
    add_candidate(code_path / "z3dk.toml");
  }
 
  if (!hack_manifest_file.empty()) {
    add_candidate(std::filesystem::path(hack_manifest_file).parent_path() /
                  "z3dk.toml");
  }
 
  if (!filepath.empty()) {
    add_candidate(std::filesystem::path(filepath).parent_path() / "z3dk.toml");
  }
 
  for (const auto& candidate : candidates) {
    if (!std::filesystem::exists(candidate)) {
      continue;
    }
 
    std::string error;
    z3dk::Config config = z3dk::LoadConfigFile(candidate.string(), &error);
    if (!error.empty()) {
      LOG_WARN("Project", "Failed to parse z3dk config '%s': %s",
               candidate.string().c_str(), error.c_str());
      continue;
    }
 
    const std::filesystem::path base_dir = candidate.parent_path();
    z3dk_settings.loaded = true;
    z3dk_settings.config_path = candidate.string();
    if (config.preset.has_value()) {
      z3dk_settings.preset = *config.preset;
    }
 
    z3dk_settings.include_paths.reserve(config.include_paths.size());
    for (const auto& include_path : config.include_paths) {
      z3dk_settings.include_paths.push_back(
          ResolveOptionalPath(base_dir, include_path));
    }
 
    z3dk_settings.defines.reserve(config.defines.size());
    for (const auto& define : config.defines) {
      z3dk_settings.defines.push_back(ParseDefineToken(define));
    }
 
    z3dk_settings.main_files.reserve(config.main_files.size());
    for (const auto& main_file : config.main_files) {
      z3dk_settings.main_files.push_back(
          ResolveOptionalPath(base_dir, main_file));
    }
 
    if (config.std_includes_path.has_value()) {
      z3dk_settings.std_includes_path =
          ResolveOptionalPath(base_dir, *config.std_includes_path);
    }
    if (config.std_defines_path.has_value()) {
      z3dk_settings.std_defines_path =
          ResolveOptionalPath(base_dir, *config.std_defines_path);
    }
    if (config.mapper.has_value()) {
      z3dk_settings.mapper = *config.mapper;
    }
    if (config.rom_size.has_value()) {
      z3dk_settings.rom_size = *config.rom_size;
    }
    if (config.symbols_format.has_value()) {
      z3dk_settings.symbols_format = *config.symbols_format;
    }
    z3dk_settings.lsp_log_enabled = config.lsp_log_enabled;
    if (config.lsp_log_path.has_value()) {
      z3dk_settings.lsp_log_path =
          ResolveOptionalPath(base_dir, *config.lsp_log_path);
    }
 
    z3dk_settings.emits.reserve(config.emits.size());
    for (const auto& emit_path : config.emits) {
      z3dk_settings.emits.push_back(ResolveOptionalPath(base_dir, emit_path));
    }
 
    for (const auto& range : config.prohibited_memory_ranges) {
      z3dk_settings.prohibited_memory_ranges.push_back(
          {.start = range.start, .end = range.end, .reason = range.reason});
    }
 
    z3dk_settings.warn_unused_symbols =
        config.warn_unused_symbols.value_or(true);
    z3dk_settings.warn_branch_outside_bank =
        config.warn_branch_outside_bank.value_or(true);
    z3dk_settings.warn_unknown_width = config.warn_unknown_width.value_or(true);
    z3dk_settings.warn_org_collision = config.warn_org_collision.value_or(true);
    z3dk_settings.warn_unauthorized_hook =
        config.warn_unauthorized_hook.value_or(true);
    z3dk_settings.warn_stack_balance = config.warn_stack_balance.value_or(true);
    z3dk_settings.warn_hook_return = config.warn_hook_return.value_or(true);
 
    if (config.rom_path.has_value()) {
      z3dk_settings.rom_path = ResolveOptionalPath(base_dir, *config.rom_path);
    }
    if (config.symbols_path.has_value()) {
      z3dk_settings.symbols_path =
          ResolveOptionalPath(base_dir, *config.symbols_path);
    }
 
    for (const auto& emit_path : z3dk_settings.emits) {
      const std::string basename = BasenameLower(emit_path);
      if (basename.ends_with(".mlb") &&
          z3dk_settings.artifact_paths.symbols_mlb.empty()) {
        z3dk_settings.artifact_paths.symbols_mlb = emit_path;
      } else if (basename == "sourcemap.json") {
        z3dk_settings.artifact_paths.sourcemap_json = emit_path;
      } else if (basename == "annotations.json") {
        z3dk_settings.artifact_paths.annotations_json = emit_path;
      } else if (basename == "hooks.json") {
        z3dk_settings.artifact_paths.hooks_json = emit_path;
      } else if (basename == "lint.json") {
        z3dk_settings.artifact_paths.lint_json = emit_path;
      }
    }
 
    if (z3dk_settings.artifact_paths.symbols_mlb.empty()) {
      if (!z3dk_settings.symbols_path.empty() &&
          BasenameLower(z3dk_settings.symbols_path).ends_with(".mlb")) {
        z3dk_settings.artifact_paths.symbols_mlb = z3dk_settings.symbols_path;
      } else {
        z3dk_settings.artifact_paths.symbols_mlb =
            GetZ3dkArtifactPath("symbols.mlb");
      }
    }
    if (z3dk_settings.artifact_paths.sourcemap_json.empty()) {
      z3dk_settings.artifact_paths.sourcemap_json =
          GetZ3dkArtifactPath("sourcemap.json");
    }
    if (z3dk_settings.artifact_paths.annotations_json.empty()) {
      z3dk_settings.artifact_paths.annotations_json =
          GetZ3dkArtifactPath("annotations.json");
    }
    if (z3dk_settings.artifact_paths.hooks_json.empty()) {
      z3dk_settings.artifact_paths.hooks_json =
          GetZ3dkArtifactPath("hooks.json");
    }
    if (z3dk_settings.artifact_paths.lint_json.empty()) {
      z3dk_settings.artifact_paths.lint_json = GetZ3dkArtifactPath("lint.json");
    }
 
    LOG_INFO("Project",
             "Loaded z3dk config from %s (%zu include paths, %zu defines)",
             z3dk_settings.config_path.c_str(),
             z3dk_settings.include_paths.size(), z3dk_settings.defines.size());
    return;
  }
#endif
}
 
void YazeProject::TryLoadHackManifest() {
#ifdef __EMSCRIPTEN__
  hack_manifest.Clear();
  zelda3::GetResourceLabels().SetHackManifest(nullptr);
  return;  // Hack manifests not supported in web builds
#endif
 
  // Clear previous state so we never keep a stale manifest across project loads.
  hack_manifest.Clear();
  zelda3::GetResourceLabels().SetHackManifest(nullptr);
 
  std::filesystem::path loaded_manifest_path;
  auto load_manifest = [&](const std::filesystem::path& candidate,
                           bool update_project_setting) -> bool {
    if (candidate.empty() || !std::filesystem::exists(candidate)) {
      return false;
    }
    auto status = hack_manifest.LoadFromFile(candidate.string());
    if (!status.ok()) {
      LOG_WARN("Project", "Failed to load hack manifest %s: %s",
               candidate.string().c_str(),
               std::string(status.message()).c_str());
      return false;
    }
    loaded_manifest_path = candidate;
    if (update_project_setting) {
      hack_manifest_file = GetRelativePath(candidate.string());
    }
    LOG_DEBUG("Project", "Loaded hack manifest: %s",
              candidate.string().c_str());
    zelda3::GetResourceLabels().SetHackManifest(&hack_manifest);
    return true;
  };
 
  // Priority 1: An explicit hack_manifest_file setting is authoritative. Do
  // not silently replace a missing or malformed configured manifest with an
  // auto-discovered file; project validation must surface the bad reference.
  const bool has_explicit_manifest = !hack_manifest_file.empty();
  if (has_explicit_manifest) {
    (void)load_manifest(GetAbsolutePath(hack_manifest_file), false);
  }
 
  // Priority 2: Auto-discover hack_manifest.json in code_folder.
  if (!has_explicit_manifest && !hack_manifest.loaded() &&
      !code_folder.empty()) {
    auto code_path = GetAbsolutePath(code_folder);
    auto candidate = std::filesystem::path(code_path) / "hack_manifest.json";
    (void)load_manifest(candidate, true);
  }
 
  // Priority 3: Fallback to the project file directory (or its parent).
  if (!has_explicit_manifest && !hack_manifest.loaded() && !filepath.empty()) {
    const std::filesystem::path project_dir =
        std::filesystem::path(filepath).parent_path();
    (void)load_manifest(project_dir / "hack_manifest.json", true);
    if (!hack_manifest.loaded() && project_dir.has_parent_path()) {
      (void)load_manifest(project_dir.parent_path() / "hack_manifest.json",
                          true);
    }
  }
 
  if (hack_manifest.loaded()) {
    zelda3::GetResourceLabels().SetHackManifest(&hack_manifest);
  }
 
  auto try_load_registry = [&](const std::filesystem::path& base) -> bool {
    if (base.empty()) {
      return false;
    }
    const auto planning = base / "Docs" / "Dev" / "Planning";
    if (!std::filesystem::exists(planning)) {
      return false;
    }
    auto status = hack_manifest.LoadProjectRegistry(base.string());
    if (!status.ok()) {
      LOG_WARN("Project", "Failed to load project registry from %s: %s",
               base.string().c_str(), std::string(status.message()).c_str());
      return false;
    }
    return hack_manifest.HasProjectRegistry();
  };
 
  bool registry_loaded = false;
 
  // Prefer configured code_folder when valid.
  if (!code_folder.empty()) {
    registry_loaded =
        try_load_registry(std::filesystem::path(GetAbsolutePath(code_folder)));
  }
 
  // Fallback to the manifest directory if code_folder is stale/misconfigured.
  if (!registry_loaded && !loaded_manifest_path.empty()) {
    registry_loaded = try_load_registry(loaded_manifest_path.parent_path());
  }
 
  // Last fallback: project directory.
  if (!registry_loaded && !filepath.empty()) {
    registry_loaded =
        try_load_registry(std::filesystem::path(filepath).parent_path());
  }
 
  if (!registry_loaded) {
    if (!hack_manifest.loaded()) {
      return;
    }
    LOG_WARN("Project",
             "Hack manifest loaded but project registry was not found "
             "(code_folder='%s', manifest='%s')",
             code_folder.c_str(), loaded_manifest_path.string().c_str());
    return;
  }
 
  // Inject all Oracle resource labels into project resource_labels.
  size_t injected = 0;
  for (const auto& [type_key, labels] :
       hack_manifest.project_registry().all_resource_labels) {
    for (const auto& [id_str, label] : labels) {
      resource_labels[type_key][id_str] = label;
      ++injected;
    }
  }
  LOG_DEBUG("Project", "Loaded project registry: %zu resource labels injected",
            injected);
}
 
void YazeProject::InitializeDefaults() {
  sprite_catalog_file.clear();
  sprite_source_root.clear();
  sprite_assets.clear();
  terrain_catalog_file.clear();
  lyra_terrain_file.clear();
  lyra_build_request_file.clear();
  native_save_producer_file.clear();
  native_save_transfer_proof_file.clear();
  native_save_receipt_file.clear();
  palette_catalog_file.clear();
  dungeon_tile_patterns.clear();
  if (metadata.project_id.empty()) {
    metadata.project_id = GenerateProjectId();
  }
 
  // Initialize default feature flags
  feature_flags.overworld.kLoadCustomOverworld = false;
  feature_flags.overworld.kApplyZSCustomOverworldASM = false;
  feature_flags.kSaveDungeonMaps = true;
  feature_flags.dungeon.kSaveObjects = true;
  feature_flags.dungeon.kSaveSprites = true;
  feature_flags.dungeon.kSaveRoomHeaders = true;
  feature_flags.dungeon.kSaveTorches = true;
  feature_flags.dungeon.kSavePits = true;
  feature_flags.dungeon.kSaveBlocks = true;
  feature_flags.dungeon.kSaveCollision = true;
  feature_flags.dungeon.kSaveChests = true;
  feature_flags.dungeon.kSavePotItems = true;
  feature_flags.dungeon.kSaveEntrances = true;
  feature_flags.dungeon.kSavePalettes = true;
  feature_flags.kSaveGraphicsSheet = true;
  // REMOVED: kLogInstructions (deprecated)
 
  // Initialize default workspace settings
  workspace_settings.font_global_scale = 1.0f;
  workspace_settings.dark_mode = true;
  workspace_settings.ui_theme = "default";
  workspace_settings.autosave_enabled = true;
  workspace_settings.autosave_interval_secs = 300.0f;  // 5 minutes
  workspace_settings.backup_on_save = true;
  workspace_settings.backup_retention_count = 20;
  workspace_settings.backup_keep_daily = true;
  workspace_settings.backup_keep_daily_days = 14;
  workspace_settings.show_grid = true;
  workspace_settings.show_collision = false;
 
  // Initialize default dungeon overlay settings (minecart tracks)
  dungeon_overlay.track_tiles.clear();
  for (uint16_t tile = 0xB0; tile <= 0xBE; ++tile) {
    dungeon_overlay.track_tiles.push_back(tile);
  }
  dungeon_overlay.track_stop_tiles = {0xB7, 0xB8, 0xB9, 0xBA};
  dungeon_overlay.track_switch_tiles = {0xD0, 0xD1, 0xD2, 0xD3};
  dungeon_overlay.track_object_ids = {0x31};
  dungeon_overlay.minecart_sprite_ids = {0xA3};
 
  rom_metadata.role = RomRole::kDev;
  rom_metadata.expected_hash.clear();
  rom_metadata.write_policy = RomWritePolicy::kWarn;
 
  // Initialize default build configurations
  build_configurations = {"Debug", "Release", "Distribution"};
  build_target.clear();
  asm_entry_point = "asm/main.asm";
  asm_sources = {"asm"};
  last_build_hash.clear();
  build_number = 0;
 
  track_changes = true;
 
  music_persistence.persist_custom_music = true;
  music_persistence.storage_key = MakeStorageKey("music");
  music_persistence.last_saved_at.clear();
 
  if (metadata.created_by.empty()) {
    metadata.created_by = "YAZE";
  }
}
 
std::string YazeProject::GenerateProjectId() const {
  auto now = std::chrono::system_clock::now().time_since_epoch();
  auto timestamp =
      std::chrono::duration_cast<std::chrono::milliseconds>(now).count();
  return absl::StrFormat("yaze_project_%lld", timestamp);
}
 
// ProjectManager Implementation
std::vector<ProjectManager::ProjectTemplate>
ProjectManager::GetProjectTemplates() {
  std::vector<ProjectTemplate> templates;
 
  // ==========================================================================
  // ZSCustomOverworld Templates (Recommended)
  // ==========================================================================
 
  // Vanilla ROM Hack - no ZSO
  {
    ProjectTemplate t;
    t.name = "Vanilla ROM Hack";
    t.description =
        "Standard ROM editing without custom ASM. Limited to vanilla features.";
    t.icon = ICON_MD_VIDEOGAME_ASSET;
    t.template_project.feature_flags.overworld.kLoadCustomOverworld = false;
    t.template_project.feature_flags.overworld.kApplyZSCustomOverworldASM =
        false;
    t.template_project.feature_flags.overworld.kSaveOverworldMaps = true;
    t.template_project.feature_flags.overworld.kSaveOverworldEntrances = true;
    t.template_project.feature_flags.overworld.kSaveOverworldExits = true;
    t.template_project.feature_flags.overworld.kSaveOverworldItems = true;
    templates.push_back(t);
  }
 
  // ZSCustomOverworld v2 - Basic expansion
  {
    ProjectTemplate t;
    t.name = "ZSCustomOverworld v2";
    t.description =
        "Basic overworld expansion: custom BG colors, main palettes, parent "
        "system.";
    t.icon = ICON_MD_MAP;
    t.template_project.feature_flags.overworld.kLoadCustomOverworld = true;
    t.template_project.feature_flags.overworld.kApplyZSCustomOverworldASM =
        true;
    t.template_project.feature_flags.overworld.kSaveOverworldMaps = true;
    t.template_project.feature_flags.overworld.kSaveOverworldEntrances = true;
    t.template_project.feature_flags.overworld.kSaveOverworldExits = true;
    t.template_project.feature_flags.overworld.kSaveOverworldItems = true;
    t.template_project.feature_flags.kSaveAllPalettes = true;
    t.template_project.feature_flags.kSaveGfxGroups = true;
    t.template_project.metadata.tags = {"zso_v2", "overworld", "expansion"};
    templates.push_back(t);
  }
 
  // ZSCustomOverworld v3 - Full features (Recommended)
  {
    ProjectTemplate t;
    t.name = "ZSCustomOverworld v3 (Recommended)";
    t.description =
        "Full overworld expansion: wide/tall areas, animated GFX, overlays, "
        "all features.";
    t.icon = ICON_MD_TERRAIN;
    t.template_project.feature_flags.overworld.kLoadCustomOverworld = true;
    t.template_project.feature_flags.overworld.kApplyZSCustomOverworldASM =
        true;
    t.template_project.feature_flags.overworld.kSaveOverworldMaps = true;
    t.template_project.feature_flags.overworld.kSaveOverworldEntrances = true;
    t.template_project.feature_flags.overworld.kSaveOverworldExits = true;
    t.template_project.feature_flags.overworld.kSaveOverworldItems = true;
    t.template_project.feature_flags.overworld.kSaveOverworldProperties = true;
    t.template_project.feature_flags.kSaveAllPalettes = true;
    t.template_project.feature_flags.kSaveGfxGroups = true;
    t.template_project.feature_flags.kSaveDungeonMaps = true;
    t.template_project.feature_flags.kSaveGraphicsSheet = true;
    t.template_project.metadata.tags = {"zso_v3", "overworld", "full",
                                        "recommended"};
    templates.push_back(t);
  }
 
  // Randomizer Compatible
  {
    ProjectTemplate t;
    t.name = "Randomizer Compatible";
    t.description =
        "Compatible with ALttP Randomizer. Minimal custom features to avoid "
        "conflicts.";
    t.icon = ICON_MD_SHUFFLE;
    t.template_project.feature_flags.overworld.kLoadCustomOverworld = false;
    t.template_project.feature_flags.overworld.kApplyZSCustomOverworldASM =
        false;
    t.template_project.feature_flags.overworld.kSaveOverworldMaps = false;
    t.template_project.feature_flags.overworld.kSaveOverworldSprites = false;
    t.template_project.feature_flags.kSaveDungeonMaps = false;
    t.template_project.metadata.tags = {"randomizer", "compatible", "minimal"};
    templates.push_back(t);
  }
 
  // ==========================================================================
  // Editor-Focused Templates
  // ==========================================================================
 
  // Dungeon Designer
  {
    ProjectTemplate t;
    t.name = "Dungeon Designer";
    t.description = "Focused on dungeon creation and modification.";
    t.icon = ICON_MD_DOMAIN;
    t.template_project.feature_flags.kSaveDungeonMaps = true;
    t.template_project.workspace_settings.show_grid = true;
    t.template_project.workspace_settings.last_layout_preset =
        "dungeon_default";
    t.template_project.metadata.tags = {"dungeons", "rooms", "design"};
    templates.push_back(t);
  }
 
  // Graphics Pack
  {
    ProjectTemplate t;
    t.name = "Graphics Pack";
    t.description =
        "Project focused on graphics, sprites, and visual modifications.";
    t.icon = ICON_MD_PALETTE;
    t.template_project.feature_flags.kSaveGraphicsSheet = true;
    t.template_project.feature_flags.kSaveAllPalettes = true;
    t.template_project.feature_flags.kSaveGfxGroups = true;
    t.template_project.workspace_settings.show_grid = true;
    t.template_project.workspace_settings.last_layout_preset =
        "graphics_default";
    t.template_project.metadata.tags = {"graphics", "sprites", "palettes"};
    templates.push_back(t);
  }
 
  // Complete Overhaul
  {
    ProjectTemplate t;
    t.name = "Complete Overhaul";
    t.description = "Full-scale ROM hack with all features enabled.";
    t.icon = ICON_MD_BUILD;
    t.template_project.feature_flags.overworld.kLoadCustomOverworld = true;
    t.template_project.feature_flags.overworld.kApplyZSCustomOverworldASM =
        true;
    t.template_project.feature_flags.overworld.kSaveOverworldMaps = true;
    t.template_project.feature_flags.overworld.kSaveOverworldEntrances = true;
    t.template_project.feature_flags.overworld.kSaveOverworldExits = true;
    t.template_project.feature_flags.overworld.kSaveOverworldItems = true;
    t.template_project.feature_flags.overworld.kSaveOverworldProperties = true;
    t.template_project.feature_flags.kSaveDungeonMaps = true;
    t.template_project.feature_flags.kSaveGraphicsSheet = true;
    t.template_project.feature_flags.kSaveAllPalettes = true;
    t.template_project.feature_flags.kSaveGfxGroups = true;
    t.template_project.metadata.tags = {"complete", "overhaul", "full-mod"};
    templates.push_back(t);
  }
 
  return templates;
}
 
absl::StatusOr<YazeProject> ProjectManager::CreateFromTemplate(
    const std::string& template_name, const std::string& project_name,
    const std::string& base_path) {
  YazeProject project;
  auto status = project.Create(project_name, base_path);
  if (!status.ok()) {
    return status;
  }
 
  // Customize based on template
  if (template_name == "Full Overworld Mod") {
    project.feature_flags.overworld.kLoadCustomOverworld = true;
    project.feature_flags.overworld.kApplyZSCustomOverworldASM = true;
    project.metadata.description = "Overworld modification project";
    project.metadata.tags = {"overworld", "maps", "graphics"};
  } else if (template_name == "Dungeon Designer") {
    project.feature_flags.kSaveDungeonMaps = true;
    project.workspace_settings.show_grid = true;
    project.metadata.description = "Dungeon design and modification project";
    project.metadata.tags = {"dungeons", "rooms", "design"};
  } else if (template_name == "Graphics Pack") {
    project.feature_flags.kSaveGraphicsSheet = true;
    project.workspace_settings.show_grid = true;
    project.metadata.description = "Graphics and sprite modification project";
    project.metadata.tags = {"graphics", "sprites", "palettes"};
  } else if (template_name == "Complete Overhaul") {
    project.feature_flags.overworld.kLoadCustomOverworld = true;
    project.feature_flags.overworld.kApplyZSCustomOverworldASM = true;
    project.feature_flags.kSaveDungeonMaps = true;
    project.feature_flags.kSaveGraphicsSheet = true;
    project.metadata.description = "Complete ROM overhaul project";
    project.metadata.tags = {"complete", "overhaul", "full-mod"};
  }
 
  status = project.Save();
  if (!status.ok()) {
    return status;
  }
 
  return project;
}
 
std::vector<std::string> ProjectManager::FindProjectsInDirectory(
    const std::string& directory) {
#ifdef __EMSCRIPTEN__
  (void)directory;
  return {};
#else
  std::vector<std::string> projects;
 
  try {
    for (const auto& entry : std::filesystem::directory_iterator(directory)) {
      if (entry.is_regular_file()) {
        std::string filename = entry.path().filename().string();
        if (filename.ends_with(".yaze") || filename.ends_with(".zsproj")) {
          projects.push_back(entry.path().string());
        }
      } else if (entry.is_directory()) {
        std::string filename = entry.path().filename().string();
        if (filename.ends_with(".yazeproj")) {
          projects.push_back(entry.path().string());
        }
      }
    }
  } catch (const std::filesystem::filesystem_error& e) {
    // Directory doesn't exist or can't be accessed
  }
 
  return projects;
#endif  // __EMSCRIPTEN__
}
 
absl::Status ProjectManager::BackupProject(const YazeProject& project) {
#ifdef __EMSCRIPTEN__
  (void)project;
  return absl::UnimplementedError(
      "Project backups are not supported in the web build");
#else
  if (project.filepath.empty()) {
    return absl::InvalidArgumentError("Project has no file path");
  }
 
  std::filesystem::path project_path(project.filepath);
  std::filesystem::path backup_dir = project_path.parent_path() / "backups";
  std::filesystem::create_directories(backup_dir);
 
  auto now = std::chrono::system_clock::now();
  auto time_t = std::chrono::system_clock::to_time_t(now);
  std::stringstream ss;
  ss << std::put_time(std::localtime(&time_t), "%Y%m%d_%H%M%S");
 
  std::string backup_filename = project.name + "_backup_" + ss.str() + ".yaze";
  std::filesystem::path backup_path = backup_dir / backup_filename;
 
  try {
    std::filesystem::copy_file(project.filepath, backup_path);
  } catch (const std::filesystem::filesystem_error& e) {
    return absl::InternalError(
        absl::StrFormat("Failed to backup project: %s", e.what()));
  }
 
  return absl::OkStatus();
#endif
}
 
absl::Status ProjectManager::ValidateProjectStructure(
    const YazeProject& project) {
  return project.Validate();
}
 
std::vector<std::string> ProjectManager::GetRecommendedFixesForProject(
    const YazeProject& project) {
  std::vector<std::string> recommendations;
 
  if (project.rom_filename.empty()) {
    recommendations.push_back("Add a ROM file to begin editing");
  }
 
  if (project.code_folder.empty()) {
    recommendations.push_back("Set up a code folder for assembly patches");
  }
 
  if (project.labels_filename.empty()) {
    recommendations.push_back("Create a labels file for better organization");
  }
 
  if (project.metadata.description.empty()) {
    recommendations.push_back("Add a project description for documentation");
  }
 
  if (project.git_repository.empty() && project.track_changes) {
    recommendations.push_back(
        "Consider setting up version control for your project");
  }
 
  auto missing_files = project.GetMissingFiles();
  if (!missing_files.empty()) {
    recommendations.push_back(
        "Some project files are missing - use Project > Repair to fix");
  }
 
  return recommendations;
}
 
// Compatibility implementations for ResourceLabelManager and related classes
bool ResourceLabelManager::LoadLabels(const std::string& filename) {
  filename_ = filename;
  std::ifstream file(filename);
  if (!file.is_open()) {
    labels_loaded_ = false;
    return false;
  }
 
  labels_.clear();
  std::string line;
  std::string current_type = "";
 
  while (std::getline(file, line)) {
    if (line.empty() || line[0] == '#')
      continue;
 
    // Check for type headers [type_name]
    if (line[0] == '[' && line.back() == ']') {
      current_type = line.substr(1, line.length() - 2);
      continue;
    }
 
    // Parse key=value pairs
    size_t eq_pos = line.find('=');
    if (eq_pos != std::string::npos && !current_type.empty()) {
      std::string key = line.substr(0, eq_pos);
      std::string value = line.substr(eq_pos + 1);
      labels_[current_type][key] = value;
    }
  }
 
  file.close();
  MigrateGfxGroupLabelKeys(labels_);
  labels_loaded_ = true;
  return true;
}
 
bool ResourceLabelManager::SaveLabels() {
  if (filename_.empty())
    return false;
 
  std::ofstream file(filename_);
  if (!file.is_open())
    return false;
 
  file << "# yaze Resource Labels\n";
  file << "# Format: [type] followed by key=value pairs\n\n";
 
  for (const auto& [type, type_labels] : labels_) {
    if (!type_labels.empty()) {
      file << "[" << type << "]\n";
      for (const auto& [key, value] : type_labels) {
        file << key << "=" << value << "\n";
      }
      file << "\n";
    }
  }
 
  file.close();
  return true;
}
 
void ResourceLabelManager::DisplayLabels(bool* p_open) {
  if (!p_open || !*p_open)
    return;
 
  // Basic implementation - can be enhanced later
  if (ImGui::Begin("Resource Labels", p_open)) {
    ImGui::Text("Resource Labels Manager");
    ImGui::Text("Labels loaded: %s", labels_loaded_ ? "Yes" : "No");
    ImGui::Text("Total types: %zu", labels_.size());
 
    for (const auto& [type, type_labels] : labels_) {
      if (ImGui::TreeNode(type.c_str())) {
        ImGui::Text("Labels: %zu", type_labels.size());
        for (const auto& [key, value] : type_labels) {
          ImGui::Text("%s = %s", key.c_str(), value.c_str());
        }
        ImGui::TreePop();
      }
    }
  }
  ImGui::End();
}
 
void ResourceLabelManager::EditLabel(const std::string& type,
                                     const std::string& key,
                                     const std::string& newValue) {
  labels_[type][key] = newValue;
}
 
void ResourceLabelManager::SelectableLabelWithNameEdit(
    bool selected, const std::string& type, const std::string& key,
    const std::string& defaultValue) {
  const auto custom_label = GetLabel(type, key);
  const auto& label = custom_label.empty() ? defaultValue : custom_label;
  if (ImGui::Selectable(
          absl::StrFormat("%s: %s", key.c_str(), label.c_str()).c_str(),
          selected)) {
    // Handle selection
  }
}
 
std::string ResourceLabelManager::GetLabel(const std::string& type,
                                           const std::string& key) {
  auto type_it = labels_.find(type);
  if (type_it == labels_.end())
    return "";
 
  auto label_it = type_it->second.find(key);
  if (label_it == type_it->second.end())
    return "";
 
  return label_it->second;
}
 
std::string ResourceLabelManager::CreateOrGetLabel(
    const std::string& type, const std::string& key,
    const std::string& defaultValue) {
  auto existing = GetLabel(type, key);
  if (!existing.empty())
    return existing;
 
  labels_[type][key] = defaultValue;
  return defaultValue;
}
 
// ============================================================================
// Embedded Labels Support
// ============================================================================
 
absl::Status YazeProject::InitializeEmbeddedLabels(
    const std::unordered_map<
        std::string, std::unordered_map<std::string, std::string>>& labels) {
  try {
    // Load all default Zelda3 resource names into resource_labels
    // We merge them with existing labels, prioritizing existing overrides?
    // Or just overwrite? The previous code was:
    // resource_labels = zelda3::Zelda3Labels::ToResourceLabels();
    // which implies overwriting. But we want to keep overrides if possible.
    // However, this is usually called on load.
 
    // Let's overwrite for now to match previous behavior, assuming overrides
    // are loaded afterwards or this is initial setup.
    // Actually, if we load project then init embedded labels, we might lose overrides.
    // But typically overrides are loaded from the project file *into* resource_labels.
    // If we call this, we might clobber them.
    // The previous implementation clobbered resource_labels.
 
    // However, if we want to support overrides + embedded, we should merge.
    // But `resource_labels` was treated as "overrides" in the old code?
    // No, `resource_labels` was the container for loaded labels.
 
    // If I look at `LoadFromYazeFormat`:
    // It parses `[labels_type]` into `resource_labels`.
 
    // If `use_embedded_labels` is true, `InitializeEmbeddedLabels` is called?
    // I need to check when `InitializeEmbeddedLabels` is called.
 
    resource_labels = labels;
    use_embedded_labels = true;
 
    LOG_DEBUG("Project", "Initialized embedded labels:");
    LOG_DEBUG("Project", "   - %d room names", resource_labels["room"].size());
    LOG_DEBUG("Project", "   - %d entrance names",
              resource_labels["entrance"].size());
    LOG_DEBUG("Project", "   - %d sprite names",
              resource_labels["sprite"].size());
    LOG_DEBUG("Project", "   - %d overlord names",
              resource_labels["overlord"].size());
    LOG_DEBUG("Project", "   - %d item names", resource_labels["item"].size());
    LOG_DEBUG("Project", "   - %d music names",
              resource_labels["music"].size());
    LOG_DEBUG("Project", "   - %d graphics names",
              resource_labels["graphics"].size());
    LOG_DEBUG("Project", "   - %d room effect names",
              resource_labels["room_effect"].size());
    LOG_DEBUG("Project", "   - %d room tag names",
              resource_labels["room_tag"].size());
    LOG_DEBUG("Project", "   - %d tile type names",
              resource_labels["tile_type"].size());
 
    return absl::OkStatus();
  } catch (const std::exception& e) {
    return absl::InternalError(
        absl::StrCat("Failed to initialize embedded labels: ", e.what()));
  }
}
 
std::string YazeProject::GetLabel(const std::string& resource_type, int id,
                                  const std::string& default_value) const {
  // First check if we have a custom label override
  auto type_it = resource_labels.find(resource_type);
  if (type_it != resource_labels.end()) {
    auto label_it = type_it->second.find(std::to_string(id));
    if (label_it != type_it->second.end()) {
      return label_it->second;
    }
  }
 
  return default_value.empty() ? resource_type + "_" + std::to_string(id)
                               : default_value;
}
 
absl::Status YazeProject::ImportLabelsFromZScream(const std::string& filepath) {
#ifdef __EMSCRIPTEN__
  (void)filepath;
  return absl::UnimplementedError(
      "File-based label import is not supported in the web build");
#else
  std::ifstream file(filepath);
  if (!file.is_open()) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Cannot open labels file: %s", filepath));
  }
 
  std::stringstream buffer;
  buffer << file.rdbuf();
  file.close();
 
  return ImportLabelsFromZScreamContent(buffer.str());
#endif
}
 
absl::Status YazeProject::ImportLabelsFromZScreamContent(
    const std::string& content) {
  // Initialize the global provider with our labels
  auto& provider = zelda3::GetResourceLabels();
  provider.SetProjectLabels(&resource_labels);
  provider.SetPreferHMagicNames(workspace_settings.prefer_hmagic_names);
 
  // Use the provider to parse ZScream format
  auto status = provider.ImportFromZScreamFormat(content);
  if (!status.ok()) {
    return status;
  }
 
  LOG_DEBUG("Project", "Imported ZScream labels:");
  LOG_DEBUG("Project", "   - %d sprite labels",
            resource_labels["sprite"].size());
  LOG_DEBUG("Project", "   - %d room labels", resource_labels["room"].size());
  LOG_DEBUG("Project", "   - %d item labels", resource_labels["item"].size());
  LOG_DEBUG("Project", "   - %d room tag labels",
            resource_labels["room_tag"].size());
 
  return absl::OkStatus();
}
 
void YazeProject::InitializeResourceLabelProvider() {
  auto& provider = zelda3::GetResourceLabels();
  provider.SetProjectLabels(&resource_labels);
  provider.SetPreferHMagicNames(workspace_settings.prefer_hmagic_names);
  provider.SetHackManifest(hack_manifest.loaded() ? &hack_manifest : nullptr);
 
  LOG_DEBUG("Project", "Initialized ResourceLabelProvider with project labels");
  LOG_DEBUG("Project", "   - prefer_hmagic_names: %s",
            workspace_settings.prefer_hmagic_names ? "true" : "false");
  LOG_DEBUG("Project", "   - hack_manifest: %s",
            hack_manifest.loaded() ? "loaded" : "not loaded");
}
 
// ============================================================================
// JSON Format Support (Optional)
// ============================================================================
 
#ifdef YAZE_ENABLE_JSON_PROJECT_FORMAT
 
absl::Status YazeProject::LoadFromJsonFormat(const std::string& project_path) {
  rom_metadata.write_policy = RomWritePolicy::kWarn;
  feature_flags.overworld.kSaveOverworldSprites = true;
  feature_flags.overworld.kEnableSpecialWorldExpansion = false;
  feature_flags.kSaveWithChangeQueue = false;
  terrain_catalog_file.clear();
  lyra_terrain_file.clear();
  lyra_build_request_file.clear();
  native_save_producer_file.clear();
  native_save_transfer_proof_file.clear();
  native_save_receipt_file.clear();
  palette_catalog_file.clear();
  dungeon_tile_patterns.clear();
#ifdef __EMSCRIPTEN__
  return absl::UnimplementedError(
      "JSON project format loading is not supported in the web build");
#endif
  std::ifstream file(project_path);
  if (!file.is_open()) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Cannot open JSON project file: %s", project_path));
  }
 
  try {
    Json j;
    file >> j;
 
    sprite_catalog_file.clear();
    sprite_source_root.clear();
    sprite_assets.clear();
 
    // Parse project metadata
    if (j.contains("yaze_project")) {
      auto& proj = j["yaze_project"];
 
      if (proj.contains("name"))
        name = proj["name"].get<std::string>();
      if (proj.contains("description"))
        metadata.description = proj["description"].get<std::string>();
      if (proj.contains("author"))
        metadata.author = proj["author"].get<std::string>();
      if (proj.contains("version"))
        metadata.version = proj["version"].get<std::string>();
      if (proj.contains("created"))
        metadata.created_date = proj["created"].get<std::string>();
      if (proj.contains("modified"))
        metadata.last_modified = proj["modified"].get<std::string>();
      if (proj.contains("created_by"))
        metadata.created_by = proj["created_by"].get<std::string>();
 
      // Files
      if (proj.contains("rom_filename"))
        rom_filename = proj["rom_filename"].get<std::string>();
      if (proj.contains("rom_backup_folder"))
        rom_backup_folder = proj["rom_backup_folder"].get<std::string>();
      if (proj.contains("code_folder"))
        code_folder = proj["code_folder"].get<std::string>();
      if (proj.contains("assets_folder"))
        assets_folder = proj["assets_folder"].get<std::string>();
      if (proj.contains("patches_folder"))
        patches_folder = proj["patches_folder"].get<std::string>();
      if (proj.contains("labels_filename"))
        labels_filename = proj["labels_filename"].get<std::string>();
      if (proj.contains("symbols_filename"))
        symbols_filename = proj["symbols_filename"].get<std::string>();
      if (proj.contains("dungeon_tile_patterns"))
        dungeon_tile_patterns =
            proj["dungeon_tile_patterns"].get<std::string>();
      if (proj.contains("palette_catalog_file"))
        palette_catalog_file = proj["palette_catalog_file"].get<std::string>();
      if (proj.contains("terrain_catalog_file"))
        terrain_catalog_file = proj["terrain_catalog_file"].get<std::string>();
      if (proj.contains("lyra_terrain_file"))
        lyra_terrain_file = proj["lyra_terrain_file"].get<std::string>();
      if (proj.contains("lyra_build_request_file"))
        lyra_build_request_file =
            proj["lyra_build_request_file"].get<std::string>();
      if (proj.contains("native_save_producer_file"))
        native_save_producer_file =
            proj["native_save_producer_file"].get<std::string>();
      if (proj.contains("native_save_transfer_proof_file"))
        native_save_transfer_proof_file =
            proj["native_save_transfer_proof_file"].get<std::string>();
      if (proj.contains("native_save_receipt_file"))
        native_save_receipt_file =
            proj["native_save_receipt_file"].get<std::string>();
      if (proj.contains("hack_manifest_file"))
        hack_manifest_file = proj["hack_manifest_file"].get<std::string>();
      if (proj.contains("sprite_catalog_file"))
        sprite_catalog_file = proj["sprite_catalog_file"].get<std::string>();
      if (proj.contains("sprite_source_root"))
        sprite_source_root = proj["sprite_source_root"].get<std::string>();
      if (proj.contains("sprite_assets")) {
        if (!proj["sprite_assets"].is_array() ||
            proj["sprite_assets"].size() > 4096)
          return absl::InvalidArgumentError("Invalid sprite_assets array");
        for (const auto& value : proj["sprite_assets"]) {
          auto asset = SpriteAssetFromJson(value);
          if (!asset.ok())
            return asset.status();
          for (const auto& prior : sprite_assets)
            if (prior.zsm_path == asset->zsm_path)
              return absl::InvalidArgumentError("Duplicate sprite asset path");
          sprite_assets.push_back(std::move(*asset));
        }
      }
 
      if (proj.contains("rom") && proj["rom"].is_object()) {
        auto& rom = proj["rom"];
        if (rom.contains("role"))
          rom_metadata.role = ParseRomRole(rom["role"].get<std::string>());
        if (rom.contains("expected_hash"))
          rom_metadata.expected_hash = rom["expected_hash"].get<std::string>();
        if (rom.contains("write_policy"))
          rom_metadata.write_policy =
              ParseRomWritePolicy(rom["write_policy"].get<std::string>());
      }
 
      // Embedded labels flag
      if (proj.contains("use_embedded_labels")) {
        use_embedded_labels = proj["use_embedded_labels"].get<bool>();
      }
 
      // Feature flags
      if (proj.contains("feature_flags")) {
        auto& flags = proj["feature_flags"];
        // REMOVED: kLogInstructions (deprecated - DisassemblyViewer always
        // active)
        if (flags.contains("kSaveDungeonMaps"))
          feature_flags.kSaveDungeonMaps =
              flags["kSaveDungeonMaps"].get<bool>();
        if (flags.contains("kSaveWithChangeQueue"))
          feature_flags.kSaveWithChangeQueue =
              flags["kSaveWithChangeQueue"].get<bool>();
        if (flags.contains("kEnableSpecialWorldExpansion"))
          feature_flags.overworld.kEnableSpecialWorldExpansion =
              flags["kEnableSpecialWorldExpansion"].get<bool>();
        if (flags.contains("kSaveOverworldMaps"))
          feature_flags.overworld.kSaveOverworldMaps =
              flags["kSaveOverworldMaps"].get<bool>();
        if (flags.contains("kSaveOverworldEntrances"))
          feature_flags.overworld.kSaveOverworldEntrances =
              flags["kSaveOverworldEntrances"].get<bool>();
        if (flags.contains("kSaveOverworldExits"))
          feature_flags.overworld.kSaveOverworldExits =
              flags["kSaveOverworldExits"].get<bool>();
        if (flags.contains("kSaveOverworldItems"))
          feature_flags.overworld.kSaveOverworldItems =
              flags["kSaveOverworldItems"].get<bool>();
        if (flags.contains("kSaveOverworldSprites"))
          feature_flags.overworld.kSaveOverworldSprites =
              flags["kSaveOverworldSprites"].get<bool>();
        if (flags.contains("kSaveOverworldProperties"))
          feature_flags.overworld.kSaveOverworldProperties =
              flags["kSaveOverworldProperties"].get<bool>();
        if (flags.contains("kSaveDungeonObjects"))
          feature_flags.dungeon.kSaveObjects =
              flags["kSaveDungeonObjects"].get<bool>();
        if (flags.contains("kSaveDungeonSprites"))
          feature_flags.dungeon.kSaveSprites =
              flags["kSaveDungeonSprites"].get<bool>();
        if (flags.contains("kSaveDungeonRoomHeaders"))
          feature_flags.dungeon.kSaveRoomHeaders =
              flags["kSaveDungeonRoomHeaders"].get<bool>();
        if (flags.contains("kSaveDungeonTorches"))
          feature_flags.dungeon.kSaveTorches =
              flags["kSaveDungeonTorches"].get<bool>();
        if (flags.contains("kSaveDungeonPits"))
          feature_flags.dungeon.kSavePits =
              flags["kSaveDungeonPits"].get<bool>();
        if (flags.contains("kSaveDungeonBlocks"))
          feature_flags.dungeon.kSaveBlocks =
              flags["kSaveDungeonBlocks"].get<bool>();
        if (flags.contains("kSaveDungeonCollision"))
          feature_flags.dungeon.kSaveCollision =
              flags["kSaveDungeonCollision"].get<bool>();
        if (flags.contains("kSaveDungeonWaterFillZones"))
          feature_flags.dungeon.kSaveWaterFillZones =
              flags["kSaveDungeonWaterFillZones"].get<bool>();
        if (flags.contains("kSaveDungeonChests"))
          feature_flags.dungeon.kSaveChests =
              flags["kSaveDungeonChests"].get<bool>();
        if (flags.contains("kSaveDungeonPotItems"))
          feature_flags.dungeon.kSavePotItems =
              flags["kSaveDungeonPotItems"].get<bool>();
        if (flags.contains("kSaveDungeonEntrances"))
          feature_flags.dungeon.kSaveEntrances =
              flags["kSaveDungeonEntrances"].get<bool>();
        if (flags.contains("kSaveDungeonPalettes"))
          feature_flags.dungeon.kSavePalettes =
              flags["kSaveDungeonPalettes"].get<bool>();
        if (flags.contains("kSaveGraphicsSheet"))
          feature_flags.kSaveGraphicsSheet =
              flags["kSaveGraphicsSheet"].get<bool>();
        if (flags.contains("kSaveAllPalettes"))
          feature_flags.kSaveAllPalettes =
              flags["kSaveAllPalettes"].get<bool>();
        if (flags.contains("kSaveGfxGroups"))
          feature_flags.kSaveGfxGroups = flags["kSaveGfxGroups"].get<bool>();
        if (flags.contains("kSaveMessages"))
          feature_flags.kSaveMessages = flags["kSaveMessages"].get<bool>();
      }
 
      // Workspace settings
      if (proj.contains("workspace_settings")) {
        auto& ws = proj["workspace_settings"];
        if (ws.contains("auto_save_enabled"))
          workspace_settings.autosave_enabled =
              ws["auto_save_enabled"].get<bool>();
        if (ws.contains("auto_save_interval"))
          workspace_settings.autosave_interval_secs =
              ws["auto_save_interval"].get<float>();
        if (ws.contains("backup_on_save"))
          workspace_settings.backup_on_save = ws["backup_on_save"].get<bool>();
        if (ws.contains("backup_retention_count"))
          workspace_settings.backup_retention_count =
              ws["backup_retention_count"].get<int>();
        if (ws.contains("backup_keep_daily"))
          workspace_settings.backup_keep_daily =
              ws["backup_keep_daily"].get<bool>();
        if (ws.contains("backup_keep_daily_days"))
          workspace_settings.backup_keep_daily_days =
              ws["backup_keep_daily_days"].get<int>();
      }
 
      if (proj.contains("rom_addresses") && proj["rom_addresses"].is_object()) {
        rom_address_overrides.addresses.clear();
        for (auto it = proj["rom_addresses"].begin();
             it != proj["rom_addresses"].end(); ++it) {
          if (it.value().is_number_unsigned()) {
            rom_address_overrides.addresses[it.key()] =
                it.value().get<uint32_t>();
          } else if (it.value().is_string()) {
            auto parsed = ParseHexUint32(it.value().get<std::string>());
            if (parsed.has_value()) {
              rom_address_overrides.addresses[it.key()] = *parsed;
            }
          }
        }
      }
 
      if (proj.contains("custom_objects") &&
          proj["custom_objects"].is_object()) {
        custom_object_files.clear();
        for (auto it = proj["custom_objects"].begin();
             it != proj["custom_objects"].end(); ++it) {
          if (!it.value().is_array())
            continue;
          auto parsed = ParseHexUint32(it.key());
          if (!parsed.has_value()) {
            continue;
          }
          std::vector<std::string> files;
          for (const auto& entry : it.value()) {
            if (entry.is_string()) {
              files.push_back(entry.get<std::string>());
            }
          }
          if (!files.empty()) {
            custom_object_files[static_cast<int>(*parsed)] = std::move(files);
          }
        }
      }
 
      if (proj.contains("agent_settings") &&
          proj["agent_settings"].is_object()) {
        auto& agent = proj["agent_settings"];
        agent_settings.ai_provider =
            agent.value("ai_provider", agent_settings.ai_provider);
        agent_settings.ai_model =
            agent.value("ai_model", agent_settings.ai_model);
        agent_settings.ollama_host =
            agent.value("ollama_host", agent_settings.ollama_host);
        agent_settings.gemini_api_key =
            agent.value("gemini_api_key", agent_settings.gemini_api_key);
        agent_settings.use_custom_prompt =
            agent.value("use_custom_prompt", agent_settings.use_custom_prompt);
        agent_settings.custom_system_prompt = agent.value(
            "custom_system_prompt", agent_settings.custom_system_prompt);
        agent_settings.show_reasoning =
            agent.value("show_reasoning", agent_settings.show_reasoning);
        agent_settings.verbose = agent.value("verbose", agent_settings.verbose);
        agent_settings.max_tool_iterations = agent.value(
            "max_tool_iterations", agent_settings.max_tool_iterations);
        agent_settings.max_retry_attempts = agent.value(
            "max_retry_attempts", agent_settings.max_retry_attempts);
        agent_settings.temperature =
            agent.value("temperature", agent_settings.temperature);
        agent_settings.top_p = agent.value("top_p", agent_settings.top_p);
        agent_settings.max_output_tokens =
            agent.value("max_output_tokens", agent_settings.max_output_tokens);
        agent_settings.stream_responses =
            agent.value("stream_responses", agent_settings.stream_responses);
        if (agent.contains("favorite_models") &&
            agent["favorite_models"].is_array()) {
          agent_settings.favorite_models.clear();
          for (const auto& model : agent["favorite_models"]) {
            if (model.is_string())
              agent_settings.favorite_models.push_back(
                  model.get<std::string>());
          }
        }
        if (agent.contains("model_chain") && agent["model_chain"].is_array()) {
          agent_settings.model_chain.clear();
          for (const auto& model : agent["model_chain"]) {
            if (model.is_string())
              agent_settings.model_chain.push_back(model.get<std::string>());
          }
        }
        agent_settings.chain_mode =
            agent.value("chain_mode", agent_settings.chain_mode);
        agent_settings.enable_tool_resources = agent.value(
            "enable_tool_resources", agent_settings.enable_tool_resources);
        agent_settings.enable_tool_dungeon = agent.value(
            "enable_tool_dungeon", agent_settings.enable_tool_dungeon);
        agent_settings.enable_tool_overworld = agent.value(
            "enable_tool_overworld", agent_settings.enable_tool_overworld);
        agent_settings.enable_tool_messages = agent.value(
            "enable_tool_messages", agent_settings.enable_tool_messages);
        agent_settings.enable_tool_dialogue = agent.value(
            "enable_tool_dialogue", agent_settings.enable_tool_dialogue);
        agent_settings.enable_tool_gui =
            agent.value("enable_tool_gui", agent_settings.enable_tool_gui);
        agent_settings.enable_tool_music =
            agent.value("enable_tool_music", agent_settings.enable_tool_music);
        agent_settings.enable_tool_sprite = agent.value(
            "enable_tool_sprite", agent_settings.enable_tool_sprite);
        agent_settings.enable_tool_emulator = agent.value(
            "enable_tool_emulator", agent_settings.enable_tool_emulator);
        agent_settings.enable_tool_memory_inspector =
            agent.value("enable_tool_memory_inspector",
                        agent_settings.enable_tool_memory_inspector);
        agent_settings.builder_blueprint_path = agent.value(
            "builder_blueprint_path", agent_settings.builder_blueprint_path);
      }
 
      // Build settings
      if (proj.contains("build_script"))
        build_script = proj["build_script"].get<std::string>();
      if (proj.contains("output_folder"))
        output_folder = proj["output_folder"].get<std::string>();
      if (proj.contains("git_repository"))
        git_repository = proj["git_repository"].get<std::string>();
      if (proj.contains("track_changes"))
        track_changes = proj["track_changes"].get<bool>();
    }
 
    return absl::OkStatus();
  } catch (const Json::exception& e) {
    return absl::InvalidArgumentError(
        absl::StrFormat("JSON parse error: %s", e.what()));
  }
}
 
absl::Status YazeProject::SaveToJsonFormat() {
#ifdef __EMSCRIPTEN__
  return absl::UnimplementedError(
      "JSON project format saving is not supported in the web build");
#endif
  Json j;
  auto& proj = j["yaze_project"];
 
  // Metadata
  proj["version"] = metadata.version;
  proj["name"] = name;
  proj["author"] = metadata.author;
  proj["created_by"] = metadata.created_by;
  proj["description"] = metadata.description;
  proj["created"] = metadata.created_date;
  proj["modified"] = metadata.last_modified;
 
  // Files
  proj["rom_filename"] = rom_filename;
  proj["rom_backup_folder"] = rom_backup_folder;
  proj["code_folder"] = code_folder;
  proj["assets_folder"] = assets_folder;
  proj["patches_folder"] = patches_folder;
  proj["labels_filename"] = labels_filename;
  proj["symbols_filename"] = symbols_filename;
  proj["dungeon_tile_patterns"] =
      GetRelativePath(GetAbsolutePath(dungeon_tile_patterns));
  proj["palette_catalog_file"] =
      GetRelativePath(GetAbsolutePath(palette_catalog_file));
  proj["terrain_catalog_file"] =
      GetRelativePath(GetAbsolutePath(terrain_catalog_file));
  proj["lyra_terrain_file"] =
      GetRelativePath(GetAbsolutePath(lyra_terrain_file));
  proj["lyra_build_request_file"] =
      GetRelativePath(GetAbsolutePath(lyra_build_request_file));
  if (!native_save_producer_file.empty()) {
    proj["native_save_producer_file"] =
        GetRelativePath(GetAbsolutePath(native_save_producer_file));
  }
  if (!native_save_transfer_proof_file.empty()) {
    proj["native_save_transfer_proof_file"] =
        GetRelativePath(GetAbsolutePath(native_save_transfer_proof_file));
  }
  if (!native_save_receipt_file.empty()) {
    proj["native_save_receipt_file"] =
        GetRelativePath(GetAbsolutePath(native_save_receipt_file));
  }
  proj["hack_manifest_file"] = hack_manifest_file;
  proj["sprite_catalog_file"] =
      GetRelativePath(GetAbsolutePath(sprite_catalog_file));
  proj["sprite_source_root"] =
      GetRelativePath(GetAbsolutePath(sprite_source_root));
  proj["sprite_assets"] = nlohmann::json::array();
  for (auto asset : sprite_assets) {
    asset.zsm_path = GetRelativePath(GetAbsolutePath(asset.zsm_path));
    for (auto& source : asset.graphics_sources) {
      if (source.kind == "bin") {
        source.path = GetRelativePath(GetAbsolutePath(source.path));
      }
    }
    proj["sprite_assets"].push_back(SpriteAssetToJson(asset));
  }
  proj["output_folder"] = output_folder;
 
  proj["rom"]["role"] = RomRoleToString(rom_metadata.role);
  proj["rom"]["expected_hash"] = rom_metadata.expected_hash;
  proj["rom"]["write_policy"] =
      RomWritePolicyToString(rom_metadata.write_policy);
 
  // Embedded labels
  proj["use_embedded_labels"] = use_embedded_labels;
 
  // Feature flags
  // REMOVED: kLogInstructions (deprecated)
  proj["feature_flags"]["kSaveDungeonMaps"] = feature_flags.kSaveDungeonMaps;
  proj["feature_flags"]["kSaveWithChangeQueue"] =
      feature_flags.kSaveWithChangeQueue;
  proj["feature_flags"]["kEnableSpecialWorldExpansion"] =
      feature_flags.overworld.kEnableSpecialWorldExpansion;
  proj["feature_flags"]["kSaveOverworldMaps"] =
      feature_flags.overworld.kSaveOverworldMaps;
  proj["feature_flags"]["kSaveOverworldEntrances"] =
      feature_flags.overworld.kSaveOverworldEntrances;
  proj["feature_flags"]["kSaveOverworldExits"] =
      feature_flags.overworld.kSaveOverworldExits;
  proj["feature_flags"]["kSaveOverworldItems"] =
      feature_flags.overworld.kSaveOverworldItems;
  proj["feature_flags"]["kSaveOverworldSprites"] =
      feature_flags.overworld.kSaveOverworldSprites;
  proj["feature_flags"]["kSaveOverworldProperties"] =
      feature_flags.overworld.kSaveOverworldProperties;
  proj["feature_flags"]["kSaveDungeonObjects"] =
      feature_flags.dungeon.kSaveObjects;
  proj["feature_flags"]["kSaveDungeonSprites"] =
      feature_flags.dungeon.kSaveSprites;
  proj["feature_flags"]["kSaveDungeonRoomHeaders"] =
      feature_flags.dungeon.kSaveRoomHeaders;
  proj["feature_flags"]["kSaveDungeonTorches"] =
      feature_flags.dungeon.kSaveTorches;
  proj["feature_flags"]["kSaveDungeonPits"] = feature_flags.dungeon.kSavePits;
  proj["feature_flags"]["kSaveDungeonBlocks"] =
      feature_flags.dungeon.kSaveBlocks;
  proj["feature_flags"]["kSaveDungeonCollision"] =
      feature_flags.dungeon.kSaveCollision;
  proj["feature_flags"]["kSaveDungeonWaterFillZones"] =
      feature_flags.dungeon.kSaveWaterFillZones;
  proj["feature_flags"]["kSaveDungeonChests"] =
      feature_flags.dungeon.kSaveChests;
  proj["feature_flags"]["kSaveDungeonPotItems"] =
      feature_flags.dungeon.kSavePotItems;
  proj["feature_flags"]["kSaveDungeonEntrances"] =
      feature_flags.dungeon.kSaveEntrances;
  proj["feature_flags"]["kSaveDungeonPalettes"] =
      feature_flags.dungeon.kSavePalettes;
  proj["feature_flags"]["kSaveGraphicsSheet"] =
      feature_flags.kSaveGraphicsSheet;
  proj["feature_flags"]["kSaveAllPalettes"] = feature_flags.kSaveAllPalettes;
  proj["feature_flags"]["kSaveGfxGroups"] = feature_flags.kSaveGfxGroups;
  proj["feature_flags"]["kSaveMessages"] = feature_flags.kSaveMessages;
 
  // Workspace settings
  proj["workspace_settings"]["auto_save_enabled"] =
      workspace_settings.autosave_enabled;
  proj["workspace_settings"]["auto_save_interval"] =
      workspace_settings.autosave_interval_secs;
  proj["workspace_settings"]["backup_on_save"] =
      workspace_settings.backup_on_save;
  proj["workspace_settings"]["backup_retention_count"] =
      workspace_settings.backup_retention_count;
  proj["workspace_settings"]["backup_keep_daily"] =
      workspace_settings.backup_keep_daily;
  proj["workspace_settings"]["backup_keep_daily_days"] =
      workspace_settings.backup_keep_daily_days;
 
  auto& agent = proj["agent_settings"];
  agent["ai_provider"] = agent_settings.ai_provider;
  agent["ai_model"] = agent_settings.ai_model;
  agent["ollama_host"] = agent_settings.ollama_host;
  agent["gemini_api_key"] = agent_settings.gemini_api_key;
  agent["use_custom_prompt"] = agent_settings.use_custom_prompt;
  agent["custom_system_prompt"] = agent_settings.custom_system_prompt;
  agent["show_reasoning"] = agent_settings.show_reasoning;
  agent["verbose"] = agent_settings.verbose;
  agent["max_tool_iterations"] = agent_settings.max_tool_iterations;
  agent["max_retry_attempts"] = agent_settings.max_retry_attempts;
  agent["temperature"] = agent_settings.temperature;
  agent["top_p"] = agent_settings.top_p;
  agent["max_output_tokens"] = agent_settings.max_output_tokens;
  agent["stream_responses"] = agent_settings.stream_responses;
  agent["favorite_models"] = agent_settings.favorite_models;
  agent["model_chain"] = agent_settings.model_chain;
  agent["chain_mode"] = agent_settings.chain_mode;
  agent["enable_tool_resources"] = agent_settings.enable_tool_resources;
  agent["enable_tool_dungeon"] = agent_settings.enable_tool_dungeon;
  agent["enable_tool_overworld"] = agent_settings.enable_tool_overworld;
  agent["enable_tool_messages"] = agent_settings.enable_tool_messages;
  agent["enable_tool_dialogue"] = agent_settings.enable_tool_dialogue;
  agent["enable_tool_gui"] = agent_settings.enable_tool_gui;
  agent["enable_tool_music"] = agent_settings.enable_tool_music;
  agent["enable_tool_sprite"] = agent_settings.enable_tool_sprite;
  agent["enable_tool_emulator"] = agent_settings.enable_tool_emulator;
  agent["enable_tool_memory_inspector"] =
      agent_settings.enable_tool_memory_inspector;
  agent["builder_blueprint_path"] = agent_settings.builder_blueprint_path;
 
  if (!rom_address_overrides.addresses.empty()) {
    auto& addrs = proj["rom_addresses"];
    for (const auto& [key, value] : rom_address_overrides.addresses) {
      addrs[key] = value;
    }
  }
 
  if (!custom_object_files.empty()) {
    auto& objs = proj["custom_objects"];
    for (const auto& [object_id, files] : custom_object_files) {
      objs[absl::StrFormat("0x%X", object_id)] = files;
    }
  }
 
  // Build settings
  proj["build_script"] = build_script;
  proj["git_repository"] = git_repository;
  proj["track_changes"] = track_changes;
 
  // Write to file
  std::ofstream file(filepath);
  if (!file.is_open()) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Cannot write JSON project file: %s", filepath));
  }
 
  file << j.dump(2);  // Pretty print with 2-space indent
  return absl::OkStatus();
}
 
#endif  // YAZE_ENABLE_JSON_PROJECT_FORMAT
 
// RecentFilesManager implementation
std::string RecentFilesManager::GetFilePath() const {
  auto config_dir = util::PlatformPaths::GetConfigDirectory();
  if (!config_dir.ok()) {
    return "";  // Or handle error appropriately
  }
  return (*config_dir / kRecentFilesFilename).string();
}
 
void RecentFilesManager::Save() {
#ifdef __EMSCRIPTEN__
  auto status = platform::WasmStorage::SaveProject(
      kRecentFilesFilename, absl::StrJoin(recent_files_, "\n"));
  if (!status.ok()) {
    LOG_WARN("RecentFilesManager", "Could not persist recent files: %s",
             status.ToString().c_str());
  }
  return;
#endif
  // Ensure config directory exists
  auto config_dir_status = util::PlatformPaths::GetConfigDirectory();
  if (!config_dir_status.ok()) {
    LOG_ERROR("Project", "Failed to get or create config directory: %s",
              config_dir_status.status().ToString().c_str());
    return;
  }
 
  std::string filepath = GetFilePath();
  std::ofstream file(filepath);
  if (!file.is_open()) {
    LOG_WARN("RecentFilesManager", "Could not save recent files to %s",
             filepath.c_str());
    return;
  }
 
  for (const auto& file_path : recent_files_) {
    file << file_path << std::endl;
  }
}
 
void RecentFilesManager::Load() {
#ifdef __EMSCRIPTEN__
  auto storage_or = platform::WasmStorage::LoadProject(kRecentFilesFilename);
  if (!storage_or.ok()) {
    return;
  }
  recent_files_.clear();
  std::istringstream stream(storage_or.value());
  std::string line;
  while (std::getline(stream, line)) {
    if (!line.empty()) {
      recent_files_.push_back(line);
    }
  }
  BumpGeneration();
  return;
#else
  std::string filepath = GetFilePath();
  std::ifstream file(filepath);
  if (!file.is_open()) {
    // File doesn't exist yet, which is fine
    return;
  }
 
  recent_files_.clear();
  std::string line;
  while (std::getline(file, line)) {
    if (!line.empty()) {
      recent_files_.push_back(line);
    }
  }
  BumpGeneration();
#endif
}
 
}  // namespace project
}  // namespace yaze