iris: fold render state into Ui

docs/LAYOUT.md

@@ -6,6 +6,24 @@ without reading that result does not make the parent's size depend on it.
 
 ## Design
 
+### UI ownership and frame access
+
+`Ui` owns both the mutable widget-side `UiData` and the retained
+`UiRenderState`. It dereferences to `UiData`, so resources expose one `Ui`
+without adding a second layer to ordinary widget, text, and texture access.
+The render state itself remains private. `Ui::render_state()` returns an owned
+`RenderHandle`, whose only public operation is a shared `get()` guard over the
+last completed frame. Owning the handle, rather than borrowing `Ui`, lets a
+controller inspect retained ancestry while it mutates other resources.
+
+`UiRsc::draw` is the mutation boundary: it clones the private handle, takes
+the exclusive guard, and updates the render state with the `Rsc`. Event
+dispatch holds a shared guard for the whole callback, so events and controller
+methods can reuse the completed tree but cannot start a draw or observe a
+partially updated one. Controller ancestry is walked directly through that
+tree; the event manager still maintains its per-event active-widget index in
+draw hooks so dispatch never has to scan every active widget.
+
 ### 1. The new `Widget` trait
 
 ```rust