feat: add production startup loading screen

apps/web/src/components/AppStartupScreen.tsx

@@ -0,0 +1,45 @@
+import { APP_BASE_NAME, APP_STAGE_LABEL } from "../branding";
+import devLogo from "../../../../assets/dev/blueprint.svg";
+import prodLogo from "../../../../assets/prod/logo.svg";
+
+const startupScreenLogo = import.meta.env.DEV ? devLogo : prodLogo;
+
+export function AppStartupScreen({
+  statusMessage = "Starting local backend…",
+}: {
+  readonly statusMessage?: string;
+}) {
+  return (
+    <div className="relative flex min-h-screen w-full items-center justify-center overflow-hidden bg-background px-6 py-10 text-foreground">
+      <div className="pointer-events-none absolute inset-0">
+        <div className="absolute inset-x-0 top-0 h-64 bg-[radial-gradient(40rem_16rem_at_top,color-mix(in_srgb,var(--primary)_18%,transparent),transparent)] opacity-90" />
+        <div className="absolute inset-0 bg-[linear-gradient(145deg,color-mix(in_srgb,var(--background)_94%,var(--color-black))_0%,var(--background)_52%)]" />
+        <div className="absolute inset-0 opacity-[0.035] [background-image:linear-gradient(to_right,var(--border)_1px,transparent_1px),linear-gradient(to_bottom,var(--border)_1px,transparent_1px)] [background-size:2.75rem_2.75rem]" />
+      </div>
+
+      <div className="relative flex flex-col items-center gap-6 text-center">
+        <div className="relative flex size-44 items-center justify-center sm:size-52">
+          <div className="animate-startup-halo absolute inset-0 rounded-full bg-[radial-gradient(circle,color-mix(in_srgb,var(--primary)_34%,transparent)_0%,transparent_70%)] blur-3xl" />
+          <img
+            src={startupScreenLogo}
+            alt={`${APP_BASE_NAME} logo`}
+            className="animate-startup-emblem relative size-32 select-none drop-shadow-[0_24px_80px_color-mix(in_srgb,var(--color-black)_28%,transparent)] sm:size-40"
+            draggable={false}
+          />
+        </div>
+
+        <div className="space-y-2">
+          <div className="flex items-center justify-center gap-2">
+            <span className="text-sm font-semibold tracking-tight text-foreground">
+              {APP_BASE_NAME}
+            </span>
+            <span className="rounded-full border border-border/70 bg-background/65 px-2 py-0.5 text-[10px] font-medium uppercase tracking-[0.18em] text-muted-foreground">
+              {APP_STAGE_LABEL}
+            </span>
+          </div>
+          <p className="text-sm text-muted-foreground">{statusMessage}</p>
+        </div>
+      </div>
+    </div>
+  );
+}

apps/web/src/components/WebSocketConnectionSurface.logic.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, it } from "vitest";
 
 import type { WsConnectionStatus } from "../rpc/wsConnectionState";
-import { shouldAutoReconnect, shouldRestartStalledReconnect } from "./WebSocketConnectionSurface";
+import {
+  shouldAutoReconnect,
+  shouldRestartStalledReconnect,
+  shouldShowProductionStartupLoader,
+} from "./WebSocketConnectionSurface";
 
 function makeStatus(overrides: Partial<WsConnectionStatus> = {}): WsConnectionStatus {
   return {
@@ -110,4 +114,49 @@ describe("WebSocketConnectionSurface.logic", () => {
       ),
     ).toBe(false);
   });
+
+  it("shows the production startup loader during the initial startup grace window", () => {
+    expect(
+      shouldShowProductionStartupLoader({
+        hasConnected: false,
+        startupTimedOut: false,
+        uiState: "connecting",
+      }),
+    ).toBe(!import.meta.env.DEV);
+    expect(
+      shouldShowProductionStartupLoader({
+        hasConnected: false,
+        startupTimedOut: false,
+        uiState: "error",
+      }),
+    ).toBe(!import.meta.env.DEV);
+    expect(
+      shouldShowProductionStartupLoader({
+        hasConnected: false,
+        startupTimedOut: false,
+        uiState: "offline",
+      }),
+    ).toBe(false);
+    expect(
+      shouldShowProductionStartupLoader({
+        hasConnected: true,
+        startupTimedOut: false,
+        uiState: "connecting",
+      }),
+    ).toBe(!import.meta.env.DEV);
+    expect(
+      shouldShowProductionStartupLoader({
+        hasConnected: true,
+        startupTimedOut: false,
+        uiState: "reconnecting",
+      }),
+    ).toBe(false);
+    expect(
+      shouldShowProductionStartupLoader({
+        hasConnected: false,
+        startupTimedOut: true,
+        uiState: "error",
+      }),
+    ).toBe(false);
+  });
 });

apps/web/src/components/WebSocketConnectionSurface.tsx

