Plan cube export face targets in app core

docs/modernization/build-inventory.md

@@ -802,8 +802,8 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
   states.
 - `pano_cli plan-export-target` exposes `pp_app_core` export target planning
   for image file exports, layer/frame collection directories, picked-directory
-  stems, and MP4 suggested names as JSON and is covered for file, collection,
-  and suggested-name states.
+  stems, cube-face work-directory file sets, and MP4 suggested names as JSON
+  and is covered for file, collection, cube-face, and suggested-name states.
 - `pano_cli plan-export-message` exposes `pp_app_core` export completion
   dialog metadata for equirectangular image, layer/frame collection,
   depth/cube, animation MP4, and timelapse success paths as JSON, including
@@ -998,8 +998,8 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
   legacy canvas work.
 - `pp_app_core_document_export_tests` covers export file targets, collection
   directory/stem targets, picked-directory stems, work-directory versus
-  picker-stem collection target planning, MP4 suggested names, and invalid
-  export naming inputs, plus export-start license/canvas availability decisions,
+  picker-stem collection target planning, cube-face legacy work-path sets, MP4
+  suggested names, and invalid export naming inputs, plus export-start license/canvas availability decisions,
   export menu executor dispatch, file/stem/collection export execution
   dispatch, failed directory creation preservation, named depth/cube export
   dispatch, malformed export target rejection, video export dispatch for
@@ -1124,7 +1124,9 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
   retained renderer/document/platform ownership is tracked by `DEBT-0043`.
   Equirectangular, layer, animation-frame, and cube-face execution now prepare
   the document snapshot plus renderer-upload readiness report before those
-  retained calls; depth export remains on the older retained path. It
+  retained calls; cube-face export writes pure face-PNG bytes to the app-core
+  planned legacy work-directory face paths before falling back to the retained
+  writer, and depth export remains on the older retained path. It
   also bridges timelapse and animation MP4 export picker-selected paths while
   preserving desktop worker-thread timelapse behavior, mobile/Web save
   callbacks, `App::rec_export`, animation `Canvas::export_anim_mp4`, and

docs/modernization/capability-map.md

@@ -26,7 +26,7 @@ and validation command.
 | PNG/JPEG import | `Image`, `Canvas` import paths | `pp_assets`, `pp_document` | Fixture import, malformed file |
 | PNG/JPEG export | `Canvas`, `Image`, export dialogs | `pp_assets`, `pp_paint_renderer`, `pp_app_core` | Golden output tolerance, export start/target planning tests, live export-adapter document snapshot readiness |
 | Equirectangular import/export | `Canvas`, shaders, RTT, export dialogs | `pp_paint_renderer`, `pp_app_core` | Tiny cube/equirect golden, app-core file target tests, live export-adapter renderer-upload readiness |
-| Cube face export | `Canvas` fallback | `pp_paint_renderer` | Pure six-face document frame composite, renderer texture-upload bridge, pure face-PNG export helper, payload-complete canvas-snapshot renderer-upload and face-PNG automation, live document/renderer face-PNG writer with retained Canvas fallback, OpenGL command-plan coverage, six-face golden set |
+| Cube face export | `Canvas` fallback | `pp_paint_renderer`, `pp_app_core` | Pure six-face document frame composite, renderer texture-upload bridge, pure face-PNG export helper, app-core face filename planning, payload-complete canvas-snapshot renderer-upload and face-PNG automation, live document/renderer face-PNG writer with retained Canvas fallback, OpenGL command-plan coverage, six-face golden set |
 | Depth export | `Canvas`, grid tools | `pp_paint_renderer` | Float/readback validation |
 
 ## Brush And Painting

docs/modernization/debt.md

@@ -510,6 +510,12 @@ agent or engineer to remove them without reconstructing context from chat.
   `work_path/document-face.png` filename set and publishes each path through the
   platform service, falling back to retained `Canvas::export_cube_faces` if
   snapshot capture, face PNG generation, or file writing fails.
+- 2026-06-05: DEBT-0043 was narrowed again. The retained cube-face filename
+  set is now planned by tested `pp_app_core`
+  `make_document_cube_face_export_target`, exposed through
+  `pano_cli plan-export-target --kind cube-faces`, and consumed by
+  `src/legacy_document_export_services.*` before writing pure face-PNG bytes.
+  Storage service ownership and non-cube retained export writers remain open.
 
 ## Open Debt
 
