Struct UiTree 

pub struct UiTree<H>
where
    H: UiHost,
{ /* private fields */ }

Retained UI tree and per-window interaction state machine.

UiTree owns the widget/node graph for a single window and is responsible for:

• mounting declarative element roots,
• routing input events and commands,
• running layout and producing paint scenes,
• producing semantics snapshots for accessibility backends,
• tracking focus/capture/hover and other interaction state across frames.

Higher-level driver layers (e.g. fret-bootstrap) orchestrate when and how a UiTree is ticked and provide host services via the UiHost trait.

Implementations

impl<H> UiTree<H>

where H: UiHost,

pub fn publish_window_runtime_snapshots(&mut self, app: &mut H)

Publishes authoritative window-level runtime snapshots for the tree’s current retained state.

Raw UiTree mutation APIs (set_root, set_focus, overlay/layer mutation, subtree removal, and similar helpers) only update retained tree state. Cross-surface consumers that read WindowInputContextService, WindowKeyContextStackService, PendingShortcutOverlayState, or WindowCommandActionAvailabilityService become authoritative only after this publish step or another full snapshot commit boundary such as declarative rebuild or non-pointer input dispatch. Paint-only boundaries refresh WindowInputContextService, but they do not republish the full key-context / command-availability snapshot set.

Layout-time raw focus/layer mutations are the one exception: they automatically schedule a post-layout refine so final layout boundaries can republish authoritative snapshots without forcing policy code to publish from inside layout().

Call this after imperative tree mutations when later same-frame consumers must observe the new authoritative window state immediately.

pub fn commit_pending_declarative_window_runtime_snapshots( &mut self, app: &mut H, root: NodeId, ) -> bool

Finalize a declarative rebuild that mounted a detached root and only later attached it to the retained tree.

render_dismissible_root_with_hooks(...) can rebuild an overlay/portal root before the caller attaches that root to a layer or parent. In that case the helper defers the window snapshot commit until the root is actually attached. Call this after push_overlay_root, set_children, or another attach operation that makes the returned root authoritative for same-frame window-level consumers.

This is intentionally narrower than publish_window_runtime_snapshots(...): raw imperative tree mutation still requires an explicit commit, while declarative detached-root authoring can finish its pending commit once attachment is complete.

pub fn is_command_available(&mut self, app: &mut H, command: &CommandId) -> bool

pub fn is_action_available(&mut self, app: &mut H, command: &CommandId) -> bool

GPUI naming parity: “is this action available along the dispatch path?”

Note: Fret models “actions” as CommandId today (especially for widget-scoped commands).

pub fn action_availability( &mut self, app: &mut H, command: &CommandId, ) -> CommandAvailability

GPUI naming parity for availability queries.

pub fn command_availability( &mut self, app: &mut H, command: &CommandId, ) -> CommandAvailability

pub fn publish_window_command_action_availability_snapshot( &mut self, app: &mut H, input_ctx: &InputContext, )

Publish a per-window action availability snapshot for widget-scoped commands.

This is a data-only integration seam for runner/platform and UI-kit layers (menus, command palette, shortcut help). Most apps should prefer publishing a filtered snapshot (e.g. only menu/palette command sets) at the app-driver layer.

Notes:

• This retained-runtime helper publishes a conservative baseline: for each widget-scoped command in the registry, NotHandled is treated as “unavailable” (false) so cross-surface gating behaves consistently.

pub fn dispatch_command( &mut self, app: &mut H, services: &mut dyn UiServices, command: &CommandId, ) -> bool

pub fn focus_traverse_in_roots( &mut self, app: &mut H, roots: &[NodeId], forward: bool, scope_root: Option<NodeId>, ) -> bool

Focus traversal mechanism used by both the runtime default and component-owned focus scopes.

Notes:

• roots are treated as the authoritative traversal roots for this dispatch path.
• scope_root gates authoritative geometry clipping when layout is current.
• This is intentionally conservative until we formalize a scroll-into-view contract (ADR 0068).

pub fn scroll_node_into_view(&mut self, app: &mut H, target: NodeId) -> bool

pub fn scroll_by(&mut self, app: &mut H, target: NodeId, delta: Point) -> bool

impl<H> UiTree<H>

where H: UiHost,

pub fn dispatch_event( &mut self, app: &mut H, services: &mut dyn UiServices, event: &Event, )

impl<H> UiTree<H>

where H: UiHost,

pub fn layer_ids_in_paint_order(&self) -> &[UiLayerId]

