Model UI capture lifetime in ui core

docs/modernization/build-inventory.md

@@ -735,9 +735,10 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
   vcpkg-backed `pp_ui_core`/tinyxml2 boundary and `pp_ui_core_layout_xml_tests`.
 - `pp_ui_core` now owns a pure `NodeLifetimeTree` target model with checked
   node handles, hidden parent/child invariants, scoped callback connections,
-  mutation-safe event dispatch, and focused destroy-during-callback coverage in
-  `pp_ui_core_node_lifetime_tests`. Retained `Node` still needs to adopt those
-  semantics under DEBT-0063.
+  pointer/keyboard capture ownership, mutation-safe event dispatch, whole-tree
+  reload invalidation, and focused destroy-during-callback/layout-reload
+  coverage in `pp_ui_core_node_lifetime_tests`. Retained `Node` still needs to
+  adopt those semantics under DEBT-0063.
 - `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/debt.md

@@ -447,6 +447,11 @@ agent or engineer to remove them without reconstructing context from chat.
   destroy the dispatched node or add new connections. Retained `Node` adoption,
   layout reload coverage, and `pp_panopainter_ui` dialog/popup lifetime tests
   remain open.
+- 2026-06-06: DEBT-0063 was narrowed again. The same `NodeLifetimeTree` model
+  now covers pointer/keyboard capture ownership, automatic capture release when
+  a captured node is destroyed, and whole-tree `clear()` invalidation for layout
+  reloads. Retained `Node` adoption and app-specific popup/dialog lifetime
+  tests 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
@@ -640,7 +645,7 @@ 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, and mutation-safe dispatch, but retained `Node` has not adopted it 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`; 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, but retained `Node` has not adopted it 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`; 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-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 |

docs/modernization/roadmap.md

@@ -470,8 +470,9 @@ destroy-during-callback tests before broad `NodePanel*`/`NodeDialog*`
 migration accelerates. The first pure `pp_ui_core::NodeLifetimeTree` slice now
 models checked handles, parent/child invariants, scoped callback connections,
 and mutation-safe dispatch for destroy-during-callback and connection-addition
-cases; wiring those semantics into retained `Node` remains tracked by the same
-debt.
+cases. It now also models pointer/keyboard capture release and whole-tree
+`clear()` invalidation for layout reload; wiring those semantics into retained
+`Node` remains tracked by the same debt.
 `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/ui_core/node_lifetime.cpp

@@ -158,11 +158,68 @@ pp::foundation::Status NodeLifetimeTree::destroy_subtree(NodeHandle node) noexce
     slot->children.clear();
     slot->connections.clear();
     slot->parent = {};
+    release_captures_for_node(node);
     slot->alive = false;
     free_nodes_.push_back(node.slot);
     return pp::foundation::Status::success();
 }
 
