guise/devtools/

probe.rs

//! The element-tree recorder behind the Elements panel.
//!
//! gpui knows which element the pointer is over — that is what
//! `Window::toggle_inspector` picking gives you — but it will not enumerate a
//! tree: `inspector_hitboxes` is crate-private and only ever holds one frame of
//! whatever happened to be under the cursor. A DOM-style outline has to be
//! recorded by the thing being inspected.
//!
//! So `guise` records its own. [`Probed::probe`] wraps a component's root
//! element in a pass-through [`Probe`] that pushes a node on the way into
//! `prepaint` and pops it on the way out. gpui prepaints depth-first, so the
//! push/pop pairs nest exactly like the element tree does, and the arena that
//! falls out is the tree the panel renders.
//!
//! Two properties make this affordable to leave in every component:
//!
//! * It is off unless the inspector is open ([`set_enabled`]), and off means
//!   two boolean checks per wrapped element per frame.
//! * It never allocates while off — attributes are dropped at the setter.
//!
//! Every window on a thread shares one recorder, so an inspector claims the
//! window it renders in ([`begin_frame`]) and elements prepainting in any
//! other window are skipped. Without that, an app with a second window open
//! records both trees into one and the inspector shows a tree its panels
//! cannot explain.
//!
//! The recorder always runs one frame behind: an entity's `render` happens
//! during `request_layout`, before anything has prepainted, so the panel reads
//! the tree the *previous* frame built. [`begin_frame`] is what rotates them.

use std::cell::RefCell;
use std::panic::Location;

use gpui::{
    App, Bounds, ElementId, GlobalElementId, InspectorElementId, IntoElement, LayoutId, Pixels,
    SharedString, StyleRefinement, Styled, Window, WindowId,
};

use super::state::SourceRef;

/// One recorded element: a row in the Elements tree.
#[derive(Debug, Clone)]
pub struct ProbeNode {
    /// The component name, rendered as the tag: `Button` shows as `<Button>`.
    pub name: SharedString,
    /// Attributes shown inline after the tag, as a DOM node shows its
    /// attributes. Ordered as the component declared them.
    pub attrs: Vec<(SharedString, SharedString)>,
    /// The gpui element id, when the element has one.
    pub element_id: Option<SharedString>,
    /// Where the component was constructed, for the Node panel and Sources.
    pub source: Option<SourceRef>,
    /// Laid-out bounds, captured during prepaint. This is what the highlight
    /// overlay and the box model read.
    pub bounds: Bounds<Pixels>,
    /// The element's own style, snapshotted before it was laid out. Boxed
    /// because a `StyleRefinement` is large and most of a tree's memory would
    /// otherwise be styles nobody has selected.
    pub style: Option<Box<StyleRefinement>>,
    /// Index of the parent in the arena, or `None` for a root.
    pub parent: Option<usize>,
    /// Indices of the children, in paint order.
    pub children: Vec<usize>,
    /// Nesting depth, precomputed for the tree's indentation.
    pub depth: usize,
    /// A path key that survives across frames, so a selection outlives the
    /// frame it was made in: parent path + tag + sibling ordinal.
    pub key: SharedString,
}

impl ProbeNode {
    /// Whether the node has no children — a leaf renders as `<Tag />`.
    pub fn is_leaf(&self) -> bool {
        self.children.is_empty()
    }
}

/// A recorded tree: a flat arena plus its roots, in the order they prepainted.
#[derive(Debug, Clone, Default)]
pub struct ProbeTree {
    pub nodes: Vec<ProbeNode>,
    pub roots: Vec<usize>,
}

impl ProbeTree {
    pub fn is_empty(&self) -> bool {
        self.nodes.is_empty()
    }

    pub fn len(&self) -> usize {
        self.nodes.len()
    }

    pub fn get(&self, index: usize) -> Option<&ProbeNode> {
        self.nodes.get(index)
    }

    /// Find a node by the stable key a previous frame handed out.
    pub fn find(&self, key: &str) -> Option<usize> {
        self.nodes.iter().position(|n| n.key.as_ref() == key)
    }

