guise-ui 1.5.3

//! The Timelines panel: the frame graph, the bands, and the event list.
//!
//! Safari records instruments — Network, Layout & Rendering, JavaScript &
//! Events — and lays them out against one ruler so you can see what overlapped
//! what. The Frames band here is measured by the inspector itself, from the
//! interval between its own renders; the others are whatever the host reported
//! through [`super::timeline_event`] and [`super::measure`].

use std::time::Duration;

use gpui::prelude::*;
use gpui::{div, px, AnyElement, Context, Hsla, SharedString, Window};

use super::shell::{
  cell, empty_state, filter_pill, header_cell, tool_button, Ink, LABEL_SIZE, MONO_SIZE, NAV_WIDTH,
  ROW_HEIGHT,
};
use super::state::{format_duration, DevToolsState, TimelineEvent, TimelineKind};
use super::DevTools;
use crate::icon::IconName;
use crate::style::MONO_FAMILY;

/// The frame budget for 60 Hz. Anything past this dropped a frame, and the
/// graph colors it accordingly.
const FRAME_BUDGET: Duration = Duration::from_micros(16_667);

#[derive(Default)]
pub struct TimelinesPanel {
  /// `None` shows every band, as Safari's "All" instrument does.
  band: Option<TimelineKind>,
  /// Whether the frame recorder is armed.
  ///
  /// Off by default, and that is not laziness. gpui paints on demand, so the
  /// interval between two frames of an idle window is however long it sat
  /// idle — reported as a frame rate it reads as a stall that never
  /// happened. Safari makes you press Record for the same reason: the
  /// measurement only means something while something is being measured.
  pub(crate) recording: bool,
}

impl TimelinesPanel {
  /// The window every band is laid out against: the earliest start to the
  /// latest end across the events being shown.
  pub fn span(events: &[TimelineEvent]) -> (Duration, Duration) {
    let start = events
      .iter()
      .map(|event| event.start)
      .min()
      .unwrap_or(Duration::ZERO);
    let end = events
      .iter()
      .map(|event| event.end())
      .max()
      .unwrap_or(Duration::ZERO);
    (start, end.max(start))
  }

  fn band_color(kind: TimelineKind, ink: &Ink) -> Hsla {
    match kind {
      TimelineKind::Frame => ink.accent,
      TimelineKind::Layout => ink.info,
      TimelineKind::Paint => ink.tag,
      TimelineKind::Script => ink.warning,
      TimelineKind::Network => ink.success,
    }
  }

  pub fn render(&self, window: &mut Window, cx: &mut Context<DevTools>) -> AnyElement {
    let ink = Ink::read(cx);
    let (events, frames, fps) = cx
      .try_global::<DevToolsState>()
      .map(|state| {
        let events: Vec<TimelineEvent> = state
          .timeline()
          .iter()
          .filter(|event| self.band.is_none_or(|band| event.kind == band))
          .cloned()
          .collect();
        let frames: Vec<Duration> = state.frames().iter().copied().collect();
        (events, frames, state.fps())
      })
      .unwrap_or_default();

    let mut bar = div()
      .flex()
      .flex_none()
      .items_center()
      .gap(px(4.0))
      .h(px(26.0))
      .px(px(8.0))
      .w_full()
      .bg(ink.chrome)
      .border_b_1()
      .border_color(ink.border)
      .child(
        tool_button(
          "devtools-timeline-record",
          if self.recording {
            IconName::Square
          } else {
            IconName::Circle
          },
          if self.recording {
            "Stop recording"
          } else {
            "Start recording"
          },
          self.recording,
          &ink,
          cx,
        )
        .on_click(cx.listener(|this: &mut DevTools, _event, _window, cx| {
          this.timelines.recording = !this.timelines.recording;
          if !this.timelines.recording && cx.has_global::<DevToolsState>() {
            cx.update_global::<DevToolsState, _>(|state, _cx| state.stop_frames());
          }
          cx.notify();
        })),
      )
      .child(
        filter_pill("devtools-timeline-all", "All", self.band.is_none(), &ink).on_click(
          cx.listener(|this: &mut DevTools, _event, _window, cx| {
            this.timelines.band = None;
            cx.notify();
          }),
        ),
      );
    for kind in TimelineKind::ALL {
      bar = bar.child(
        filter_pill(
          ("devtools-timeline-band", kind as usize),
          kind.label(),
          self.band == Some(kind),
          &ink,
        )
        .on_click(
          cx.listener(move |this: &mut DevTools, _event, _window, cx| {
            this.timelines.band = Some(kind);
            cx.notify();
          }),
        ),
      );
    }
    bar = bar.child(div().flex_1()).when_some(fps, |el, fps| {
      el.child(
        div()
          .text_size(px(LABEL_SIZE))
          .text_color(if fps >= 55.0 {
            ink.success
          } else {
            ink.warning
          })
          .child(SharedString::from(format!("{fps:.0} fps"))),
      )
    });

    let _ = window;

    div()
      .flex()
      .flex_col()
      .flex_1()
      .min_h(px(0.0))
      .w_full()
      .child(bar)
      .child(self.frame_graph(&frames, &ink))
      .child(self.bands(&events, &ink))
      .child(self.list(&events, &ink, cx))
      .into_any_element()
  }

