Add UI core node lifetime handles

CMakeLists.txt

@@ -220,7 +220,8 @@ target_link_libraries(pp_paint_renderer
 add_library(pp_ui_core STATIC
     src/ui_core/color.cpp
     src/ui_core/layout_value.cpp
-    src/ui_core/layout_xml.cpp)
+    src/ui_core/layout_xml.cpp
+    src/ui_core/node_lifetime.cpp)
 target_include_directories(pp_ui_core
     PUBLIC
         "${CMAKE_CURRENT_SOURCE_DIR}/src")

docs/modernization/build-inventory.md

@@ -733,6 +733,11 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
   and platform triplet migration. Root CMake target
   `panopainter_platform_build_vcpkg_ui_core` focuses that gate on the
   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.
 - `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
@@ -1248,8 +1253,9 @@ Known warnings after the current CMake app build:
   `ShaderManager::ext_*` fields directly.
 - `pp_legacy_ui_core` is an object-library containment boundary because the
   retained base `Node` controls still depend on legacy renderer and app
-  headers. It should shrink as layout parsing, colors, generic controls, and
-  text/image primitives move to `pp_ui_core`.
+  headers. It should shrink as layout parsing, colors, generic controls,
+  tested node lifetime handles/connections, and text/image primitives move to
+  `pp_ui_core`.
 - `pp_panopainter_ui` currently surfaces existing legacy `Node`/`Serializer`
   header and static-analysis warnings while it still depends on
   `pp_legacy_app`; these should be reduced as the UI core/app UI boundary is

docs/modernization/debt.md

@@ -441,6 +441,12 @@ agent or engineer to remove them without reconstructing context from chat.
   replaced incrementally by `pp_ui_core` ownership handles, scoped callback
   connections, and mutation-safe dispatch tests before broad panel/dialog
   migration accelerates.
+- 2026-06-06: DEBT-0063 was narrowed. `pp_ui_core::NodeLifetimeTree` now owns a
+  pure checked-handle model for parent/child invariants, subtree destruction,
+  scoped callback disconnection, and mutation-safe dispatch when callbacks
+  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-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
@@ -634,7 +640,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 while `pp_ui_core` only owns parsing/color/layout helpers so far | 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`; future `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` | `pp_ui_core` owns the UI tree lifetime model with 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, 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

@@ -467,7 +467,11 @@ and lookup pointers, public mutable child ownership, raw callback targets, and
 manual destroy flags. `pp_ui_core` should introduce owned tree/handle APIs,
 scoped callback connections, mutation-safe event dispatch, and focused
 destroy-during-callback tests before broad `NodePanel*`/`NodeDialog*`