    /// The chain from the root down to `index`, which is what the Elements
    /// panel's breadcrumb bar shows.
    pub fn ancestry(&self, index: usize) -> Vec<usize> {
        let mut chain = Vec::new();
        let mut cursor = Some(index);
        while let Some(i) = cursor {
            chain.push(i);
            cursor = self.nodes.get(i).and_then(|n| n.parent);
        }
        chain.reverse();
        chain
    }

    /// The deepest node whose bounds contain `point`, searched in reverse paint
    /// order so the topmost element wins — the same rule as hit testing.
    pub fn hit(&self, point: gpui::Point<Pixels>) -> Option<usize> {
        let mut best: Option<(usize, usize)> = None;
        for (index, node) in self.nodes.iter().enumerate() {
            if node.bounds.contains(&point) {
                let deeper = best.is_none_or(|(_, depth)| node.depth >= depth);
                if deeper {
                    best = Some((index, node.depth));
                }
            }
        }
        best.map(|(index, _)| index)
    }
}

/// Recording state. Thread-local rather than a gpui `Global` because element
/// methods run in the hot path of every frame and a thread-local read is a
/// pointer deref, where `App::global` is a hash lookup.
#[derive(Default)]
struct Registry {
    /// How many inspectors are alive.
    ///
    /// A count rather than a flag because instances overlap: replacing a
    /// `DevTools` constructs the new one before dropping the old, so a boolean
    /// would have the old one's `Drop` switch recording off underneath its
    /// replacement.
    recorders: usize,
    /// The tree the current frame is prepainting into.
    building: ProbeTree,
    /// The last completed tree — what panels read.
    current: ProbeTree,
    /// Open ancestors, innermost last.
    stack: Vec<usize>,
    /// The window whose inspector claimed this frame, if one did. `None` means
    /// record every window, which is what a host driving the recorder by hand
    /// through [`set_enabled`] wants.
    window: Option<WindowId>,
}

impl Registry {
    fn is_recording(&self) -> bool {
        self.recorders > 0
    }

    fn clear(&mut self) {
        self.building = ProbeTree::default();
        self.current = ProbeTree::default();
        self.stack.clear();
        self.window = None;
    }
}

thread_local! {
    static REGISTRY: RefCell<Registry> = RefCell::new(Registry::default());
}

/// Turn recording on or off outright, ignoring how many inspectors are alive.
/// For a host driving the recorder by hand, and for tests; an inspector uses
/// [`retain`] and [`release`] instead.
pub fn set_enabled(enabled: bool) {
    REGISTRY.with(|registry| {
        let mut registry = registry.borrow_mut();
        registry.recorders = usize::from(enabled);
        if !enabled {
            registry.clear();
        }
    });
}

/// Register an inspector. Recording starts on the first one.
pub(crate) fn retain() {
    REGISTRY.with(|registry| registry.borrow_mut().recorders += 1);
}

/// Drop an inspector. Recording stops, and the recorded tree is released, when
/// the last one goes.
pub(crate) fn release() {
    REGISTRY.with(|registry| {
        let mut registry = registry.borrow_mut();
        registry.recorders = registry.recorders.saturating_sub(1);
        if registry.recorders == 0 {
            registry.clear();
        }
    });
}

pub fn is_enabled() -> bool {
    REGISTRY.with(|registry| registry.borrow().recorders > 0)
}

/// Promote the tree the last frame recorded and start a fresh one, claiming
/// this frame for `window`. Called from the inspector's `render`, which runs
/// before any of this frame's prepaints, so elements in every other window
/// this thread draws are skipped for the rest of the frame.
///
/// There is one tree per thread, so two inspectors in two windows take the
/// claim from each other every frame and both come up empty. Showing each of
/// them a tree of both windows would be worse.
pub fn begin_frame(window: &Window) {
    rotate(Some(window.window_handle().window_id()))
}

/// Rotate with no window claimed, so every window records. For the sibling
/// tests, which drive the recorder without standing up a window.
#[cfg(test)]
pub(crate) fn begin_frame_unclaimed() {
    rotate(None)
}

