Plan picked path callbacks in app core

CMakeLists.txt

@@ -213,6 +213,7 @@ target_link_libraries(pp_ui_core
 add_library(pp_app_core STATIC
     src/app_core/document_cloud.h
     src/app_core/document_export.cpp
+    src/app_core/document_platform_io.h
     src/app_core/document_recording.h
     src/app_core/document_route.cpp
     src/app_core/document_sharing.h

docs/modernization/build-inventory.md

@@ -426,6 +426,10 @@ Known local toolchain state:
   as JSON for unsaved and saved document paths; the live platform share command
   consumes the same contract before reaching iOS/macOS sharing bridges or
   retained no-op platform branches.
+- `pano_cli plan-picked-path` exposes `pp_app_core` selected-path planning as
+  JSON for empty and non-empty file picker results; live image/file/save/
+  directory picker branches consume the same contract before invoking retained
+  platform callbacks or legacy picker bridges.
 - `pano_cli plan-cloud-upload` exposes `pp_app_core` cloud upload availability,
   new-document warning, publish prompt, and save-before-upload planning as JSON;
   the live cloud upload command consumes the same start contract before
@@ -456,6 +460,8 @@ Known local toolchain state:
   and oversized progress-total clamping.
 - `pp_app_core_document_sharing_tests` covers saved-path gating before platform
   share execution.
+- `pp_app_core_document_platform_io_tests` covers empty selected-path filtering
+  and non-empty picked-path callback planning before platform picker callbacks.
 - `pp_app_core_document_cloud_tests` covers cloud upload no-canvas,
   new-document warning, clean publish prompt, and dirty save-before-upload
   decisions, plus cloud browse no-canvas/show-browser and selected-download

docs/modernization/capability-map.md

@@ -67,7 +67,7 @@ and validation command.
 | --- | --- | --- | --- |
 | Mouse/keyboard/touch/gestures | `App`, platform entrypoints | `pp_platform_*`, app | Synthetic event playback |
 | Wacom pressure | `WacomTablet` | `pp_platform_windows` | Adapter smoke with fallback |
-| Clipboard/file picker/share | `App` platform methods | `pp_app_core`, `pp_platform_*` | Share saved-path decision tests, platform smoke or mocked service |
+| Clipboard/file picker/share | `App` platform methods | `pp_app_core`, `pp_platform_*` | Share saved-path and picked-path decision tests, platform smoke or mocked service |
 | Virtual keyboard | platform entrypoints | `pp_platform_*` | Platform smoke |
 | OpenVR desktop | `HMD`, `Vive`, `app_vr` | `pp_platform_vr`, app | Compile gate and mocked pose tests |
 | Quest/OVR | Android Quest files | `pp_platform_android_quest` | Compile/package gate |

docs/modernization/debt.md

@@ -22,7 +22,7 @@ agent or engineer to remove them without reconstructing context from chat.
 | --- | --- | --- | --- | --- | --- | --- |
 | DEBT-0001 | Open | Modernization | Existing platform build files remain alongside new CMake | Required for incremental migration without losing platform coverage | Existing platform builds plus new CMake configure | Remove after all platform builds consume shared CMake targets |
 | DEBT-0002 | Open | Modernization | Vendored SDK and patched libraries retained initially | Some dependencies are SDK-only, patched, or have platform-specific binaries | Dependency inventory and platform build smoke tests | Replace with vcpkg packages or document permanent vendored status after triplet evaluation |
-| DEBT-0003 | Open | Modernization | Existing singletons remain during initial split; `App::open_document`, `App::request_close`, `App::share_file`, `App::cloud_upload`, `App::cloud_upload_all`, `App::cloud_browse`, `App::rec_start`, `App::rec_stop`, `App::rec_clear`, `App::rec_export`, file-menu save actions, `NodeCanvas` save hotkeys, new/open/browse dirty-document workflow prompts, new-document target/resolution/overwrite decisions, save-as document file naming and overwrite decisions, save-version target decisions, export start/target naming/path decisions, share-file saved-path decisions, recording lifecycle/export progress decisions, cloud-upload prompt/save-before-upload decisions, cloud-browse availability and selected-download decisions, bulk cloud-upload progress decisions, `pano_cli classify-open`, `pano_cli plan-open-route`, `pano_cli plan-new-document`, `pano_cli plan-document-file`, `pano_cli plan-document-version`, `pano_cli plan-export-start`, `pano_cli plan-export-target`, `pano_cli plan-recording-session`, `pano_cli plan-share-file`, `pano_cli plan-cloud-upload`, `pano_cli plan-cloud-browse`, `pano_cli plan-cloud-upload-all`, and `pano_cli simulate-app-session` now consume pure `pp_app_core` route/session/export/recording/share/cloud contracts, but document creation/loading, brush import execution, saving, export execution, platform share execution, recording/MP4 execution, cloud upload execution, and cloud browse/download execution still reach legacy `Canvas::I`/UI/network/video/platform singletons | Avoid behavior changes while introducing component boundaries | App launch and component tests; `pp_app_core_document_route_tests`; `pp_app_core_document_export_tests`; `pp_app_core_document_recording_tests`; `pp_app_core_document_sharing_tests`; `pp_app_core_document_cloud_tests`; `pp_app_core_document_session_tests`; `pano_cli classify-open --path D:/Paint/demo.ppi`; `pano_cli plan-open-route --path D:/Paint/demo.ppi --unsaved`; `pano_cli plan-new-document --work-dir D:/Paint --name demo --resolution-index 3 --target-exists`; `pano_cli plan-document-file --work-dir D:/Paint --name demo --target-exists`; `pano_cli plan-document-version --directory D:/Paint --doc-name demo.01 --existing-path D:/Paint/demo.02.ppi`; `pano_cli plan-export-start --requires-license --demo`; `pano_cli plan-export-target --kind file --work-dir D:/Paint --doc-name demo --extension .png`; `pano_cli plan-recording-session --running --frame-count 12`; `pano_cli plan-share-file --path D:/Paint/demo.ppi`; `pano_cli plan-cloud-upload --new-document --unsaved`; `pano_cli plan-cloud-browse --selected-file demo.ppi`; `pano_cli plan-cloud-upload-all --file-count 3`; `pano_cli simulate-app-session --unsaved --save-intent save-dirty-version`; `pano_cli simulate-app-session --no-canvas`; `ctest --preset desktop-fast --build-config Debug` | Replace singleton reaches with context/service injection at component boundaries |
+| DEBT-0003 | Open | Modernization | Existing singletons remain during initial split; `App::open_document`, `App::request_close`, `App::share_file`, `App::cloud_upload`, `App::cloud_upload_all`, `App::cloud_browse`, `App::rec_start`, `App::rec_stop`, `App::rec_clear`, `App::rec_export`, file-menu save actions, `NodeCanvas` save hotkeys, new/open/browse dirty-document workflow prompts, new-document target/resolution/overwrite decisions, save-as document file naming and overwrite decisions, save-version target decisions, export start/target naming/path decisions, share-file saved-path decisions, file/image/save/directory picker selected-path decisions, recording lifecycle/export progress decisions, cloud-upload prompt/save-before-upload decisions, cloud-browse availability and selected-download decisions, bulk cloud-upload progress decisions, `pano_cli classify-open`, `pano_cli plan-open-route`, `pano_cli plan-new-document`, `pano_cli plan-document-file`, `pano_cli plan-document-version`, `pano_cli plan-export-start`, `pano_cli plan-export-target`, `pano_cli plan-recording-session`, `pano_cli plan-share-file`, `pano_cli plan-picked-path`, `pano_cli plan-cloud-upload`, `pano_cli plan-cloud-browse`, `pano_cli plan-cloud-upload-all`, and `pano_cli simulate-app-session` now consume pure `pp_app_core` route/session/export/recording/share/platform-I/O/cloud contracts, but document creation/loading, brush import execution, saving, export execution, platform share execution, picker callback execution, recording/MP4 execution, cloud upload execution, and cloud browse/download execution still reach legacy `Canvas::I`/UI/network/video/platform singletons | Avoid behavior changes while introducing component boundaries | App launch and component tests; `pp_app_core_document_route_tests`; `pp_app_core_document_export_tests`; `pp_app_core_document_recording_tests`; `pp_app_core_document_sharing_tests`; `pp_app_core_document_platform_io_tests`; `pp_app_core_document_cloud_tests`; `pp_app_core_document_session_tests`; `pano_cli classify-open --path D:/Paint/demo.ppi`; `pano_cli plan-open-route --path D:/Paint/demo.ppi --unsaved`; `pano_cli plan-new-document --work-dir D:/Paint --name demo --resolution-index 3 --target-exists`; `pano_cli plan-document-file --work-dir D:/Paint --name demo --target-exists`; `pano_cli plan-document-version --directory D:/Paint --doc-name demo.01 --existing-path D:/Paint/demo.02.ppi`; `pano_cli plan-export-start --requires-license --demo`; `pano_cli plan-export-target --kind file --work-dir D:/Paint --doc-name demo --extension .png`; `pano_cli plan-recording-session --running --frame-count 12`; `pano_cli plan-share-file --path D:/Paint/demo.ppi`; `pano_cli plan-picked-path --path D:/Paint/demo.ppi`; `pano_cli plan-cloud-upload --new-document --unsaved`; `pano_cli plan-cloud-browse --selected-file demo.ppi`; `pano_cli plan-cloud-upload-all --file-count 3`; `pano_cli simulate-app-session --unsaved --save-intent save-dirty-version`; `pano_cli simulate-app-session --no-canvas`; `ctest --preset desktop-fast --build-config Debug` | Replace singleton reaches with context/service injection at component boundaries |
 | DEBT-0004 | Open | Modernization | Android, Linux, WebGL, Apple, and AppX build files remain platform-specific until root CMake alignment reaches them | Prevent platform regressions during incremental migration; raw Windows `.sln/.vcxproj` files were removed on 2026-05-31 by user decision | `cmake --preset windows-msvc-default`; platform-specific configure/build smoke checks as each platform is migrated | Root CMake owns every platform source list and package path |
 | DEBT-0005 | Open | Modernization | Temporary local CTest harness is used before Catch2 is wired through vcpkg | `vcpkg` is not currently on PATH, but headless tests need to run now | `ctest --preset desktop-fast --build-config Debug` | Replace `tests/test_harness.h` tests with Catch2 tests once vcpkg toolchain/presets are validated |
 | DEBT-0007 | Open | Modernization | `vcpkg.json` and `windows-msvc-vcpkg-headless` are validated for the headless Windows component matrix, but app targets still use vendored libraries and Android/Apple triplets are not proven | Dependency migration must stay incremental while SDK/patched/vendor dependencies remain in use | `$env:VCPKG_ROOT="C:\Program Files\Microsoft Visual Studio\2022\Community\VC\vcpkg"; cmake --preset windows-msvc-vcpkg-headless`; `ctest --preset desktop-fast-vcpkg --build-config Debug` | Component targets consume vcpkg packages where reliable and desktop app, Android, and Apple triplets are validated or explicitly documented as permanent vendor exceptions |

docs/modernization/roadmap.md

@@ -451,6 +451,9 @@ PBO readback, and MP4 encoder execution continue.
 `pano_cli plan-share-file` exposes the app-core saved-path decision used by the
 live platform share command before iOS/macOS sharing bridges or retained no-op
 platform branches execute.
+`pano_cli plan-picked-path` exposes the app-core selected-path decision used by
+live image, file, save-file, and directory picker branches before retained
+platform callbacks or legacy picker bridges continue.
 `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,
@@ -937,6 +940,12 @@ Results:
 - `pano_cli_plan_share_file_unsaved_smoke` and
   `pano_cli_plan_share_file_saved_smoke` passed and expose app-core share
   decisions as JSON.
+- `pp_app_core_document_platform_io_tests` passed, covering empty selected-path
+  filtering and non-empty picked-path callback planning before platform picker
+  callbacks.
+- `pano_cli_plan_picked_path_empty_smoke` and
+  `pano_cli_plan_picked_path_selected_smoke` passed and expose app-core picker
+  selected-path decisions as JSON.
 - `panopainter_validate_shaders` passed, validating 25 shader programs and 7
   shader includes for stage markers and include graph integrity.
 - `pp_renderer_gl_capabilities_tests` passed on default MSVC, vcpkg-headless,

src/app_core/document_platform_io.h

@@ -0,0 +1,19 @@
+#pragma once
+
+#include <string_view>
+
+namespace pp::app {
+
+enum class PickedPathAction {
+    ignore_empty_path,
+    invoke_callback,
+};
+
+[[nodiscard]] constexpr PickedPathAction plan_picked_path(std::string_view path) noexcept
+{
+    return path.empty()
+        ? PickedPathAction::ignore_empty_path
+        : PickedPathAction::invoke_callback;
+}
+
+}

src/app_events.cpp

@@ -1,5 +1,6 @@
 #include "pch.h"
 #include "app.h"
+#include "app_core/document_platform_io.h"
 #include "app_core/document_sharing.h"
 #include "renderer_gl/opengl_capabilities.h"
 
@@ -10,6 +11,14 @@ namespace {
     return static_cast<GLint>(pp::renderer::gl::rgba8_internal_format());
 }
 
+void invoke_picked_path_if_selected(
+    const std::string& path,
+    const std::function<void(std::string path)>& callback)
+{
+    if (pp::app::plan_picked_path(path) == pp::app::PickedPathAction::invoke_callback)
+        callback(path);
+}
+
 }
 
 #ifdef __ANDROID__
@@ -156,18 +165,16 @@ void App::pick_image(std::function<void(std::string path)> callback)
     dispatch_async(dispatch_get_main_queue(), ^{
         NSArray* fileTypes = [NSArray arrayWithObjects:@"png", @"PNG", @"jpg", @"JPG", @"jpeg", nil];
         std::string path = [osx_view pick_file:fileTypes];
-        if (!path.empty())
-            callback(path);
+        invoke_picked_path_if_selected(path, callback);
     });
 #elif __ANDROID__
     android_pick_file(callback);
 #elif _WIN32
     std::string path = win32_open_file("Image Files (*.jpg, *.png)\0*.jpg;*.png");
-    if (!path.empty())
-        callback(path);
+    invoke_picked_path_if_selected(path, callback);
 #elif __LINUX__
     if (auto p = tinyfd_openFileDialog("Open File", "", 0, nullptr, nullptr, false))
-        callback(p);
+        invoke_picked_path_if_selected(p, callback);
 #elif __WEB__
     webgl_pick_file(callback);
 #endif
@@ -189,8 +196,7 @@ void App::pick_file(std::vector<std::string> types, std::function<void (std::str
         for (const auto& t : types)
             [fileTypes addObject:[NSString stringWithCString:t.c_str() encoding:NSUTF8StringEncoding]];
         std::string path = [osx_view pick_file:fileTypes];
-        if (!path.empty())
-            callback(path);
+        invoke_picked_path_if_selected(path, callback);
     });
 #elif __ANDROID__
     android_pick_file(callback);
@@ -212,11 +218,10 @@ void App::pick_file(std::vector<std::string> types, std::function<void (std::str
     }
     filter.push_back(0);
     std::string path = win32_open_file(filter.c_str());
-    if (!path.empty())
-        callback(path);
+    invoke_picked_path_if_selected(path, callback);
 #elif __LINUX__
     if (auto p = tinyfd_openFileDialog("Open File", "", 0, nullptr, nullptr, false))
-        callback(p);
+        invoke_picked_path_if_selected(p, callback);
 #elif __WEB__
     webgl_pick_file(callback);
 #endif
@@ -258,8 +263,7 @@ void App::pick_file_save(std::vector<std::string> types, std::function<void(std:
         for (const auto& t : types)
             [fileTypes addObject:[NSString stringWithCString:t.c_str() encoding:NSUTF8StringEncoding]];
         std::string path = [osx_view pick_file_save:fileTypes];
-        if (!path.empty())
-            callback(path);
+        invoke_picked_path_if_selected(path, callback);
     });
 #elif __ANDROID__
     android_pick_file_save(callback);
@@ -281,8 +285,7 @@ void App::pick_file_save(std::vector<std::string> types, std::function<void(std:
     }
     filter.push_back(0);
     std::string path = win32_save_file(filter.c_str());
-    if (!path.empty())
-        callback(path);
+    invoke_picked_path_if_selected(path, callback);
 #endif
 }
 #endif
@@ -295,16 +298,14 @@ void App::pick_dir(std::function<void(std::string path)> callback)
 #elif __OSX__
     dispatch_async(dispatch_get_main_queue(), ^{
         std::string path = [osx_view pick_dir];
-        if (!path.empty())
-            callback(path);
+        invoke_picked_path_if_selected(path, callback);
     });
 #elif __ANDROID__
     // NOT IMPLEMENTED
 #elif _WIN32
     // TODO: to be implemented
    std::string path = win32_open_dir();
-   if (!path.empty())
-       callback(path);
+   invoke_picked_path_if_selected(path, callback);
 #endif
 }
 

tests/CMakeLists.txt

@@ -288,6 +288,16 @@ add_test(NAME pp_app_core_document_cloud_tests COMMAND pp_app_core_document_clou
 set_tests_properties(pp_app_core_document_cloud_tests PROPERTIES
     LABELS "app;desktop-fast;fuzz")
 
+add_executable(pp_app_core_document_platform_io_tests
+    app_core/document_platform_io_tests.cpp)
+target_link_libraries(pp_app_core_document_platform_io_tests PRIVATE
+    pp_app_core
+    pp_test_harness)
+
+add_test(NAME pp_app_core_document_platform_io_tests COMMAND pp_app_core_document_platform_io_tests)
+set_tests_properties(pp_app_core_document_platform_io_tests PROPERTIES
+    LABELS "app;desktop-fast;fuzz")
+
 add_executable(pp_app_core_document_recording_tests
     app_core/document_recording_tests.cpp)
 target_link_libraries(pp_app_core_document_recording_tests PRIVATE
@@ -593,6 +603,18 @@ if(TARGET pano_cli)
         LABELS "app;integration;desktop-fast"
         PASS_REGULAR_EXPRESSION "\"command\":\"plan-share-file\".*\"path\":\"D:/Paint/demo.ppi\".*\"decision\":\"share-now\"")
 
+    add_test(NAME pano_cli_plan_picked_path_empty_smoke
+        COMMAND pano_cli plan-picked-path)
+    set_tests_properties(pano_cli_plan_picked_path_empty_smoke PROPERTIES
+        LABELS "app;integration;desktop-fast;fuzz"
+        PASS_REGULAR_EXPRESSION "\"command\":\"plan-picked-path\".*\"path\":\"\".*\"decision\":\"ignore-empty-path\"")
+
+    add_test(NAME pano_cli_plan_picked_path_selected_smoke
+        COMMAND pano_cli plan-picked-path --path D:/Paint/demo.ppi)
+    set_tests_properties(pano_cli_plan_picked_path_selected_smoke PROPERTIES
+        LABELS "app;integration;desktop-fast"
+        PASS_REGULAR_EXPRESSION "\"command\":\"plan-picked-path\".*\"path\":\"D:/Paint/demo.ppi\".*\"decision\":\"invoke-callback\"")
+
     add_test(NAME pano_cli_simulate_app_session_clean_smoke
         COMMAND pano_cli simulate-app-session)
     set_tests_properties(pano_cli_simulate_app_session_clean_smoke PROPERTIES

tests/app_core/document_platform_io_tests.cpp

@@ -0,0 +1,28 @@
+#include "app_core/document_platform_io.h"
+#include "test_harness.h"
+
+namespace {
+
+void picked_path_ignores_empty_path(pp::tests::Harness& harness)
+{
+    PP_EXPECT(
+        harness,
+        pp::app::plan_picked_path("") == pp::app::PickedPathAction::ignore_empty_path);
+}
+
+void picked_path_invokes_callback_for_nonempty_path(pp::tests::Harness& harness)
+{
+    PP_EXPECT(
+        harness,
+        pp::app::plan_picked_path("D:/Paint/demo.ppi") == pp::app::PickedPathAction::invoke_callback);
+}
+
+}
+
+int main()
+{
+    pp::tests::Harness harness;
+    harness.run("picked path ignores empty path", picked_path_ignores_empty_path);
+    harness.run("picked path invokes callback for nonempty path", picked_path_invokes_callback_for_nonempty_path);
+    return harness.finish();
+}

tools/pano_cli/main.cpp

@@ -1,5 +1,6 @@
 #include "app_core/document_export.h"
 #include "app_core/document_cloud.h"
+#include "app_core/document_platform_io.h"
 #include "app_core/document_recording.h"
 #include "app_core/document_route.h"
 #include "app_core/document_sharing.h"
@@ -165,6 +166,10 @@ struct PlanShareFileArgs {
     std::string path;
 };
 
+struct PlanPickedPathArgs {
+    std::string path;
+};
+
 struct SimulateAppSessionArgs {
     bool has_canvas = true;
     bool new_document = false;
@@ -498,6 +503,18 @@ const char* document_share_action_name(pp::app::DocumentShareAction action) noex
     return "show-save-required-warning";
 }
 
+const char* picked_path_action_name(pp::app::PickedPathAction action) noexcept
+{
+    switch (action) {
+    case pp::app::PickedPathAction::ignore_empty_path:
+        return "ignore-empty-path";
+    case pp::app::PickedPathAction::invoke_callback:
+        return "invoke-callback";
+    }
+
+    return "ignore-empty-path";
+}
+
 pp::foundation::Result<float> parse_float_arg(std::string_view text)
 {
     float value = 0.0F;
@@ -539,6 +556,7 @@ void print_help()
         << "  plan-cloud-upload-all [--file-count N] [--no-progress-ui]\n"
         << "  plan-recording-session [--running] [--frame-count N] [--platform-deletes-recorded-files]\n"
         << "  plan-share-file [--path FILE]\n"
+        << "  plan-picked-path [--path FILE]\n"
         << "  load-project --path FILE\n"
         << "  parse-layout --path FILE\n"
         << "  record-render [--width N] [--height N] [--exercise-clear]\n"
@@ -1909,6 +1927,43 @@ int plan_share_file(int argc, char** argv)
     return 0;
 }
 
+pp::foundation::Status parse_plan_picked_path_args(
+    int argc,
+    char** argv,
+    PlanPickedPathArgs& args)
+{
+    for (int i = 2; i < argc; ++i) {
+        const std::string_view key(argv[i]);
+        if (key == "--path") {
+            if (i + 1 >= argc) {
+                return pp::foundation::Status::invalid_argument("missing value for option");
+            }
+            args.path = argv[++i];
+        } else {
+            return pp::foundation::Status::invalid_argument("unknown option");
+        }
+    }
+
+    return pp::foundation::Status::success();
+}
+
+int plan_picked_path(int argc, char** argv)
+{
+    PlanPickedPathArgs args;
+    const auto status = parse_plan_picked_path_args(argc, argv, args);
+    if (!status.ok()) {
+        print_error("plan-picked-path", status.message);
+        return 2;
+    }
+
+    const auto decision = pp::app::plan_picked_path(args.path);
+    std::cout << "{\"ok\":true,\"command\":\"plan-picked-path\""
+              << ",\"state\":{\"path\":\"" << json_escape(args.path)
+              << "\"},\"decision\":\"" << picked_path_action_name(decision)
+              << "\"}\n";
+    return 0;
+}
+
 pp::foundation::Status parse_plan_export_target_args(
     int argc,
     char** argv,
@@ -4080,6 +4135,10 @@ int main(int argc, char** argv)
         return plan_share_file(argc, argv);
     }
 
+    if (command == "plan-picked-path") {
+        return plan_picked_path(argc, argv);
+    }
+
     if (command == "load-project") {
         return load_project(argc, argv);
     }