Returns the current UI layer order in paint order (back-to-front).

This includes the base layer and any overlay layers (even if currently invisible).

pub fn reorder_layers_in_paint_order(&mut self, desired: Vec<UiLayerId>)

Reorders layers in paint order (back-to-front).

This is a mechanism-only API intended for component-layer overlay orchestration. Policy code should treat this as “stable z-order correction” rather than a per-component knob.

Notes:

• The base layer (when present) is always kept at the back (index 0).
• Unknown/missing layer IDs are ignored, and missing existing layers are appended in their previous relative order.

pub fn base_root(&self) -> Option<NodeId>

pub fn set_base_root(&mut self, root: NodeId) -> UiLayerId

pub fn push_overlay_root( &mut self, root: NodeId, blocks_underlay_input: bool, ) -> UiLayerId

pub fn push_overlay_root_with_options( &mut self, root: NodeId, options: OverlayRootOptions, ) -> UiLayerId

pub fn remove_layer( &mut self, services: &mut dyn UiServices, layer: UiLayerId, ) -> Option<NodeId>

Uninstalls an overlay layer and removes its root subtree.

This is the symmetric operation to push_overlay_root(...) / push_overlay_root_with_options(...) and exists to keep the overlay substrate contract minimal but complete (ADR 0066).

Notes:

• The base layer cannot be removed (use set_base_root instead).
• This removes the layer root node, and recursively removes its children unless a child subtree is itself a layer root (which is treated as an independent root).

pub fn set_layer_visible(&mut self, layer: UiLayerId, visible: bool)

pub fn set_layer_hit_testable(&mut self, layer: UiLayerId, hit_testable: bool)

pub fn set_layer_pointer_occlusion( &mut self, layer: UiLayerId, occlusion: PointerOcclusion, )

pub fn set_layer_blocks_underlay_focus( &mut self, layer: UiLayerId, blocks: bool, )

pub fn is_layer_visible(&self, layer: UiLayerId) -> bool

pub fn layer_root(&self, layer: UiLayerId) -> Option<NodeId>

pub fn set_layer_wants_pointer_move_events( &mut self, layer: UiLayerId, wants: bool, )

pub fn set_layer_wants_pointer_down_outside_events( &mut self, layer: UiLayerId, wants: bool, )

pub fn set_layer_consume_pointer_down_outside_events( &mut self, layer: UiLayerId, consume: bool, )

pub fn set_layer_pointer_down_outside_branches( &mut self, layer: UiLayerId, branches: Vec<NodeId>, )

pub fn set_layer_scroll_dismiss_elements( &mut self, layer: UiLayerId, elements: Vec<GlobalElementId>, )

Register elements that should dismiss this overlay when a scroll event targets an ancestor of any element’s current node.

This is intended for Radix-aligned tooltip behavior: when the tooltip trigger is scrolled, the tooltip should close (Radix closes when event.target.contains(trigger) on scroll).

pub fn set_layer_wants_timer_events(&mut self, layer: UiLayerId, wants: bool)

pub fn node_layer(&self, node: NodeId) -> Option<UiLayerId>

impl<H> UiTree<H>

where H: UiHost,

pub fn layout_all( &mut self, app: &mut H, services: &mut dyn UiServices, bounds: Rect, scale_factor: f32, )

pub fn layout( &mut self, app: &mut H, services: &mut dyn UiServices, root: NodeId, available: Size, scale_factor: f32, ) -> Size

pub fn layout_in( &mut self, app: &mut H, services: &mut dyn UiServices, root: NodeId, bounds: Rect, scale_factor: f32, ) -> Size

pub fn layout_in_with_pass_kind( &mut self, app: &mut H, services: &mut dyn UiServices, root: NodeId, bounds: Rect, scale_factor: f32, pass_kind: LayoutPassKind, overflow_ctx: LayoutOverflowContext, ) -> Size

pub fn measure_in( &mut self, app: &mut H, services: &mut dyn UiServices, node: NodeId, constraints: LayoutConstraints, scale_factor: f32, ) -> Size

impl<H> UiTree<H>

where H: UiHost,

pub fn debug_write_taffy_subtree_json( &self, app: &mut H, window: AppWindowId, root: NodeId, root_bounds: Rect, scale_factor: f32, root_label_filter: Option<&str>, out_dir: impl AsRef<Path>, filename_tag: &str, ) -> Result<PathBuf, Error>

Write a Taffy layout dump for a subtree rooted at root.

