feat(context): cache PointerOverIds during SetPointerState

Mirror canonical clay.c's pointerOverIds array so consumers can find
all elements whose bounding box contains the pointer in topmost-first
order (highest-ZIndex root first; within a root, deepest last-child
before ancestors via postorder + forward-child push). Honors floating
Capture mode by short-circuiting lower roots.

Exposes Clay.PointerOverIds (ReadOnlySpan<ElementId>) and
RefreshPointerOverIds() for rebuilding against the current frame's
layout without advancing the pointer state machine — needed because
SetPointerState is called before BeginLayout in typical flow.

Author: andreakarasho

src/Clay/Clay.cs

@@ -164,6 +164,23 @@ public static bool PointerOver(ElementId elementId)
         return _context?.PointerOver(elementId) ?? false;
     }
 
+    /// <summary>
+    /// All element IDs whose bounding box contains the current pointer, ordered
+    /// topmost-first (highest-ZIndex root first; within a root, deepest last-child
+    /// before its ancestors). Empty when no layout has been built.
+    /// Refreshed by <see cref="SetPointerState"/>.
+    /// </summary>
+    public static ReadOnlySpan<ElementId> PointerOverIds
+        => _context is null ? ReadOnlySpan<ElementId>.Empty : _context.PointerOverIds.AsReadOnlySpan();
+
+    /// <summary>
+    /// Rebuilds <see cref="PointerOverIds"/> against the current pointer position
+    /// without advancing pointer state. Call after <see cref="EndLayout"/> if
+    /// hit-testing must reflect the freshly computed layout.
+    /// </summary>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public static void RefreshPointerOverIds() => _context?.RefreshPointerOverIds();
+
     /// <summary>
     /// Gets element data for the element with the given ID.
     /// </summary>

src/Clay/Core/ClayContext.cs

@@ -106,9 +106,16 @@ public class ClayContext : IDisposable
     public ClayList<int> OpenClipElementStack;
     public ClayList<ScrollContainerDataInternal> ScrollContainerDatas;
 
+    // IDs whose bounding box contains the pointer this frame.
+    // Ordered topmost-first: highest-ZIndex root first, and within a root the
+    // deepest last-child appears before its ancestors (postorder + forward-child push).
+    public ClayList<ElementId> PointerOverIds;
+
     // Reusable temporary collections (avoid per-frame allocations)
     private readonly List<int> _bfsQueue = new(256);
     private readonly Dictionary<uint, int> _scrollContainerIndex = new();
+    private ClayList<int> _pointerDfsStack = new(256);
+    private ClayList<bool> _pointerDfsVisited = new(256);
 
     public ClayContext(int maxElementCount = 8192)
     {
@@ -140,6 +147,7 @@ public ClayContext(int maxElementCount = 8192)
         LayoutElementsHashMap = new ClayList<int>(maxElementCount);
         OpenClipElementStack = new ClayList<int>(64);
         ScrollContainerDatas = new ClayList<ScrollContainerDataInternal>(16);
+        PointerOverIds = new ClayList<ElementId>(maxElementCount);
     }
 
     /// <summary>
@@ -1442,6 +1450,88 @@ public void SetPointerState(Vector2 position, bool pressed)
                 ? PointerInteractionState.ReleasedThisFrame
                 : PointerInteractionState.Released;
         }
+
+        RebuildPointerOverIds(position);
+    }
+
+    /// <summary>
+    /// Rebuilds <see cref="PointerOverIds"/> for the current pointer position
+    /// without advancing the pointer state machine. Call after <see cref="EndLayout"/>
+    /// when hit-testing must run against the freshly computed layout.
+    /// </summary>
+    public void RefreshPointerOverIds() => RebuildPointerOverIds(PointerInfo.Position);
+
+    private void RebuildPointerOverIds(Vector2 position)
+    {
+        PointerOverIds.Clear();
+        if (LayoutElementTreeRoots.Length == 0 || LayoutElements.Length == 0)
+            return;
+
+        // Iterate roots topmost-first. EndLayout sorts roots ascending by ZIndex,
+        // so reverse iteration visits highest-ZIndex root first.
+        for (int rootIndex = LayoutElementTreeRoots.Length - 1; rootIndex >= 0; rootIndex--)
+        {
+            ref var root = ref LayoutElementTreeRoots[rootIndex];
+            var pointerOffset = root.PointerOffset;
+            var adjustedPos = new Vector2(position.X + pointerOffset.X, position.Y + pointerOffset.Y);
+
+            _pointerDfsStack.Clear();
+            _pointerDfsVisited.Clear();
+            _pointerDfsStack.Add(root.LayoutElementIndex);
+            _pointerDfsVisited.Add(false);
+
+            bool found = false;
+            while (_pointerDfsStack.Length > 0)
+            {
+                int depth = _pointerDfsStack.Length - 1;
+                int elementIndex = _pointerDfsStack[depth];
+
+                if (_pointerDfsVisited[depth])
+                {
+                    // Post-order add: children already processed.
+                    int hashIdx = GetHashMapItemIndex(LayoutElements[elementIndex].Id);
+                    if (hashIdx >= 0)
+                    {
+                        ref var item = ref LayoutElementsHashMapInternal[hashIdx];
+                        if (item.BoundingBox.Contains(adjustedPos))
+                        {
+                            PointerOverIds.Add(item.ElementId);
+                            found = true;
+                        }
+                    }
+                    _pointerDfsStack.Length--;
+                    _pointerDfsVisited.Length--;
+                    continue;
+                }
+
+                _pointerDfsVisited[depth] = true;
+                ref var element = ref LayoutElements[elementIndex];
+
+                // Text leaves: no children to descend into.
+                if (HasConfig(ref element, ElementConfigType.Text))
+                    continue;
+
+                // Push children forward so last-child pops first (topmost subtree first).
+                int childStart = element.Children.StartIndex;
+                int childLen = element.Children.Length;
+                for (int i = 0; i < childLen; i++)
+                {
+                    _pointerDfsStack.Add(LayoutElementChildren[childStart + i]);
+                    _pointerDfsVisited.Add(false);
+                }
+            }
+
+            // Floating root with Capture mode swallows pointer events: don't continue
+            // into roots underneath it.
+            if (!found) continue;
+            ref var rootElement = ref LayoutElements[root.LayoutElementIndex];
+            int floatingIdx = FindConfigIndex(ref rootElement, ElementConfigType.Floating);
+            if (floatingIdx >= 0 &&
+                FloatingElementConfigs[floatingIdx].PointerCaptureMode == PointerCaptureMode.Capture)
+            {
+                break;
+            }
+        }
     }
 
     public void SetLayoutDimensions(Dimensions dimensions)