@@ -523,7 +529,7 @@ agent or engineer to remove them without reconstructing context from chat.
 | DEBT-0007 | Open | Modernization | `vcpkg.json` and `windows-msvc-vcpkg-headless` are validated for the headless Windows component matrix, and root CMake now exposes a focused `panopainter_platform_build_vcpkg_ui_core` target for the vcpkg-backed `pp_ui_core`/tinyxml2 boundary, 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 | `cmake --preset windows-msvc-vcpkg-headless`; `ctest --preset desktop-fast-vcpkg --build-config Debug`; `cmake --build --preset windows-msvc-default --config Debug --target panopainter_platform_build_vcpkg_ui_core` | Component targets consume vcpkg packages where reliable and desktop app, Android, and Apple triplets are validated or explicitly documented as permanent vendor exceptions |
 | DEBT-0008 | Open | Modernization | `windows-msvc-default` and `windows-msvc-vcpkg-headless` explicitly select Visual Studio 18 2026 for local validation, but non-VS2026 CMake executables on PATH may not know that generator | The local machine has VS 2026, but using an older CMake can still default to Ninja or reject the VS 2026 generator | `cmake --preset windows-msvc-default`; `cmake --build --preset windows-msvc-default --config Debug --target PanoPainter`; `ctest --preset desktop-fast --build-config Debug` | The repo automation invokes or locates a CMake executable that supports `Visual Studio 18 2026`, and VS 2026 generator validation is the normal Windows path without manual tool selection |
 | DEBT-0009 | Open | Modernization | Android root CMake validation currently builds headless targets only, while retained standard/Quest/Focus package CMake paths now have a refreshed CMake 3.10/C++23 baseline outside root CMake; automation queries `sdkmanager`, installs newer or missing SDK Manager NDK/CMake packages, selects the resulting pair before configure, and reports update decisions; root CMake exposes non-default platform-build and retained native package validation targets | Platform app entrypoints still live in legacy Gradle/CMake projects and need Phase 6 alignment | `powershell -ExecutionPolicy Bypass -File scripts\automation\platform-build.ps1 -Presets android-arm64`; `cmake --build --preset android-x64`; `cmake --build --preset android-quest-arm64`; `cmake --build --preset android-focus-arm64`; `cmake --build --preset windows-msvc-default --config Debug --target panopainter_platform_build_android_assets`; `powershell -ExecutionPolicy Bypass -File scripts\automation\android-legacy-package-build.ps1 -Packages standard`; `powershell -ExecutionPolicy Bypass -File scripts\automation\android-legacy-package-build.ps1 -Packages quest,focus -ConfigureOnly`; `powershell -ExecutionPolicy Bypass -File scripts\automation\package-smoke.ps1 -ReadinessOnly -AndroidNativeChecks -PackageKinds android-standard-apk,android-quest-apk,android-focus-apk`; `cmake --build --preset windows-msvc-default --config Debug --target panopainter_android_native_package_smoke` | Android standard, Quest, and Focus/Wave package targets consume shared component targets and have package smoke commands |
