added default speaker layout config functionality - unsure of windows functiolity

Author: lucianpar

internalDocs/AGENTS.md

@@ -190,6 +190,42 @@ spatialroot/
 
 ---
 
+---
+
+## App Storage Conventions
+
+Two separate storage areas are used at runtime. **Never mix them.**
+
+### Session temp/cache (auto-deleted on app close)
+
+| Platform | Path |
+|----------|------|
+| macOS    | `~/Library/Caches/CultDSP/SpatialRoot/temp-sessions/` |
+| Windows  | `%LOCALAPPDATA%/CultDSP/SpatialRoot/Cache/temp-sessions/` |
+| Linux    | `$XDG_CACHE_HOME/CultDSP/SpatialRoot/temp-sessions/` or `~/.cache/CultDSP/SpatialRoot/temp-sessions/` |
+
+Contents: temporary LUSID scenes, transcoder outputs, diagnostic reports. Each session gets a UUID-stamped subdirectory with a `.spatialroot_temp_session` marker file. Deleted on clean shutdown unless `--keep-temp-sessions` is set.  
+Override: `SPATIALROOT_TEMP_ROOT` env var.  
+Implementation: `SpatialRootPaths::cacheRoot()` / `tempSessionsRoot()` / `SpatialRootPaths.cpp`.
+
+### Persistent app settings (never auto-deleted)
+
+| Platform | Path |
+|----------|------|
+| macOS    | `~/Library/Application Support/Spatial Root/` |
+| Windows  | `%APPDATA%/Spatial Root/` |
+| Linux    | `$XDG_CONFIG_HOME/spatial-root/` or `~/.config/spatial-root/` |
+
+Contents:
+- `default_layout.json` — authoritative copy of the saved default speaker layout
+- `default_layout.meta.json` — display metadata (sourcePath, savedAt, layoutName)
+
+These files are **not** deleted on app close. The engine never reads these directly — the GUI reads and validates them on startup, then passes the layout path into `EngineSession::applyLayout()` explicitly.  
+Override: `SPATIALROOT_SETTINGS_ROOT` env var.  
+Implementation: `SpatialRootPaths::appSettingsRoot()` / `DefaultLayoutManager`.
+
+---
+
 ## Runtime Control Plane
 
 **Primary (in-process):** ImGui GUI calls direct C++ setters on `EngineSession`:

internalDocs/devHistory.md

@@ -593,3 +593,4 @@ processedData/stageForRender/    — cult-transcoder writes scene.lusid.json her
 | Phase 6 | March 31, 2026 | C++ refactor complete. Python GUI/entrypoints/build/venv removed. ImGui + GLFW GUI shipped. |
 | Phase 7 | April 17, 2026 | Normalized DBAP (`sum(v_k²)=1`). `thirdparty/allolib` → `internal/cult-allolib`. Auto-compensation removed. |
 | Bug 10.1 | May 7, 2026 | Fast-mover continuity anchor fix for normalized DBAP (`mPrevSafePos` written as last sub-step position). |
+| Phase 8  | May 10, 2026 | Persistent default speaker layout + cross-platform app settings paths. `DefaultLayoutManager` added to GUI layer. Settings dir (`~/Library/Application Support/Spatial Root/` etc.) is strictly separate from session temp cache. Atomic writes, non-fatal startup fallback, GUI controls: Set as Default / Clear Default / status display. |

source/gui/imgui/CMakeLists.txt