fn rotate(claim: Option<WindowId>) {
    REGISTRY.with(|registry| {
        let mut registry = registry.borrow_mut();
        if !registry.is_recording() {
            return;
        }
        let previous = std::mem::replace(&mut registry.window, claim);
        // An unbalanced stack would mean an element was pushed and never
        // popped; drop it rather than nesting the next frame under a ghost.
        registry.stack.clear();
        let built = std::mem::take(&mut registry.building);
        // A tree recorded before this window held the claim belongs to some
        // other window, or to no window in particular — the frame an inspector
        // first opens on. Drop it rather than show a tree its panels cannot
        // explain; the next frame records a real one.
        if previous == claim && !built.is_empty() {
            registry.current = built;
        }
    });
}

/// The most recently completed tree.
pub fn tree() -> ProbeTree {
    REGISTRY.with(|registry| registry.borrow().current.clone())
}

/// Run `f` against the current tree without cloning it — for a host that wants
/// to inspect the tree without paying for a copy of it.
pub fn with_tree<R>(f: impl FnOnce(&ProbeTree) -> R) -> R {
    REGISTRY.with(|registry| f(&registry.borrow().current))
}

fn push(meta: &ProbeMeta, window: Option<WindowId>) -> Option<usize> {
    REGISTRY.with(|registry| {
        let mut registry = registry.borrow_mut();
        if !registry.is_recording() {
            return None;
        }
        // Another window prepainting into a tree this window's inspector
        // claimed. Its elements are not what is being inspected.
        if registry.window.is_some() && registry.window != window {
            return None;
        }

        let parent = registry.stack.last().copied();
        let depth = registry.stack.len();
        let ordinal = match parent {
            Some(parent) => registry.building.nodes[parent].children.len(),
            None => registry.building.roots.len(),
        };
        let key = match parent {
            Some(parent) => format!(
                "{}/{}[{}]",
                registry.building.nodes[parent].key, meta.name, ordinal
            ),
            None => format!("{}[{}]", meta.name, ordinal),
        };

        let index = registry.building.nodes.len();
        registry.building.nodes.push(ProbeNode {
            name: meta.name.clone(),
            attrs: meta.attrs.clone(),
            element_id: None,
            source: meta.source.clone(),
            bounds: Bounds::default(),
            style: meta.style.clone(),
            parent,
            children: Vec::new(),
            depth,
            key: key.into(),
        });

        match parent {
            Some(parent) => registry.building.nodes[parent].children.push(index),
            None => registry.building.roots.push(index),
        }
        registry.stack.push(index);
        Some(index)
    })
}

fn pop(index: usize, bounds: Bounds<Pixels>, element_id: Option<ElementId>) {
    REGISTRY.with(|registry| {
        let mut registry = registry.borrow_mut();
        if let Some(node) = registry.building.nodes.get_mut(index) {
            node.bounds = bounds;
            node.element_id = element_id.map(|id| SharedString::from(id.to_string()));
        }
        // Pop back to this node's own frame. A child that failed to pop would
        // otherwise leave the stack permanently deeper.
        while let Some(top) = registry.stack.pop() {
            if top == index {
                break;
            }
        }
    });
}

/// Drive the recorder directly. Only for tests in sibling modules that need a
/// tree without standing up a window and a full element pass.
#[cfg(test)]
pub(crate) fn test_record(name: &'static str, children: impl FnOnce()) {
    let meta = ProbeMeta {
        name: SharedString::new_static(name),
        attrs: Vec::new(),
        source: None,
        style: None,
    };
    let index = push(&meta, None);
    children();
    if let Some(index) = index {
        pop(index, Bounds::default(), None);
    }
}

/// What a probe knows about the element it wraps, before it becomes one.
#[derive(Debug, Clone)]
struct ProbeMeta {
    name: SharedString,
    attrs: Vec<(SharedString, SharedString)>,
    source: Option<SourceRef>,
    style: Option<Box<StyleRefinement>>,
}

/// A component's root element, tagged for the Elements panel. Built by
/// [`Probed::probe`].
pub struct Probe<E> {
    inner: E,
    meta: ProbeMeta,
    /// Recording state, sampled once at construction so the attribute setters
    /// can skip their allocations entirely while the inspector is closed.
    recording: bool,
}