  /// One bar per recorded frame, red past the 60 Hz budget. This is the band
  /// that makes a stutter visible without any host instrumentation at all.
  fn frame_graph(&self, frames: &[Duration], ink: &Ink) -> AnyElement {
    let mut graph = div()
      .flex()
      .flex_none()
      .items_end()
      .gap(px(1.0))
      .h(px(46.0))
      .w_full()
      .px(px(8.0))
      .py(px(4.0))
      .bg(ink.content)
      .border_b_1()
      .border_color(ink.border);

    if frames.is_empty() {
      return graph
        .items_center()
        .child(
          div()
            .text_size(px(LABEL_SIZE))
            .text_color(ink.dim)
            .child(SharedString::new_static(if self.recording {
              "Measuring frames…"
            } else {
              "Press Record to measure frames"
            })),
        )
        .into_any_element();
    }

    // Scale against twice the budget so a normal frame sits at half height
    // and a dropped one visibly spikes.
    let ceiling = (FRAME_BUDGET.as_secs_f32() * 2.0).max(0.001);
    for delta in frames {
      let fraction = (delta.as_secs_f32() / ceiling).clamp(0.02, 1.0);
      let over = *delta > FRAME_BUDGET;
      graph = graph.child(
        div()
          .flex_1()
          .min_w(px(1.0))
          .h(gpui::relative(fraction))
          .bg(if over { ink.danger } else { ink.success }),
      );
    }

    graph.into_any_element()
  }

  /// The instrument bands: one row per kind, spans placed on a shared ruler.
  fn bands(&self, events: &[TimelineEvent], ink: &Ink) -> AnyElement {
    if events.is_empty() {
      return div().into_any_element();
    }

    let (start, end) = Self::span(events);
    let window = (end.saturating_sub(start)).as_secs_f32().max(0.001);

    let mut rows = div()
      .flex()
      .flex_col()
      .flex_none()
      .w_full()
      .bg(ink.content)
      .border_b_1()
      .border_color(ink.border);

    for kind in TimelineKind::ALL {
      let band: Vec<&TimelineEvent> = events.iter().filter(|event| event.kind == kind).collect();
      if band.is_empty() {
        continue;
      }

      let mut track = div().relative().flex_1().h(px(14.0)).bg(ink.stripe);
      for event in band {
        let offset = event.start.saturating_sub(start).as_secs_f32() / window;
        let width = (event.duration.as_secs_f32() / window).clamp(0.002, 1.0);
        track = track.child(
          div()
            .absolute()
            .top(px(2.0))
            .left(gpui::relative(offset.clamp(0.0, 0.998)))
            .w(gpui::relative(width))
            .h(px(10.0))
            .rounded(px(2.0))
            .bg(Self::band_color(kind, ink)),
        );
      }

      rows = rows.child(
        div()
          .flex()
          .items_center()
          .gap(px(6.0))
          .w_full()
          .px(px(8.0))
          .py(px(2.0))
          .child(
            div()
              .flex_none()
              .w(px(NAV_WIDTH - 40.0))
              .text_size(px(LABEL_SIZE))
              .text_color(ink.dim)
              .child(SharedString::new_static(kind.label())),
          )
          .child(track),
      );
    }

    rows.into_any_element()
  }