-migration accelerates.
+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.
 `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

@@ -0,0 +1,379 @@
+#include "ui_core/node_lifetime.h"
+
+#include <algorithm>
+#include <utility>
+
+namespace pp::ui {
+namespace {
+
+void bump_generation(std::uint32_t& generation) noexcept
+{
+    ++generation;
+    if (generation == 0U) {
+        generation = 1U;
+    }
+}
+
+}
+
+ScopedUiConnection::ScopedUiConnection(NodeLifetimeTree& tree, UiConnection connection) noexcept
+    : tree_(&tree)
+    , connection_(connection)
+{
+}
+
+ScopedUiConnection::ScopedUiConnection(ScopedUiConnection&& other) noexcept
+    : tree_(std::exchange(other.tree_, nullptr))
+    , connection_(std::exchange(other.connection_, UiConnection {}))
+{
+}
+
+ScopedUiConnection& ScopedUiConnection::operator=(ScopedUiConnection&& other) noexcept
+{
+    if (this != &other) {
+        reset();
+        tree_ = std::exchange(other.tree_, nullptr);
+        connection_ = std::exchange(other.connection_, UiConnection {});
+    }
+
+    return *this;
+}
+
+ScopedUiConnection::~ScopedUiConnection()
+{
+    reset();
+}
+
+void ScopedUiConnection::reset() noexcept
+{
+    if (tree_ != nullptr && connection_.valid()) {
+        (void)tree_->disconnect(connection_);
+    }
+    tree_ = nullptr;
+    connection_ = {};
+}
+
+UiConnection ScopedUiConnection::connection() const noexcept
+{
+    return connection_;
+}
+
+bool ScopedUiConnection::connected() const noexcept
+{
+    return tree_ != nullptr && connection_.valid();
+}
+
+pp::foundation::Result<NodeHandle> NodeLifetimeTree::create_root()
+{
+    return allocate_node(NodeHandle {});
+}
+
+pp::foundation::Result<NodeHandle> NodeLifetimeTree::create_child(NodeHandle parent)
+{
+    if (node_slot(parent) == nullptr) {
+        return pp::foundation::Result<NodeHandle>::failure(
+            pp::foundation::Status::invalid_argument("UI child node requires a live parent"));
+    }
+
+    auto child = allocate_node(parent);
+    if (!child) {
+        return child;
+    }
+
+    node_slot(parent)->children.push_back(child.value());
+    return child;
+}
+
+bool NodeLifetimeTree::contains(NodeHandle node) const noexcept
+{
+    return node_slot(node) != nullptr;
+}
+
+pp::foundation::Result<NodeHandle> NodeLifetimeTree::parent_of(NodeHandle node) const noexcept
+{
+    const auto* slot = node_slot(node);
+    if (slot == nullptr) {
+        return pp::foundation::Result<NodeHandle>::failure(
+            pp::foundation::Status::invalid_argument("UI node handle is not live"));
+    }
+
+    if (!slot->parent.valid()) {
+        return pp::foundation::Result<NodeHandle>::failure(
+            pp::foundation::Status::invalid_argument("UI root node does not have a parent"));
+    }
+
+    return pp::foundation::Result<NodeHandle>::success(slot->parent);
+}
+
+pp::foundation::Result<std::size_t> NodeLifetimeTree::child_count(NodeHandle node) const noexcept
+{
+    const auto* slot = node_slot(node);
+    if (slot == nullptr) {
+        return pp::foundation::Result<std::size_t>::failure(
+            pp::foundation::Status::invalid_argument("UI node handle is not live"));
+    }
+
+    return pp::foundation::Result<std::size_t>::success(slot->children.size());
+}
+
+pp::foundation::Result<NodeHandle> NodeLifetimeTree::child_at(NodeHandle node, std::size_t index) const noexcept
+{
+    const auto* slot = node_slot(node);
+    if (slot == nullptr) {
+        return pp::foundation::Result<NodeHandle>::failure(
+            pp::foundation::Status::invalid_argument("UI node handle is not live"));
+    }
+
+    if (index >= slot->children.size()) {
+        return pp::foundation::Result<NodeHandle>::failure(
+            pp::foundation::Status::out_of_range("UI child index is outside the node"));
+    }
+
+    return pp::foundation::Result<NodeHandle>::success(slot->children[index]);
+}
+
+pp::foundation::Status NodeLifetimeTree::destroy_subtree(NodeHandle node) noexcept
+{
+    auto* slot = node_slot(node);
+    if (slot == nullptr) {
+        return pp::foundation::Status::invalid_argument("UI node handle is not live");
+    }
+
+    const auto children = slot->children;
+    for (const auto child : children) {
+        (void)destroy_subtree(child);
+    }
+
+    const auto connections = slot->connections;
+    for (const auto connection : connections) {
+        release_connection(connection);
+    }
+
+    unlink_from_parent(node);
+    slot = node_slot(node);
+    if (slot == nullptr) {
+        return pp::foundation::Status::success();
+    }
+
+    slot->children.clear();
+    slot->connections.clear();
+    slot->parent = {};
+    slot->alive = false;
+    free_nodes_.push_back(node.slot);
+    return pp::foundation::Status::success();
+}
+
+pp::foundation::Result<UiConnection> NodeLifetimeTree::connect(NodeHandle node, Callback callback)
+{
+    if (node_slot(node) == nullptr) {
+        return pp::foundation::Result<UiConnection>::failure(
+            pp::foundation::Status::invalid_argument("UI connection requires a live node"));
+    }
+
+    if (!callback) {
+        return pp::foundation::Result<UiConnection>::failure(
+            pp::foundation::Status::invalid_argument("UI connection requires a callback"));
+    }
+
+    UiConnection connection;
+    if (!free_connections_.empty()) {
+        connection.slot = free_connections_.back();
+        free_connections_.pop_back();
+        auto& slot = connections_[connection.slot];
+        bump_generation(slot.generation);
+        slot.alive = true;
+        slot.node = node;
+        slot.callback = std::move(callback);
+        connection.generation = slot.generation;
+    } else {
+        connection.slot = static_cast<std::uint32_t>(connections_.size());
+        connection.generation = 1U;
+        connections_.push_back(ConnectionSlot {
+            .generation = connection.generation,
+            .alive = true,
+            .node = node,
+            .callback = std::move(callback),
+        });
+    }
+
+    node_slot(node)->connections.push_back(connection);
+    return pp::foundation::Result<UiConnection>::success(connection);
+}
+
+pp::foundation::Result<ScopedUiConnection> NodeLifetimeTree::scoped_connect(NodeHandle node, Callback callback)
+{
+    auto connection = connect(node, std::move(callback));
+    if (!connection) {
+        return pp::foundation::Result<ScopedUiConnection>::failure(connection.status());
+    }
+
+    return pp::foundation::Result<ScopedUiConnection>::success(ScopedUiConnection(*this, connection.value()));
+}
+
+pp::foundation::Status NodeLifetimeTree::disconnect(UiConnection connection) noexcept
+{
+    if (connection_slot(connection) == nullptr) {
+        return pp::foundation::Status::invalid_argument("UI connection handle is not live");
+    }
+
+    release_connection(connection);
+    return pp::foundation::Status::success();
+}
+
+pp::foundation::Result<std::size_t> NodeLifetimeTree::live_connection_count(NodeHandle node) const noexcept
+{
+    const auto* slot = node_slot(node);
+    if (slot == nullptr) {
+        return pp::foundation::Result<std::size_t>::failure(
+            pp::foundation::Status::invalid_argument("UI node handle is not live"));
+    }
+
+    return pp::foundation::Result<std::size_t>::success(slot->connections.size());
+}
+
+pp::foundation::Status NodeLifetimeTree::dispatch(NodeHandle node)
+{
+    const auto* slot = node_slot(node);
+    if (slot == nullptr) {
+        return pp::foundation::Status::invalid_argument("UI dispatch requires a live node");
+    }
+
+    const auto connections = slot->connections;
+    for (const auto connection : connections) {
+        if (node_slot(node) == nullptr) {
+            break;
+        }
+
+        auto* connection_value = connection_slot(connection);
+        if (connection_value == nullptr || connection_value->node != node) {
+            continue;
+        }
+
+        connection_value->callback(node);
+    }
+
+    return pp::foundation::Status::success();
+}
+
+NodeLifetimeTree::NodeSlot* NodeLifetimeTree::node_slot(NodeHandle node) noexcept
+{
+    if (!node.valid() || node.slot >= nodes_.size()) {
+        return nullptr;
+    }
+
+    auto& slot = nodes_[node.slot];
+    if (!slot.alive || slot.generation != node.generation) {
+        return nullptr;
+    }
+
+    return &slot;
+}
+
+const NodeLifetimeTree::NodeSlot* NodeLifetimeTree::node_slot(NodeHandle node) const noexcept
+{
+    if (!node.valid() || node.slot >= nodes_.size()) {
+        return nullptr;
+    }
+
+    const auto& slot = nodes_[node.slot];
+    if (!slot.alive || slot.generation != node.generation) {
+        return nullptr;
+    }
+
+    return &slot;
+}
+
+NodeLifetimeTree::ConnectionSlot* NodeLifetimeTree::connection_slot(UiConnection connection) noexcept
+{
+    if (!connection.valid() || connection.slot >= connections_.size()) {
+        return nullptr;
+    }
+
+    auto& slot = connections_[connection.slot];
+    if (!slot.alive || slot.generation != connection.generation) {
+        return nullptr;
+    }
+
+    return &slot;
+}
+
+const NodeLifetimeTree::ConnectionSlot* NodeLifetimeTree::connection_slot(UiConnection connection) const noexcept
+{
+    if (!connection.valid() || connection.slot >= connections_.size()) {
+        return nullptr;
+    }
+
+    const auto& slot = connections_[connection.slot];
+    if (!slot.alive || slot.generation != connection.generation) {
+        return nullptr;
+    }
+
+    return &slot;
+}
+
+pp::foundation::Result<NodeHandle> NodeLifetimeTree::allocate_node(NodeHandle parent)
+{
+    NodeHandle node;
+    if (!free_nodes_.empty()) {
+        node.slot = free_nodes_.back();
+        free_nodes_.pop_back();
+        auto& slot = nodes_[node.slot];
+        bump_generation(slot.generation);
+        slot.alive = true;
+        slot.parent = parent;
+        slot.children.clear();
+        slot.connections.clear();
+        node.generation = slot.generation;
+    } else {
+        node.slot = static_cast<std::uint32_t>(nodes_.size());
+        node.generation = 1U;
+        nodes_.push_back(NodeSlot {
+            .generation = node.generation,
+            .alive = true,
+            .parent = parent,
+            .children = {},
+            .connections = {},
+        });
+    }
+
+    return pp::foundation::Result<NodeHandle>::success(node);
+}
+
+void NodeLifetimeTree::unlink_from_parent(NodeHandle node) noexcept
+{
+    const auto* slot = node_slot(node);
+    if (slot == nullptr || !slot->parent.valid()) {
+        return;
+    }
+
+    auto* parent = node_slot(slot->parent);
+    if (parent == nullptr) {
+        return;
+    }
+
+    parent->children.erase(
+        std::remove(parent->children.begin(), parent->children.end(), node),
+        parent->children.end());
+}
+
+void NodeLifetimeTree::release_connection(UiConnection connection) noexcept
+{
+    auto* slot = connection_slot(connection);
+    if (slot == nullptr) {
+        return;
+    }
+
+    auto* node = node_slot(slot->node);
+    if (node != nullptr) {
+        node->connections.erase(
+            std::remove(node->connections.begin(), node->connections.end(), connection),
+            node->connections.end());
+    }
+
+    slot->alive = false;
+    slot->node = {};
+    slot->callback = nullptr;
+    free_connections_.push_back(connection.slot);
+}
+
+}

src/ui_core/node_lifetime.h

@@ -0,0 +1,127 @@
+#pragma once
+
+#include "foundation/result.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <vector>
+
+namespace pp::ui {
+
+inline constexpr std::uint32_t invalid_node_slot = 0xffffffffU;
+inline constexpr std::uint32_t invalid_connection_slot = 0xffffffffU;
+
+struct NodeHandle {
+    std::uint32_t slot = invalid_node_slot;
+    std::uint32_t generation = 0;
+
+    [[nodiscard]] constexpr bool valid() const noexcept
+    {
+        return slot != invalid_node_slot && generation != 0U;
+    }
+};
+
+[[nodiscard]] constexpr bool operator==(NodeHandle left, NodeHandle right) noexcept
+{
+    return left.slot == right.slot && left.generation == right.generation;
+}
+
+[[nodiscard]] constexpr bool operator!=(NodeHandle left, NodeHandle right) noexcept
+{
+    return !(left == right);
+}
+
+struct UiConnection {
+    std::uint32_t slot = invalid_connection_slot;
+    std::uint32_t generation = 0;
+
+    [[nodiscard]] constexpr bool valid() const noexcept
+    {
+        return slot != invalid_connection_slot && generation != 0U;
+    }
+};
+
+[[nodiscard]] constexpr bool operator==(UiConnection left, UiConnection right) noexcept
+{
+    return left.slot == right.slot && left.generation == right.generation;
+}
+
+[[nodiscard]] constexpr bool operator!=(UiConnection left, UiConnection right) noexcept
+{
+    return !(left == right);
+}
+
+class NodeLifetimeTree;
+
+class ScopedUiConnection {
+public:
+    ScopedUiConnection() noexcept = default;
+    ScopedUiConnection(NodeLifetimeTree& tree, UiConnection connection) noexcept;
+    ScopedUiConnection(const ScopedUiConnection&) = delete;
+    ScopedUiConnection& operator=(const ScopedUiConnection&) = delete;
+    ScopedUiConnection(ScopedUiConnection&& other) noexcept;
+    ScopedUiConnection& operator=(ScopedUiConnection&& other) noexcept;
+    ~ScopedUiConnection();
+
+    void reset() noexcept;
+
+    [[nodiscard]] UiConnection connection() const noexcept;
+    [[nodiscard]] bool connected() const noexcept;
+
+private:
+    NodeLifetimeTree* tree_ = nullptr;
+    UiConnection connection_ {};
+};
+
+class NodeLifetimeTree {
+public:
+    using Callback = std::function<void(NodeHandle)>;
+
+    [[nodiscard]] pp::foundation::Result<NodeHandle> create_root();
+    [[nodiscard]] pp::foundation::Result<NodeHandle> create_child(NodeHandle parent);
+
+    [[nodiscard]] bool contains(NodeHandle node) const noexcept;
+    [[nodiscard]] pp::foundation::Result<NodeHandle> parent_of(NodeHandle node) const noexcept;
+    [[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;
+
+    [[nodiscard]] pp::foundation::Result<UiConnection> connect(NodeHandle node, Callback callback);
+    [[nodiscard]] pp::foundation::Result<ScopedUiConnection> scoped_connect(NodeHandle node, Callback callback);
+    [[nodiscard]] pp::foundation::Status disconnect(UiConnection connection) noexcept;
+    [[nodiscard]] pp::foundation::Result<std::size_t> live_connection_count(NodeHandle node) const noexcept;
+    [[nodiscard]] pp::foundation::Status dispatch(NodeHandle node);
+
+private:
+    struct NodeSlot {
+        std::uint32_t generation = 1;
+        bool alive = false;
+        NodeHandle parent {};
+        std::vector<NodeHandle> children;
+        std::vector<UiConnection> connections;
+    };
+
+    struct ConnectionSlot {
+        std::uint32_t generation = 1;
+        bool alive = false;
+        NodeHandle node {};
+        Callback callback;
+    };
+
+    [[nodiscard]] NodeSlot* node_slot(NodeHandle node) noexcept;
+    [[nodiscard]] const NodeSlot* node_slot(NodeHandle node) const noexcept;
+    [[nodiscard]] ConnectionSlot* connection_slot(UiConnection connection) noexcept;
+    [[nodiscard]] const ConnectionSlot* connection_slot(UiConnection connection) const noexcept;
+
+    [[nodiscard]] pp::foundation::Result<NodeHandle> allocate_node(NodeHandle parent);
+    void unlink_from_parent(NodeHandle node) noexcept;
+    void release_connection(UiConnection connection) noexcept;
+
+    std::vector<NodeSlot> nodes_;
+    std::vector<std::uint32_t> free_nodes_;
+    std::vector<ConnectionSlot> connections_;
+    std::vector<std::uint32_t> free_connections_;
+};
+
+}

tests/CMakeLists.txt

@@ -300,6 +300,16 @@ add_test(NAME pp_ui_core_layout_xml_tests COMMAND pp_ui_core_layout_xml_tests)
 set_tests_properties(pp_ui_core_layout_xml_tests PROPERTIES
     LABELS "ui;desktop-fast;fuzz")
 
+add_executable(pp_ui_core_node_lifetime_tests
+    ui_core/node_lifetime_tests.cpp)
+target_link_libraries(pp_ui_core_node_lifetime_tests PRIVATE
+    pp_ui_core
+    pp_test_harness)
+
+add_test(NAME pp_ui_core_node_lifetime_tests COMMAND pp_ui_core_node_lifetime_tests)
+set_tests_properties(pp_ui_core_node_lifetime_tests PROPERTIES
+    LABELS "ui;desktop-fast")
+
 add_executable(pp_app_core_about_menu_tests
     app_core/about_menu_tests.cpp)
 target_link_libraries(pp_app_core_about_menu_tests PRIVATE

tests/ui_core/node_lifetime_tests.cpp

@@ -0,0 +1,225 @@
+#include "ui_core/node_lifetime.h"
+#include "test_harness.h"
+
+using pp::foundation::StatusCode;
+using pp::ui::NodeLifetimeTree;
+
+namespace {
+
+void creates_parent_child_handles(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.contains(root.value()));
+    PP_EXPECT(h, tree.contains(child.value()));
+
+    const auto parent = tree.parent_of(child.value());
+    PP_EXPECT(h, parent);
+    if (parent) {
+        PP_EXPECT(h, parent.value() == root.value());
+    }
+
+    const auto count = tree.child_count(root.value());
+    PP_EXPECT(h, count);
+    if (count) {
+        PP_EXPECT(h, count.value() == 1U);
+    }
+
+    const auto first_child = tree.child_at(root.value(), 0);
+    PP_EXPECT(h, first_child);
+    if (first_child) {
+        PP_EXPECT(h, first_child.value() == child.value());
+    }
+}
+
+void rejects_invalid_parent_and_child_lookup(pp::tests::Harness& h)
+{
+    NodeLifetimeTree tree;
+    const auto invalid_child = tree.create_child({});
+    PP_EXPECT(h, !invalid_child.ok());
+    PP_EXPECT(h, invalid_child.status().code == StatusCode::invalid_argument);
+
+    const auto root = tree.create_root();
+    PP_EXPECT(h, root);
+    if (!root) {
+        return;
+    }
+
+    const auto root_parent = tree.parent_of(root.value());
+    const auto missing_child = tree.child_at(root.value(), 2);
+    PP_EXPECT(h, !root_parent.ok());
+    PP_EXPECT(h, root_parent.status().code == StatusCode::invalid_argument);
+    PP_EXPECT(h, !missing_child.ok());
+    PP_EXPECT(h, missing_child.status().code == StatusCode::out_of_range);
+}
+
+void invalidates_destroyed_subtree_handles(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;
+    }
+
+    const auto status = tree.destroy_subtree(root.value());
+    PP_EXPECT(h, status.ok());
+    PP_EXPECT(h, !tree.contains(root.value()));
+    PP_EXPECT(h, !tree.contains(child.value()));
+
+    const auto reused = tree.create_root();
+    PP_EXPECT(h, reused);
+    if (reused) {
+        PP_EXPECT(h, reused.value().slot == root.value().slot);
+        PP_EXPECT(h, reused.value().generation != root.value().generation);
+        PP_EXPECT(h, tree.contains(reused.value()));
+        PP_EXPECT(h, !tree.contains(root.value()));
+    }
+}
+
+void scoped_connections_disconnect_on_reset(pp::tests::Harness& h)
+{
+    NodeLifetimeTree tree;
+    const auto root = tree.create_root();
+    PP_EXPECT(h, root);
+    if (!root) {
+        return;
+    }
+
+    int call_count = 0;
+    auto scoped = tree.scoped_connect(root.value(), [&call_count](pp::ui::NodeHandle) {
+        ++call_count;
+    });
+    PP_EXPECT(h, scoped);
+    if (!scoped) {
+        return;
+    }
+
+    PP_EXPECT(h, scoped.value().connected());
+    PP_EXPECT(h, tree.dispatch(root.value()).ok());
+    PP_EXPECT(h, call_count == 1);
+
+    scoped.value().reset();
+    PP_EXPECT(h, !scoped.value().connected());
+    PP_EXPECT(h, tree.dispatch(root.value()).ok());
+    PP_EXPECT(h, call_count == 1);
+}
+
+void destroying_node_disconnects_callbacks(pp::tests::Harness& h)
+{
+    NodeLifetimeTree tree;
+    const auto root = tree.create_root();
+    PP_EXPECT(h, root);
+    if (!root) {
+        return;
+    }
+
+    int call_count = 0;
+    const auto connection = tree.connect(root.value(), [&call_count](pp::ui::NodeHandle) {
+        ++call_count;
+    });
+    PP_EXPECT(h, connection);
+    if (!connection) {
+        return;
+    }
+
+    const auto live_count = tree.live_connection_count(root.value());
+    PP_EXPECT(h, live_count);
+    if (live_count) {
+        PP_EXPECT(h, live_count.value() == 1U);
+    }
+
+    PP_EXPECT(h, tree.destroy_subtree(root.value()).ok());
+    PP_EXPECT(h, !tree.disconnect(connection.value()).ok());
+}
+
+void dispatch_survives_destroy_during_callback(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 first_count = 0;
+    int second_count = 0;
+    PP_EXPECT(h, tree.connect(child.value(), [&tree, &first_count](pp::ui::NodeHandle node) {
+        ++first_count;
+        (void)tree.destroy_subtree(node);
+    }));
+    PP_EXPECT(h, tree.connect(child.value(), [&second_count](pp::ui::NodeHandle) {
+        ++second_count;
+    }));
+
+    const auto dispatch = tree.dispatch(child.value());
+    PP_EXPECT(h, dispatch.ok());
+    PP_EXPECT(h, first_count == 1);
+    PP_EXPECT(h, second_count == 0);
+    PP_EXPECT(h, !tree.contains(child.value()));
+}
+
+void dispatch_uses_stable_connection_snapshot(pp::tests::Harness& h)
+{
+    NodeLifetimeTree tree;
+    const auto root = tree.create_root();
+    PP_EXPECT(h, root);
+    if (!root) {
+        return;
+    }
+
+    int first_count = 0;
+    int second_count = 0;
+    PP_EXPECT(h, tree.connect(root.value(), [&tree, &root, &first_count, &second_count](pp::ui::NodeHandle) {
+        ++first_count;
+        (void)tree.connect(root.value(), [&second_count](pp::ui::NodeHandle) {
+            ++second_count;
+        });
+    }));
+
+    PP_EXPECT(h, tree.dispatch(root.value()).ok());
+    PP_EXPECT(h, first_count == 1);
+    PP_EXPECT(h, second_count == 0);
+
+    PP_EXPECT(h, tree.dispatch(root.value()).ok());
+    PP_EXPECT(h, first_count == 2);
+    PP_EXPECT(h, second_count == 1);
+}
+
+}
+
+int main()
+{
+    pp::tests::Harness harness;
+    harness.run("creates_parent_child_handles", creates_parent_child_handles);
+    harness.run("rejects_invalid_parent_and_child_lookup", rejects_invalid_parent_and_child_lookup);
+    harness.run("invalidates_destroyed_subtree_handles", invalidates_destroyed_subtree_handles);
+    harness.run("scoped_connections_disconnect_on_reset", scoped_connections_disconnect_on_reset);
+    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);
+    return harness.finish();
+}