Refine mobile environment connection flows

- Rename backends to environments across mobile UI
- Add richer loading and empty states for connections, home, and new task flows
- Improve review section loading handling and terminal keyboard layout

Author: juliusmarminge

apps/mobile/src/app/connections/index.tsx

@@ -33,7 +33,7 @@ export default function ConnectionsRouteScreen() {
     <View collapsable={false} className="flex-1 bg-sheet">
       <Stack.Screen
         options={{
-          title: "Backends",
+          title: "Environments",
           headerRight: () => (
             <Link href="/connections/new" asChild>
               <Pressable className="h-10 w-10 items-center justify-center rounded-full bg-primary active:opacity-70">
@@ -53,10 +53,10 @@ export default function ConnectionsRouteScreen() {
         contentInsetAdjustmentBehavior="automatic"
         showsVerticalScrollIndicator={false}
         style={{ flex: 1 }}
+        contentInset={{ bottom: Math.max(insets.bottom, 18) + 18 }}
         contentContainerStyle={{
           paddingHorizontal: 20,
           paddingTop: 16,
-          paddingBottom: Math.max(insets.bottom, 18) + 18,
         }}
       >
         {hasEnvironments ? (
@@ -92,7 +92,7 @@ export default function ConnectionsRouteScreen() {
               />
             </View>
             <Text className="text-center text-[14px] leading-[20px] text-foreground-muted">
-              No backends connected yet.{"\n"}Tap{" "}
+              No environments connected yet.{"\n"}Tap{" "}
               <Text className="font-t3-bold text-foreground">+</Text> to add one.
             </Text>
           </View>

apps/mobile/src/app/connections/new.tsx

@@ -16,11 +16,10 @@ import { buildPairingUrl, parsePairingUrl } from "../../features/connection/pair
 
 export default function ConnectionsNewRouteScreen() {
   const {
-    connectionError,
     connectionPairingUrl,
-    connectionState,
     onChangeConnectionPairingUrl,
     onConnectPress,
+    pairingConnectionError,
   } = useRemoteConnections();
   const router = useRouter();
   const params = useLocalSearchParams<{ mode?: string }>();
@@ -35,8 +34,7 @@ export default function ConnectionsNewRouteScreen() {
   const textColor = useThemeColor("--color-icon");
   const placeholderColor = useThemeColor("--color-placeholder");
 
-  const connectDisabled =
-    isSubmitting || connectionState === "connecting" || hostInput.trim().length === 0;
+  const connectDisabled = isSubmitting || hostInput.trim().length === 0;
 
   useEffect(() => {
     const { host, code } = parsePairingUrl(connectionPairingUrl);
@@ -45,10 +43,10 @@ export default function ConnectionsNewRouteScreen() {
   }, [connectionPairingUrl]);
 
   useEffect(() => {
-    if (connectionError) {
+    if (pairingConnectionError) {
       setIsSubmitting(false);
     }
-  }, [connectionError]);
+  }, [pairingConnectionError]);
 
   const handleHostChange = useCallback((value: string) => {
     setHostInput(value);
@@ -72,7 +70,10 @@ export default function ConnectionsNewRouteScreen() {
       return;
     }
 
-    Alert.alert("Camera access needed", "Allow camera access to scan a backend pairing QR code.");
+    Alert.alert(
+      "Camera access needed",
+      "Allow camera access to scan an environment pairing QR code.",
+    );
   }, [cameraPermission?.granted, requestCameraPermission]);
 
   const closeScanner = useCallback(() => {
@@ -126,7 +127,7 @@ export default function ConnectionsNewRouteScreen() {
     <View collapsable={false} className="flex-1 bg-sheet">
       <Stack.Screen
         options={{
-          title: showScanner ? "Scan QR Code" : "Add Backend",
+          title: showScanner ? "Scan QR Code" : "Add Environment",
           headerRight: () => (
             <Pressable
               className="h-10 w-10 items-center justify-center rounded-full border border-border bg-secondary"
@@ -154,10 +155,10 @@ export default function ConnectionsNewRouteScreen() {
         contentInsetAdjustmentBehavior="automatic"
         showsVerticalScrollIndicator={false}
         style={{ flex: 1 }}
+        contentInset={{ bottom: Math.max(insets.bottom, 18) + 18 }}
         contentContainerStyle={{
           paddingHorizontal: 20,
           paddingTop: 16,
-          paddingBottom: Math.max(insets.bottom, 18) + 18,
         }}
       >
         <View collapsable={false} className="gap-5">
@@ -231,13 +232,11 @@ export default function ConnectionsNewRouteScreen() {
                 />
               </View>
 
-              {connectionError ? <ErrorBanner message={connectionError} /> : null}
+              {pairingConnectionError ? <ErrorBanner message={pairingConnectionError} /> : null}
 
               <ConnectionSheetButton
                 icon="plus"
-                label={
-                  isSubmitting || connectionState === "connecting" ? "Pairing..." : "Add backend"
-                }
+                label={isSubmitting ? "Pairing..." : "Add environment"}
                 disabled={connectDisabled}
                 tone="primary"
                 onPress={() => {

apps/mobile/src/app/index.tsx

@@ -1,23 +1,50 @@
 import { Stack, useRouter } from "expo-router";
-import { useState } from "react";
-import { Text as RNText, View, useColorScheme } from "react-native";
+import { type ComponentProps, useState } from "react";
+import { Pressable, Text as RNText, View, useColorScheme } from "react-native";
+import { SymbolView } from "expo-symbols";
 import { useThemeColor } from "../lib/useThemeColor";
 
 import { buildThreadRoutePath } from "../lib/routes";
 import { useRemoteCatalog } from "../state/use-remote-catalog";
 import { useRemoteEnvironmentState } from "../state/use-remote-environment-registry";
 import { HomeScreen } from "../features/home/HomeScreen";
+import type { RemoteCatalogState } from "../state/use-remote-catalog";
+
+function resolveHeaderStatus(state: RemoteCatalogState): {
+  readonly icon: ComponentProps<typeof SymbolView>["name"];
+  readonly color: string;
+  readonly label: string;
+} {
+  if (state.isLoadingSavedConnections) {
+    return { icon: "hourglass", color: "#737373", label: "Loading environments" };
+  }
+  if (state.connectionError) {
+    return { icon: "exclamationmark.triangle.fill", color: "#ef4444", label: "Environment error" };
+  }
+  if (state.connectionState === "ready") {
+    return { icon: "checkmark.circle.fill", color: "#22c55e", label: "Environment online" };
+  }
+  if (state.connectionState === "connecting" || state.connectionState === "reconnecting") {
+    return {
+      icon: "arrow.triangle.2.circlepath",
+      color: "#f59e0b",
+      label: "Environment connecting",
+    };
+  }
+  return { icon: "wifi.slash", color: "#ef4444", label: "Environment offline" };
+}
 
 /* ─── Route screen ───────────────────────────────────────────────────── */
 
 export default function HomeRouteScreen() {
-  const { projects, threads } = useRemoteCatalog();
+  const { projects, state: catalogState, threads } = useRemoteCatalog();
   const { savedConnectionsById } = useRemoteEnvironmentState();
   const router = useRouter();
   const [searchQuery, setSearchQuery] = useState("");
 
   const isDark = useColorScheme() === "dark";
   const iconColor = String(useThemeColor("--color-icon"));
+  const status = resolveHeaderStatus(catalogState);
 
   return (
     <>
@@ -78,11 +105,15 @@ export default function HomeRouteScreen() {
       </Stack.Toolbar>
 
       <Stack.Toolbar placement="right">
-        <Stack.Toolbar.Button
-          icon="network"
-          onPress={() => router.push("/connections")}
-          separateBackground
-        />
+        <Stack.Toolbar.View hidesSharedBackground>
+          <Pressable
+            accessibilityLabel={status.label}
+            className="h-11 w-11 items-center justify-center rounded-full bg-card active:opacity-70"
+            onPress={() => router.push("/connections")}
+          >
+            <SymbolView name={status.icon} size={21} tintColor={status.color} type="monochrome" />
+          </Pressable>
+        </Stack.Toolbar.View>
       </Stack.Toolbar>
 
       {/* Bottom toolbar: search + compose, visually split like iMessage */}
@@ -99,8 +130,10 @@ export default function HomeRouteScreen() {
       <HomeScreen
         projects={projects}
         threads={threads}
+        catalogState={catalogState}
         savedConnectionsById={savedConnectionsById}
         searchQuery={searchQuery}
+        onAddConnection={() => router.push("/connections/new")}
         onSelectThread={(thread) => {
           router.push(buildThreadRoutePath(thread));
         }}

apps/mobile/src/app/new/index.tsx

@@ -1,22 +1,74 @@
-import { Link, Stack } from "expo-router";
+import { Link, Stack, useRouter } from "expo-router";
 import { SymbolView } from "expo-symbols";
 import type { EnvironmentId, ProjectId } from "@t3tools/contracts";
 import { useMemo } from "react";
-import { Pressable, ScrollView, View } from "react-native";
+import { ActivityIndicator, Pressable, ScrollView, View } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { useThemeColor } from "../../lib/useThemeColor";
 
 import { AppText as Text } from "../../components/AppText";
 import { ProjectFavicon } from "../../components/ProjectFavicon";
 import { groupProjectsByRepository } from "../../lib/repositoryGroups";
-import { useRemoteCatalog } from "../../state/use-remote-catalog";
+import { type RemoteCatalogState, useRemoteCatalog } from "../../state/use-remote-catalog";
 import { useRemoteEnvironmentState } from "../../state/use-remote-environment-registry";
 
+function deriveProjectEmptyState(catalogState: RemoteCatalogState): {
+  readonly title: string;
+  readonly detail: string;
+  readonly loading: boolean;
+} {
+  if (catalogState.isLoadingSavedConnections) {
+    return {
+      title: "Loading environments",
+      detail: "Checking saved environments on this device.",
+      loading: true,
+    };
+  }
+
+  if (!catalogState.hasSavedConnections) {
+    return {
+      title: "No environments connected",
+      detail: "Add an environment before creating a task.",
+      loading: false,
+    };
+  }
+
+  if (catalogState.connectionState === "disconnected" && !catalogState.hasLoadedShellSnapshot) {
+    return {
+      title: "Environment unavailable",
+      detail:
+        catalogState.connectionError ??
+        "The saved environment is offline. Check the URL or start the environment, then retry.",
+      loading: false,
+    };
+  }
+
+  if (
+    catalogState.hasConnectingEnvironment &&
+    !catalogState.hasLoadedShellSnapshot &&
+    catalogState.connectionError === null
+  ) {
+    return {
+      title: "Connecting to environment",
+      detail: "Loading projects from the saved environment.",
+      loading: true,
+    };
+  }
+
+  return {
+    title: "No projects found",
+    detail: "The connected environment did not report any projects.",
+    loading: false,
+  };
+}
+
 export default function NewTaskRoute() {
-  const { projects, threads } = useRemoteCatalog();
+  const { projects, state: catalogState, threads } = useRemoteCatalog();
   const { savedConnectionsById } = useRemoteEnvironmentState();
+  const router = useRouter();
   const insets = useSafeAreaInsets();
   const chevronColor = useThemeColor("--color-chevron");
+  const accentColor = useThemeColor("--color-icon-muted");
   const borderSubtleColor = useThemeColor("--color-border-subtle");
   const repositoryGroups = useMemo(
     () => groupProjectsByRepository({ projects, threads }),
@@ -45,6 +97,7 @@ export default function NewTaskRoute() {
     }
     return nextItems;
   }, [repositoryGroups]);
+  const projectEmptyState = deriveProjectEmptyState(catalogState);
 
   return (
     <View collapsable={false} className="flex-1 bg-sheet">
@@ -65,17 +118,31 @@ export default function NewTaskRoute() {
       <ScrollView
         showsVerticalScrollIndicator={false}
         style={{ flex: 1 }}
+        contentInset={{ bottom: Math.max(insets.bottom, 18) + 18 }}
         contentContainerStyle={{
           paddingHorizontal: 20,
           paddingTop: 8,
-          paddingBottom: Math.max(insets.bottom, 18) + 18,
         }}
       >
         {items.length === 0 ? (
-          <View collapsable={false} className="items-center rounded-[24px] bg-card px-6 py-8">
-            <Text className="text-[16px] font-medium text-foreground-muted">
-              Loading projects...
+          <View collapsable={false} className="items-center gap-3 rounded-[24px] bg-card px-6 py-8">
+            {projectEmptyState.loading ? <ActivityIndicator color={accentColor} /> : null}
+            <Text className="text-center text-[17px] font-t3-bold text-foreground">
+              {projectEmptyState.title}
+            </Text>
+            <Text className="text-center text-[14px] leading-[20px] text-foreground-muted">
+              {projectEmptyState.detail}
             </Text>
+            {!catalogState.hasReadyEnvironment ? (
+              <Pressable
+                className="mt-1 rounded-full bg-primary px-4 py-2.5 active:opacity-70"
+                onPress={() => router.push("/connections/new")}
+              >
+                <Text className="text-[13px] font-t3-bold text-primary-foreground">
+                  Add environment
+                </Text>
+              </Pressable>
+            ) : null}
           </View>
         ) : (
           <View collapsable={false} className="overflow-hidden rounded-[24px] bg-card">

apps/mobile/src/components/EmptyState.tsx

@@ -1,14 +1,29 @@
-import { View } from "react-native";
+import { Pressable, View } from "react-native";
 
 import { AppText as Text } from "./AppText";
 
-export function EmptyState(props: { readonly title: string; readonly detail: string }) {
+export function EmptyState(props: {
+  readonly title: string;
+  readonly detail: string;
+  readonly actionLabel?: string;
+  readonly onAction?: () => void;
+}) {
   return (
     <View className="rounded-[22px] border border-border bg-card p-5">
       <Text className="font-t3-bold text-lg text-foreground">{props.title}</Text>
       <Text className="mt-2 font-sans text-sm leading-[21px] text-foreground-muted">
         {props.detail}
       </Text>
+      {props.actionLabel && props.onAction ? (
+        <Pressable
+          className="mt-4 self-start rounded-full bg-primary px-4 py-2.5 active:opacity-70"
+          onPress={props.onAction}
+        >
+          <Text className="text-[13px] font-t3-bold text-primary-foreground">
+            {props.actionLabel}
+          </Text>
+        </Pressable>
+      ) : null}
     </View>
   );
 }