perf(desktop): defer hidden dashboard startup

desktop/src-tauri/src/lib.rs

@@ -135,9 +135,7 @@ impl Default for AppState {
 #[tauri::command]
 fn show_dashboard(app: tauri::AppHandle) {
     popup::hide(&app);
-    if let Some(window) = app.get_webview_window("main") {
-        window::show(&window);
-    }
+    startup::open_dashboard(&app);
 }
 
 #[tauri::command]
@@ -191,10 +189,8 @@ fn decide_takeover(app: tauri::AppHandle, approved: bool) {
 pub fn run() {
     let builder = tauri::Builder::default()
         .plugin(tauri_plugin_single_instance::init(|app, _args, _cwd| {
-            if let Some(window) = app.get_webview_window("main") {
-                popup::hide(app);
-                window::show(&window);
-            }
+            popup::hide(app);
+            startup::open_dashboard(app);
         }))
         .plugin(tauri_plugin_opener::init())
         .plugin(tauri_plugin_process::init())

desktop/src-tauri/src/startup.rs

@@ -365,6 +365,12 @@ pub struct Startup {
     /// before `live`, and never held across an await.
     reporting: Mutex<()>,
     running: AtomicBool,
+    /// Whether this window has already left the bundled bootstrap surface.
+    ///
+    /// Explicit open actions can arrive repeatedly from the tray, the single-instance hook, and
+    /// the shell command. Navigating on every action would recreate the React application and
+    /// discard renderer state, so the transition is owned here and consumed exactly once per run.
+    dashboard_loaded: AtomicBool,
     /// Which run the state belongs to.
     ///
     /// A run's deadline guard outlives the run it was started for, and a retry that begins before
@@ -385,6 +391,7 @@ impl Startup {
             }),
             reporting: Mutex::new(()),
             running: AtomicBool::new(false),
+            dashboard_loaded: AtomicBool::new(false),
             generation: AtomicU64::new(0),
             registered: Mutex::new(None),
         }
@@ -460,6 +467,11 @@ impl Startup {
         live.consent = ConsentState::Idle;
         live.reported.clear();
         live.latest = Progress::new(Phase::NotStarted, 0);
+        self.dashboard_loaded.store(false, Ordering::Release);
+    }
+
+    fn should_navigate_dashboard(&self) -> bool {
+        !self.dashboard_loaded.swap(true, Ordering::AcqRel)
     }
 
     /// Whether the run has already said how it ended.
@@ -1379,12 +1391,51 @@ fn finish(app: &AppHandle, started: Instant, endpoint: ProxyEndpoint) {
         return;
     }
     if let Some(window) = app.get_webview_window("main") {
-        // justified: replacing the bootstrap page with the dashboard is how this window has always
-        // navigated, and the string is a URL this process resolved, not anything a page supplied.
-        let _ = window.eval(format!("window.location.replace({dashboard:?})"));
+        let visible = window.is_visible().unwrap_or(true);
+        if loads_dashboard_on_ready(LaunchOrigin::detect(), visible) {
+            if app
+                .try_state::<Startup>()
+                .map_or(true, |startup| startup.should_navigate_dashboard())
+            {
+                navigate_dashboard(&window, &dashboard);
+            }
+        }
     }
 }
 
+/// Open the full dashboard only when a person asks for it.
+///
+/// A hidden login launch deliberately leaves its WebView on the tiny bundled startup surface after
+/// the runtime becomes ready. The tray, a second ordinary application launch, or the bootstrap
+/// command reaches this function and pays the dashboard cost at that point. If startup is still in
+/// progress the bootstrap is merely shown; `finish` observes the now-visible window and performs
+/// the navigation once the endpoint is ready.
+pub fn open_dashboard(app: &AppHandle) {
+    let dashboard = app.try_state::<Startup>().and_then(|startup| {
+        let progress = startup.latest();
+        (progress.phase == Phase::Ready.id())
+            .then_some(progress.dashboard)
+            .flatten()
+            .filter(|_| startup.should_navigate_dashboard())
+    });
+    if let Some(window) = app.get_webview_window("main") {
+        if let Some(dashboard) = dashboard {
+            navigate_dashboard(&window, &dashboard);
+        }
+        crate::window::show(&window);
+    }
+}
+
+fn loads_dashboard_on_ready(origin: LaunchOrigin, window_visible: bool) -> bool {
+    origin == LaunchOrigin::User || window_visible
+}
+
+fn navigate_dashboard(window: &tauri::WebviewWindow, dashboard: &str) {
+    // justified: replacing the bootstrap page with the dashboard is how this window has always
+    // navigated, and the string is a URL this process resolved, not anything a page supplied.
+    let _ = window.eval(format!("window.location.replace({dashboard:?})"));
+}
+
 #[allow(clippy::too_many_arguments)]
 fn fail(
     app: &AppHandle,
@@ -1489,9 +1540,9 @@ fn elapsed(started: Instant) -> u64 {
 #[cfg(test)]
 mod tests {
     use super::{
-        approval_still_current, attach_plan, claim_after_silence, shows_window,
-        stop_after_approval, unavailable, AttachPlan, ConsentState, Expiry, LaunchOrigin, Phase,
-        Progress, Startup, AUTOSTART_FLAG, DEADLINE, PHASES, POLL,
+        approval_still_current, attach_plan, claim_after_silence, loads_dashboard_on_ready,
+        shows_window, stop_after_approval, unavailable, AttachPlan, ConsentState, Expiry,
+        LaunchOrigin, Phase, Progress, Startup, AUTOSTART_FLAG, DEADLINE, PHASES, POLL,
     };
     use crate::claim::ClaimResult;
     use crate::ownership::{Claim, Consent, Owner, Recorded};
@@ -1773,6 +1824,25 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn only_a_hidden_login_launch_defers_the_full_dashboard() {
+        assert!(loads_dashboard_on_ready(LaunchOrigin::User, false));
+        assert!(loads_dashboard_on_ready(LaunchOrigin::User, true));
+        assert!(loads_dashboard_on_ready(LaunchOrigin::Autostart, true));
+        assert!(!loads_dashboard_on_ready(LaunchOrigin::Autostart, false));
+    }
+
+    #[test]
+    fn explicit_dashboard_navigation_is_consumed_once_per_run() {
+        let startup = Startup::new();
+        assert!(startup.should_navigate_dashboard());
+        assert!(!startup.should_navigate_dashboard());
+
+        startup.restart();
+        assert!(startup.should_navigate_dashboard());
+        assert!(!startup.should_navigate_dashboard());
+    }
+
     #[test]
     fn a_login_launch_hides_only_where_there_is_a_tray_to_hide_in() {
         assert!(!shows_window(

desktop/src-tauri/src/tray.rs

@@ -162,9 +162,7 @@ pub fn install(app: &AppHandle) -> tauri::Result<()> {
                 let _ = popup::show(app, endpoint, anchor);
             }
             "open-dashboard" => {
-                if let Some(window) = app.get_webview_window("main") {
-                    window::show(&window);
-                }
+                crate::startup::open_dashboard(app);
             }
             "open-browser" => {
                 let Some(endpoint) = app

structure/decisions/ADR-5494-lightweight-background-startup.md

@@ -0,0 +1,12 @@
+# ADR-5494 — decision recorded under "Startup, quit and the tray"
+
+- Contract owner: [desktop-shell.md](../desktop-shell.md#startup-quit-and-the-tray)
+
+## Decision record
+
+- 목적과 의도: Keep a login-started desktop shell ready in the background without paying the full dashboard's render and polling cost before a person opens it.
+- 기존 구현 및 제약 조건: The shell already owns a small bundled startup surface, but every successful startup replaced it with the loopback dashboard even when the main window remained hidden behind a usable tray.
+- 검토한 주요 대안: Destroy and recreate the WebView on every open; add a second dashboard window; suspend individual dashboard pollers; or retain the existing startup surface until the first explicit open.
+- 선택한 방식: A hidden autostart launch stays on the bundled ready surface. Manual launches and any visible no-tray launch keep eager dashboard navigation; tray Open Dashboard, a second ordinary launch, and the shell command lazily navigate before showing.
+- 다른 대안 대신 이 방식을 선택한 이유: It removes background React work without adding a window, renderer lifecycle, daemon, or new state owner, and it preserves the already-tested visible startup and failure surface.
+- 장점, 단점 및 영향: Background login uses less work and explicit opens remain immediate after one navigation. The first open after hidden startup now pays the dashboard load once, while visible/manual behavior is unchanged.

structure/desktop-shell.md

@@ -5,9 +5,11 @@ discovers the loopback proxy, lazily retries management authentication, starts
 the bundled `ocx` sidecar only when the configured endpoint is unreachable,
 and owns the tray, autostart, single-instance, and window lifecycle behavior.
 
-`desktop/ui/` is the startup surface. Once the runtime reports healthy the shell navigates the
-webview to the proxy's loopback dashboard (`/#/usage`) rather than bundling or serving `gui/dist`
-itself. The page renders what the shell tells it and probes nothing on its own; it asks
+`desktop/ui/` is the startup surface. Once the runtime reports healthy, a visible or manually
+launched shell navigates the webview to the proxy's loopback dashboard (`/#/usage`) rather than
+bundling or serving `gui/dist` itself. A hidden login launch retains the small bundled ready surface
+until a person explicitly opens the dashboard. The page renders what the shell tells it and probes
+nothing on its own; it asks
 `startup_phases` for the state list rather than restating it, takes the current state from
 `startup_snapshot` on load because the first states finish in milliseconds, and then follows the
 `startup-phase` event. `startup_snapshot` always answers with a state; it used to be able to
@@ -74,6 +76,15 @@ manual launch shows its window before the sequence begins, a login launch after
 Registering happens once per process, so a retry re-runs only the runtime half and cannot build a
 second tray icon with its own refresh loop.
 
+A hidden login launch does not preload the full dashboard after Ready. `finish` keeps the bundled
+startup surface while the main window remains hidden; Open Dashboard, a second ordinary app launch,
+and the shell's explicit open command all pass through `startup::open_dashboard`, which performs the
+one lazy navigation before showing the window. A no-tray login launch is already visible and keeps
+the eager behavior, as does every manual launch. If a person opens during startup, the bootstrap is
+shown immediately and the successful `finish` observes that visibility and navigates then.
+
+> Decision record: [ADR-5494](decisions/ADR-5494-lightweight-background-startup.md)
+
 `desktop/src-tauri/src/exit.rs` owns what ends the process. Where there is a usable tray, closing
 the window and the platform's quit gesture both hide; only the tray's Quit asks to end, and an
 installed update asks for a coordinated restart. Where there is no usable tray, closing the window

tests/clients/desktop-startup-surface.test.ts

@@ -159,6 +159,28 @@ describe("desktop startup surface", () => {
     expect(page).toContain("progress.failedPhase");
   });
 
+  test("a hidden login launch keeps the lightweight surface until an explicit open", () => {
+    const finish = startup.slice(
+      startup.indexOf("fn finish("),
+      startup.indexOf("pub fn diagnostic("),
+    );
+    expect(finish).toContain("loads_dashboard_on_ready(LaunchOrigin::detect(), visible)");
+    expect(finish).toContain("window.is_visible()");
+    expect(finish).toContain("pub fn open_dashboard(");
+    expect(finish).toContain("progress.phase == Phase::Ready.id()");
+    expect(finish).toContain("startup.should_navigate_dashboard()");
+    expect(finish).toContain("crate::window::show(&window)");
+    expect(startup).toContain("fn explicit_dashboard_navigation_is_consumed_once_per_run()");
+    expect(startup).toContain("assert!(startup.should_navigate_dashboard())");
+    expect(startup).toContain("assert!(!startup.should_navigate_dashboard())");
+
+    expect(lib).toContain("startup::open_dashboard(&app)");
+    expect(lib).toContain("startup::open_dashboard(app)");
+    const tray = code(repoPath(`${SRC}/tray.rs`));
+    expect(tray).toContain('"open-dashboard" =>');
+    expect(tray).toContain("crate::startup::open_dashboard(app)");
+  });
+
   test("the snapshot answers with a state rather than with nothing", () => {
     // The page returns early on a falsy progress, so an absent answer was not a neutral one: it
     // was a window frozen on its own markup, with no diagnostic in it and no event coming.