+void NodeLifetimeTree::clear() noexcept
+{
+    free_nodes_.clear();
+    for (std::uint32_t index = 0; index < nodes_.size(); ++index) {
+        auto& slot = nodes_[index];
+        slot.alive = false;
+        slot.parent = {};
+        slot.children.clear();
+        slot.connections.clear();
+        free_nodes_.push_back(index);
+    }
+
+    free_connections_.clear();
+    for (std::uint32_t index = 0; index < connections_.size(); ++index) {
+        auto& slot = connections_[index];
+        slot.alive = false;
+        slot.node = {};
+        slot.callback = nullptr;
+        free_connections_.push_back(index);
+    }
+
+    captures_ = {};
+}
+
+pp::foundation::Status NodeLifetimeTree::capture(UiCaptureKind kind, NodeHandle node) noexcept
+{
+    if (node_slot(node) == nullptr) {
+        return pp::foundation::Status::invalid_argument("UI capture requires a live node");
+    }
+
+    captures_[capture_index(kind)] = node;
+    return pp::foundation::Status::success();
+}
+
+pp::foundation::Status NodeLifetimeTree::release_capture(UiCaptureKind kind, NodeHandle node) noexcept
+{
+    auto& captured = captures_[capture_index(kind)];
+    if (captured != node) {
+        return pp::foundation::Status::invalid_argument("UI capture release requires the captured node");
+    }
+
+    captured = {};
+    return pp::foundation::Status::success();
+}
+
+pp::foundation::Result<NodeHandle> NodeLifetimeTree::captured_node(UiCaptureKind kind) const noexcept
+{
+    const auto captured = captures_[capture_index(kind)];
+    if (node_slot(captured) == nullptr) {
+        return pp::foundation::Result<NodeHandle>::failure(
+            pp::foundation::Status::invalid_argument("UI capture slot is empty"));
+    }
+
+    return pp::foundation::Result<NodeHandle>::success(captured);
+}
+
 pp::foundation::Result<UiConnection> NodeLifetimeTree::connect(NodeHandle node, Callback callback)
 {
     if (node_slot(node) == nullptr) {
@@ -339,6 +396,18 @@ pp::foundation::Result<NodeHandle> NodeLifetimeTree::allocate_node(NodeHandle pa
     return pp::foundation::Result<NodeHandle>::success(node);
 }
 
+std::size_t NodeLifetimeTree::capture_index(UiCaptureKind kind) const noexcept
+{
+    switch (kind) {
+    case UiCaptureKind::pointer:
+        return 0U;
+    case UiCaptureKind::keyboard:
+        return 1U;
+    }
+
+    return 0U;
+}
+
 void NodeLifetimeTree::unlink_from_parent(NodeHandle node) noexcept
 {
     const auto* slot = node_slot(node);
@@ -376,4 +445,13 @@ void NodeLifetimeTree::release_connection(UiConnection connection) noexcept
     free_connections_.push_back(connection.slot);
 }
 
+void NodeLifetimeTree::release_captures_for_node(NodeHandle node) noexcept
+{
+    for (auto& capture : captures_) {
+        if (capture == node) {
+            capture = {};
+        }
+    }
+}
+
 }

src/ui_core/node_lifetime.h

@@ -5,6 +5,7 @@
 #include <cstddef>
 #include <cstdint>
 #include <functional>
+#include <array>
 #include <vector>
 
 namespace pp::ui {
@@ -52,6 +53,11 @@ struct UiConnection {
     return !(left == right);
 }
 
+enum class UiCaptureKind : std::uint8_t {
+    pointer,
+    keyboard,
+};
+
 class NodeLifetimeTree;
 
 class ScopedUiConnection {
@@ -86,6 +92,11 @@ public:
     [[nodiscard]] pp::foundation::Result<std::size_t> child_count(NodeHandle node) const noexcept;
     [[nodiscard]] pp::foundation::Result<NodeHandle> child_at(NodeHandle node, std::size_t index) const noexcept;
     [[nodiscard]] pp::foundation::Status destroy_subtree(NodeHandle node) noexcept;
+    void clear() noexcept;
+
+    [[nodiscard]] pp::foundation::Status capture(UiCaptureKind kind, NodeHandle node) noexcept;
+    [[nodiscard]] pp::foundation::Status release_capture(UiCaptureKind kind, NodeHandle node) noexcept;
+    [[nodiscard]] pp::foundation::Result<NodeHandle> captured_node(UiCaptureKind kind) const noexcept;
 
     [[nodiscard]] pp::foundation::Result<UiConnection> connect(NodeHandle node, Callback callback);
     [[nodiscard]] pp::foundation::Result<ScopedUiConnection> scoped_connect(NodeHandle node, Callback callback);
@@ -115,13 +126,16 @@ private:
     [[nodiscard]] const ConnectionSlot* connection_slot(UiConnection connection) const noexcept;
 
     [[nodiscard]] pp::foundation::Result<NodeHandle> allocate_node(NodeHandle parent);
+    [[nodiscard]] std::size_t capture_index(UiCaptureKind kind) const noexcept;
     void unlink_from_parent(NodeHandle node) noexcept;
     void release_connection(UiConnection connection) noexcept;
+    void release_captures_for_node(NodeHandle node) noexcept;
 
     std::vector<NodeSlot> nodes_;
     std::vector<std::uint32_t> free_nodes_;
     std::vector<ConnectionSlot> connections_;
     std::vector<std::uint32_t> free_connections_;
+    std::array<NodeHandle, 2> captures_ {};
 };
 
 }

tests/ui_core/node_lifetime_tests.cpp

@@ -3,6 +3,7 @@
 
 using pp::foundation::StatusCode;
 using pp::ui::NodeLifetimeTree;
+using pp::ui::UiCaptureKind;
 
 namespace {
 
@@ -209,6 +210,104 @@ void dispatch_uses_stable_connection_snapshot(pp::tests::Harness& h)
     PP_EXPECT(h, second_count == 1);
 }
 
+void captures_and_releases_pointer_and_keyboard_nodes(pp::tests::Harness& h)
+{
+    NodeLifetimeTree tree;
+    const auto root = tree.create_root();
+    PP_EXPECT(h, root);
+    if (!root) {
+        return;
+    }
+
+    const auto child = tree.create_child(root.value());
+    PP_EXPECT(h, child);
+    if (!child) {
+        return;
+    }
+
+    PP_EXPECT(h, tree.capture(UiCaptureKind::pointer, child.value()).ok());
+    PP_EXPECT(h, tree.capture(UiCaptureKind::keyboard, root.value()).ok());
+
+    const auto pointer = tree.captured_node(UiCaptureKind::pointer);
+    const auto keyboard = tree.captured_node(UiCaptureKind::keyboard);
+    PP_EXPECT(h, pointer);
+    PP_EXPECT(h, keyboard);
+    if (pointer) {
+        PP_EXPECT(h, pointer.value() == child.value());
+    }
+    if (keyboard) {
+        PP_EXPECT(h, keyboard.value() == root.value());
+    }
+
+    PP_EXPECT(h, !tree.release_capture(UiCaptureKind::pointer, root.value()).ok());
+    PP_EXPECT(h, tree.release_capture(UiCaptureKind::pointer, child.value()).ok());
+    PP_EXPECT(h, !tree.captured_node(UiCaptureKind::pointer).ok());
+    PP_EXPECT(h, tree.captured_node(UiCaptureKind::keyboard));
+}
+
+void destroying_captured_node_releases_capture(pp::tests::Harness& h)
+{
+    NodeLifetimeTree tree;
+    const auto root = tree.create_root();
+    PP_EXPECT(h, root);
+    if (!root) {
+        return;
+    }
+
+    const auto child = tree.create_child(root.value());
+    PP_EXPECT(h, child);
+    if (!child) {
+        return;
+    }
+
+    PP_EXPECT(h, tree.capture(UiCaptureKind::pointer, child.value()).ok());
+    PP_EXPECT(h, tree.capture(UiCaptureKind::keyboard, root.value()).ok());
+    PP_EXPECT(h, tree.destroy_subtree(child.value()).ok());
+    PP_EXPECT(h, !tree.captured_node(UiCaptureKind::pointer).ok());
+    PP_EXPECT(h, tree.captured_node(UiCaptureKind::keyboard));
+
+    PP_EXPECT(h, tree.destroy_subtree(root.value()).ok());
+    PP_EXPECT(h, !tree.captured_node(UiCaptureKind::keyboard).ok());
+}
+
+void clear_models_layout_reload(pp::tests::Harness& h)
+{
+    NodeLifetimeTree tree;
+    const auto root = tree.create_root();
+    PP_EXPECT(h, root);
+    if (!root) {
+        return;
+    }
+
+    const auto child = tree.create_child(root.value());
+    PP_EXPECT(h, child);
+    if (!child) {
+        return;
+    }
+
+    int call_count = 0;
+    const auto connection = tree.connect(child.value(), [&call_count](pp::ui::NodeHandle) {
+        ++call_count;
+    });
+    PP_EXPECT(h, connection);
+    PP_EXPECT(h, tree.capture(UiCaptureKind::pointer, child.value()).ok());
+
+    tree.clear();
+    PP_EXPECT(h, !tree.contains(root.value()));
+    PP_EXPECT(h, !tree.contains(child.value()));
+    PP_EXPECT(h, !tree.dispatch(child.value()).ok());
+    PP_EXPECT(h, !tree.disconnect(connection.value()).ok());
+    PP_EXPECT(h, !tree.captured_node(UiCaptureKind::pointer).ok());
+    PP_EXPECT(h, call_count == 0);
+
+    const auto reloaded_root = tree.create_root();
+    PP_EXPECT(h, reloaded_root);
+    if (reloaded_root) {
+        PP_EXPECT(h, tree.contains(reloaded_root.value()));
+        PP_EXPECT(h, reloaded_root.value().generation != root.value().generation);
+    }
+}
+
 }
 
 int main()
@@ -221,5 +320,8 @@ int main()
     harness.run("destroying_node_disconnects_callbacks", destroying_node_disconnects_callbacks);
     harness.run("dispatch_survives_destroy_during_callback", dispatch_survives_destroy_during_callback);
     harness.run("dispatch_uses_stable_connection_snapshot", dispatch_uses_stable_connection_snapshot);
+    harness.run("captures_and_releases_pointer_and_keyboard_nodes", captures_and_releases_pointer_and_keyboard_nodes);
+    harness.run("destroying_captured_node_releases_capture", destroying_captured_node_releases_capture);
+    harness.run("clear_models_layout_reload", clear_models_layout_reload);
     return harness.finish();
 }