impl<E> Probe<E> {
    /// Add an attribute, shown inline after the tag name. Dropped without
    /// allocating when the inspector is closed.
    pub fn attr(mut self, name: impl Into<SharedString>, value: impl Into<SharedString>) -> Self {
        if self.recording {
            self.meta.attrs.push((name.into(), value.into()));
        }
        self
    }

    /// Add an attribute whose value costs something to build. The closure runs
    /// only while the inspector is recording, so a `format!` in a component's
    /// hot render path is not paid for by every release build.
    pub fn attr_with<V: Into<SharedString>>(
        mut self,
        name: impl Into<SharedString>,
        value: impl FnOnce() -> V,
    ) -> Self {
        if self.recording {
            self.meta.attrs.push((name.into(), value().into()));
        }
        self
    }

    /// Add an attribute only when `value` is set — the usual shape for a
    /// component's optional props.
    pub fn attr_opt(
        self,
        name: impl Into<SharedString>,
        value: Option<impl Into<SharedString>>,
    ) -> Self {
        match value {
            Some(value) => self.attr(name, value),
            None => self,
        }
    }

    /// Add an attribute only when `present`, the way a boolean HTML attribute
    /// either appears bare or not at all.
    pub fn attr_if(self, name: impl Into<SharedString>, present: bool) -> Self {
        if present {
            self.attr(name, "")
        } else {
            self
        }
    }
}

/// Tag any element as a component for the Elements panel.
///
/// Call it last, on the element a component's `render` returns:
///
/// ```ignore
/// impl RenderOnce for Button {
///     fn render(self, _window: &mut Window, cx: &mut App) -> impl IntoElement {
///         div()
///             // ...
///             .probe("Button")
///             .attr("variant", self.variant.label())
///     }
/// }
/// ```
///
/// The bound is [`Styled`] rather than plain [`IntoElement`] so the probe can
/// snapshot the element's style on the way past — that snapshot is the whole
/// Styles and Computed sidebar. Every component root is a styled element, so
/// in practice this costs nothing.
pub trait Probed: IntoElement + Styled + Sized {
    /// Wrap this element in a probe named `name`.
    #[track_caller]
    fn probe(mut self, name: impl Into<SharedString>) -> Probe<Self> {
        let recording = is_enabled();
        let style = recording.then(|| Box::new(self.style().clone()));
        // `Location::caller()` has to be read here rather than inside the
        // `then` closure: a closure body is not `#[track_caller]`, so it would
        // resolve to this file instead of to the component that called us.
        let caller = Location::caller();
        Probe {
            inner: self,
            meta: ProbeMeta {
                name: name.into(),
                attrs: Vec::new(),
                source: recording.then(|| SourceRef::from(caller)),
                style,
            },
            recording,
        }
    }
}

impl<E: IntoElement + Styled> Probed for E {}

/// The same, for an element that has no style of its own.
///
/// A handful of components return something already composed — a `Field`, a
/// `deferred(..)` overlay, another component — rather than a styled element.
/// Those have no `StyleRefinement` to hand over; the style that matters belongs
/// to whatever they wrapped, and that reports itself separately. They still
/// belong in the tree, so they probe through here, and their Styles sidebar
/// reads as empty — which is the truth.
pub trait ProbedAny: IntoElement + Sized {
    /// Wrap this element in a probe named `name`, without a style snapshot.
    #[track_caller]
    fn probe_any(self, name: impl Into<SharedString>) -> Probe<Self> {
        let recording = is_enabled();
        let caller = Location::caller();
        Probe {
            inner: self,
            meta: ProbeMeta {
                name: name.into(),
                attrs: Vec::new(),
                source: recording.then(|| SourceRef::from(caller)),
                style: None,
            },
            recording,
        }
    }
}

impl<E: IntoElement> ProbedAny for E {}

impl<E: IntoElement> IntoElement for Probe<E> {
    type Element = ProbeElement<E::Element>;

    fn into_element(self) -> Self::Element {
        ProbeElement {
            inner: self.inner.into_element(),
            meta: self.meta,
            index: None,
        }
    }
}

