Route startup storage paths through platform services

docs/modernization/build-inventory.md

@@ -445,10 +445,11 @@ Known local toolchain state:
   live clipboard get/set requests consume the same contracts before retained
   platform clipboard bridges.
 - `pp_platform_api` exposes the SDK-free `PlatformServices` interface for
-  clipboard text, cursor visibility, virtual-keyboard visibility, external
+  startup storage path preparation, clipboard text, cursor visibility,
-  file display, file sharing, native app/window close, UI-thread lifecycle
+  virtual-keyboard visibility, external file display, file sharing, native
-  hooks, render-context lifecycle hooks, render-capture frame hooks, per-frame
+  app/window close, UI-thread lifecycle hooks, render-context lifecycle hooks,
-  platform hooks, picker callbacks, and prepared-file save/download handoff;
+  render-capture frame hooks, per-frame platform hooks, picker callbacks, and
+  prepared-file save/download handoff;
   Windows
   live app execution now uses injected
   `WindowsPlatformServices` from

docs/modernization/debt.md

@@ -35,7 +35,7 @@ agent or engineer to remove them without reconstructing context from chat.
 | DEBT-0014 | Open | Modernization | `windows-clangcl-asan` now configures as a headless Ninja/clang-cl preset and uses the release MSVC runtime required by ASan, but local builds still fail because installed clang-cl 18.1.8 is paired with VS 2026-preview STL headers that require Clang 20 or newer | Sanitizer validation should be local and repeatable, but this machine's compiler/header pairing is incompatible | `cmake --fresh --preset windows-clangcl-asan`; `cmake --build --preset windows-clangcl-asan --target pp_foundation` | Install/use Clang 20+ with the VS 2026 STL, or point the preset at a compatible VS 2022 toolchain, then make `platform-build.ps1 -Presets windows-clangcl-asan` pass for the headless matrix |
 | DEBT-0015 | Open | Modernization | Cursor visibility requests now consume pure `pp_app_core` planning through `pano_cli plan-cursor-visibility`, `App::show_cursor`/`App::hide_cursor` dispatch through `PlatformServices` without platform guards, and Windows live execution uses injected `WindowsPlatformServices`, but macOS cursor execution still reaches the retained fallback adapter | Keep canvas cursor behavior stable while platform shells are extracted incrementally | `pp_app_core_document_platform_io_tests`; `pano_cli plan-cursor-visibility --visible`; `ctest --preset desktop-fast --build-config Debug` | Cursor visibility execution is owned by injected `pp_platform_*` services for every supported platform |
 | DEBT-0016 | Open | Modernization | Clipboard get/set requests now consume pure `pp_app_core` planning through `pano_cli plan-clipboard-read` and `pano_cli plan-clipboard-write`, and Windows live execution uses injected `WindowsPlatformServices`, but Apple/Android clipboard execution still reaches retained fallback adapter branches from `App::clipboard_get_text` and `App::clipboard_set_text` | Keep picker/color text clipboard behavior stable while platform shells are extracted incrementally | `pp_app_core_document_platform_io_tests`; `pano_cli plan-clipboard-write --text #ff00aa`; `ctest --preset desktop-fast --build-config Debug` | Clipboard execution is owned by injected `pp_platform_*` services for every supported platform |