@@ -13,11 +13,13 @@ import {
   useWsConnectionStatus,
   WS_RECONNECT_MAX_ATTEMPTS,
 } from "../rpc/wsConnectionState";
+import { AppStartupScreen } from "./AppStartupScreen";
 import { Button } from "./ui/button";
 import { toastManager } from "./ui/toast";
 import { getWsRpcClient } from "~/wsRpcClient";
 
 const FORCED_WS_RECONNECT_DEBOUNCE_MS = 5_000;
+const PRODUCTION_STARTUP_SCREEN_TIMEOUT_MS = 30_000;
 type WsAutoReconnectTrigger = "focus" | "online";
 
 const connectionTimeFormatter = new Intl.DateTimeFormat(undefined, {
@@ -195,6 +197,25 @@ function buildConnectionDetails(status: WsConnectionStatus, uiState: WsConnectio
   return details.join("\n");
 }
 
+export function shouldShowProductionStartupLoader({
+  hasConnected,
+  startupTimedOut,
+  uiState,
+}: {
+  readonly hasConnected: boolean;
+  readonly startupTimedOut: boolean;
+  readonly uiState: WsConnectionUiState;
+}): boolean {
+  // Planned local-model support means some users may intentionally stay offline
+  // after install, so known offline state should remain explicit immediately.
+  return (
+    !import.meta.env.DEV &&
+    !startupTimedOut &&
+    uiState !== "offline" &&
+    (!hasConnected || uiState === "connecting")
+  );
+}
+
 function WebSocketBlockingState({
   status,
   uiState,
@@ -532,15 +553,36 @@ export function SlowRpcAckToastCoordinator() {
 export function WebSocketConnectionSurface({ children }: { readonly children: ReactNode }) {
   const serverConfig = useServerConfig();
   const status = useWsConnectionStatus();
+  const [startupTimedOut, setStartupTimedOut] = useState(false);
+
+  useEffect(() => {
+    if (import.meta.env.DEV || serverConfig !== null || startupTimedOut) {
+      return;
+    }
+
+    const timeoutId = window.setTimeout(() => {
+      setStartupTimedOut(true);
+    }, PRODUCTION_STARTUP_SCREEN_TIMEOUT_MS);
+
+    return () => {
+      window.clearTimeout(timeoutId);
+    };
+  }, [serverConfig, startupTimedOut]);
 
   if (serverConfig === null) {
     const uiState = getWsConnectionUiState(status);
-    return (
-      <WebSocketBlockingState
-        status={status}
-        uiState={uiState === "connected" ? "connecting" : uiState}
-      />
-    );
+    const blockingUiState = uiState === "connected" ? "connecting" : uiState;
+    if (
+      shouldShowProductionStartupLoader({
+        hasConnected: status.hasConnected,
+        startupTimedOut,
+        uiState: blockingUiState,
+      })
+    ) {
+      return <AppStartupScreen />;
+    }
+
+    return <WebSocketBlockingState status={status} uiState={blockingUiState} />;
   }
 
   return children;

apps/web/src/index.css

@@ -4,6 +4,8 @@
 
 @theme inline {
   --animate-skeleton: skeleton 2s -1s infinite linear;
+  --animate-startup-emblem: startup-emblem 2.8s ease-in-out infinite;
+  --animate-startup-halo: startup-halo 2.8s ease-in-out infinite;
   --color-warning-foreground: var(--warning-foreground);
   --color-warning: var(--warning);
   --color-success-foreground: var(--success-foreground);
@@ -41,6 +43,28 @@
       background-position: -200% 0;
     }
   }
+  @keyframes startup-emblem {
+    0%,
+    100% {
+      opacity: 0.84;
+      transform: scale(0.96);
+    }
+    50% {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+  @keyframes startup-halo {
+    0%,
+    100% {
+      opacity: 0.12;
+      transform: scale(0.9);
+    }
+    50% {
+      opacity: 0.3;
+      transform: scale(1.08);
+    }
+  }
 }
 
 @layer base {

apps/web/src/routes/__root.tsx

@@ -18,6 +18,7 @@ import { resolveUtilityModelSelectionDefault } from "@t3tools/shared/model";
 
 import { APP_DISPLAY_NAME } from "../branding";
 import { AppSidebarLayout } from "../components/AppSidebarLayout";
+import { AppStartupScreen } from "../components/AppStartupScreen";
 import { DesktopWindowFrame } from "../components/DesktopWindowFrame";
 import {
   SlowRpcAckToastCoordinator,
@@ -72,13 +73,7 @@ function RootRouteView() {
   if (!readNativeApi()) {
     return (
       <DesktopWindowFrame>
-        <div className="flex h-screen flex-col bg-background text-foreground">
-          <div className="flex flex-1 items-center justify-center">
-            <p className="text-sm text-muted-foreground">
-              Connecting to {APP_DISPLAY_NAME} server...
-            </p>
-          </div>
-        </div>
+        <AppStartupScreen />
       </DesktopWindowFrame>
     );
   }