/// The element half of [`Probe`]: forwards every call to the wrapped element,
/// and brackets `prepaint` with the push/pop that builds the tree.
pub struct ProbeElement<E> {
    inner: E,
    meta: ProbeMeta,
    /// Arena slot claimed during prepaint, carried to the pop.
    index: Option<usize>,
}

impl<E: gpui::Element> IntoElement for ProbeElement<E> {
    type Element = Self;

    fn into_element(self) -> Self::Element {
        self
    }
}

impl<E: gpui::Element> gpui::Element for ProbeElement<E> {
    type RequestLayoutState = E::RequestLayoutState;
    type PrepaintState = E::PrepaintState;

    fn id(&self) -> Option<ElementId> {
        self.inner.id()
    }

    fn source_location(&self) -> Option<&'static Location<'static>> {
        self.inner.source_location()
    }

    fn request_layout(
        &mut self,
        id: Option<&GlobalElementId>,
        inspector_id: Option<&InspectorElementId>,
        window: &mut Window,
        cx: &mut App,
    ) -> (LayoutId, Self::RequestLayoutState) {
        self.inner.request_layout(id, inspector_id, window, cx)
    }

    fn prepaint(
        &mut self,
        id: Option<&GlobalElementId>,
        inspector_id: Option<&InspectorElementId>,
        bounds: Bounds<Pixels>,
        request_layout: &mut Self::RequestLayoutState,
        window: &mut Window,
        cx: &mut App,
    ) -> Self::PrepaintState {
        self.index = push(&self.meta, Some(window.window_handle().window_id()));
        let state = self
            .inner
            .prepaint(id, inspector_id, bounds, request_layout, window, cx);
        if let Some(index) = self.index {
            pop(index, bounds, self.inner.id());
        }
        state
    }