-| DEBT-0017 | Open | Modernization | `App::clipboard_get_text`, `App::clipboard_set_text`, `App::show_cursor`, `App::hide_cursor`, `App::showKeyboard`, `App::hideKeyboard`, `App::display_file`, `App::share_file`, native app/window close, UI-thread lifecycle hooks, render-context acquire/release/present hooks, render-capture frame hooks, per-frame platform hooks, `App::pick_image`, `App::pick_file`, the non-writer `App::pick_file_save`, `App::pick_dir`, and prepared-file save/download handoff now call the SDK-free `pp::platform::PlatformServices` interface, and Windows injects `WindowsPlatformServices` from `src/platform_windows/windows_platform_services.*`; non-Windows live implementations still use `src/platform_legacy/legacy_platform_services.*`, a named fallback adapter that forwards to retained Apple/Android/Linux/Web bridge functions and retained no-op branches | Preserve behavior while moving platform execution behind a testable service boundary before platform shell implementations are injected | `pp_platform_api_tests`; `pp_app_core_document_platform_io_tests`; `ctest --preset desktop-fast --build-config Debug`; `powershell -ExecutionPolicy Bypass -File scripts\automation\package-smoke.ps1 -Preset windows-msvc-default -Configuration Debug` | Replace `src/platform_legacy/legacy_platform_services.*` with injected `pp_platform_*` service implementations owned by each non-Windows platform shell |
+| DEBT-0017 | Open | Modernization | Startup storage path preparation, `App::clipboard_get_text`, `App::clipboard_set_text`, `App::show_cursor`, `App::hide_cursor`, `App::showKeyboard`, `App::hideKeyboard`, `App::display_file`, `App::share_file`, native app/window close, UI-thread lifecycle hooks, render-context acquire/release/present hooks, render-capture frame hooks, per-frame platform hooks, `App::pick_image`, `App::pick_file`, the non-writer `App::pick_file_save`, `App::pick_dir`, and prepared-file save/download handoff now call the SDK-free `pp::platform::PlatformServices` interface, and Windows injects `WindowsPlatformServices` from `src/platform_windows/windows_platform_services.*`; non-Windows live implementations still use `src/platform_legacy/legacy_platform_services.*`, a named fallback adapter that forwards to retained Apple/Android/Linux/Web bridge functions and retained no-op branches | Preserve behavior while moving platform execution behind a testable service boundary before platform shell implementations are injected | `pp_platform_api_tests`; `pp_app_core_document_platform_io_tests`; `ctest --preset desktop-fast --build-config Debug`; `powershell -ExecutionPolicy Bypass -File scripts\automation\package-smoke.ps1 -Preset windows-msvc-default -Configuration Debug` | Replace `src/platform_legacy/legacy_platform_services.*` with injected `pp_platform_*` service implementations owned by each non-Windows platform shell |
 
 ## Closed Debt
 

docs/modernization/roadmap.md

@@ -469,10 +469,10 @@ cursor bridges continue.
 app-core clipboard text decisions used by live clipboard get/set requests
 before retained platform clipboard bridges continue.
 `pp_platform_api` now owns a headless `PlatformServices` interface for
-clipboard text, cursor visibility, virtual-keyboard visibility, UI-thread
+startup storage path preparation, clipboard text, cursor visibility,
-lifecycle hooks, render-context acquire/release/present hooks, render-capture
+virtual-keyboard visibility, UI-thread lifecycle hooks, render-context
-frame hooks, external file display, file sharing, image/file/save-file
+acquire/release/present hooks, render-capture frame hooks, external file
-pickers, and directory pickers.
+display, file sharing, image/file/save-file pickers, and directory pickers.
 Windows installs an injected `WindowsPlatformServices` implementation from
 `src/platform_windows/windows_platform_services.*` in `pp_platform_windows`;
 other platforms still route through the debt-tracked legacy fallback adapter
@@ -504,6 +504,10 @@ shells are injected.
 Windows RenderDoc frame capture hooks now also dispatch through
 `PlatformServices`, keeping capture integration in the platform service while
 leaving non-Windows adapters as no-ops.
+Startup data/work/recording/temp path preparation now dispatches through
+`PlatformServices`, with Windows creating the Documents/PanoPainter folder
+tree in `WindowsPlatformServices` and Apple/Linux/Web behavior preserved in the
+legacy adapter until platform shells are injected.
 `pano_cli plan-cloud-upload` exposes the app-core cloud upload decision used by
 the live cloud upload command for missing-canvas, new-document warning, publish
 prompt, and dirty-document save-before-upload states before legacy UI, canvas,