-| DEBT-0010 | Open | Modernization | `pp_document` is a pure layer/frame/document/undo-history model with alpha-lock metadata, snapshot construction, per-layer frame metadata, renderer-free RGBA8 face payload storage, snapshot-embedded face-payload validation, renderer-free alpha8 selection-mask storage, PPI import/export helpers, stroke-script-to-face-payload CLI automation, `pp_paint_renderer` document face/frame compositors, renderer-neutral six-face texture upload, pure six-face PNG export, OpenGL command-planner validation through CLI render automation, live Canvas snapshot projection through `pp_app_core`/`legacy_document_canvas_services`, captured RGBA8 payload attachment to `pp_document`, live Save/Save As/Save Version/save-before-workflow snapshot-readiness reporting before retained save execution, pure app-core PPI export for payload-complete canvas snapshots, payload-complete canvas-snapshot renderer-upload plus face-PNG export automation, live cube-face face-PNG writer execution with retained fallback, and live equirectangular/layer/animation-frame/cube-face export snapshot/render/export-readiness reporting, but action-command adoption, live save-writer replacement, broader renderer-owned export execution, and renderer-owned cube-face readback ownership are not yet wired | Keep extraction incremental while preserving app behavior | `ctest --preset desktop-fast --build-config Debug`; `pano_cli create-document --width 64 --height 32 --layers 2`; `pano_cli load-project --path tests\data\projects\minimal-project.ppi`; `pano_cli simulate-document-render --width 64 --height 32`; `pano_cli plan-canvas-document-snapshot --width 64 --height 32`; `pano_cli plan-canvas-document-snapshot --captured-face-payloads-per-layer 1`; `pp_document_tests`; `pp_document_ppi_import_tests`; `pp_document_ppi_export_tests`; `pp_paint_renderer_compositor_tests`; `pp_app_core_document_canvas_tests`; `pano_cli_simulate_document_edits_smoke`; `pano_cli_simulate_document_export_smoke`; `pano_cli_simulate_document_render_smoke`; `pano_cli_plan_canvas_document_snapshot_smoke`; `pano_cli_plan_canvas_document_snapshot_payload_smoke`; `pano_cli_save_document_project_roundtrip_smoke`; `pano_cli_apply_stroke_script_roundtrip_smoke`; `pano_cli_apply_stroke_script_rejects_tiny_canvas` | Legacy document behavior is represented by `pp_document`/`pp_paint_renderer` tests and the app consumes it through a boundary/facade |
+| DEBT-0010 | Open | Modernization | `pp_document` is a pure layer/frame/document/undo-history model with alpha-lock metadata, snapshot construction, per-layer frame metadata, renderer-free RGBA8 face payload storage, snapshot-embedded face-payload validation, renderer-free alpha8 selection-mask storage, PPI import/export helpers, stroke-script-to-face-payload CLI automation, `pp_paint_renderer` document face/frame compositors, renderer-neutral six-face texture upload, pure six-face PNG export, OpenGL command-planner validation through CLI render automation, live Canvas snapshot projection through `pp_app_core`/`legacy_document_canvas_services`, captured RGBA8 payload attachment to `pp_document`, live Save/Save As/Save Version/save-before-workflow snapshot-readiness reporting before retained save execution, pure app-core PPI export for payload-complete canvas snapshots, payload-complete canvas-snapshot renderer-upload plus face-PNG export automation, live cube-face face-PNG writer execution using app-core face target planning with retained fallback, and live equirectangular/layer/animation-frame/cube-face export snapshot/render/export-readiness reporting, but action-command adoption, live save-writer replacement, broader renderer-owned export execution, and renderer-owned cube-face readback ownership are not yet wired | Keep extraction incremental while preserving app behavior | `ctest --preset desktop-fast --build-config Debug`; `pano_cli create-document --width 64 --height 32 --layers 2`; `pano_cli load-project --path tests\data\projects\minimal-project.ppi`; `pano_cli simulate-document-render --width 64 --height 32`; `pano_cli plan-canvas-document-snapshot --width 64 --height 32`; `pano_cli plan-canvas-document-snapshot --captured-face-payloads-per-layer 1`; `pp_document_tests`; `pp_document_ppi_import_tests`; `pp_document_ppi_export_tests`; `pp_paint_renderer_compositor_tests`; `pp_app_core_document_canvas_tests`; `pano_cli_simulate_document_edits_smoke`; `pano_cli_simulate_document_export_smoke`; `pano_cli_simulate_document_render_smoke`; `pano_cli_plan_canvas_document_snapshot_smoke`; `pano_cli_plan_canvas_document_snapshot_payload_smoke`; `pano_cli_save_document_project_roundtrip_smoke`; `pano_cli_apply_stroke_script_roundtrip_smoke`; `pano_cli_apply_stroke_script_rejects_tiny_canvas` | Legacy document behavior is represented by `pp_document`/`pp_paint_renderer` tests and the app consumes it through a boundary/facade |
 | DEBT-0011 | Open | Modernization | `package-smoke` validates the Windows CMake app artifact and launch-folder DLL payload, and reports a structured package readiness matrix for Windows AppX, Android standard/Quest/Focus APKs, Apple bundles, Linux app output, and WebGL output; the Windows app smoke passes the configure-time CMake executable so VS 2026 generator validation does not depend on `cmake` from PATH, retained Android package native CMake paths, and retained Linux/WebGL CMake baseline metadata are reachable from package validation and root CMake package-readiness targets, but Windows AppX/APK/Linux/Apple/WebGL package outputs are still `blocked` because root CMake package targets do not exist yet | Platform package targets are not migrated to root CMake yet | `powershell -ExecutionPolicy Bypass -File scripts\automation\package-smoke.ps1 -Preset windows-msvc-default -Configuration Debug`; `cmake --build --preset windows-msvc-default --config Debug --target panopainter_windows_app_package_smoke`; `powershell -ExecutionPolicy Bypass -File scripts\automation\package-smoke.ps1 -ReadinessOnly -AndroidNativeChecks -PackageKinds android-standard-apk,android-quest-apk,android-focus-apk`; `cmake --build --preset windows-msvc-default --config Debug --target panopainter_android_native_package_smoke`; `cmake --build --preset windows-msvc-default --config Debug --target panopainter_linux_webgl_package_readiness`; `python scripts/dev/check_package_smoke_readiness.py`; `bash -n scripts/automation/package-smoke.sh` | Package-smoke builds and validates Windows AppX, Android APK variants, Linux app, Apple bundles, and WebGL output where local toolchains are present |
 | DEBT-0012 | Open | Modernization | `pp_ui_core` uses vcpkg tinyxml2 on `windows-msvc-vcpkg-headless`, but retains `pp_vendor_tinyxml2` for default and unproven platform presets | Mobile/AppX/Apple triplets and app packaging still need validation before removing the vendored fallback | `ctest --preset desktop-fast-vcpkg --build-config Debug`; `ctest --preset desktop-fast --build-config Debug`; `powershell -ExecutionPolicy Bypass -File scripts\automation\platform-build.ps1 -Presets android-arm64` | All supported presets consume vcpkg tinyxml2 or document a permanent vendored exception |
 | DEBT-0013 | Open | Modernization | `pp_assets`, `pp_document`, `pano_cli inspect-project`, `pano_cli load-project`, and `pano_cli save-project` validate the fixed PPI header, thumbnail/body byte layout, generated multi-layer/multi-frame PPI writing with explicit layer opacity/blend/alpha-lock/visibility metadata, per-layer frame durations, metadata-only and targeted dirty-face-payload save/load round-trips, layer/frame index, dirty-face descriptors, dirty-face PNG payload metadata, asset-level RGBA PNG payload decoding, pure document-to-PPI export, CLI document export automation, file-writing document export automation, stroke-script-generated document payload export, decoded pixel attachment to `pp_document`, live save-path snapshot-readiness reporting, and app-core canvas-snapshot-to-PPI export automation, but full legacy PPI round-trip parity and pure live save writer replacement are not yet extracted | Full PPI save parity requires staged extraction of legacy `Canvas` serialization and image/layer payload handling | `ctest --preset desktop-fast --build-config Debug`; `pp_assets_image_pixels_tests`; `pp_assets_ppi_header_tests`; `pp_document_ppi_import_tests`; `pp_document_ppi_export_tests`; `pano_cli_inspect_project_layout_smoke`; `pano_cli_load_project_metadata_smoke`; `pano_cli_save_project_roundtrip_smoke`; `pano_cli_save_project_payload_roundtrip_smoke`; `pano_cli_simulate_document_export_smoke`; `pano_cli_save_document_project_roundtrip_smoke`; `pano_cli_apply_stroke_script_roundtrip_smoke`; `pano_cli_apply_stroke_script_rejects_tiny_canvas` | Full PPI load/save fixtures cover thumbnails, decoded layer face payloads attached to documents, frames, corrupt payloads, dirty-face payload saving, arbitrary legacy canvas payload/layout combinations, and legacy app round-trip compatibility |