The dump includes both local and absolute rects plus a debug label per node. When root_label_filter is provided, the dump will search for the first node whose debug label contains the filter string and use that node as the dump root (falling back to root when the filter does not match anything).

This is a debug-only escape hatch intended for diagnosing layout regressions and scroll / clipping issues. The output is JSON and is written to out_dir.

pub fn debug_write_layout_sidecar_taffy_v1_json( &self, app: &mut H, window: AppWindowId, root: NodeId, root_bounds: Rect, scale_factor: f32, root_label_filter: Option<&str>, out_dir: impl AsRef<Path>, captured_at_unix_ms: u64, ) -> Result<PathBuf, Error>

Write a bundle-scoped layout sidecar (Taffy dump) intended for scripted diagnostics runs.

This is a diagnostics-only escape hatch and should remain best-effort. Tooling should treat missing sidecars as warnings rather than failures.

The file name is stable: layout.taffy.v1.json.

impl<H> UiTree<H>

where H: UiHost,

pub fn paint_all( &mut self, app: &mut H, services: &mut dyn UiServices, bounds: Rect, scene: &mut SceneRecording, scale_factor: f32, )

pub fn paint( &mut self, app: &mut H, services: &mut dyn UiServices, root: NodeId, bounds: Rect, scene: &mut SceneRecording, scale_factor: f32, )

impl<H> UiTree<H>

where H: UiHost,

pub fn live_attached_node_for_element( &self, app: &mut H, element: GlobalElementId, ) -> Option<NodeId>

Resolve the live attached node currently associated with element in this tree.

This is the authoritative element-to-node query when callers already have access to the current UiTree and need a node that is still attached to an active layer tree.

impl<H> UiTree<H>

where H: UiHost,

pub fn debug_cache_root_stats(&self) -> Vec<UiDebugCacheRootStats>

pub fn debug_view_cache_contained_relayout_roots(&self) -> &[NodeId]

pub fn debug_record_overlay_policy_decision( &mut self, frame_id: FrameId, layer: UiLayerId, kind: &'static str, present: bool, interactive: bool, wants_timer_events: bool, reason: &'static str, )

pub fn debug_layout_engine_solves(&self) -> &[UiDebugLayoutEngineSolve]

pub fn debug_layout_hotspots(&self) -> &[UiDebugLayoutHotspot]

pub fn debug_layout_inclusive_hotspots(&self) -> &[UiDebugLayoutHotspot]

pub fn debug_widget_measure_hotspots(&self) -> &[UiDebugWidgetMeasureHotspot]

pub fn debug_paint_widget_hotspots(&self) -> &[UiDebugPaintWidgetHotspot]

pub fn debug_paint_text_prepare_hotspots( &self, ) -> &[UiDebugPaintTextPrepareHotspot]

pub fn set_debug_enabled(&mut self, enabled: bool)

pub fn debug_stats(&self) -> UiDebugFrameStats

pub fn debug_hover_declarative_invalidation_hotspots( &self, max: usize, ) -> Vec<UiDebugHoverDeclarativeInvalidationHotspot>

pub fn debug_invalidation_walks(&self) -> &[UiDebugInvalidationWalk]

pub fn debug_dirty_views(&self) -> &[UiDebugDirtyView]

pub fn debug_notify_requests(&self) -> &[UiDebugNotifyRequest]

pub fn debug_virtual_list_windows(&self) -> &[UiDebugVirtualListWindow]

pub fn debug_virtual_list_window_shift_samples( &self, ) -> &[UiDebugVirtualListWindowShiftSample]

pub fn debug_retained_virtual_list_reconciles( &self, ) -> &[UiDebugRetainedVirtualListReconcile]

pub fn debug_scroll_handle_changes(&self) -> &[UiDebugScrollHandleChange]

pub fn debug_scroll_nodes(&self) -> &[UiDebugScrollNodeTelemetry]

pub fn debug_scrollbars(&self) -> &[UiDebugScrollbarTelemetry]

pub fn debug_prepaint_actions(&self) -> &[UiDebugPrepaintAction]

pub fn debug_model_change_hotspots(&self) -> &[UiDebugModelChangeHotspot]

pub fn debug_model_change_unobserved(&self) -> &[UiDebugModelChangeUnobserved]

pub fn debug_global_change_hotspots(&self) -> &[UiDebugGlobalChangeHotspot]

pub fn debug_global_change_unobserved(&self) -> &[UiDebugGlobalChangeUnobserved]