@@ -1015,13 +1019,13 @@ Results:
   `pano_cli_plan_clipboard_write_empty_smoke` passed and expose app-core
   clipboard decisions as JSON, including empty write text.
 - `pp_platform_api_tests` passed, covering the SDK-free `PlatformServices`
-  interface for clipboard read/write, empty clipboard writes, cursor
+  interface for startup storage path preparation, clipboard read/write, empty
-  visibility dispatch, virtual-keyboard visibility dispatch, external file
+  clipboard writes, cursor visibility dispatch, virtual-keyboard visibility
-  display dispatch, file sharing dispatch, native app/window close dispatch,
+  dispatch, external file display dispatch, file sharing dispatch, native
-  UI-thread lifecycle dispatch, render-context lifecycle dispatch,
+  app/window close dispatch, UI-thread lifecycle dispatch, render-context
-  render-capture frame hook dispatch, per-frame platform hook dispatch, picker
+  lifecycle dispatch, render-capture frame hook dispatch, per-frame platform
-  callback dispatch, and prepared-file save/download callback dispatch. The
+  hook dispatch, picker callback dispatch, and prepared-file save/download
-  live Windows app now
+  callback dispatch. The live Windows app now
   consumes this interface through an injected
   `WindowsPlatformServices` instance isolated in
   `src/platform_windows/windows_platform_services.*`; other platforms still

src/app.cpp

@@ -8,6 +8,7 @@
 #include "app_core/document_recording.h"
 #include "app_core/document_route.h"
 #include "app_core/document_session.h"
+#include "platform_api/platform_services.h"
 #include "renderer_gl/opengl_capabilities.h"
 
 #ifdef __APPLE__
@@ -16,13 +17,6 @@
 #endif
 #include "settings.h"
 
-#ifdef __LINUX__
-std::string linux_home_path();
-int mkpath(const std::string& dir, mode_t mode = DEFFILEMODE);
-#elif __WEB__
-#include <unistd.h>
-#endif
-
 App* App::I = nullptr; // singleton
 
 std::deque<AppTask> App::render_tasklist;
