Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

31.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
#include "../ecs/TransformSystem.hpp"
#include "./UILayoutSystem.hpp"
#include "./UISystem.hpp"

#include "../ecs/components/Transform.hpp"
#include "../ecs/components/Canvas.hpp"
#include "../ecs/components/FlexContainer.hpp"
#include "../ecs/components/Hierarchy.hpp"
#include "../ecs/components/UINode.hpp"   // UINode + AlignSelf

#include <yoga/Yoga.h>
#include <unordered_map>
#include <unordered_set>
#include <vector>
#include <algorithm>

namespace esengine::ecs {

// Reused across frames so the per-frame inherited walk allocates nothing.
static std::vector<f32> inherited_alpha_stack_;
static std::vector<u8> inherited_block_stack_;

// Retained Yoga node cache: one YGNode per UI entity, kept alive across frames.
// A stable UI tree reuses its allocations instead of YGNodeNew/FreeRecursive
// every solve; entities that leave the tree are reaped. The hierarchy + style
// are still rebuilt each frame here (Stage 1) — dirty-gating that avoids the
// rebuild/solve when nothing changed is layered on top separately.
struct LayoutCache {
    std::unordered_map<Entity, YGNodeRef> nodes;

    ~LayoutCache() {
        for (auto& [entity, node] : nodes) YGNodeFree(node);
    }

    YGNodeRef getOrCreate(Entity entity) {
        auto it = nodes.find(entity);
        if (it != nodes.end()) return it->second;
        YGNodeRef node = YGNodeNew();
        nodes.emplace(entity, node);
        return node;
    }

