Centralize retained UI overlay insertion

cmake/PanoPainterSources.cmake

@@ -102,6 +102,8 @@ set(PP_PANOPAINTER_APP_SOURCES
     src/legacy_document_open_services.h
     src/legacy_document_session_services.cpp
     src/legacy_document_session_services.h
+    src/legacy_ui_overlay_services.cpp
+    src/legacy_ui_overlay_services.h
     src/platform_legacy/legacy_platform_services.cpp
     src/platform_legacy/legacy_platform_services.h
     src/version.cpp

docs/modernization/build-inventory.md

@@ -742,6 +742,12 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
   dialog, capture-restore, branch-close, and layout-reload coverage in
   `pp_ui_core_overlay_lifetime_tests`. Retained `Node`/popup/dialog code still
   needs to adopt those semantics under DEBT-0063.
+- `panopainter_app` now owns `src/legacy_ui_overlay_services.*` as the retained
+  app-dialog overlay adapter. App-level progress/message/input dialogs and the
+  retained about/manual/changelog, document open/save/new/browse/resize/
+  layer-rename, PPBR export, shortcuts, and what's-new overlays route their root
+  attachment through that helper while raw `Node` ownership and callbacks remain
+  legacy debt.
 - `scripts/automation/analyze.*` runs shader validation plus a
   renderer-boundary guard that reports JSON and fails if active non-backend
   source code reintroduces raw `GL_*`/`WGL_*` constants outside the allowed

docs/modernization/capability-map.md

@@ -58,7 +58,7 @@ and validation command.
 | XML layout parsing | `LayoutManager`, `Node` | `pp_ui_core` | Layout fixtures and malformed XML |
 | Yoga layout | `Node` | `pp_ui_core` | Deterministic geometry fixtures |
 | Generic controls | `NodeButton`, sliders, text, images | `pp_ui_core` | Event dispatch, layout, ownership-handle, callback-disconnect, and destroy-during-callback tests |
-| PanoPainter panels/dialogs | `NodePanel*`, `NodeDialog*` | `pp_panopainter_ui`, `pp_ui_core` | UI automation scripts, command-dispatch view models, pure overlay lifetime tests, retained popup/dialog lifetime tests |
+| PanoPainter panels/dialogs | `NodePanel*`, `NodeDialog*` | `pp_panopainter_ui`, `pp_ui_core` | UI automation scripts, command-dispatch view models, pure overlay lifetime tests, retained overlay-adapter build coverage, retained popup/dialog lifetime tests |
 | Canvas viewport UI | `NodeCanvas` | `pp_panopainter_ui`, `pp_paint_renderer` | Input-to-command automation |
 | Settings UI | `Settings`, `NodeSettings` | `pp_assets`, `pp_panopainter_ui` | Round-trip settings |
 

docs/modernization/debt.md

@@ -457,6 +457,12 @@ agent or engineer to remove them without reconstructing context from chat.
   policy, capture restoration after child/modal close, parent popup branch
   teardown, untracked close rejection, and layout-reload invalidation. Retained
   `NodePopupMenu`/`NodeDialog*` adoption remains open.
+- 2026-06-06: DEBT-0063/DEBT-0058 were narrowed. `src/legacy_ui_overlay_services.*`
+  now centralizes retained app-dialog overlay initialization and root attachment,
+  and the app-level progress/message/input dialogs plus about/manual/changelog,
+  document open/save/new/browse/resize/layer-rename, PPBR export, shortcuts, and
+  what's-new overlays route through it. Raw `Node` ownership, callback captures,
+  and retained popup/menu lifetime semantics remain open.
 - 2026-06-05: DEBT-0011 was narrowed. The Windows app package smoke target now
   passes the configure-time CMake executable into `package-smoke.ps1`, so VS
   2026 generator validation does not depend on an older `cmake` on PATH, and
@@ -650,9 +656,9 @@ agent or engineer to remove them without reconstructing context from chat.
 | DEBT-0060 | Open | Modernization | Retained Android package CMake generates a patched `nanort.h` overlay in the build tree for `native-lib` instead of modifying the `libs/nanort` submodule | Current SDK Manager NDK/Clang rejects `TriangleSAHPred::operator=` assigning to a `const size_t` member, but the retained grid/lightmap path still includes `nanort` before that dependency is replaced or updated | `powershell -ExecutionPolicy Bypass -File scripts\automation\android-legacy-package-build.ps1 -Packages standard`; Quest/Focus retained package configure checks; Windows app build | Update/replace `nanort`, move grid/lightmap baking behind a component that owns its dependency, or retire the retained Android package CMake path so no generated vendor overlay is required |
 | DEBT-0061 | Open | Modernization | Desktop XR runtime selection now lives in tested `pp_platform_api` policy and prefers OpenXR, but `WindowsPlatformServices` still reports OpenXR unavailable and reaches the retained OpenVR SDK bridge as a legacy fallback; Windows runtime deployment copies `openvr_api.dll` beside `PanoPainter.exe` until that fallback is removed | Preserve current desktop VR behavior while replacing OpenVR with OpenXR behind the platform/renderer boundary | `pp_platform_api_tests`; `ctest --preset desktop-fast --build-config Debug -R pp_platform_api_tests --output-on-failure`; `cmake --build --preset windows-msvc-default --config Debug --target PanoPainter` | Add an OpenXR SDK/package target, implement desktop OpenXR startup/shutdown/pose/controller submission behind `pp_platform_vr` or `PlatformServices`, validate parity with mocked/runtime smoke coverage, and remove `libs/openvr` plus the OpenVR link/include paths from root CMake |
 | DEBT-0062 | Open | Modernization | VS 2026 builds generate a patched fmt `format.h` overlay in the build tree for `pp_legacy_vendor`, disabling the old `_SECURE_SCL` checked-array iterator branch while leaving the fmt submodule clean | VS 2026's STL no longer exposes the legacy checked-array iterator used by this old fmt release, but replacing fmt is part of the dependency migration rather than this platform unblock | `cmake --build --preset windows-msvc-default --config Debug --target PanoPainter`; `cmake --build --preset windows-msvc-default --config Debug --target pp_platform_api_tests`; `ctest --preset desktop-fast --build-config Debug -R pp_platform_api_tests --output-on-failure` | Move fmt to a supported vcpkg/package version or update the vendored fmt release, then remove the generated fmt overlay from `pp_legacy_vendor` |
-| DEBT-0063 | Open | Modernization | The retained UI tree still exposes `Node* m_parent`, public `std::vector<std::shared_ptr<Node>> m_children`, raw `find<T>()` lookup results, `add_child<T>()` allocation through `new`, callbacks/observers that take or capture raw `Node*`, and manual `destroy()`/`m_destroyed` semantics. `pp_ui_core` now owns a tested `NodeLifetimeTree` target model with checked node handles, scoped callback connections, subtree destruction, pointer/keyboard capture release, whole-tree clear for layout reload, and mutation-safe dispatch, plus a tested `UiOverlayLifetime` popup/dialog stack model, but retained `Node`/`NodePopupMenu`/`NodeDialog*` have not adopted them yet | Preserve current UI behavior while making panel/dialog extraction safe instead of spreading lifetime hazards into the new architecture | `pp_ui_core_layout_xml_tests`; `pp_ui_core_node_lifetime_tests`; `pp_ui_core_overlay_lifetime_tests`; future `pp_panopainter_ui_dialog_lifetime_tests`; `ctest --preset desktop-fast --build-config Debug`; `cmake --build --preset windows-msvc-default --config Debug --target PanoPainter` | Retained `Node` and `pp_panopainter_ui` adopt checked node handles or equivalent non-owning references, scoped callback connection/disconnect semantics, mutation-safe event dispatch, parent/child invariants hidden behind APIs, and destroy-during-callback/capture-release/popup-close/layout-reload tests; retained `Node*` APIs are removed or isolated behind compatibility adapters |
+| DEBT-0063 | Open | Modernization | The retained UI tree still exposes `Node* m_parent`, public `std::vector<std::shared_ptr<Node>> m_children`, raw `find<T>()` lookup results, `add_child<T>()` allocation through `new`, callbacks/observers that take or capture raw `Node*`, and manual `destroy()`/`m_destroyed` semantics. `pp_ui_core` now owns a tested `NodeLifetimeTree` target model with checked node handles, scoped callback connections, subtree destruction, pointer/keyboard capture release, whole-tree clear for layout reload, and mutation-safe dispatch, plus a tested `UiOverlayLifetime` popup/dialog stack model. Retained app-dialog root insertion is now centralized in `src/legacy_ui_overlay_services.*`, but retained `Node`/`NodePopupMenu`/`NodeDialog*` still have not adopted checked handles or scoped callback ownership | Preserve current UI behavior while making panel/dialog extraction safe instead of spreading lifetime hazards into the new architecture | `pp_ui_core_layout_xml_tests`; `pp_ui_core_node_lifetime_tests`; `pp_ui_core_overlay_lifetime_tests`; future `pp_panopainter_ui_dialog_lifetime_tests`; `ctest --preset desktop-fast --build-config Debug`; `cmake --build --preset windows-msvc-default --config Debug --target PanoPainter` | Retained `Node` and `pp_panopainter_ui` adopt checked node handles or equivalent non-owning references, scoped callback connection/disconnect semantics, mutation-safe event dispatch, parent/child invariants hidden behind APIs, and destroy-during-callback/capture-release/popup-close/layout-reload tests; retained `Node*` APIs are removed or isolated behind compatibility adapters |
 | DEBT-0057 | Open | Modernization | Default canvas allocation size now dispatches through `PlatformServices::default_canvas_resolution`, removing the `CANVAS_RES` platform macro from `src/canvas.h`; WebGL's retained 512 default now lives in tested `pp_platform_api::platform_policy`, but the Web shell still reaches it through the legacy platform fallback until injected Web services own the policy | Preserve WebGL memory behavior while moving canvas creation policy out of shared canvas headers and into the platform boundary | `pp_platform_api_tests`; `ctest --preset desktop-fast --build-config Debug -R pp_platform_api_tests`; Windows app build; WebGL package smoke once root Web build exists | Default canvas resolution is owned by injected `pp_platform_*` services for every supported platform, with no WebGL branch in the legacy fallback |
-| DEBT-0058 | Open | Modernization | App-level progress/message/input dialog metadata, including message-dialog OK/cancel captions, now consumes pure `pp_app_core` through `App::show_progress`, `App::message_box`, `App::input_box`, `pano_cli plan-app-dialog`, and `pp_app_core_app_dialog_tests`; live execution is centralized in `src/legacy_app_dialog_services.*`, but the bridge still creates retained `NodeProgressBar`, `NodeMessageBox`, and `NodeInputBox` instances and inserts them into the legacy layout tree | Preserve current app-shell dialog behavior while moving shared dialog policy toward UI/app services | `pp_app_core_app_dialog_tests`; `pano_cli plan-app-dialog --kind progress --total -4`; `pano_cli plan-app-dialog --kind message --cancel`; `pano_cli plan-app-dialog --kind input --ok-caption Save`; `ctest --preset desktop-fast --build-config Debug`; Windows app build | Progress/message/input dialog creation, callback wiring, layout insertion, lifetime ownership, and headless automation are owned by injected app/UI services with `App` methods acting only as adapters |
+| DEBT-0058 | Open | Modernization | App-level progress/message/input dialog metadata, including message-dialog OK/cancel captions, now consumes pure `pp_app_core` through `App::show_progress`, `App::message_box`, `App::input_box`, `pano_cli plan-app-dialog`, and `pp_app_core_app_dialog_tests`; live execution is centralized in `src/legacy_app_dialog_services.*`, and retained root insertion now routes through `src/legacy_ui_overlay_services.*`, but the bridge still creates retained `NodeProgressBar`, `NodeMessageBox`, and `NodeInputBox` instances with raw callback/lifetime ownership | Preserve current app-shell dialog behavior while moving shared dialog policy toward UI/app services | `pp_app_core_app_dialog_tests`; `pano_cli plan-app-dialog --kind progress --total -4`; `pano_cli plan-app-dialog --kind message --cancel`; `pano_cli plan-app-dialog --kind input --ok-caption Save`; `ctest --preset desktop-fast --build-config Debug`; Windows app build | Progress/message/input dialog creation, callback wiring, layout insertion, lifetime ownership, and headless automation are owned by injected app/UI services with `App` methods acting only as adapters |
 | DEBT-0059 | Open | Modernization | iOS root CMake headless builds assign generated bundle identifiers and disable code signing for executable test/tool targets | The current Apple gate is compile validation for shared component targets; signed iOS app/package validation is not migrated to root CMake yet | `powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.ps1 -Presets macos,ios-simulator,ios-device`; `sh scripts/automation/platform-build.sh "ios-device"` on `panopainter-mac` | Root CMake owns the signed Apple app/package targets, package-smoke validates Apple bundles where signing material is available, and headless iOS test/tool targets are either excluded from signed package builds or use explicit test-runner signing policy |
 
 ## Closed Debt

docs/modernization/roadmap.md

@@ -476,6 +476,11 @@ layers popup/dialog stack ownership on top of that model, covering root and
 nested popups, modal versus modeless dialogs, capture restoration, parent-popup
 branch close, and layout-reload invalidation. Wiring those semantics into
 retained `Node`/`NodePopupMenu`/`NodeDialog*` remains tracked by the same debt.
+The first retained adoption point is `src/legacy_ui_overlay_services.*`, which
+now centralizes app-dialog overlay initialization and root attachment for
+progress/message/input dialogs, about/manual/changelog, document open/save/new/
+browse/resize/layer-rename dialogs, PPBR export, shortcuts, and the what's-new
+remote page before those paths reach raw `Node` insertion.
 `pano_cli inspect-image` exposes PNG IHDR metadata as JSON,
 `pano_cli import-image` accepts a PNG path and imports decoded RGBA8 pixels
 into a new pure `pp_document` face payload,

src/app_dialogs.cpp

@@ -11,6 +11,7 @@
 #include "legacy_document_export_services.h"
 #include "legacy_document_layer_services.h"
 #include "legacy_document_session_services.h"
+#include "legacy_ui_overlay_services.h"
 #include "settings.h"
 #include "node_dialog_open.h"
 #include "node_dialog_browse.h"
@@ -147,35 +148,17 @@ std::shared_ptr<NodeInputBox> App::input_box(const std::string& title,
 
 void App::dialog_usermanual()
 {
-    auto dialog = std::make_shared<NodeUserManual>();
+    (void)pp::panopainter::add_legacy_overlay_node<NodeUserManual>(*this);
-    dialog->set_manager(&layout);
-    dialog->init();
-    dialog->create();
-    dialog->loaded();
-
-    layout[main_id]->add_child(dialog);
 }
 
 void App::dialog_changelog()
 {
-    auto dialog = std::make_shared<NodeChangelog>();
+    (void)pp::panopainter::add_legacy_overlay_node<NodeChangelog>(*this);
-    dialog->set_manager(&layout);
-    dialog->init();
-    dialog->create();
-    dialog->loaded();
-
-    layout[main_id]->add_child(dialog);
 }
 
 void App::dialog_about()
 {
-    auto dialog = std::make_shared<NodeAbout>();
+    (void)pp::panopainter::add_legacy_overlay_node<NodeAbout>(*this);
-    dialog->set_manager(&layout);
-    dialog->init();
-    dialog->create();
-    dialog->loaded();
-
-    layout[main_id]->add_child(dialog);
 }
 
 void App::continue_document_workflow_after_optional_save(std::function<void()> action)
@@ -194,14 +177,10 @@ void App::continue_document_workflow_after_optional_save(std::function<void()> a
 void App::dialog_newdoc()
 {
     auto show_dialog = [this] {
-        auto dialog = std::make_shared<NodeDialogNewDoc>();
+        auto dialog = pp::panopainter::make_legacy_overlay_node<NodeDialogNewDoc>(*this);
-        dialog->set_manager(&layout);
-        dialog->init();
-        dialog->create();
-        dialog->loaded();
         dialog->input->set_text("name");
 
-        layout[main_id]->add_child(dialog);
+        (void)pp::panopainter::attach_legacy_overlay_node(*this, dialog);
 
         App::I->showKeyboard();
 
@@ -245,13 +224,9 @@ void App::dialog_open()
 {
     auto show_dialog = [this] {
         // load thumbnail test
-        auto dialog = std::make_shared<NodeDialogOpen>();
+        auto dialog = pp::panopainter::make_legacy_overlay_node<NodeDialogOpen>(*this);
-        dialog->set_manager(&layout);
-        dialog->init();
-        dialog->create();
-        dialog->loaded();
 
-        layout[main_id]->add_child(dialog);
+        (void)pp::panopainter::attach_legacy_overlay_node(*this, dialog);
 
         dialog->btn_ok->on_click = [this, dialog](Node*)
         {
@@ -279,13 +254,10 @@ void App::dialog_browse()
     auto show_dialog = [this] {
         // load thumbnail test
         auto dialog = std::make_shared<NodeDialogBrowse>();
-        dialog->set_manager(&layout);
         dialog->search_paths = document_browse_roots();
-        dialog->init();
+        pp::panopainter::initialize_legacy_overlay_node(*this, *dialog);
-        dialog->create();
-        dialog->loaded();
 
-        layout[main_id]->add_child(dialog);
+        (void)pp::panopainter::attach_legacy_overlay_node(*this, dialog);
 
         dialog->btn_ok->on_click = [this, dialog](Node*)
         {
@@ -345,11 +317,7 @@ void App::dialog_save()
     
     if (canvas)
     {
-        auto dialog = std::make_shared<NodeDialogSave>();
+        auto dialog = pp::panopainter::make_legacy_overlay_node<NodeDialogSave>(*this);
-        dialog->set_manager(&layout);
-        dialog->init();
-        dialog->create();
-        dialog->loaded();
         dialog->input->set_text(doc_name);
 
         App::I->showKeyboard();
@@ -379,7 +347,7 @@ void App::dialog_save()
             App::I->hideKeyboard();
         };
 
-        layout[main_id]->add_child(dialog);
+        (void)pp::panopainter::attach_legacy_overlay_node(*this, dialog);
     }
 }
 
@@ -442,13 +410,9 @@ void App::dialog_export_depth()
 
 void App::dialog_resize()
 {
-    auto dialog = std::make_shared<NodeDialogResize>();
+    auto dialog = pp::panopainter::make_legacy_overlay_node<NodeDialogResize>(*this);
-    dialog->set_manager(&layout);
-    dialog->init();
-    dialog->create();
-    dialog->loaded();
 
-    layout[main_id]->add_child(dialog);
+    (void)pp::panopainter::attach_legacy_overlay_node(*this, dialog);
 
     dialog->btn_ok->on_click = [this,dialog](Node*)
     {
@@ -481,16 +445,12 @@ void App::dialog_export_cube_faces()
 
 void App::dialog_layer_rename()
 {
-    auto dialog = std::make_shared<NodeDialogLayerRename>();
+    auto dialog = pp::panopainter::make_legacy_overlay_node<NodeDialogLayerRename>(*this);
-    dialog->set_manager(&layout);
-    dialog->init();
-    dialog->create();
-    dialog->loaded();
     dialog->input->set_text(layers->m_current_layer->m_label_text);
 
     App::I->showKeyboard();
 
-    layout[main_id]->add_child(dialog);
+    (void)pp::panopainter::attach_legacy_overlay_node(*this, dialog);
 
     dialog->btn_ok->on_click = [this,dialog](Node*)
     {
@@ -516,8 +476,7 @@ void App::dialog_preset_download()
 
 void App::dialog_ppbr_export()
 {
-    auto root = layout[main_id];
+    auto dialog = pp::panopainter::add_legacy_overlay_node<NodeDialogExportPPBR>(*this);
-    auto dialog = root->add_child_ref<NodeDialogExportPPBR>();
     dialog->btn_ok->on_click = [this, dialog] (Node*) {
         const auto request = pp::panopainter::make_legacy_brush_package_export_request(*dialog);
 
@@ -662,7 +621,7 @@ void App::dialog_export_mp4()
 void App::dialog_whatsnew(bool force_show)
 {
     auto whatsnew = std::make_shared<NodeRemotePage>();
-    whatsnew->m_manager = &layout;
+    whatsnew->set_manager(&layout);
     whatsnew->init();
     std::string url = fmt::format("https://panopainter.com/app-content/whatsnew/?version={}", g_version_build);
     whatsnew->load_url(url, [this, whatsnew, force_show](bool success) {
@@ -673,7 +632,7 @@ void App::dialog_whatsnew(bool force_show)
             {
                 whatsnew->set_title(fmt::format("What's new in version {}", g_version_number));
                 if (!force_show)
-                    layout[main_id]->add_child(whatsnew);
+                    (void)pp::panopainter::attach_legacy_overlay_node(*this, whatsnew);
             }
         }
     });
@@ -691,10 +650,10 @@ void App::dialog_whatsnew(bool force_show)
         whatsnew->destroy();
     });
     if (force_show)
-        layout[main_id]->add_child(whatsnew);
+        (void)pp::panopainter::attach_legacy_overlay_node(*this, whatsnew);
 }
 
 void App::dialog_shortcuts()
 {
-    layout[main_id]->add_child<NodeShortcuts>();
+    (void)pp::panopainter::add_legacy_overlay_node<NodeShortcuts>(*this);
 }

src/legacy_app_dialog_services.cpp

@@ -2,6 +2,7 @@
 #include "legacy_app_dialog_services.h"
 
 #include "app.h"
+#include "legacy_ui_overlay_services.h"
 #include "node_input_box.h"
 #include "node_message_box.h"
 #include "node_progress_bar.h"
@@ -12,16 +13,12 @@ std::shared_ptr<NodeProgressBar> create_legacy_app_progress_dialog(
     App& app,
     const pp::app::AppProgressDialogPlan& plan)
 {
-    auto progress = std::make_shared<NodeProgressBar>();
+    auto progress = make_legacy_overlay_node<NodeProgressBar>(app);
-    progress->set_manager(&app.layout);
-    progress->init();
-    progress->create();
-    progress->loaded();
     progress->m_progress->SetWidthP(plan.progress_fraction);
     progress->m_title->set_text(plan.title.c_str());
     progress->m_total = plan.total;
     progress->m_count = plan.count;
-    app.layout[app.main_id]->add_child(progress);
+    (void)attach_legacy_overlay_node(app, progress);
     return progress;
 }
 
@@ -29,11 +26,7 @@ std::shared_ptr<NodeMessageBox> create_legacy_app_message_dialog(
     App& app,
     const pp::app::AppMessageDialogPlan& plan)
 {
-    auto message = std::make_shared<NodeMessageBox>();
+    auto message = make_legacy_overlay_node<NodeMessageBox>(app);
-    message->set_manager(&app.layout);
-    message->init();
-    message->create();
-    message->loaded();
     message->m_title->set_text(plan.title.c_str());
     message->m_message->set_text(plan.message.c_str());
     message->btn_ok->m_text->set_text(plan.ok_caption.c_str());
@@ -41,7 +34,7 @@ std::shared_ptr<NodeMessageBox> create_legacy_app_message_dialog(
         message->btn_cancel->m_text->set_text(plan.cancel_caption.c_str());
     else
         message->btn_cancel->destroy();
-    app.layout[app.main_id]->add_child(message);
+    (void)attach_legacy_overlay_node(app, message);
     return message;
 }
 
@@ -49,15 +42,11 @@ std::shared_ptr<NodeInputBox> create_legacy_app_input_dialog(
     App& app,
     const pp::app::AppInputDialogPlan& plan)
 {
-    auto input = std::make_shared<NodeInputBox>();
+    auto input = make_legacy_overlay_node<NodeInputBox>(app);
-    input->set_manager(&app.layout);
-    input->init();
-    input->create();
-    input->loaded();
     input->m_title->set_text(plan.title.c_str());
     input->m_field_name->set_text(plan.field_name.c_str());
     input->btn_ok->m_text->set_text(plan.ok_caption.c_str());
-    app.layout[app.main_id]->add_child(input);
+    (void)attach_legacy_overlay_node(app, input);
     return input;
 }
 

src/legacy_ui_overlay_services.cpp

@@ -0,0 +1,34 @@
+#include "pch.h"
+#include "legacy_ui_overlay_services.h"
+
+#include "app.h"
+#include "node.h"
+
+namespace pp::panopainter {
+
+void initialize_legacy_overlay_node(App& app, Node& node)
+{
+    node.set_manager(&app.layout);
+    node.init();
+    node.create();
+    node.loaded();
+}
+
+pp::foundation::Status attach_legacy_overlay_node(
+    App& app,
+    const std::shared_ptr<Node>& node) noexcept
+{
+    if (!node) {
+        return pp::foundation::Status::invalid_argument("legacy overlay node is null");
+    }
+
+    auto* root = app.layout[app.main_id];
+    if (!root) {
+        return pp::foundation::Status::invalid_argument("legacy overlay root is missing");
+    }
+
+    root->add_child(node);
+    return pp::foundation::Status::success();
+}
+
+} // namespace pp::panopainter

src/legacy_ui_overlay_services.h

@@ -0,0 +1,34 @@
+#pragma once
+
+#include "foundation/result.h"
+
+#include <memory>
+
+class App;
+class Node;
+
+namespace pp::panopainter {
+
+void initialize_legacy_overlay_node(App& app, Node& node);
+
+[[nodiscard]] pp::foundation::Status attach_legacy_overlay_node(
+    App& app,
+    const std::shared_ptr<Node>& node) noexcept;
+
+template <class T>
+std::shared_ptr<T> make_legacy_overlay_node(App& app)
+{
+    auto node = std::make_shared<T>();
+    initialize_legacy_overlay_node(app, *node);
+    return node;
+}
+
+template <class T>
+std::shared_ptr<T> add_legacy_overlay_node(App& app)
+{
+    auto node = make_legacy_overlay_node<T>(app);
+    (void)attach_legacy_overlay_node(app, node);
+    return node;
+}
+
+} // namespace pp::panopainter