  fn list(&self, events: &[TimelineEvent], ink: &Ink, cx: &mut Context<DevTools>) -> AnyElement {
    if events.is_empty() {
      return empty_state(
        "No timeline events recorded. Wrap work in devtools::measure to populate this.",
        ink,
      )
      .into_any_element();
    }

    let mut list = div()
      .id("devtools-timeline-list")
      .flex()
      .flex_col()
      .flex_1()
      .min_h(px(0.0))
      .w_full()
      .overflow_scroll()
      .bg(ink.content)
      .font_family(MONO_FAMILY)
      .text_size(px(MONO_SIZE));

    list = list.child(
      div()
        .flex()
        .flex_none()
        .items_center()
        .h(px(20.0))
        .w_full()
        .bg(ink.chrome)
        .border_b_1()
        .border_color(ink.border)
        .child(header_cell("Event", None, ink))
        .child(header_cell("Type", Some(140.0), ink))
        .child(header_cell("Start", Some(80.0), ink))
        .child(header_cell("Duration", Some(80.0), ink)),
    );

    // Newest first: the thing that just happened is the thing being chased.
    for (position, event) in events.iter().rev().enumerate() {
      let source = event.source.clone();
      let hover_bg = ink.hover;
      let mut row = div()
        .id(("devtools-timeline-row", position))
        .flex()
        .items_center()
        .flex_none()
        .h(px(ROW_HEIGHT))
        .w_full()
        .when(position % 2 == 1, |el| el.bg(ink.stripe))
        .hover(move |st| st.bg(hover_bg))
        .child(cell(event.label.clone(), None, ink.text))
        .child(cell(
          event.kind.label(),
          Some(140.0),
          Self::band_color(event.kind, ink),
        ))
        .child(cell(format_duration(event.start), Some(80.0), ink.dim))
        .child(cell(
          format_duration(event.duration),
          Some(80.0),
          if event.duration > FRAME_BUDGET {
            ink.warning
          } else {
            ink.dim
          },
        ));

      if let Some(source) = source {
        row = row.on_click(
          cx.listener(move |this: &mut DevTools, _event, _window, cx| {
            this.reveal_source(source.clone(), cx);
          }),
        );
      }

      list = list.child(row);
    }

    list.into_any_element()
  }
}

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

  fn event(kind: TimelineKind, start_ms: u64, duration_ms: u64) -> TimelineEvent {
    let mut event = TimelineEvent::new(kind, "work", Duration::from_millis(duration_ms));
    event.start = Duration::from_millis(start_ms);
    event
  }

  #[test]
  fn the_span_covers_every_event() {
    let events = vec![
      event(TimelineKind::Script, 100, 40),
      event(TimelineKind::Layout, 20, 10),
      event(TimelineKind::Paint, 60, 5),
    ];

    let (start, end) = TimelinesPanel::span(&events);
    assert_eq!(start, Duration::from_millis(20));
    assert_eq!(end, Duration::from_millis(140));
  }

  #[test]
  fn an_empty_timeline_has_a_zero_span() {
    assert_eq!(TimelinesPanel::span(&[]), (Duration::ZERO, Duration::ZERO));
  }

  #[test]
  fn a_single_instant_event_does_not_invert_the_span() {
    let events = vec![event(TimelineKind::Script, 50, 0)];
    let (start, end) = TimelinesPanel::span(&events);
    assert_eq!(start, Duration::from_millis(50));
    assert_eq!(end, Duration::from_millis(50));
  }

  #[test]
  fn the_frame_budget_is_sixty_hertz() {
    assert!(FRAME_BUDGET < Duration::from_millis(17));
    assert!(FRAME_BUDGET > Duration::from_millis(16));
  }
}