    // Free the YGNodes of entities no longer in the tree. YGNodeFree disconnects
    // each from its owner/children, so order is irrelevant (live nodes hold only
    // live children after the pass, so none point at a reaped node).
    void reap(const std::unordered_set<Entity>& live) {
        for (auto it = nodes.begin(); it != nodes.end();) {
            if (live.find(it->first) == live.end()) {
                YGNodeFree(it->second);
                it = nodes.erase(it);
            } else {
                ++it;
            }
        }
    }
};

namespace {

// =============================================================================
// Flex enum → Yoga mappers (shared by the UINode container + item styling)
// =============================================================================

YGFlexDirection toYGFlexDirection(FlexDirection dir) {
    switch (dir) {
        case FlexDirection::Row:            return YGFlexDirectionRow;
        case FlexDirection::Column:         return YGFlexDirectionColumn;
        case FlexDirection::RowReverse:     return YGFlexDirectionRowReverse;
        case FlexDirection::ColumnReverse:  return YGFlexDirectionColumnReverse;
    }
    return YGFlexDirectionRow;
}

YGWrap toYGWrap(FlexWrap wrap) {
    switch (wrap) {
        case FlexWrap::NoWrap: return YGWrapNoWrap;
        case FlexWrap::Wrap:   return YGWrapWrap;
    }
    return YGWrapNoWrap;
}

YGJustify toYGJustify(JustifyContent jc) {
    switch (jc) {
        case JustifyContent::Start:        return YGJustifyFlexStart;
        case JustifyContent::Center:       return YGJustifyCenter;
        case JustifyContent::End:          return YGJustifyFlexEnd;
        case JustifyContent::SpaceBetween: return YGJustifySpaceBetween;
        case JustifyContent::SpaceAround:  return YGJustifySpaceAround;
        case JustifyContent::SpaceEvenly:  return YGJustifySpaceEvenly;
    }
    return YGJustifyFlexStart;
}

YGAlign toYGAlign(AlignItems ai) {
    switch (ai) {
        case AlignItems::Start:   return YGAlignFlexStart;
        case AlignItems::Center:  return YGAlignCenter;
        case AlignItems::End:     return YGAlignFlexEnd;
        case AlignItems::Stretch: return YGAlignStretch;
    }
    return YGAlignStretch;
}

YGAlign toYGAlignContent(AlignContent ac) {
    switch (ac) {
        case AlignContent::Start:        return YGAlignFlexStart;
        case AlignContent::Center:       return YGAlignCenter;
        case AlignContent::End:          return YGAlignFlexEnd;
        case AlignContent::Stretch:      return YGAlignStretch;
        case AlignContent::SpaceBetween: return YGAlignSpaceBetween;
        case AlignContent::SpaceAround:  return YGAlignSpaceAround;
    }
    return YGAlignFlexStart;
}

YGAlign toYGAlignSelf(AlignSelf as) {
    switch (as) {
        case AlignSelf::Auto:    return YGAlignAuto;
        case AlignSelf::Start:   return YGAlignFlexStart;
        case AlignSelf::Center:  return YGAlignCenter;
        case AlignSelf::End:     return YGAlignFlexEnd;
        case AlignSelf::Stretch: return YGAlignStretch;
    }
    return YGAlignAuto;
}

// =============================================================================
// UINode (CSS box) → single-pass Yoga (the single layout model)
// =============================================================================
//
// A UINode subtree is laid out by ONE Yoga solve: each entity becomes a YGNode,
// the hierarchy is mirrored, the root is sized to its available box, and one
// YGNodeCalculateLayout resolves the whole subtree. Output is written as the
// engine's center-based, y-up local Transform (implicit pivot 0.5, matching
// UIElementPlugin) plus UINode.computed_size_ (read by the renderer/hit-test).

// Dimension.unit codes — mirror the TS DimensionUnit enum.
constexpr u8 DIM_PX = 0, DIM_PERCENT = 1, DIM_AUTO = 2;

void applyWidth(YGNodeRef n, const Dimension& d) {
    if (d.unit == DIM_PERCENT) YGNodeStyleSetWidthPercent(n, d.value);
    else if (d.unit == DIM_AUTO) YGNodeStyleSetWidthAuto(n);
    else YGNodeStyleSetWidth(n, d.value);
}
void applyHeight(YGNodeRef n, const Dimension& d) {
    if (d.unit == DIM_PERCENT) YGNodeStyleSetHeightPercent(n, d.value);
    else if (d.unit == DIM_AUTO) YGNodeStyleSetHeightAuto(n);
    else YGNodeStyleSetHeight(n, d.value);
}
// min/max have no Yoga "auto"; Auto means "no constraint" → leave unset.
void applyMinWidth(YGNodeRef n, const Dimension& d) {
    if (d.unit == DIM_PERCENT) YGNodeStyleSetMinWidthPercent(n, d.value);
    else if (d.unit == DIM_PX) YGNodeStyleSetMinWidth(n, d.value);
}
void applyMinHeight(YGNodeRef n, const Dimension& d) {
    if (d.unit == DIM_PERCENT) YGNodeStyleSetMinHeightPercent(n, d.value);
    else if (d.unit == DIM_PX) YGNodeStyleSetMinHeight(n, d.value);
}
void applyMaxWidth(YGNodeRef n, const Dimension& d) {
    if (d.unit == DIM_PERCENT) YGNodeStyleSetMaxWidthPercent(n, d.value);
    else if (d.unit == DIM_PX) YGNodeStyleSetMaxWidth(n, d.value);
}
void applyMaxHeight(YGNodeRef n, const Dimension& d) {
    if (d.unit == DIM_PERCENT) YGNodeStyleSetMaxHeightPercent(n, d.value);
    else if (d.unit == DIM_PX) YGNodeStyleSetMaxHeight(n, d.value);
}
void applyFlexBasis(YGNodeRef n, const Dimension& d) {
    if (d.unit == DIM_PERCENT) YGNodeStyleSetFlexBasisPercent(n, d.value);
    else if (d.unit == DIM_AUTO) YGNodeStyleSetFlexBasisAuto(n);
    else YGNodeStyleSetFlexBasis(n, d.value);
}
void applyMargin(YGNodeRef n, YGEdge edge, const Dimension& d) {
    if (d.unit == DIM_PERCENT) YGNodeStyleSetMarginPercent(n, edge, d.value);
    else if (d.unit == DIM_AUTO) YGNodeStyleSetMarginAuto(n, edge);
    else YGNodeStyleSetMargin(n, edge, d.value);
}
void applyInset(YGNodeRef n, YGEdge edge, const Dimension& d) {
    // Auto = that edge is unconstrained; leave it unset so size/flow decides.
    if (d.unit == DIM_PERCENT) YGNodeStyleSetPositionPercent(n, edge, d.value);
    else if (d.unit == DIM_PX) YGNodeStyleSetPosition(n, edge, d.value);
}

void applyUINodeStyle(Registry& registry, Entity entity, YGNodeRef yg) {
    auto& n = registry.get<UINode>(entity);
    YGNodeStyleSetDisplay(yg, n.display == UIDisplay::None
        ? YGDisplayNone : YGDisplayFlex);
    YGNodeStyleSetPositionType(yg, n.position == UIPositionType::Absolute
        ? YGPositionTypeAbsolute : YGPositionTypeRelative);
    applyInset(yg, YGEdgeLeft, n.insetLeft);
    applyInset(yg, YGEdgeTop, n.insetTop);
    applyInset(yg, YGEdgeRight, n.insetRight);
    applyInset(yg, YGEdgeBottom, n.insetBottom);
    applyWidth(yg, n.width);
    applyHeight(yg, n.height);
    applyMinWidth(yg, n.minWidth);
    applyMinHeight(yg, n.minHeight);
    applyMaxWidth(yg, n.maxWidth);
    applyMaxHeight(yg, n.maxHeight);
    YGNodeStyleSetFlexGrow(yg, n.flexGrow);
    YGNodeStyleSetFlexShrink(yg, n.flexShrink);
    applyFlexBasis(yg, n.flexBasis);
    YGNodeStyleSetAlignSelf(yg, toYGAlignSelf(n.alignSelf));
    applyMargin(yg, YGEdgeLeft, n.marginLeft);
    applyMargin(yg, YGEdgeTop, n.marginTop);
    applyMargin(yg, YGEdgeRight, n.marginRight);
    applyMargin(yg, YGEdgeBottom, n.marginBottom);

    // Container properties still come from FlexContainer (folded into UILayout in F4).
    //
    // The absent case is written out rather than skipped: this runs against a
    // node that KEEPS its style between frames, so "no FlexContainer" has to
    // actively say Yoga's defaults. Leaving them alone would let a removed
    // FlexContainer's padding and justify go on laying the node out forever —
    // the one thing a total style application must not do.
    if (auto* fc = registry.tryGet<FlexContainer>(entity)) {
        YGNodeStyleSetFlexDirection(yg, toYGFlexDirection(fc->direction));
        YGNodeStyleSetFlexWrap(yg, toYGWrap(fc->wrap));
        YGNodeStyleSetJustifyContent(yg, toYGJustify(fc->justifyContent));
        YGNodeStyleSetAlignItems(yg, toYGAlign(fc->alignItems));
        YGNodeStyleSetAlignContent(yg, toYGAlignContent(fc->alignContent));
        YGNodeStyleSetGap(yg, YGGutterColumn, fc->gap.x);
        YGNodeStyleSetGap(yg, YGGutterRow, fc->gap.y);
        YGNodeStyleSetPadding(yg, YGEdgeLeft, fc->padding.left);
        YGNodeStyleSetPadding(yg, YGEdgeTop, fc->padding.top);
        YGNodeStyleSetPadding(yg, YGEdgeRight, fc->padding.right);
        YGNodeStyleSetPadding(yg, YGEdgeBottom, fc->padding.bottom);
    } else {
        YGNodeStyleSetFlexDirection(yg, YGFlexDirectionColumn);
        YGNodeStyleSetFlexWrap(yg, YGWrapNoWrap);
        YGNodeStyleSetJustifyContent(yg, YGJustifyFlexStart);
        YGNodeStyleSetAlignItems(yg, YGAlignStretch);
        YGNodeStyleSetAlignContent(yg, YGAlignFlexStart);
        YGNodeStyleSetGap(yg, YGGutterColumn, 0.0f);
        YGNodeStyleSetGap(yg, YGGutterRow, 0.0f);
        YGNodeStyleSetPadding(yg, YGEdgeLeft, 0.0f);
        YGNodeStyleSetPadding(yg, YGEdgeTop, 0.0f);
        YGNodeStyleSetPadding(yg, YGEdgeRight, 0.0f);
        YGNodeStyleSetPadding(yg, YGEdgeBottom, 0.0f);
    }
}

// Lay out the UINode subtree rooted at tree index `rootIdx` in one Yoga solve.
// `availW/H` + `parentPivot*` describe the available box the root sits in.
void layoutUINodeSubtree(
    Registry& registry, UITree& tree, LayoutCache& cache, i32 rootIdx,
    f32 availW, f32 availH, f32 parentPivotX, f32 parentPivotY,
    bool structureChanged, bool forceWriteback
) {
    i32 begin = rootIdx;
    i32 end = rootIdx + tree.nodes_[rootIdx].subtree_size;

    std::vector<YGNodeRef> yg(static_cast<usize>(end - begin), nullptr);
    std::unordered_map<Entity, i32> slotOf;  // entity → local slot index
    // The retained YGNode KEEPS its style between frames, and re-applying it is
    // how Yoga is told what moved: every YGNodeStyleSet* is `if (old != new)
    // { set; markDirtyAndPropagate(); }`, so a field that did not change costs
    // one comparison and dirties nothing. Resetting first (as this used to) made
    // every field look changed, which dirtied every node and threw away the
    // incremental solve the retained nodes exist for.
    for (i32 k = begin; k < end; ++k) {
        Entity e = tree.nodes_[k].entity;
        if (!registry.has<UINode>(e)) continue;  // tree is homogeneously UINode
        YGNodeRef node = cache.getOrCreate(e);
        applyUINodeStyle(registry, e, node);
        yg[static_cast<usize>(k - begin)] = node;
        slotOf[e] = k - begin;
    }
    YGNodeRef rootYG = yg[0];
    if (!rootYG) return;

    // Parenting is rebuilt only when the tree's shape actually changed. Yoga's
    // own child list is the retained hierarchy the rest of the time — and
    // re-inserting an unchanged child would dirty it for nothing.
    if (structureChanged) {
        for (i32 k = begin; k < end; ++k) {
            YGNodeRef node = yg[static_cast<usize>(k - begin)];
            if (node) YGNodeRemoveAllChildren(node);
        }
        for (i32 k = begin + 1; k < end; ++k) {
            YGNodeRef child = yg[static_cast<usize>(k - begin)];
            if (!child) continue;
            auto it = slotOf.find(tree.nodes_[k].parent);
            if (it == slotOf.end()) continue;
            YGNodeRef parentYG = yg[static_cast<usize>(it->second)];
            YGNodeInsertChild(parentYG, child, YGNodeGetChildCount(parentYG));
        }
    }

    // The root fills the available box on axes it leaves auto.
    auto& rootNode = registry.get<UINode>(tree.nodes_[begin].entity);
    if (rootNode.width.unit == DIM_AUTO) YGNodeStyleSetWidth(rootYG, availW);
    if (rootNode.height.unit == DIM_AUTO) YGNodeStyleSetHeight(rootYG, availH);

    YGNodeCalculateLayout(rootYG, availW, availH, YGDirectionLTR);

    // Which nodes' own box changed, by local slot. A node whose PARENT resized
    // has to be written even when Yoga left its own box alone: the local
    // position below is expressed against the parent's computed size, so the
    // same Yoga offset inside a resized parent is a different world position.
    // DFS order guarantees a parent's entry is filled before its children read it.
    std::vector<u8> resized(static_cast<usize>(end - begin), 0);

    for (i32 k = begin; k < end; ++k) {
        YGNodeRef node = yg[static_cast<usize>(k - begin)];
        if (!node) continue;
        Entity e = tree.nodes_[k].entity;

        bool parentResized = false;
        if (k != begin) {
            auto it = slotOf.find(tree.nodes_[k].parent);
            if (it != slotOf.end()) parentResized = resized[static_cast<usize>(it->second)] != 0;
        }
        // Yoga tells us what it recomputed; everything else still holds the
        // output of the last solve, which is still correct.
        if (!forceWriteback && !YGNodeGetHasNewLayout(node) && !parentResized) continue;
        YGNodeSetHasNewLayout(node, false);

        auto& un = registry.get<UINode>(e);
        f32 fw = YGNodeLayoutGetWidth(node);
        f32 fh = YGNodeLayoutGetHeight(node);
        resized[static_cast<usize>(k - begin)] =
            (un.computed_size_.x != fw || un.computed_size_.y != fh) ? 1 : 0;
        un.computed_size_.x = fw;
        un.computed_size_.y = fh;

        // Position frame = the parent box (root's available box, else the parent
        // UINode whose computed_size_ is already set — DFS order guarantees it).
        f32 pw, ph, ppx, ppy;
        if (k == begin) {
            pw = availW; ph = availH; ppx = parentPivotX; ppy = parentPivotY;
        } else {
            auto& pn = registry.get<UINode>(tree.nodes_[k].parent);
            pw = pn.computed_size_.x; ph = pn.computed_size_.y; ppx = 0.5f; ppy = 0.5f;
        }
        f32 yl = YGNodeLayoutGetLeft(node);
        f32 yt = YGNodeLayoutGetTop(node);

        // An absolute child centres an axis when both its insets AND both its
        // margins on that axis are `auto`. A pivot-less CSS box can't otherwise
        // centre an out-of-flow node: Yoga's abspos centring keys off the
        // parent's justifyContent, so it can't differ per sibling under one
        // Canvas. Overriding the Yoga offset makes centring a self-contained
        // per-node anchor, independent of the parent and of which axis is main.
        if (k != begin && un.position == UIPositionType::Absolute) {
            auto axisCentred = [](const Dimension& a, const Dimension& b,
                                  const Dimension& m0, const Dimension& m1) {
                return a.unit == DIM_AUTO && b.unit == DIM_AUTO &&
                       m0.unit == DIM_AUTO && m1.unit == DIM_AUTO;
            };
            if (axisCentred(un.insetLeft, un.insetRight, un.marginLeft, un.marginRight))
                yl = 0.5f * (pw - fw);
            if (axisCentred(un.insetTop, un.insetBottom, un.marginTop, un.marginBottom))
                yt = 0.5f * (ph - fh);
        }

        // Center-based, y-up local position (implicit pivot 0.5).
        f32 localX = -ppx * pw + yl + 0.5f * fw;
        f32 localY = (1.0f - ppy) * ph - yt - 0.5f * fh;

        if (auto* t = registry.tryGet<Transform>(e)) {
            // Leave tween-driven position axes alone (see TweenSystem anim_override_).
            if (!(un.anim_override_ & UINode::ANIM_POS_X)) t->position.x = localX;
            if (!(un.anim_override_ & UINode::ANIM_POS_Y)) t->position.y = localY;
        }
    }

    // Retained nodes are not freed here — layoutUpdate reaps entities that left
    // the tree and the LayoutCache frees the rest on teardown.
}

// Resolve display:none hierarchically over the DFS-ordered tree: a node with
// display None hides its whole subtree. Rendering, text and hit-testing read
// the resulting UINode.hidden_in_tree_ bit so they never need tree knowledge.
void propagateHiddenInTree(Registry& registry, UITree& tree) {
    auto& nodes = tree.nodes_;
    for (i32 i = 0; i < static_cast<i32>(nodes.size()); ) {
        auto* n = registry.tryGet<UINode>(nodes[i].entity);
        if (n && n->display == UIDisplay::None) {
            i32 end = i + nodes[i].subtree_size;
            for (i32 k = i; k < end; ++k) {
                if (auto* c = registry.tryGet<UINode>(nodes[k].entity)) c->hidden_in_tree_ = true;
            }
            i = end;
        } else {
            if (n) n->hidden_in_tree_ = false;
            ++i;
        }
    }
}

// Resolve opacity and pointer-events hierarchically over the same DFS-ordered
// tree: opacity multiplies down (CSS `opacity`), pointer-events latches off
// (CSS `pointer-events: none` on an ancestor is not overridable by a child).
// Rendering and hit-testing read the resulting UINode bits, so neither needs
// tree knowledge — the contract propagateHiddenInTree already established.
//
// `depth` is monotonic in DFS order, so one running stack indexed by depth
// carries each node's inherited value to its children without a second walk.
void propagateInheritedUIState(Registry& registry, UITree& tree) {
    auto& nodes = tree.nodes_;
    if (nodes.empty()) return;

    inherited_alpha_stack_.assign(nodes.size() + 1, 1.0f);
    inherited_block_stack_.assign(nodes.size() + 1, static_cast<u8>(0));

    for (usize i = 0; i < nodes.size(); ++i) {
        const u32 depth = nodes[i].depth;
        const f32 parentAlpha = depth == 0 ? 1.0f : inherited_alpha_stack_[depth - 1];
        const bool parentBlocked = depth == 0 ? false : inherited_block_stack_[depth - 1] != 0;

        auto* n = registry.tryGet<UINode>(nodes[i].entity);
        if (!n) {
            inherited_alpha_stack_[depth] = parentAlpha;
            inherited_block_stack_[depth] = static_cast<u8>(parentBlocked);
            continue;
        }
        const f32 alpha = parentAlpha * std::clamp(n->opacity, 0.0f, 1.0f);
        const bool blocked = n->pointerEvents == UIPointerEvents::None
            || (parentBlocked && n->pointerEvents != UIPointerEvents::Receive);
        n->alpha_in_tree_ = alpha;
        n->pointer_blocked_in_tree_ = blocked;
        inherited_alpha_stack_[depth] = alpha;
        inherited_block_stack_[depth] = static_cast<u8>(blocked);
    }
}

// A tween drives Transform fields directly in C++ (TweenSystem), invisible to the
// TS change-tracking that feeds tsPropertyDirty. Scan the UINode anim_override_
// bits so the gate keeps solving while any tween is active — and, via the caller's
// lastAnimActive_, once more on the frame a tween ends (override already cleared)
// so layout reclaims the position it had ceded.
bool anyUIAnimActive(Registry& registry) {
    bool active = false;
    registry.eachLive<UINode>([&](Entity, UINode& n) {
        if (n.anim_override_ != 0) active = true;
    });
    return active;
}

/** @brief Whether a subtree root IS the screen: no Transform parent, so the layout
 *         box places it. A parented root rides its parent and the box only sizes it. */
bool isScreenRoot(Registry& registry, Entity e) {
    auto* p = registry.tryGet<Parent>(e);
    return !p || p->entity == INVALID_ENTITY || !registry.valid(p->entity);
}

/** @brief Place every screen root at the box's world center — authoritative for those
 *         roots' position, and idempotent, so a move-only pass may call it alone. */
void placeScreenRoots(Registry& registry, UITree& tree, LayoutCache& cache,
                      const LayoutRect& box) {
    const f32 availW = box.width();
    const f32 availH = box.height();
    const f32 cx = box.centerX();
    const f32 cy = box.centerY();
    for (i32 i = 0; i < static_cast<i32>(tree.nodes_.size()); ) {
        auto& node = tree.nodes_[i];
        bool parentIsUINode = node.parent != INVALID_ENTITY && registry.has<UINode>(node.parent);
        if (!parentIsUINode && isScreenRoot(registry, node.entity)) {
            auto it = cache.nodes.find(node.entity);
            auto* t = registry.tryGet<Transform>(node.entity);
            auto* un = registry.tryGet<UINode>(node.entity);
            if (it != cache.nodes.end() && t && un) {
                const f32 fw = YGNodeLayoutGetWidth(it->second);
                const f32 fh = YGNodeLayoutGetHeight(it->second);
                const f32 localX = -0.5f * availW + YGNodeLayoutGetLeft(it->second) + 0.5f * fw;
                const f32 localY = 0.5f * availH - YGNodeLayoutGetTop(it->second) - 0.5f * fh;
                if (!(un->anim_override_ & UINode::ANIM_POS_X)) t->position.x = cx + localX;
                if (!(un->anim_override_ & UINode::ANIM_POS_Y)) t->position.y = cy + localY;
            }
        }
        i += node.subtree_size;
    }
}

/** @brief Adds @p entity and its whole Transform subtree to @p out. */
void addSubtree(Registry& registry, Entity entity, std::unordered_set<u32>& out) {
    std::vector<Entity> pending{entity};
    while (!pending.empty()) {
        const Entity current = pending.back();
        pending.pop_back();
        if (!registry.valid(current) || !out.insert(current.id()).second) continue;
        auto* children = registry.tryGet<Children>(current);
        if (!children) continue;
        for (Entity child : children->entities) pending.push_back(child);
    }
}

/**
 * @brief Which entities are the screen's rather than the world's.
 *
 * @details Decided at each Canvas and inherited downward, so one subtree has one
 *          answer. Walks the TRANSFORM hierarchy, not the layout tree: a plain
 *          Sprite parented into a HUD is not a layout node, yet its transform
 *          composes from a screen root all the same.
 */
void collectScreenDomain(Registry& registry, std::unordered_set<u32>& out) {
    out.clear();
    registry.each<Canvas>([&](Entity entity, Canvas&) {
        if (!registry.has<UINode>(entity) || !registry.has<Transform>(entity)) return;
        if (!isScreenRoot(registry, entity)) return;
        addSubtree(registry, entity, out);
    });
}

void unifiedLayoutPass(Registry& registry, UITree& tree, LayoutCache& cache,
                       const LayoutRect& box, bool structureChanged,
                       bool forceWriteback) {
    for (i32 i = 0; i < static_cast<i32>(tree.nodes_.size()); ) {
        auto& node = tree.nodes_[i];

        // Every node is a UINode. A subtree root (its parent is not a UINode —
        // a top-level UI element / Canvas) is resolved in one Yoga solve over its
        // whole subtree; skip past it. The available box is the layout box's size;
        // where that box sits is applied by placeScreenRoots.
        bool parentIsUINode = node.parent != INVALID_ENTITY && registry.has<UINode>(node.parent);
        if (!parentIsUINode) {
            layoutUINodeSubtree(registry, tree, cache, i, box.width(), box.height(), 0.5f, 0.5f,
                                structureChanged, forceWriteback);
        }
        i += node.subtree_size;
    }
}

}  // anonymous namespace

// =============================================================================
// UISystem layout entry (defined here to share the anon-namespace helpers)
// =============================================================================

void UISystem::propagateDetachedUIState(Registry& registry) {
    if (++inherited_stamp_ == 0) {
        inherited_cache_.clear();
        ++inherited_stamp_;
    }
    registry.each<UINode>([&](Entity entity, UINode&) {
        inherited_path_.clear();
        InheritedState state;
        Entity current = entity;
        while (registry.valid(current)) {
            auto& memo = inherited_cache_[current];
            if (memo.stamp == inherited_stamp_) {
                state = memo.resolving ? InheritedState{true, 0.0f, true} : memo.state;
                break;
            }
            memo.stamp = inherited_stamp_;
            memo.resolving = true;
            inherited_path_.push_back(current);
            const auto* parent = registry.tryGet<Parent>(current);
            current = parent ? parent->entity : INVALID_ENTITY;
        }
        for (auto it = inherited_path_.rbegin(); it != inherited_path_.rend(); ++it) {
            if (auto* node = registry.tryGet<UINode>(*it)) {
                state.hidden = state.hidden || node->display == UIDisplay::None;
                state.alpha *= std::clamp(node->opacity, 0.0f, 1.0f);
                state.blocked = node->pointerEvents == UIPointerEvents::None
                    || (state.blocked && node->pointerEvents != UIPointerEvents::Receive);
                node->hidden_in_tree_ = state.hidden;
                node->alpha_in_tree_ = state.alpha;
                node->pointer_blocked_in_tree_ = state.blocked;
            }
            auto& memo = inherited_cache_.at(*it);
            memo.state = state;
            memo.resolving = false;
        }
    });
    // Keep live ancestry entries for reuse, but do not retain removed trees.
    for (auto it = inherited_cache_.begin(); it != inherited_cache_.end();) {
        if (it->second.stamp != inherited_stamp_) it = inherited_cache_.erase(it);
        else ++it;
    }
}

void UISystem::layoutUpdate(
    Registry& registry,
    f32 boxLeft, f32 boxBottom, f32 boxRight, f32 boxTop,
    bool tsPropertyDirty
) {
    // The retained nodes are keyed by entity, and entity ids restart with each
    // registry — so a scene reload or an editor play/stop would otherwise hand
    // the new world the previous world's layout. This is only load-bearing now
    // that styles persist between frames: the old pass reset every node it
    // touched, which hid the aliasing by throwing the stale state away.
    if (lastRegistryId_ != registry.instanceId()) {
        layoutCache_.reset();
        inherited_cache_.clear();
    }
    lastRegistryId_ = registry.instanceId();
    if (!layoutCache_) {
        layoutCache_ = std::make_unique<LayoutCache>();
        layoutPrimed_ = false;  // a fresh cache has no hierarchy to reuse
    }

    // Rebuild the DFS node list every pass: it is O(N) pointer-walking (no Yoga)
    // and yields the structure signature that detects spawn/despawn/reparent —
    // the reliable structural signal we don't otherwise have. The expensive part
    // (orphan + propagateHidden + Yoga solve + reap) is what the gate below skips.
    tree.rebuild(registry);
    // Beside the rebuild and never behind the skip gate below: a frame that needs
    // no re-solve can still have reparented something, and a renderer reading a
    // stale set would draw it in the wrong domain rather than in the wrong place.
    collectScreenDomain(registry, screen_domain_);

    // Layout belongs to Canvas; visibility and input inheritance belong to the
    // whole UI hierarchy, including nodes that just left their Canvas.
    const bool detached = registry.view<UINode>().size() != tree.nodes_.size();
    if (detached) propagateDetachedUIState(registry);
    else if (!inherited_cache_.empty()) inherited_cache_.clear();

    LayoutRect box{ boxLeft, boxBottom, boxRight, boxTop };

    bool animNow = anyUIAnimActive(registry);
    bool sigChanged = tree.structure_sig_ != lastSig_;
    // A resized box invalidates the solve; a box that merely MOVED does not —
    // Yoga solves against the size alone, and only the screen roots' world
    // placement depends on where the box sits. Keeping these apart is what stops
    // a panning camera from rewriting the whole UI tree every frame.
    bool sizeChanged = box.width() != lastBoxW_ || box.height() != lastBoxH_;
    bool centerChanged = box.centerX() != lastBoxCX_ || box.centerY() != lastBoxCY_;
    bool wasAnimActive = lastAnimActive_;

    lastSig_ = tree.structure_sig_;
    lastBoxW_ = box.width(); lastBoxH_ = box.height();
    lastBoxCX_ = box.centerX(); lastBoxCY_ = box.centerY();
    lastAnimActive_ = animNow;

    // A fully static frame — no structural, box-size, property, or tween change
    // since the last solve — leaves the retained YGNodes and every UINode's
    // computed output valid, so the whole solve is safely skipped. `wasAnimActive`
    // forces one more solve on the frame a tween just ended (see anyUIAnimActive).
    bool first = !layoutPrimed_;
    bool dirty = first || sigChanged || sizeChanged || tsPropertyDirty
              || animNow || wasAnimActive;
    layoutPrimed_ = true;
    if (!dirty) {
        if (centerChanged) {
            invalidateTransformComposition();
            placeScreenRoots(registry, tree, *layoutCache_, box);
        }
        return;
    }

    // Only a pass that may write local transforms invalidates their composition.
    invalidateTransformComposition();

    // Two signals, because they answer different questions. The hierarchy has to
    // be rebuilt when the tree's SHAPE changed. Output has to be written for
    // every node when the ROOT'S FRAME changed — a subtree root positions itself
    // against the box, so the same Yoga result inside a resized box is a
    // different world position, and Yoga would rightly report no new layout.
    bool structureChanged = first || sigChanged;
    bool forceWriteback = structureChanged || sizeChanged;

    // The retained hierarchy is rebuilt only when the tree's shape changed —
    // which is exactly when an entity may still be owned by the parent it had
    // last frame. Orphaning unconditionally (as this used to) dirtied every
    // Yoga node on every pass, so no solve could ever be partial.
    if (!detached) {
        propagateHiddenInTree(registry, tree);
        propagateInheritedUIState(registry, tree);
    }
    unifiedLayoutPass(registry, tree, *layoutCache_, box, structureChanged, forceWriteback);
    placeScreenRoots(registry, tree, *layoutCache_, box);

    // Reaping is likewise a structural concern: with the same set of entities in
    // the tree there is nothing to free, and building the live set is a hash
    // insert per node.
    if (structureChanged) {
        std::unordered_set<Entity> live;
        live.reserve(tree.nodes_.size());
        for (auto& node : tree.nodes_) live.insert(node.entity);
        layoutCache_->reap(live);
    }
}

// Out-of-line so LayoutCache is complete here (it holds Yoga types kept out of
// the header). Defaulted — the unique_ptr frees the cache, whose destructor
// frees the retained YGNodes.
UISystem::UISystem() = default;
UISystem::~UISystem() = default;


}  // namespace esengine::ecs