@@ -56,6 +56,7 @@ set(IMGUI_SOURCES
 set(APP_SOURCES
     src/main.cpp
     src/App.cpp
+    src/DefaultLayoutManager.cpp
     src/SpatialRootPaths.cpp
     src/SubprocessRunner.cpp
     src/FileDialog.cpp

source/gui/imgui/src/App.cpp

@@ -60,6 +60,7 @@ App::App(std::string projectRoot, bool keepTempSessions, std::string tempRootOve
     : mProjectRoot(std::move(projectRoot))
     , mKeepTempSessions(keepTempSessions)
     , mTempRootOverride(std::move(tempRootOverride))
+    , mDefaultLayoutMgr()
     , mSession(std::make_unique<EngineSession>()) {
     mLayoutPath = resolveProjectPath(kLayoutPaths[0]);
 
@@ -70,6 +71,9 @@ App::App(std::string projectRoot, bool keepTempSessions, std::string tempRootOve
         appendEngineLog("[GUI] Keeping temporary sessions for debugging is enabled.",
                         {1.f, 0.8f, 0.2f, 1.f});
     }
+
+    tryLoadDefaultLayoutOnStartup();
+
     appendEngineLog("[GUI] Select a source and layout, then click START.");
 
     int lw = 0, lh = 0, lch = 0;
@@ -305,6 +309,8 @@ void App::renderEngineTab() {
             if (!p.empty()) { mLayoutPath = p; mLayoutPreset = IM_ARRAYSIZE(kLayoutNames) - 1; }
         }
 
+        renderDefaultLayoutControls();
+
         ImGui::SetCursorPosX(120.f);
         if (ImGui::Button("Layout Builder##layoutbuilder")) {
 #ifdef __APPLE__
@@ -1105,6 +1111,116 @@ void App::doLaunchEngine(const std::string& scenePath,
     appendEngineLog("[Engine] Started successfully. OSC port 9009.", {0.3f, 0.9f, 0.3f, 1.f});
 }
 
+void App::tryLoadDefaultLayoutOnStartup() {
+    const DefaultLayoutResult r = mDefaultLayoutMgr.loadDefaultLayout();
+    mDefaultLayoutStatus     = r.status;
+    mDefaultLayoutSavedAt    = r.savedAt;
+    mDefaultLayoutName       = r.layoutName;
+    mDefaultLayoutSourcePath = r.sourcePath;
+
+    if (r.status == DefaultLayoutStatus::None) {
+        appendEngineLog("[GUI] No default layout saved.");
+        return;
+    }
+    if (!r.success) {
+        appendEngineLog("[GUI] WARNING: Saved default layout could not be loaded: " + r.message,
+                        {1.f, 0.8f, 0.2f, 1.f});
+        return;
+    }
+    // Write the validated JSON to a temp file so we can point mLayoutPath at it.
+    // We write it to the same settings dir — it IS the settings dir copy.
+    mLayoutPath   = pathString(mDefaultLayoutMgr.layoutPath());
+    mLayoutPreset = IM_ARRAYSIZE(kLayoutNames) - 1;  // "Custom"
+
+    const std::string displayName = r.layoutName.empty() ? "default layout" : r.layoutName;
+    appendEngineLog("[GUI] Default layout loaded: " + displayName, {0.3f, 0.9f, 0.3f, 1.f});
+}
+
+void App::onSetAsDefaultLayout() {
+    if (mLayoutPath.empty()) {
+        appendEngineLog("[GUI] No layout selected — cannot save as default.", {1.f, 0.5f, 0.2f, 1.f});
+        return;
+    }
+    std::ifstream f(mLayoutPath);
+    if (!f.is_open()) {
+        appendEngineLog("[GUI] Cannot read layout file: " + mLayoutPath, {1.f, 0.4f, 0.4f, 1.f});
+        return;
+    }
+    const std::string jsonText((std::istreambuf_iterator<char>(f)),
+                                std::istreambuf_iterator<char>());
+
+    const DefaultLayoutResult r = mDefaultLayoutMgr.saveDefaultLayout(jsonText, mLayoutPath);
+    mDefaultLayoutStatus     = r.status;
+    mDefaultLayoutSavedAt    = r.savedAt;
+    mDefaultLayoutName       = r.layoutName;
+    mDefaultLayoutSourcePath = r.sourcePath;
+
+    if (r.success) {
+        appendEngineLog("[GUI] Default layout saved: " +
+                        (r.layoutName.empty() ? mLayoutPath : r.layoutName),
+                        {0.3f, 0.9f, 0.3f, 1.f});
+    } else {
+        appendEngineLog("[GUI] Failed to save default layout: " + r.message, {1.f, 0.4f, 0.4f, 1.f});
+    }
+}
+
+void App::onClearDefaultLayout() {
+    const DefaultLayoutResult r = mDefaultLayoutMgr.clearDefaultLayout();
+    mDefaultLayoutStatus     = DefaultLayoutStatus::None;
+    mDefaultLayoutSavedAt.clear();
+    mDefaultLayoutName.clear();
+    mDefaultLayoutSourcePath.clear();
+    appendEngineLog("[GUI] Default layout cleared.", {0.65f, 0.65f, 0.9f, 1.f});
+    (void)r;
+}
+
+void App::renderDefaultLayoutControls() {
+    const ImVec4 kGreen = {0.20f, 0.62f, 0.25f, 1.f};
+    const ImVec4 kAmber = {0.70f, 0.45f, 0.08f, 1.f};
+    const ImVec4 kRed   = {0.72f, 0.18f, 0.15f, 1.f};
+    const ImVec4 kBlue  = {0.40f, 0.60f, 0.90f, 1.f};
+
+    ImGui::TextDisabled("DEFAULT LAYOUT");
+    ImGui::SameLine(160.f);
+
+    // Status indicator
+    switch (mDefaultLayoutStatus) {
+        case DefaultLayoutStatus::None:
+            ImGui::TextDisabled("none saved");
+            break;
+        case DefaultLayoutStatus::Loaded:
+            ImGui::TextColored(kGreen, "loaded");
+            if (!mDefaultLayoutName.empty()) {
+                ImGui::SameLine(); ImGui::TextDisabled("(%s)", mDefaultLayoutName.c_str());
+            }
+            if (!mDefaultLayoutSavedAt.empty()) {
+                ImGui::SameLine(); ImGui::TextDisabled("saved %s", mDefaultLayoutSavedAt.c_str());
+            }
+            break;
+        case DefaultLayoutStatus::Invalid:
+            ImGui::TextColored(kAmber, "saved file invalid — check layout JSON");
+            break;
+        case DefaultLayoutStatus::Unavailable:
+            ImGui::TextColored(kRed, "unavailable (permission/read error)");
+            break;
+    }
+
+    ImGui::SameLine(ImGui::GetContentRegionAvail().x + ImGui::GetCursorPosX() - 300.f);
+
+    const bool hasLayout = !mLayoutPath.empty();
+    if (!hasLayout) ImGui::BeginDisabled(true);
+    if (ImGui::SmallButton("Set as Default")) onSetAsDefaultLayout();
+    if (!hasLayout) ImGui::EndDisabled();
+    if (ImGui::IsItemHovered()) ImGui::SetTooltip("Save current layout as startup default");
+
+    ImGui::SameLine();
+    const bool hasDefault = (mDefaultLayoutStatus != DefaultLayoutStatus::None);
+    if (!hasDefault) ImGui::BeginDisabled(true);
+    if (ImGui::SmallButton("Clear Default")) onClearDefaultLayout();
+    if (!hasDefault) ImGui::EndDisabled();
+    if (ImGui::IsItemHovered()) ImGui::SetTooltip("Remove the saved default layout");
+}
+
 void App::resetRuntimeToDefaults() {
     mGainDb = 0.0f;
     mFocus = 1.5f;

source/gui/imgui/src/App.hpp

@@ -15,6 +15,7 @@
 //   DEV NOTE: Evaluate whether to add an OSC enable/disable toggle in a future
 //   iteration. For V1, always-on is simplest and matches current behaviour.
 
+#include "DefaultLayoutManager.hpp"
 #include "EngineSession.hpp"
 #include "SpatialRootPaths.hpp"
 #include "SubprocessRunner.hpp"
@@ -70,6 +71,13 @@ class App {
     bool        mKeepTempSessions = false;
     std::string mTempRootOverride;
 
+    // ── Default layout manager (persistent settings, not session temp) ───
+    DefaultLayoutManager      mDefaultLayoutMgr;
+    DefaultLayoutStatus       mDefaultLayoutStatus = DefaultLayoutStatus::None;
+    std::string               mDefaultLayoutSavedAt;
+    std::string               mDefaultLayoutName;
+    std::string               mDefaultLayoutSourcePath;
+
     // ── Engine ───────────────────────────────────────────────────────────
     std::unique_ptr<EngineSession> mSession;
     AppState      mState      = AppState::Idle;
@@ -251,6 +259,12 @@ class App {
     void         clearStandaloneTranscodeTempState();
     static std::string pathString(const std::filesystem::path& path);
 
+    // Default layout helpers
+    void tryLoadDefaultLayoutOnStartup();
+    void onSetAsDefaultLayout();
+    void onClearDefaultLayout();
+    void renderDefaultLayoutControls();
+
     // Log helpers (main thread only for mEngineLog)
     void appendEngineLog(const std::string& text,
                          ImVec4 color = {0.85f, 0.85f, 0.85f, 1.f});