@@ -295,78 +289,16 @@ void App::initAssets()
 
 void App::initLog()
 {
-#if defined(__IOS__)
+    const auto paths = prepare_storage_paths();
-    [ios_view init_dirs];
+    if (!paths.data_path.empty())
-#elif defined(__OSX__)
+        data_path = paths.data_path;
-    [osx_app init_dirs];
+    if (!paths.recording_path.empty())
-#elif defined(_WIN32)
+        rec_path = paths.recording_path;
-    //CHAR my_documents[MAX_PATH];
+    if (!paths.temporary_path.empty())
-    //HRESULT result = SHGetFolderPathA(NULL, CSIDL_PERSONAL, NULL, SHGFP_TYPE_CURRENT, my_documents);
+        tmp_path = paths.temporary_path;
-
-    //HMODULE hModule = GetModuleHandle(NULL);
-    //CHAR path[MAX_PATH];
-    //GetModuleFileNameA(hModule, path, MAX_PATH);
-    //CHAR out_drive[MAX_PATH];
-    //CHAR out_path[MAX_PATH];
-    //_splitpath(path, out_drive, out_path, nullptr, nullptr);
-    //sprintf_s(path, "%s%s", out_drive, out_path);
-    //data_path = path;
-
-
-    CHAR my_documents[MAX_PATH];
-    HRESULT result = SHGetFolderPathA(NULL, CSIDL_PERSONAL, NULL, SHGFP_TYPE_CURRENT, my_documents);
-    if (SUCCEEDED(result))
-    {
-        std::string path = std::string(my_documents) + "\\PanoPainter";
-        if (!PathFileExistsA(path.c_str()))
-            CreateDirectoryA(path.c_str(), NULL);
-        data_path = path;
-    }
-    else
-    {
-        CHAR path[MAX_PATH];
-        GetCurrentDirectoryA(sizeof(path), path);
-        data_path = path;
-    }
-
-    rec_path = data_path + "\\frames";
-    if (!PathFileExistsA(rec_path.c_str()))
-        CreateDirectoryA(rec_path.c_str(), NULL);
-
-    if (!PathFileExistsA((data_path + "\\brushes").c_str()))
-        CreateDirectoryA((data_path + "\\brushes").c_str(), NULL);
-    if (!PathFileExistsA((data_path + "\\brushes\\thumbs").c_str()))
-        CreateDirectoryA((data_path + "\\brushes\\thumbs").c_str(), NULL);
-
-    if (!PathFileExistsA((data_path + "\\patterns").c_str()))
-        CreateDirectoryA((data_path + "\\patterns").c_str(), NULL);
-    if (!PathFileExistsA((data_path + "\\patterns\\thumbs").c_str()))
-        CreateDirectoryA((data_path + "\\patterns\\thumbs").c_str(), NULL);
-
-    if (!PathFileExistsA((data_path + "\\settings").c_str()))
-        CreateDirectoryA((data_path + "\\settings").c_str(), NULL);
-
-#elif __LINUX__
-    data_path = linux_home_path() + "/PanoPainter";
-    mkpath(data_path + "/brushes");
-    mkpath(data_path + "/brushes/thumbs");
-    mkpath(data_path + "/patterns");
-    mkpath(data_path + "/patterns/thumbs");
-    mkpath(data_path + "/settings");
-    mkpath(data_path + "/frames");
-#elif __WEB__
-    data_path = "/PanoPainter";
-    mkdir(data_path.c_str(), 0777);
-    mkdir((data_path + "/brushes").c_str(), 0777);
-    mkdir((data_path + "/brushes/thumbs").c_str(), 0777);
-    mkdir((data_path + "/patterns").c_str(), 0777);
-    mkdir((data_path + "/patterns/thumbs").c_str(), 0777);
-    mkdir((data_path + "/settings").c_str(), 0777);
-    mkdir((data_path + "/frames").c_str(), 0777);
-#endif
 
     // TODO: save this path somewhere in the settings, don't overwrite every start
-    work_path = data_path;
+    work_path = paths.work_path.empty() ? data_path : paths.work_path;
 
     //LogRemote::I.start();
     LogRemote::I.file_init();

src/app.h

@@ -28,6 +28,7 @@
 
 namespace pp::platform {
 class PlatformServices;
+struct PlatformStoragePaths;
 }
 
 #if defined(__OBJC__) && defined(__IOS__)
@@ -205,6 +206,7 @@ public:
         std::function<void(const std::string& path, bool saved)> callback);
     void set_platform_services(pp::platform::PlatformServices* services) noexcept;
     [[nodiscard]] pp::platform::PlatformServices* platform_services() const noexcept;
+    [[nodiscard]] pp::platform::PlatformStoragePaths prepare_storage_paths();
     void showKeyboard();
     void hideKeyboard();
     void initLog();

src/app_events.cpp

@@ -56,6 +56,11 @@ pp::platform::PlatformServices* App::platform_services() const noexcept
     return platform_services_;
 }
 
