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

docs/RUST.md

@@ -60,8 +60,9 @@ runs inside `cargo test`.
 
 1. **Headless, in-process, no compositor and no GPU -- the default.**
    `iris::harness` (`iris/src/harness.rs`), plus the fixture crate it
-   opens. `Harness::new(size, density)` builds an `Rsc`, a
-   `UiRenderState` and a state whose `FocusHost`/`OpenUrl` *record* what
+   opens. `Harness::new(size, density)` builds an `Rsc` whose `Ui` owns
+   the retained render state, and a state whose `FocusHost`/`OpenUrl`
+   *record* what
    the platform was asked for; `frame(t_ms)`/`frames_until(..)` run
    frames on a clock the test owns, and `replay(&TouchScript)` feeds a
    recorded gesture one sample at a time exactly as