pub fn debug_node_bounds(&self, node: NodeId) -> Option<Rect>

pub fn debug_node_element(&self, node: NodeId) -> Option<GlobalElementId>

pub fn debug_node_clips_hit_test(&self, node: NodeId) -> Option<bool>

pub fn debug_node_can_scroll_descendant_into_view( &self, node: NodeId, ) -> Option<bool>

pub fn debug_node_render_transform(&self, node: NodeId) -> Option<Transform2D>

pub fn debug_node_children_render_transform( &self, node: NodeId, ) -> Option<Transform2D>

pub fn debug_text_constraints_snapshot( &self, node: NodeId, ) -> UiDebugTextConstraintsSnapshot

pub fn debug_node_visual_bounds(&self, node: NodeId) -> Option<Rect>

Returns the node bounds after applying the accumulated render_transform stack.

This is intended for debugging and tests that need screen-space geometry for overlay placement/hit-testing scenarios. Unlike debug_node_bounds, this includes render-time transforms such as Anchored placement.

This is not a stable cross-frame geometry query (see fret_ui::elements::visual_bounds_for_element for that contract).

pub fn debug_node_path(&self, node: NodeId) -> Vec<NodeId>

pub fn debug_layers_in_paint_order(&self) -> Vec<UiDebugLayerInfo>

pub fn debug_hit_test(&self, position: Point) -> UiDebugHitTest

pub fn debug_hit_test_routing(&mut self, position: Point) -> UiDebugHitTest

Hit-test using the same cached fast paths used by pointer routing.

This is intended for diagnostics tooling that needs “what the runtime would route right now”, including bounds-tree acceleration and view-cache/prepaint interaction data.

Note: this method mutates internal hit-test caches.

impl<H> UiTree<H>

where H: UiHost,

pub fn new() -> UiTree<H>

impl<H> UiTree<H>

where H: UiHost,

pub fn set_window(&mut self, window: AppWindowId)

pub fn focus(&self) -> Option<NodeId>

pub fn request_focus_element(&mut self, app: &mut H, target: GlobalElementId)

Request focus for a declarative element.

If the target element is already attached to a live node, focus moves immediately. If the target is being rebuilt and its node is not yet attached, the request is retained and retried at later authoritative same-frame boundaries (window snapshot publish / final layout), so policy code does not need to guess whether the node is “ready” yet.

pub fn set_focus(&mut self, focus: Option<NodeId>)

impl<H> UiTree<H>

where H: UiHost,

pub fn captured_for(&self, pointer_id: PointerId) -> Option<NodeId>

pub fn captured(&self) -> Option<NodeId>

pub fn any_captured_node(&self) -> Option<NodeId>

pub fn input_arbitration_snapshot(&self) -> UiInputArbitrationSnapshot

impl<H> UiTree<H>

where H: UiHost,

pub fn invalidate(&mut self, node: NodeId, inv: Invalidation)

pub fn invalidate_with_source( &mut self, node: NodeId, inv: Invalidation, source: UiDebugInvalidationSource, )

pub fn invalidate_with_detail( &mut self, node: NodeId, inv: Invalidation, detail: UiDebugInvalidationDetail, )

pub fn invalidate_with_source_and_detail( &mut self, node: NodeId, inv: Invalidation, source: UiDebugInvalidationSource, detail: UiDebugInvalidationDetail, )

impl<H> UiTree<H>

where H: UiHost,

pub fn propagate_pending_model_changes(&mut self, app: &mut H) -> bool

Convenience helper for single-window/single-tree setups.

This drains pending model changes from the host and immediately propagates them into the tree. Multi-window runtimes should drain take_changed_models() once per frame and fan the resulting list out to each window’s UiTree instead.

pub fn propagate_model_changes( &mut self, app: &mut H, changed: &[ModelId], ) -> bool

pub fn propagate_global_changes( &mut self, app: &mut H, changed: &[TypeId], ) -> bool

impl<H> UiTree<H>

where H: UiHost,

pub fn set_root(&mut self, root: NodeId)

pub fn add_child(&mut self, parent: NodeId, child: NodeId)

pub fn set_children(&mut self, parent: NodeId, children: Vec<NodeId>)

impl<H> UiTree<H>

where H: UiHost,

pub fn children(&self, parent: NodeId) -> Vec<NodeId>

pub fn node_parent(&self, node: NodeId) -> Option<NodeId>

pub fn debug_node_measured_size(&self, node: NodeId) -> Option<Size>