    fn paint(
        &mut self,
        id: Option<&GlobalElementId>,
        inspector_id: Option<&InspectorElementId>,
        bounds: Bounds<Pixels>,
        request_layout: &mut Self::RequestLayoutState,
        prepaint: &mut Self::PrepaintState,
        window: &mut Window,
        cx: &mut App,
    ) {
        self.inner.paint(
            id,
            inspector_id,
            bounds,
            request_layout,
            prepaint,
            window,
            cx,
        );
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The recorder is thread-local and these tests drive it directly, so each
    /// one starts from a known state.
    fn reset() {
        set_enabled(false);
        set_enabled(true);
    }

    fn meta(name: &str) -> ProbeMeta {
        ProbeMeta {
            name: SharedString::from(name.to_owned()),
            attrs: Vec::new(),
            source: None,
            style: None,
        }
    }

    fn record(name: &str, children: impl FnOnce()) {
        let index = push(&meta(name), None);
        children();
        if let Some(index) = index {
            pop(index, Bounds::default(), None);
        }
    }

    #[test]
    fn nesting_follows_the_push_pop_pairs() {
        reset();
        record("Stack", || {
            record("Button", || {});
            record("Badge", || {});
        });
        begin_frame_unclaimed();

        let tree = tree();
        assert_eq!(tree.roots, vec![0]);
        assert_eq!(tree.nodes[0].name.as_ref(), "Stack");
        assert_eq!(tree.nodes[0].children, vec![1, 2]);
        assert_eq!(tree.nodes[1].parent, Some(0));
        assert_eq!(tree.nodes[1].depth, 1);
        assert_eq!(tree.nodes[2].name.as_ref(), "Badge");
    }

    #[test]
    fn keys_are_path_plus_sibling_ordinal() {
        reset();
        record("Stack", || {
            record("Button", || {});
            record("Button", || {});
        });
        begin_frame_unclaimed();

        let tree = tree();
        assert_eq!(tree.nodes[0].key.as_ref(), "Stack[0]");
        assert_eq!(tree.nodes[1].key.as_ref(), "Stack[0]/Button[0]");
        assert_eq!(tree.nodes[2].key.as_ref(), "Stack[0]/Button[1]");
        assert_eq!(tree.find("Stack[0]/Button[1]"), Some(2));
    }

    #[test]
    fn a_key_survives_the_next_frame() {
        reset();
        record("Stack", || record("Button", || {}));
        begin_frame_unclaimed();
        let before = tree().find("Stack[0]/Button[0]");

        record("Stack", || record("Button", || {}));
        begin_frame_unclaimed();
        let after = tree().find("Stack[0]/Button[0]");

        assert_eq!(before, after);
        assert!(after.is_some());
    }

    #[test]
    fn ancestry_runs_root_first() {
        reset();
        record("AppShell", || record("Stack", || record("Button", || {})));
        begin_frame_unclaimed();

        let tree = tree();
        let button = tree.find("AppShell[0]/Stack[0]/Button[0]").unwrap();
        let names: Vec<_> = tree
            .ancestry(button)
            .into_iter()
            .map(|i| tree.nodes[i].name.to_string())
            .collect();
        assert_eq!(names, vec!["AppShell", "Stack", "Button"]);
    }

    #[test]
    fn multiple_roots_are_kept_in_order() {
        reset();
        record("AppShell", || {});
        record("Modal", || {});
        begin_frame_unclaimed();

        let tree = tree();
        assert_eq!(tree.roots, vec![0, 1]);
        assert_eq!(tree.nodes[1].key.as_ref(), "Modal[1]");
    }

    #[test]
    fn overlapping_inspectors_keep_recording_until_the_last_one_goes() {
        set_enabled(false);
        assert!(!is_enabled());

        retain();
        assert!(is_enabled());

        // Replacing an inspector constructs the new one before dropping the
        // old; a flag would have the old one's `Drop` switch recording off
        // underneath its replacement.
        retain();
        release();
        assert!(is_enabled());

        release();
        assert!(!is_enabled());
    }

    #[test]
    fn an_unbalanced_release_cannot_underflow() {
        set_enabled(false);
        release();
        release();
        retain();
        assert!(is_enabled());
        release();
        assert!(!is_enabled());
    }

    #[test]
    fn the_recorded_tree_is_released_with_the_last_inspector() {
        reset();
        record("Stack", || {});
        begin_frame_unclaimed();
        assert!(!tree().is_empty());

        release();
        assert!(tree().is_empty());
    }

    #[test]
    fn nothing_records_while_disabled() {
        reset();
        set_enabled(false);
        record("Stack", || record("Button", || {}));
        begin_frame_unclaimed();

        assert!(tree().is_empty());
    }

    #[test]
    fn hit_testing_picks_the_deepest_containing_node() {
        reset();
        let outer = push(&meta("Stack"), None).unwrap();
        let inner = push(&meta("Button"), None).unwrap();
        pop(
            inner,
            Bounds {
                origin: gpui::point(gpui::px(10.0), gpui::px(10.0)),
                size: gpui::size(gpui::px(50.0), gpui::px(20.0)),
            },
            None,
        );
        pop(
            outer,
            Bounds {
                origin: gpui::point(gpui::px(0.0), gpui::px(0.0)),
                size: gpui::size(gpui::px(200.0), gpui::px(100.0)),
            },
            None,
        );
        begin_frame_unclaimed();

        let tree = tree();
        let hit = tree
            .hit(gpui::point(gpui::px(20.0), gpui::px(15.0)))
            .unwrap();
        assert_eq!(tree.nodes[hit].name.as_ref(), "Button");

        let outside = tree
            .hit(gpui::point(gpui::px(150.0), gpui::px(80.0)))
            .unwrap();
        assert_eq!(tree.nodes[outside].name.as_ref(), "Stack");

        assert!(tree
            .hit(gpui::point(gpui::px(400.0), gpui::px(400.0)))
            .is_none());
    }

    #[test]
    fn an_unbalanced_stack_does_not_leak_into_the_next_frame() {
        reset();
        // Push without popping, as a panicking prepaint would leave things.
        push(&meta("Orphan"), None);
        begin_frame_unclaimed();
        record("Stack", || {});
        begin_frame_unclaimed();

        let tree = tree();
        assert_eq!(tree.roots.len(), 1);
        assert_eq!(tree.nodes[tree.roots[0]].name.as_ref(), "Stack");
        assert_eq!(tree.nodes[tree.roots[0]].depth, 0);
    }
}