+pp::platform::PlatformStoragePaths App::prepare_storage_paths()
+{
+    return active_platform_services().prepare_storage_paths();
+}
+
 std::string App::clipboard_get_text()
 {
     if (pp::app::plan_clipboard_read() != pp::app::ClipboardReadAction::read_text)

src/platform_api/platform_services.h

@@ -10,10 +10,18 @@ namespace pp::platform {
 using PickedPathCallback = std::function<void(std::string path)>;
 using PreparedFileCallback = std::function<void(std::string path, bool saved)>;
 
+struct PlatformStoragePaths {
+    std::string data_path;
+    std::string work_path;
+    std::string recording_path;
+    std::string temporary_path;
+};
+
 class PlatformServices {
 public:
     virtual ~PlatformServices() = default;
 
+    [[nodiscard]] virtual PlatformStoragePaths prepare_storage_paths() = 0;
     [[nodiscard]] virtual std::string clipboard_text() = 0;
     [[nodiscard]] virtual bool set_clipboard_text(std::string_view text) = 0;
     virtual void set_cursor_visible(bool visible) = 0;

src/platform_legacy/legacy_platform_services.cpp

@@ -18,6 +18,8 @@ bool android_set_clipboard(const std::string& s);
 #elif __APPLE__
 #elif __LINUX__
 #include <tinyfiledialogs.h>
+std::string linux_home_path();
+int mkpath(const std::string& dir, mode_t mode = DEFFILEMODE);
 void linux_update_fps(int frames);
 #elif __WEB__
 void webgl_pick_file(std::function<void(std::string)> callback);
@@ -41,6 +43,63 @@ void invoke_picked_path_if_selected(
 // DEBT-0017: fallback for platforms that do not inject PlatformServices yet.
 class LegacyPlatformServices final : public pp::platform::PlatformServices {
 public:
+    [[nodiscard]] pp::platform::PlatformStoragePaths prepare_storage_paths() override
+    {
+#if defined(__IOS__)
+        [App::I->ios_view init_dirs];
+        return {
+            App::I->data_path,
+            App::I->work_path,
+            App::I->rec_path,
+            App::I->tmp_path,
+        };
+#elif defined(__OSX__)
+        [App::I->osx_app init_dirs];
+        return {
+            App::I->data_path,
+            App::I->work_path,
+            App::I->rec_path,
+            App::I->tmp_path,
+        };
+#elif __LINUX__
+        const std::string data_path = linux_home_path() + "/PanoPainter";
+        mkpath(data_path + "/brushes");
+        mkpath(data_path + "/brushes/thumbs");
+        mkpath(data_path + "/patterns");
+        mkpath(data_path + "/patterns/thumbs");
+        mkpath(data_path + "/settings");
+        mkpath(data_path + "/frames");
+        return {
+            data_path,
+            data_path,
+            data_path + "/frames",
+            {},
+        };
+#elif __WEB__
+        const std::string data_path = "/PanoPainter";
+        mkdir(data_path.c_str(), 0777);
+        mkdir((data_path + "/brushes").c_str(), 0777);
+        mkdir((data_path + "/brushes/thumbs").c_str(), 0777);
+        mkdir((data_path + "/patterns").c_str(), 0777);
+        mkdir((data_path + "/patterns/thumbs").c_str(), 0777);
+        mkdir((data_path + "/settings").c_str(), 0777);
+        mkdir((data_path + "/frames").c_str(), 0777);
+        return {
+            data_path,
+            data_path,
+            data_path + "/frames",
+            {},
+        };
+#else
+        return {
+            App::I->data_path,
+            App::I->work_path,
+            App::I->rec_path,
+            App::I->tmp_path,
+        };
+#endif
+    }
+
     [[nodiscard]] std::string clipboard_text() override
     {
 #if __IOS__

src/platform_windows/windows_platform_services.cpp

@@ -134,6 +134,12 @@ void invoke_selected_path(
         callback(path);
 }
 
+void ensure_directory(const std::string& path)
+{
+    if (!PathFileExistsA(path.c_str()))
+        CreateDirectoryA(path.c_str(), NULL);
+}
+
 std::string build_supported_files_filter(const std::vector<std::string>& types)
 {
     std::string filter = "Supported Files (";
@@ -157,6 +163,38 @@ std::string build_supported_files_filter(const std::vector<std::string>& types)
 
 class WindowsPlatformServices final : public pp::platform::PlatformServices {
 public:
+    [[nodiscard]] pp::platform::PlatformStoragePaths prepare_storage_paths() override
+    {
+        std::string data_path;
+        CHAR my_documents[MAX_PATH];
+        HRESULT result = SHGetFolderPathA(NULL, CSIDL_PERSONAL, NULL, SHGFP_TYPE_CURRENT, my_documents);
+        if (SUCCEEDED(result))
+        {
+            data_path = std::string(my_documents) + "\\PanoPainter";
+            ensure_directory(data_path);
+        }
+        else
+        {
+            CHAR path[MAX_PATH];
+            GetCurrentDirectoryA(sizeof(path), path);
+            data_path = path;
+        }
+
+        ensure_directory(data_path + "\\frames");
+        ensure_directory(data_path + "\\brushes");
+        ensure_directory(data_path + "\\brushes\\thumbs");
+        ensure_directory(data_path + "\\patterns");
+        ensure_directory(data_path + "\\patterns\\thumbs");
+        ensure_directory(data_path + "\\settings");
+
+        return {
+            data_path,
+            data_path,
+            data_path + "\\frames",
+            {},
+        };
+    }
+
     [[nodiscard]] std::string clipboard_text() override
     {
         return ::clipboard_text();

tests/platform_api/platform_services_tests.cpp

@@ -15,6 +15,12 @@ public:
     {
     }
 
+    [[nodiscard]] pp::platform::PlatformStoragePaths prepare_storage_paths() override
+    {
+        ++storage_prepares;
+        return storage_paths;
+    }
+
     [[nodiscard]] std::string clipboard_text() override
     {
         ++clipboard_reads;
@@ -152,6 +158,7 @@ public:
     int render_context_presents = 0;
     int render_capture_begins = 0;
     int render_capture_ends = 0;
+    int storage_prepares = 0;
     int platform_frame_updates = 0;
     int frame_reports = 0;
     int display_file_requests = 0;
@@ -174,6 +181,12 @@ public:
     std::string picker_path = "D:/Paint/import.png";
     std::string save_path = "D:/Paint/export.ppi";
     std::string directory_path = "D:/Paint";
+    pp::platform::PlatformStoragePaths storage_paths{
+        "D:/Paint",
+        "D:/Paint/work",
+        "D:/Paint/frames",
+        "D:/Paint/tmp",
+    };
     std::vector<std::string> picked_file_types;
     std::vector<std::string> save_file_types;
 
@@ -193,6 +206,20 @@ void platform_services_dispatch_clipboard_reads_and_writes(pp::tests::Harness& h
     PP_EXPECT(harness, fake.clipboard_writes == 1);
 }
 
+void platform_services_dispatch_storage_path_preparation(pp::tests::Harness& harness)
+{
+    FakePlatformServices fake("unused");
+    pp::platform::PlatformServices& services = fake;
+
+    const auto paths = services.prepare_storage_paths();
+
+    PP_EXPECT(harness, fake.storage_prepares == 1);
+    PP_EXPECT(harness, paths.data_path == "D:/Paint");
+    PP_EXPECT(harness, paths.work_path == "D:/Paint/work");
+    PP_EXPECT(harness, paths.recording_path == "D:/Paint/frames");
+    PP_EXPECT(harness, paths.temporary_path == "D:/Paint/tmp");
+}
+
 void platform_services_preserve_empty_clipboard_writes(pp::tests::Harness& harness)
 {
     FakePlatformServices fake("initial");
@@ -340,6 +367,7 @@ void platform_services_dispatch_prepared_file_save(pp::tests::Harness& harness)
 int main()
 {
     pp::tests::Harness harness;
+    harness.run("platform services dispatch storage path preparation", platform_services_dispatch_storage_path_preparation);
     harness.run("platform services dispatch clipboard reads and writes", platform_services_dispatch_clipboard_reads_and_writes);
     harness.run("platform services preserve empty clipboard writes", platform_services_preserve_empty_clipboard_writes);
     harness.run("platform services dispatch visibility updates", platform_services_dispatch_visibility_updates);