@@ -555,7 +561,7 @@ agent or engineer to remove them without reconstructing context from chat.
 | DEBT-0040 | Open | Modernization | Close request, document save, save-before-workflow planning/execution dispatch, and close/save-before/save-error prompt metadata now consume pure `pp_app_core` through `App::request_close`, `App::save_document`, `App::continue_document_workflow_after_optional_save`, `pano_cli simulate-app-session`, `pano_cli plan-document-session-prompt`, `DocumentSaveServices`, `CloseRequestServices`, `DocumentWorkflowServices`, and `src/legacy_document_session_services.*`; close/save-before prompt creation now uses `src/legacy_app_dialog_services.*`, Save dialog working-directory picker visibility/path formatting now dispatches through `PlatformServices`, and existing-project save/save-before-workflow execution prepares a payload-bearing canvas snapshot report before retained saving, but the bridge still opens retained save dialogs, wires prompt callbacks directly, delegates actual writing to `Canvas::project_save`, mutates the unsaved flag on close confirmation, invokes native app close, and routes save-version through the retained legacy dialog | Preserve current close/save/dirty-workflow behavior while document session execution moves toward app/document/UI/platform services | `pp_app_core_document_session_tests`; `pp_platform_api_tests`; `pano_cli plan-document-session-prompt --kind close-unsaved`; `pano_cli plan-document-session-prompt --kind save-before-workflow`; `pano_cli simulate-app-session --unsaved --save-intent save-dirty-version`; `pano_cli simulate-app-session --no-canvas`; `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`; `ctest --preset desktop-fast --build-config Debug` | Close prompt execution, native close requests, dirty-workflow save prompts, existing-project saves, save dialogs, save-version execution, and unsaved-flag mutation are owned by injected app/document/UI/platform services with `App` methods acting only as adapters |
 | DEBT-0041 | Open | Modernization | Accepted new-document planning/execution dispatch and new-document overwrite prompt metadata now consume pure `pp_app_core` through `App::dialog_newdoc`, `pano_cli plan-new-document`, `pano_cli plan-document-session-prompt`, `NewDocumentServices`, and `src/legacy_document_session_services.*`; new-document overwrite prompt creation now uses `src/legacy_app_dialog_services.*`, and New Document dialog working-directory picker visibility/path formatting now dispatches through `PlatformServices`, but the bridge still mutates legacy app document fields, clears legacy layer UI, resizes legacy `Canvas`, clears legacy history, creates the default layer through legacy UI, mutates unsaved/new-document flags, updates the title, wires overwrite callbacks directly, and handles keyboard/dialog cleanup directly | Preserve current New Document dialog behavior while document creation moves toward app/document/UI services | `pp_app_core_document_session_tests`; `pp_platform_api_tests`; `pano_cli plan-new-document --work-dir D:/Paint --name demo --resolution-index 3`; `pano_cli plan-new-document --work-dir D:/Paint --name demo --resolution-index 3 --target-exists`; `pano_cli plan-document-session-prompt --kind new-document-overwrite`; `pano_cli simulate-app-session --save-intent save`; `ctest --preset desktop-fast --build-config Debug` | New document creation, overwrite confirmation, canvas/document allocation, default layer creation, history clearing, title updates, dirty/new-document state, and keyboard/dialog cleanup are owned by injected app/document/UI services with `App::dialog_newdoc` acting only as a UI adapter |
 | DEBT-0042 | Open | Modernization | Accepted Save As and Save Version planning/execution dispatch plus Save As overwrite prompt metadata now consumes pure `pp_app_core` through `App::dialog_save`, `App::dialog_save_ver`, `pano_cli plan-document-file`, `pano_cli plan-document-version`, `pano_cli plan-document-session-prompt`, `DocumentFileSaveServices`, `DocumentVersionSaveServices`, and `src/legacy_document_session_services.*`; Save As overwrite prompt creation now uses `src/legacy_app_dialog_services.*`, and accepted Save As/Save Version execution prepares a payload-bearing canvas snapshot report before retained saving, but the bridge still wires overwrite callbacks directly, delegates actual writing to legacy `Canvas::project_save`, mutates app document name/path/directory fields, marks version saves dirty before saving, updates the title, and handles keyboard/dialog cleanup directly | Preserve current Save As and Save Version behavior while document persistence moves toward app/document/storage/UI services | `pp_app_core_document_session_tests`; `pano_cli plan-document-file --work-dir D:/Paint --name demo --target-exists`; `pano_cli plan-document-session-prompt --kind file-overwrite --name demo`; `pano_cli plan-document-version --directory D:/Paint --doc-name demo.01 --existing-path D:/Paint/demo.02.ppi`; `pano_cli simulate-app-session --save-intent save-as`; `pano_cli simulate-app-session --save-intent save-version`; `ctest --preset desktop-fast --build-config Debug` | Save As overwrite prompting, project-save execution, app document metadata updates, title updates, version-save dirty-state handling, and keyboard/dialog cleanup are owned by injected app/document/storage/UI services with `App::dialog_save` and `App::dialog_save_ver` acting only as UI adapters |