pub fn debug_declarative_instance_kind( &self, app: &mut H, window: AppWindowId, node: NodeId, ) -> Option<&'static str>

Debug helper for mapping a NodeId back to the declarative ElementInstance kind (when the node is driven by the declarative renderer).

pub fn first_focusable_ancestor_including_declarative( &self, app: &mut H, window: AppWindowId, start: NodeId, ) -> Option<NodeId>

pub fn first_focusable_descendant(&self, root: NodeId) -> Option<NodeId>

pub fn first_focusable_descendant_including_declarative( &self, app: &mut H, window: AppWindowId, root: NodeId, ) -> Option<NodeId>

Like first_focusable_descendant, but also considers declarative element instances that haven’t run layout yet.

This is needed because declarative nodes derive focusability from their element instance (PressableProps.focusable, TextInput, …), and the ElementHostWidget only caches that information during layout. Overlay policies commonly want to set initial focus immediately after installing an overlay root, before layout runs.

pub fn first_focusable_descendant_including_declarative_present_only( &self, app: &mut H, window: AppWindowId, root: NodeId, ) -> Option<NodeId>

Like first_focusable_descendant_including_declarative, but treats InteractivityGate as a pointer/activation gate, not a traversal boundary for initial focus.

This is useful for overlay autofocus policies where content may be temporarily non-interactive (e.g. during motion) but still present and should be eligible for focus.

impl<H> UiTree<H>

where H: UiHost,

pub fn remove_subtree( &mut self, services: &mut dyn UiServices, root: NodeId, ) -> Vec<NodeId>

impl<H> UiTree<H>

where H: UiHost,

pub fn request_semantics_snapshot(&mut self)

pub fn semantics_snapshot(&self) -> Option<&SemanticsSnapshot>

pub fn semantics_snapshot_arc(&self) -> Option<Arc<SemanticsSnapshot>>

pub fn is_descendant(&self, root: NodeId, node: NodeId) -> bool

impl<H> UiTree<H>

where H: UiHost,

pub fn platform_text_input_query( &mut self, app: &mut H, services: &mut dyn UiServices, scale_factor: f32, query: &PlatformTextInputQuery, ) -> PlatformTextInputQueryResult

pub fn platform_text_input_replace_text_in_range_utf16( &mut self, app: &mut H, services: &mut dyn UiServices, scale_factor: f32, range: Utf16Range, text: &str, ) -> bool

pub fn platform_text_input_replace_and_mark_text_in_range_utf16( &mut self, app: &mut H, services: &mut dyn UiServices, scale_factor: f32, range: Utf16Range, text: &str, marked: Option<Utf16Range>, selected: Option<Utf16Range>, ) -> bool

impl<H> UiTree<H>

where H: UiHost,

pub fn set_paint_cache_policy(&mut self, policy: PaintCachePolicy)

pub fn paint_cache_policy(&self) -> PaintCachePolicy

pub fn set_view_cache_enabled(&mut self, enabled: bool)

pub fn view_cache_enabled(&self) -> bool

pub fn set_inspection_active(&mut self, active: bool)

pub fn inspection_active(&self) -> bool

pub fn set_paint_cache_enabled(&mut self, enabled: bool)

pub fn paint_cache_enabled(&self) -> bool

pub fn ingest_paint_cache_source(&mut self, scene: &mut SceneRecording)

Ingest the previous frame’s recorded ops from scene for paint-cache replay.

Call this before clearing scene for the next frame.

Important:

• This method is destructive: it swaps the scene op storage into the UI tree. Do not call it more than once for the same Scene before Scene::clear().
• scene must contain the previous frame ops that were produced by this UiTree.
• The paint cache records absolute op index ranges into the previous frame ops vector, so sharing a single Scene across multiple UiTrees is not compatible with paint-cache ingestion unless each tree records into an isolated scene.

pub fn set_node_view_cache_flags( &mut self, node: NodeId, enabled: bool, contained_layout: bool, layout_definite: bool, )

Configure view-cache behavior for a specific node.

This is an advanced/low-level knob. Most applications should prefer declarative view-cache boundaries, but retained widgets (and diagnostics harnesses) may need to enable view caching explicitly on a node.

impl<H> UiTree<H>

where H: UiHost,

pub fn cleanup_subtree(&mut self, services: &mut dyn UiServices, root: NodeId)

Trait Implementations

impl<H> Default for UiTree<H>

where H: UiHost,

fn default() -> UiTree<H>

Returns the “default value” for a type.