Fix TUI zero-state onboarding flicker (#14612)

Author: kevinyang372

app/src/tui_onboarding_markers.rs

@@ -121,7 +121,7 @@ impl TuiOnboardingMarkers {
     }
 
     /// Starts a fresh, account-scoped load. Terminal creation never waits for
-    /// this request; consumers reconcile provisional one-time UI on
+    /// this request; consumers keep one-time UI hidden until
     /// [`TuiOnboardingMarkersEvent::Ready`].
     pub fn load_current_account(&mut self, ctx: &mut ModelContext<Self>) {
         self.state = TuiOnboardingMarkersState::Loading;

crates/warp_tui/src/terminal_session_view.rs

@@ -162,7 +162,8 @@ mod todo_menu;
 use self::completions::CompletionRequestState;
 use self::input_detection::InputDetectionState;
 use self::state::{
-    TuiTerminalSessionState, TuiTerminalSessionStateModel, TuiTerminalSessionStateResolveError,
+    TuiFirstZeroStateState, TuiTerminalSessionState, TuiTerminalSessionStateModel,
+    TuiTerminalSessionStateResolveError,
 };
 
 /// Width used before the first layout pass pushes the real terminal width into the editor.
@@ -1779,15 +1780,22 @@ impl TuiTerminalSessionView {
         let orchestration_tab_bar = ctx.add_typed_action_tui_view(|_| TuiTabBarView::empty());
         let onboarding_markers =
             handles_first_run_onboarding.then(|| TuiOnboardingMarkers::handle(ctx));
-        let show_first_zero_state = onboarding_markers.as_ref().is_some_and(|markers| {
-            markers.update(ctx, |markers, ctx| {
-                if markers.is_ready() {
-                    markers.consume(TuiOnboardingMarker::FirstZeroState, ctx)
-                } else {
-                    true
-                }
-            })
-        });
+        let first_zero_state =
+            onboarding_markers
+                .as_ref()
+                .map_or(TuiFirstZeroStateState::Dismissed, |markers| {
+                    markers.update(ctx, |markers, ctx| {
+                        if markers.is_ready() {
+                            if markers.consume(TuiOnboardingMarker::FirstZeroState, ctx) {
+                                TuiFirstZeroStateState::Visible
+                            } else {
+                                TuiFirstZeroStateState::Dismissed
+                            }
+                        } else {
+                            TuiFirstZeroStateState::Pending
+                        }
+                    })
+                });
         let session_state = ctx.add_model(|_| {
             TuiTerminalSessionStateModel::new(
                 &model,
@@ -1796,7 +1804,7 @@ impl TuiTerminalSessionView {
                 &ai_input_model,
                 &suggestions_mode,
                 &orchestration_tab_bar,
-                show_first_zero_state,
+                first_zero_state,
             )
         });
         if let Some(onboarding_markers) = onboarding_markers {
@@ -1806,17 +1814,15 @@ impl TuiTerminalSessionView {
                 move |_, markers, event, ctx| match event {
                     TuiOnboardingMarkersEvent::Loading => {
                         session_state_for_markers.update(ctx, |state, ctx| {
-                            state.set_show_first_zero_state(true, ctx);
+                            state.set_first_zero_state_pending(ctx);
                         });
                     }
                     TuiOnboardingMarkersEvent::Ready => {
                         let keep_showing = markers.update(ctx, |markers, ctx| {
                             markers.consume(TuiOnboardingMarker::FirstZeroState, ctx)
                         });
                         session_state_for_markers.update(ctx, |state, ctx| {
-                            if state.show_first_zero_state() {
-                                state.set_show_first_zero_state(keep_showing, ctx);
-                            }
+                            state.resolve_first_zero_state(keep_showing, ctx);
                         });
                     }
                 },
@@ -3725,7 +3731,7 @@ impl TuiTerminalSessionView {
         ctx: &mut ViewContext<Self>,
     ) {
         self.session_state.update(ctx, |state, ctx| {
-            state.set_show_first_zero_state(false, ctx);
+            state.dismiss_first_zero_state(ctx);
         });
         // A stale editor frame must not submit into a shell that is still
         // bootstrapping or has handed input to a foreground process.

crates/warp_tui/src/terminal_session_view/state.rs

@@ -47,6 +47,12 @@ enum TuiTerminalSessionStateSource {
         orchestration_tabs_available: Rc<dyn Fn(&AppContext) -> bool>,
     },
 }
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(super) enum TuiFirstZeroStateState {
+    Pending,
+    Visible,
+    Dismissed,
+}
 
 /// Persistent session-owned model that resolves a live state snapshot.
 ///
@@ -56,7 +62,7 @@ enum TuiTerminalSessionStateSource {
 /// presentation components one shared state source.
 pub(crate) struct TuiTerminalSessionStateModel {
     source: TuiTerminalSessionStateSource,
-    show_first_zero_state: bool,
+    first_zero_state: TuiFirstZeroStateState,
 }
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -97,14 +103,14 @@ impl Entity for TuiTerminalSessionStateModel {
 }
 
 impl TuiTerminalSessionStateModel {
-    pub(crate) fn new(
+    pub(super) fn new(
         terminal_model: &Arc<FairMutex<TerminalModel>>,
         cli_subagent_controller: &ModelHandle<CLISubagentController>,
         transcript: &ViewHandle<TuiTranscriptView>,
         input_mode: &ModelHandle<BlocklistAIInputModel>,
         suggestions_mode: &ModelHandle<TuiInputSuggestionsModeModel>,
         orchestration_tab_bar: &ViewHandle<TuiTabBarView>,
-        show_first_zero_state: bool,
+        first_zero_state: TuiFirstZeroStateState,
     ) -> Self {
         Self {
             source: TuiTerminalSessionStateSource::Session {
@@ -115,17 +121,36 @@ impl TuiTerminalSessionStateModel {
                 suggestions_mode: suggestions_mode.downgrade(),
                 orchestration_tab_bar: orchestration_tab_bar.downgrade(),
             },
-            show_first_zero_state,
+            first_zero_state,
         }
     }
 
     pub(crate) fn show_first_zero_state(&self) -> bool {
-        self.show_first_zero_state
+        self.first_zero_state == TuiFirstZeroStateState::Visible
+    }
+
+    pub(crate) fn set_first_zero_state_pending(&mut self, ctx: &mut ModelContext<Self>) {
+        if self.first_zero_state != TuiFirstZeroStateState::Pending {
+            self.first_zero_state = TuiFirstZeroStateState::Pending;
+            ctx.notify();
+        }
+    }
+
+    pub(crate) fn resolve_first_zero_state(&mut self, show: bool, ctx: &mut ModelContext<Self>) {
+        if self.first_zero_state != TuiFirstZeroStateState::Pending {
+            return;
+        }
+        self.first_zero_state = if show {
+            TuiFirstZeroStateState::Visible
+        } else {
+            TuiFirstZeroStateState::Dismissed
+        };
+        ctx.notify();
     }
 
-    pub(crate) fn set_show_first_zero_state(&mut self, show: bool, ctx: &mut ModelContext<Self>) {
-        if self.show_first_zero_state != show {
-            self.show_first_zero_state = show;
+    pub(crate) fn dismiss_first_zero_state(&mut self, ctx: &mut ModelContext<Self>) {
+        if self.first_zero_state != TuiFirstZeroStateState::Dismissed {
+            self.first_zero_state = TuiFirstZeroStateState::Dismissed;
             ctx.notify();
         }
     }
@@ -141,7 +166,7 @@ impl TuiTerminalSessionStateModel {
                 suggestions_mode: suggestions_mode.downgrade(),
                 orchestration_tabs_available: Rc::new(orchestration_tabs_available),
             },
-            show_first_zero_state: false,
+            first_zero_state: TuiFirstZeroStateState::Dismissed,
         }
     }
 

crates/warp_tui/src/terminal_session_view_tests.rs

@@ -3863,7 +3863,7 @@ fn zero_state_renders_with_only_zero_height_bootstrap_blocks() {
 }
 
 #[test]
-fn first_zero_state_is_provisional_and_reconciles_without_replacing_the_session() {
+fn first_zero_state_stays_hidden_while_markers_load_and_reconciles_without_replacing_session() {
     App::test((), |mut app| async move {
         let fixture = focus_test_fixture(&mut app);
         app.update(|ctx| {
@@ -3875,18 +3875,19 @@ fn first_zero_state_is_provisional_and_reconciles_without_replacing_the_session(
 
         app.read(|ctx| {
             assert!(
-                view.as_ref(ctx)
+                !view
+                    .as_ref(ctx)
                     .session_state
                     .as_ref(ctx)
                     .show_first_zero_state()
             );
         });
         let lines = render_session(&mut app, &view, 100, 24);
-        assert!(lines.iter().any(|line| line.contains("Welcome to Warp")));
+        assert!(lines.iter().any(|line| line.contains("Warp Agent CLI")));
         assert!(
             lines
                 .iter()
-                .any(|line| line.contains("What’s different about Warp"))
+                .all(|line| !line.contains("What’s different about Warp"))
         );
         assert!(lines.iter().all(|line| !line.contains("████")));
 
@@ -3913,7 +3914,7 @@ fn first_zero_state_is_provisional_and_reconciles_without_replacing_the_session(
 }
 
 #[test]
-fn dismissed_provisional_zero_state_stays_hidden_but_consumes_ready_marker() {
+fn dismissed_pending_zero_state_stays_hidden_but_consumes_ready_marker() {
     App::test((), |mut app| async move {
         let fixture = focus_test_fixture(&mut app);
         app.update(|ctx| {
@@ -3925,7 +3926,7 @@ fn dismissed_provisional_zero_state_stays_hidden_but_consumes_ready_marker() {
 
         view.update(&mut app, |view, ctx| {
             view.session_state.update(ctx, |state, ctx| {
-                state.set_show_first_zero_state(false, ctx);
+                state.dismiss_first_zero_state(ctx);
             });
         });
         app.update(|ctx| {
@@ -3966,7 +3967,7 @@ fn background_session_does_not_receive_first_run_onboarding() {
 
         app.read(|ctx| {
             assert!(
-                onboarding_view
+                !onboarding_view
                     .as_ref(ctx)
                     .session_state
                     .as_ref(ctx)
@@ -4001,11 +4002,18 @@ fn background_session_does_not_receive_first_run_onboarding() {
                     .show_first_zero_state()
             );
         });
+        let lines = render_session(&mut app, &onboarding_view, 100, 24);
+        assert!(lines.iter().any(|line| line.contains("Welcome to Warp")));
+        assert!(
+            lines
+                .iter()
+                .any(|line| line.contains("What’s different about Warp"))
+        );
     });
 }
 
 #[test]
-fn account_transition_restores_provisional_zero_state_on_existing_session() {
+fn account_transition_hides_first_zero_state_while_markers_reload() {
     App::test((), |mut app| async move {
         let fixture = focus_test_fixture(&mut app);
         let (view, session_id) = add_first_run_onboarding_test_session(&mut app, &fixture, true);
@@ -4026,7 +4034,8 @@ fn account_transition_restores_provisional_zero_state_on_existing_session() {
         });
         app.read(|ctx| {
             assert!(
-                view.as_ref(ctx)
+                !view
+                    .as_ref(ctx)
                     .session_state
                     .as_ref(ctx)
                     .show_first_zero_state()