-| DEBT-0043 | Open | Modernization | Equirectangular, layer, animation-frame, depth, and cube-face export planning/execution dispatch now consumes pure `pp_app_core` through `App::dialog_export`, `App::dialog_export_layers`, `App::dialog_export_anim_frames`, `App::dialog_export_depth`, `App::dialog_export_cube_faces`, `pano_cli plan-export-*`, `DocumentExportServices`, and `src/legacy_document_export_services.*`; layer/frame dialogs also consume `plan_document_export_collection_target` plus `PlatformServices::uses_work_directory_document_export_collections()` instead of spelling local iOS branches, export success/failure/license dialog metadata plus execution log labels now come from `pp_app_core`, equirectangular/layer/animation-frame/cube-face execution prepares a payload-bearing document snapshot plus renderer-neutral upload and face-PNG export reports, and cube-face export writes the pure face PNG bytes before falling back to retained Canvas execution on failure, but the bridge still calls legacy `Canvas` export methods for equirectangular/layers/animation/depth, creates export directories, handles picker-selected stems, performs Web prepared-file handoff directly, and leaves depth export on the retained path | Preserve current image/collection/depth/cube export behavior while export execution moves toward document/renderer/platform/storage services | `pp_app_core_document_export_tests`; `pp_platform_api_tests`; `pano_cli plan-export-start --requires-license --demo`; `pano_cli plan-export-menu --kind layers`; `pano_cli plan-export-target --kind collection --work-dir D:/Paint --doc-name demo --suffix _layers`; `pano_cli plan-export-message --kind equirectangular --destination work --detail D:/Paint`; `pano_cli plan-export-report --kind license-disabled`; `pano_cli simulate-document-export`; `ctest --preset desktop-fast --build-config Debug` | File, collection, stem, depth, and remaining retained export execution, export-directory creation, Web file handoff, picker-selected stem handling, and legacy canvas export calls are owned by injected document/renderer/platform/storage services with export dialogs acting only as UI adapters |
+| DEBT-0043 | Open | Modernization | Equirectangular, layer, animation-frame, depth, and cube-face export planning/execution dispatch now consumes pure `pp_app_core` through `App::dialog_export`, `App::dialog_export_layers`, `App::dialog_export_anim_frames`, `App::dialog_export_depth`, `App::dialog_export_cube_faces`, `pano_cli plan-export-*`, `DocumentExportServices`, and `src/legacy_document_export_services.*`; layer/frame dialogs also consume `plan_document_export_collection_target` plus `PlatformServices::uses_work_directory_document_export_collections()` instead of spelling local iOS branches, export success/failure/license dialog metadata plus execution log labels now come from `pp_app_core`, equirectangular/layer/animation-frame/cube-face execution prepares a payload-bearing document snapshot plus renderer-neutral upload and face-PNG export reports, and cube-face export writes the pure face PNG bytes to `pp_app_core` planned work-directory face paths before falling back to retained Canvas execution on failure, but the bridge still calls legacy `Canvas` export methods for equirectangular/layers/animation/depth, creates export directories, handles picker-selected stems, performs Web prepared-file handoff directly, and leaves depth export on the retained path | Preserve current image/collection/depth/cube export behavior while export execution moves toward document/renderer/platform/storage services | `pp_app_core_document_export_tests`; `pp_platform_api_tests`; `pano_cli plan-export-start --requires-license --demo`; `pano_cli plan-export-menu --kind layers`; `pano_cli plan-export-target --kind collection --work-dir D:/Paint --doc-name demo --suffix _layers`; `pano_cli plan-export-target --kind cube-faces --work-dir D:/Paint --doc-name demo`; `pano_cli plan-export-message --kind equirectangular --destination work --detail D:/Paint`; `pano_cli plan-export-report --kind license-disabled`; `pano_cli simulate-document-export`; `ctest --preset desktop-fast --build-config Debug` | File, collection, stem, depth, and remaining retained export execution, export-directory creation, Web file handoff, picker-selected stem handling, and legacy canvas export calls are owned by injected document/renderer/platform/storage services with export dialogs acting only as UI adapters |
 | DEBT-0044 | Open | Modernization | Timelapse and animation MP4 export execution dispatch now consumes pure `pp_app_core` through `App::dialog_timelapse_export`, `App::dialog_export_mp4`, `pano_cli plan-export-menu`, `pano_cli plan-export-target --kind name`, `pano_cli plan-export-message`, `pano_cli plan-export-report`, `DocumentVideoExportServices`, and `src/legacy_document_export_services.*`, and success/failure/license dialog metadata plus execution log labels now come from `pp_app_core`, but the bridge still launches legacy desktop timelapse worker threads, calls `App::rec_export`, calls `Canvas::export_anim_mp4`, and owns mobile/Web save callbacks | Preserve current MP4/timelapse export behavior while video export moves toward app/document/renderer/video/platform/storage services | `pp_app_core_document_export_tests`; `pano_cli plan-export-menu --kind animation-mp4`; `pano_cli plan-export-menu --kind timelapse`; `pano_cli plan-export-target --kind name --doc-name demo --suffix -animation`; `pano_cli plan-export-target --kind name --doc-name demo --suffix -timelapse`; `pano_cli plan-export-message --kind timelapse --destination success`; `pano_cli plan-export-report --kind animation-mp4 --message "video export path must not be empty"`; `ctest --preset desktop-fast --build-config Debug` | Timelapse and animation MP4 execution, desktop worker threading, frame readback/video encoding handoff, and mobile/Web save callbacks are owned by injected app/document/renderer/video/platform/storage services with export dialogs acting only as UI adapters |
 | DEBT-0045 | Open | Modernization | Options-menu preference execution now consumes pure `pp_app_core` through UI scale, viewport scale, RTL direction, VR mode, VR-controller, auto-timelapse, and canvas cursor-mode callbacks plus `AppPreferenceServices` and `src/legacy_app_preference_services.*`; viewport-density and cursor-mode execution now delegate to `src/legacy_canvas_view_services.*`, but the bridges still call legacy `App::set_ui_scale`, `App::set_ui_rtl`, `App::rec_start`, `App::rec_stop`, retained canvas view mutation, and `Settings::save` directly; VR mode callbacks now call `App` VR wrappers that dispatch to `PlatformServices`, whose desktop runtime policy prefers OpenXR while the actual Windows OpenVR SDK bridge still lives in `WindowsPlatformServices` under DEBT-0061 | Preserve current options-menu behavior while preferences move toward app/UI/platform/storage services | `pp_app_core_app_preferences_tests`; `pp_app_core_canvas_view_tests`; `pano_cli plan-app-preferences --ui-scale 1.5 --display-density 2 --current-scale 1.6 --scale-option 1 --scale-option 1.5 --rtl`; `pano_cli plan-canvas-view-density --density 1.5`; `pano_cli plan-canvas-view-cursor-mode --mode 3`; `ctest --preset desktop-fast --build-config Debug`; `cmake --build --preset windows-msvc-default --config Debug --target PanoPainter` | Preference persistence, UI/layout direction, viewport density, cursor mode, VR mode start/stop/failure handling, VR-controller state, and auto-timelapse recording side effects are owned by injected app/UI/platform/storage services with options-menu callbacks acting only as UI adapters |
 | DEBT-0046 | Open | Modernization | Startup preference/runtime execution and startup resource sequencing now consume pure `pp_app_core` through `App::init`, `pano_cli plan-app-startup`, `pano_cli plan-app-startup-resources`, `AppStartupServices`, `AppStartupResourceServices`, and `src/legacy_app_startup_services.*`, but the bridge still calls legacy `Settings::set`, `Settings::save`, `App::rec_start`, app VR-controller state mutation, message-box license warning execution, shader loading, asset initialization, layout creation, title updates, and UI render-target creation directly | Preserve current startup behavior while app startup moves toward app/preferences/storage/recording/UI/renderer services | `pp_app_core_app_startup_tests`; `pano_cli plan-app-startup --run-counter 7 --vr-controllers-disabled --license-invalid`; `pano_cli plan-app-startup --run-counter -1`; `pano_cli plan-app-startup-resources --width 1280 --height 720`; `pano_cli plan-app-startup-resources --bad-size`; `ctest --preset desktop-fast --build-config Debug`; `cmake --build --preset windows-msvc-default --config Debug --target PanoPainter` | Startup preference persistence, auto-timelapse startup, stored VR-controller state, license validation/warning, startup resource initialization, title updates, and UI render-target allocation are owned by injected app/preferences/storage/recording/UI/renderer services with `App::init` acting only as orchestration |

