fix(onboarding): delay first-run modal until splash screen despawns
Build and Deploy / build-and-push (push) Successful in 4m35s
Web E2E / web-e2e (push) Successful in 4m25s

OnboardingPlugin previously used PostStartup which fires before the
first Update tick — guaranteeing the onboarding modal and the launch
splash (MOTION_SPLASH_TOTAL_SECS = 1.6 s) overlap for the entire
splash duration. The splash sits at Z_SPLASH (the highest UI z-index),
so the two screens fought visually and the user saw a confusing frozen
composite before the splash faded out.

Fix: move spawn_if_first_run to Update and gate it on
`splashes.is_empty()` (no SplashRoot entity alive). A Local<bool>
ensures the spawn fires at most once per session. Cost: ~one frame of
latency after the splash clears, which is imperceptible.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
funman300
2026-06-02 12:59:58 -07:00
parent d45b7cb82b
commit de7ae16830
3 changed files with 35 additions and 15 deletions
+23 -3
View File
@@ -36,6 +36,7 @@ use crate::ui_theme::{
BORDER_SUBTLE, HighContrastBorder, RADIUS_SM, TEXT_PRIMARY, TYPE_BODY, TYPE_CAPTION,
VAL_SPACE_1, VAL_SPACE_2, VAL_SPACE_3,
};
use crate::splash_plugin::SplashRoot;
use crate::ui_theme::{TEXT_SECONDARY, Z_ONBOARDING};
// ---------------------------------------------------------------------------
@@ -153,7 +154,7 @@ pub struct OnboardingPlugin;
impl Plugin for OnboardingPlugin {
fn build(&self, app: &mut App) {
app.init_resource::<OnboardingSlideIndex>()
.add_systems(PostStartup, spawn_if_first_run)
.add_systems(Update, spawn_if_first_run)
.add_systems(
Update,
(handle_onboarding_buttons, handle_onboarding_keyboard).chain(),
@@ -170,11 +171,30 @@ fn spawn_if_first_run(
settings: Option<Res<SettingsResource>>,
font_res: Option<Res<FontResource>>,
mut slide_index: ResMut<OnboardingSlideIndex>,
splashes: Query<(), With<SplashRoot>>,
existing: Query<(), With<OnboardingScreen>>,
mut spawned: Local<bool>,
) {
let Some(s) = settings else { return };
if s.0.first_run_complete {
if *spawned {
return;
}
// Wait until the launch splash has despawned so the two screens
// never overlap. PostStartup would fire before the first Update
// tick, guaranteeing overlap; checking here costs one frame of
// latency after the splash clears, which is imperceptible.
if !splashes.is_empty() {
return;
}
if !existing.is_empty() {
*spawned = true;
return;
}
let Some(s) = settings else { return };
if s.0.first_run_complete {
*spawned = true;
return;
}
*spawned = true;
slide_index.0 = 0;
spawn_slide(&mut commands, 0, font_res.as_deref());
}