docs/modernization/roadmap.md

@@ -529,7 +529,8 @@ candidate generation, collision skipping, and no-slot failure behavior used by
 the live save-version dialog.
 `pano_cli plan-export-target` exposes app-core export target planning for
 equirectangular image files, layer/frame collection stems, picked-directory
-stems, and MP4 suggested names used by the live export dialogs.
+stems, cube-face work-directory file sets, and MP4 suggested names used by the
+live export dialogs and cube-face writer bridge.
 `pano_cli plan-export-start` exposes the app-core export availability decision
 used by live image, layer, animation-frame, depth, and cube-face export dialogs
 plus MP4 animation and timelapse export dialogs before they call legacy
@@ -688,10 +689,10 @@ renderer-owned readback remain under
 Live equirectangular, layer, animation-frame, and cube-face export adapters now
 prepare the same payload-bearing document snapshot and renderer-neutral upload
 report helper plus pure face-PNG export report. Cube-face export writes those
-document/renderer-owned PNG bytes to the legacy face filenames when available
-and falls back to retained `Canvas::export_cube_faces` on snapshot/write failure;
-the other export workflows still delegate to retained `Canvas` writers after
-readiness reporting.
+document/renderer-owned PNG bytes to the app-core-planned legacy face filenames
+when available and falls back to retained `Canvas::export_cube_faces` on
+snapshot/write failure; the other export workflows still delegate to retained
+`Canvas` writers after readiness reporting.
 `pano_cli plan-image-import` exposes app-core planning for File > Import image
 route decisions, including wide equirectangular images, legacy vertical cube
 strips, regular transform-placement images, and invalid image dimensions; live
@@ -2531,10 +2532,10 @@ Results:
 - Live image/collection/cube export adapters now prepare and log the same
   document/canvas plus shared renderer-upload and face-PNG export readiness
   reports. Cube-face export now writes the pure document/renderer PNG bytes to
-  the legacy face filenames before falling back to retained `Canvas` execution
-  on failure. Equirectangular, layer, animation-frame, depth, and video export
-  remain on their prior retained writer paths; actual broader writer replacement
-  remains tracked under export debt.
+  the `pp_app_core` planned legacy face filenames before falling back to
+  retained `Canvas` execution on failure. Equirectangular, layer,
+  animation-frame, depth, and video export remain on their prior retained writer
+  paths; actual broader writer replacement remains tracked under export debt.
 - Snapshot creation now rejects invalid embedded RGBA8 face payloads before
   document export or history can persist malformed state.
 - Package-smoke wrappers validate the Windows CMake app executable/runtime

src/app_core/document_export.h

@@ -1,8 +1,11 @@
 #pragma once
 
 #include "app_core/app_dialog.h"
+#include "document/document.h"
 #include "foundation/result.h"
 
+#include <array>
+#include <cstddef>
 #include <string>
 #include <string_view>
 #include <utility>
@@ -23,6 +26,16 @@ struct DocumentExportStemTarget {
     std::string stem_path;
 };
 
+struct DocumentCubeFaceExportFileTarget {
+    std::string face_name;
+    std::string path;
+};
+
+struct DocumentCubeFaceExportTarget {
+    std::array<DocumentCubeFaceExportFileTarget, pp::document::cube_face_count> faces;
+    std::size_t face_count = 0;
+};
+
 struct DocumentExportSuggestedName {
     std::string name;
 };
@@ -535,6 +548,51 @@ public:
     return pp::foundation::Result<DocumentExportStemTarget>::success(std::move(target));
 }
 
+[[nodiscard]] constexpr std::array<std::string_view, pp::document::cube_face_count>
+document_cube_face_export_names() noexcept
+{
+    return {
+        "front",
+        "right",
+        "back",
+        "left",
+        "top",
+        "bottom",
+    };
+}
+
+[[nodiscard]] inline pp::foundation::Result<DocumentCubeFaceExportTarget> make_document_cube_face_export_target(
+    std::string_view work_directory,
+    std::string_view document_name)
+{
+    if (work_directory.empty()) {
+        return pp::foundation::Result<DocumentCubeFaceExportTarget>::failure(
+            pp::foundation::Status::invalid_argument("work directory must not be empty"));
+    }
+
+    if (document_name.empty()) {
+        return pp::foundation::Result<DocumentCubeFaceExportTarget>::failure(
+            pp::foundation::Status::invalid_argument("document name must not be empty"));
+    }
+
+    DocumentCubeFaceExportTarget target;
+    const auto face_names = document_cube_face_export_names();
+    target.face_count = face_names.size();
+    for (std::size_t face_index = 0; face_index < face_names.size(); ++face_index) {
+        auto& face = target.faces[face_index];
+        face.face_name = face_names[face_index];
+        face.path.reserve(work_directory.size() + document_name.size() + face_names[face_index].size() + 6);
+        face.path += work_directory;
+        face.path += "/";
+        face.path += document_name;
+        face.path += "-";
+        face.path += face_names[face_index];
+        face.path += ".png";
+    }
+
+    return pp::foundation::Result<DocumentCubeFaceExportTarget>::success(std::move(target));
+}
+
 [[nodiscard]] inline pp::foundation::Result<DocumentExportSuggestedName> make_document_export_suggested_name(
     std::string_view document_name,
     std::string_view suffix)

src/legacy_document_export_services.cpp

@@ -6,7 +6,6 @@
 #include "legacy_document_canvas_services.h"
 #include "paint_renderer/compositor.h"
 
-#include <array>
 #include <fstream>
 #include <limits>
 #include <span>
@@ -142,30 +141,21 @@ pp::foundation::Status export_cube_faces_from_document_snapshot(
     std::string_view document_name,
     const LegacyDocumentExportSnapshotReports& reports)
 {
-    static constexpr std::array<std::string_view, pp::document::cube_face_count> plane_names {
-        "front",
-        "right",
-        "back",
-        "left",
-        "top",
-        "bottom",
-    };
-
-    if (document_name.empty()) {
-        return pp::foundation::Status::invalid_argument("document name must not be empty");
+    const auto target = pp::app::make_document_cube_face_export_target(app.work_path, document_name);
+    if (!target) {
+        return target.status();
     }
     if (reports.face_pngs.face_count != pp::document::cube_face_count) {
         return pp::foundation::Status::invalid_argument("document snapshot did not produce all cube face PNGs");
     }
 
-    for (std::size_t face_index = 0; face_index < plane_names.size(); ++face_index) {
-        const std::string path = app.work_path + "/" + std::string(document_name) + "-"
-            + std::string(plane_names[face_index]) + ".png";
-        const auto status = write_binary_file(path, reports.face_pngs.face_pngs[face_index]);
+    for (std::size_t face_index = 0; face_index < target.value().face_count; ++face_index) {
+        const auto& face = target.value().faces[face_index];
+        const auto status = write_binary_file(face.path, reports.face_pngs.face_pngs[face_index]);
         if (!status.ok()) {
             return status;
         }
-        app.publish_exported_image(path);
+        app.publish_exported_image(face.path);
     }
 
     return pp::foundation::Status::success();

tests/CMakeLists.txt

@@ -898,6 +898,12 @@ if(TARGET pano_cli)
         LABELS "app;integration;desktop-fast"
         PASS_REGULAR_EXPRESSION "\"command\":\"plan-export-target\".*\"kind\":\"collection\".*\"directory\":\"D:/Paint/demo_layers\".*\"stemPath\":\"D:/Paint/demo_layers/demo\"")
 
+    add_test(NAME pano_cli_plan_export_target_cube_faces_smoke
+        COMMAND pano_cli plan-export-target --kind cube-faces --work-dir D:/Paint --doc-name demo)
+    set_tests_properties(pano_cli_plan_export_target_cube_faces_smoke PROPERTIES
+        LABELS "app;integration;desktop-fast"
+        PASS_REGULAR_EXPRESSION "\"command\":\"plan-export-target\".*\"kind\":\"cube-faces\".*\"faceCount\":6.*\"name\":\"front\".*\"path\":\"D:/Paint/demo-front.png\".*\"name\":\"bottom\".*\"path\":\"D:/Paint/demo-bottom.png\"")
+
     add_test(NAME pano_cli_plan_export_target_name_smoke
         COMMAND pano_cli plan-export-target --kind name --doc-name demo --suffix -timelapse)
     set_tests_properties(pano_cli_plan_export_target_name_smoke PROPERTIES

tests/app_core/document_export_tests.cpp

@@ -182,6 +182,36 @@ void picked_directory_export_builds_stem(pp::tests::Harness& harness)
     PP_EXPECT(harness, target.value().stem_path == "D:/Exports/demo");
 }
 
+void cube_face_export_builds_legacy_work_paths(pp::tests::Harness& harness)
+{
+    const auto target = pp::app::make_document_cube_face_export_target("D:/Paint", "demo");
+    PP_EXPECT(harness, target);
+    PP_EXPECT(harness, target.value().face_count == 6U);
+    PP_EXPECT(harness, target.value().faces[0].face_name == "front");
+    PP_EXPECT(harness, target.value().faces[0].path == "D:/Paint/demo-front.png");
+    PP_EXPECT(harness, target.value().faces[1].face_name == "right");
+    PP_EXPECT(harness, target.value().faces[1].path == "D:/Paint/demo-right.png");
+    PP_EXPECT(harness, target.value().faces[2].face_name == "back");
+    PP_EXPECT(harness, target.value().faces[2].path == "D:/Paint/demo-back.png");
+    PP_EXPECT(harness, target.value().faces[3].face_name == "left");
+    PP_EXPECT(harness, target.value().faces[3].path == "D:/Paint/demo-left.png");
+    PP_EXPECT(harness, target.value().faces[4].face_name == "top");
+    PP_EXPECT(harness, target.value().faces[4].path == "D:/Paint/demo-top.png");
+    PP_EXPECT(harness, target.value().faces[5].face_name == "bottom");
+    PP_EXPECT(harness, target.value().faces[5].path == "D:/Paint/demo-bottom.png");
+}
+
+void cube_face_export_rejects_invalid_target_inputs(pp::tests::Harness& harness)
+{
+    const auto missing_work_directory = pp::app::make_document_cube_face_export_target("", "demo");
+    const auto missing_name = pp::app::make_document_cube_face_export_target("D:/Paint", "");
+
+    PP_EXPECT(harness, !missing_work_directory);
+    PP_EXPECT(harness, missing_work_directory.status().code == pp::foundation::StatusCode::invalid_argument);
+    PP_EXPECT(harness, !missing_name);
+    PP_EXPECT(harness, missing_name.status().code == pp::foundation::StatusCode::invalid_argument);
+}
+
 void video_export_builds_suggested_name(pp::tests::Harness& harness)
 {
     const auto timelapse = pp::app::make_document_export_suggested_name("demo", "-timelapse");
@@ -717,6 +747,8 @@ int main()
     harness.run("export file target rejects invalid input", export_file_target_rejects_invalid_input);
     harness.run("collection export builds directory and stem", collection_export_builds_directory_and_stem);
     harness.run("picked directory export builds stem", picked_directory_export_builds_stem);
+    harness.run("cube face export builds legacy work paths", cube_face_export_builds_legacy_work_paths);
+    harness.run("cube face export rejects invalid target inputs", cube_face_export_rejects_invalid_target_inputs);
     harness.run("video export builds suggested name", video_export_builds_suggested_name);
     harness.run("collection export target plan selects platform destination", collection_export_target_plan_selects_platform_destination);
     harness.run("export success dialog plans image destinations", export_success_dialog_plans_image_destinations);

tools/pano_cli/main.cpp

@@ -2384,7 +2384,7 @@ void print_help()
         << "  plan-document-session-prompt --kind close-unsaved|save-before-workflow|new-document-overwrite|file-overwrite|save-error [--name NAME]\n"
         << "  plan-export-start [--requires-license] [--demo] [--no-canvas]\n"
         << "  plan-export-menu --kind jpeg|png|layers|cube-faces|depth|animation-frames|animation-mp4|timelapse [--demo] [--no-canvas]\n"
-        << "  plan-export-target --kind file|collection|stem|name --doc-name NAME [--work-dir DIR] [--directory DIR] [--extension EXT] [--suffix SUFFIX]\n"
+        << "  plan-export-target --kind file|collection|stem|cube-faces|name --doc-name NAME [--work-dir DIR] [--directory DIR] [--extension EXT] [--suffix SUFFIX]\n"
         << "  plan-export-message --kind equirectangular|layers|animation-frames|depth|cube-faces|animation-mp4|timelapse --destination photos|pictures|files|work|path|success|suppressed [--detail TEXT]\n"
         << "  plan-export-report --kind license-disabled|equirectangular|layers|animation-frames|depth|cube-faces|animation-mp4|timelapse [--message TEXT]\n"
         << "  plan-cloud-upload [--no-canvas] [--new-document] [--unsaved]\n"
@@ -9637,7 +9637,8 @@ pp::foundation::Status parse_plan_export_target_args(
         return pp::foundation::Status::invalid_argument("document name must not be empty");
     }
 
-    if ((args.kind == "file" || args.kind == "collection") && args.work_directory.empty()) {
+    if ((args.kind == "file" || args.kind == "collection" || args.kind == "cube-faces")
+        && args.work_directory.empty()) {
         return pp::foundation::Status::invalid_argument("work directory must not be empty");
     }
 
@@ -9653,7 +9654,8 @@ pp::foundation::Status parse_plan_export_target_args(
         return pp::foundation::Status::invalid_argument("suffix must not be empty");
     }
 
-    if (args.kind != "file" && args.kind != "collection" && args.kind != "stem" && args.kind != "name") {
+    if (args.kind != "file" && args.kind != "collection" && args.kind != "stem"
+        && args.kind != "cube-faces" && args.kind != "name") {
         return pp::foundation::Status::invalid_argument("unknown export target kind");
     }
 
@@ -9716,6 +9718,31 @@ int plan_export_target(int argc, char** argv)
         return 0;
     }
 
+    if (args.kind == "cube-faces") {
+        const auto target = pp::app::make_document_cube_face_export_target(
+            args.work_directory,
+            args.document_name);
+        if (!target) {
+            print_error("plan-export-target", target.status().message);
+            return 2;
+        }
+
+        std::cout << "{\"ok\":true,\"command\":\"plan-export-target\""
+                  << ",\"kind\":\"cube-faces\",\"target\":{\"faceCount\":" << target.value().face_count
+                  << ",\"faces\":[";
+        for (std::size_t face_index = 0; face_index < target.value().face_count; ++face_index) {
+            if (face_index != 0U) {
+                std::cout << ",";
+            }
+            const auto& face = target.value().faces[face_index];
+            std::cout << "{\"name\":\"" << json_escape(face.face_name)
+                      << "\",\"path\":\"" << json_escape(face.path)
+                      << "\"}";
+        }
+        std::cout << "]}}\n";
+        return 0;
+    }
+
     const auto target = pp::app::make_document_export_suggested_name(args.document_name, args.suffix);
     if (!target) {
         print_error("plan-export-target", target.status().message);