Polish WSL backend settings UX

Jgratton24 · Jgratton24 · commit f241be624a03 · 2026-04-27T11:38:26.000-04:00
- Replace the native &lt;select&gt; for distro selection with the design
  system's &lt;Select&gt; component (built on @base-ui/react/select), used
  elsewhere in settings. Fixes the slightly off-axis chevron and matches
  the dropdown styling of the rest of the panel.

- Stop disabling the distro dropdown when WSL is off. The selection now
  stages locally (stagedDesktopWslDistro) without hitting the backend;
  flipping the toggle on uses the staged value as the new distro, while
  changes made while WSL is already enabled still go through the existing
  confirmation dialog. A useEffect mirrors the saved distro into the
  staged value on first load and whenever WSL is enabled.

- Wire reauthenticatePrimaryEnvironment() into handleDesktopWslChange
  so the renderer re-exchanges the desktop bootstrap token for a session
  cookie signed by the new backend before any WS reconnect attempts. The
  call sits inside suppressWsConnectionLifecycle alongside the descriptor
  refresh so its 401-then-200 doesn't briefly surface as a connection
  hiccup in the UI.

- Track a desktopWslChangeStage ('restarting-backend' / 'reauthenticating')
  so the dialog button reads "Restarting backend…" then "Re-establishing
  session…" instead of a single static "Restarting…" — gives the user
  feedback during the longer cold-launch path.

- Expand the confirmation copy: set the time expectation ("can take up
  to 30 seconds the first time") and clarify that each backend keeps its
  own threads, so the previous list isn't gone — it returns when you
  switch back.
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1,5 +1,6 @@
 import { PlusIcon, QrCodeIcon } from "lucide-react";
-import { memo, useCallback, useEffect, useMemo, useState } from "react";
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useLocation, useNavigate } from "@tanstack/react-router";
 import {
   type AuthClientSession,
   type AuthPairingLink,
@@ -41,6 +42,7 @@ import {
 } from "../ui/alert-dialog";
 import { Popover, PopoverPopup, PopoverTrigger } from "../ui/popover";
 import { QRCodeSvg } from "../ui/qr-code";
+import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "../ui/select";
 import { Spinner } from "../ui/spinner";
 import { Switch } from "../ui/switch";
 import { stackedThreadToast, toastManager } from "../ui/toast";
@@ -51,6 +53,9 @@ import { setPairingTokenOnUrl } from "../../pairingUrl";
 import {
   createServerPairingCredential,
   fetchSessionState,
+  reauthenticatePrimaryEnvironment,
+  refreshPrimaryEnvironmentDescriptor,
+  readPrimaryEnvironmentDescriptor,
   revokeOtherServerClientSessions,
   revokeServerClientSession,
   revokeServerPairingLink,
@@ -69,6 +74,7 @@ import {
   reconnectSavedEnvironment,
   removeSavedEnvironment,
 } from "~/environments/runtime";
+import { suppressWsConnectionLifecycle } from "~/rpc/wsConnectionState";
 
 const accessTimestampFormatter = new Intl.DateTimeFormat(undefined, {
   dateStyle: "medium",
@@ -758,6 +764,8 @@ function SavedBackendListRow({
 }
 
 export function ConnectionsSettings() {
+  const navigate = useNavigate();
+  const pathname = useLocation({ select: (location) => location.pathname });
   const desktopBridge = window.desktopBridge;
   const [currentSessionRole, setCurrentSessionRole] = useState<"owner" | "client" | null>(
     desktopBridge ? "owner" : null,
@@ -781,6 +789,9 @@ export function ConnectionsSettings() {
   const [desktopWslDistros, setDesktopWslDistros] = useState<DesktopWslDistro[]>([]);
   const [desktopWslError, setDesktopWslError] = useState<string | null>(null);
   const [isUpdatingDesktopWsl, setIsUpdatingDesktopWsl] = useState(false);
+  const [desktopWslChangeStage, setDesktopWslChangeStage] = useState<
+    "restarting-backend" | "reauthenticating" | null
+  >(null);
   const [desktopPairingLinks, setDesktopPairingLinks] = useState<
     ReadonlyArray<ServerPairingLinkRecord>
   >([]);
@@ -816,12 +827,49 @@ export function ConnectionsSettings() {
   const [pendingDesktopServerExposureMode, setPendingDesktopServerExposureMode] = useState<
     DesktopServerExposureState["mode"] | null
   >(null);
+  const [pendingDesktopWslConfig, setPendingDesktopWslConfig] = useState<DesktopWslConfig | null>(
+    null,
+  );
+  // When WSL is off, the dropdown stages a distro choice locally (no backend hit) until
+  // the user flips the toggle on. When WSL is on, dropdown changes flow through the
+  // confirmation dialog like before.
+  const [stagedDesktopWslDistro, setStagedDesktopWslDistro] = useState<string | null>(null);
+  const stagedDesktopWslDistroInitializedRef = useRef(false);
   const canManageLocalBackend = currentSessionRole === "owner";
   const isLocalBackendNetworkAccessible = desktopBridge
     ? desktopServerExposureState?.mode === "network-accessible"
     : currentAuthPolicy === "remote-reachable";
-  const defaultDesktopWslDistro = desktopWslDistros.find((distro) => distro.isDefault)?.name ?? null;
-  const selectedDesktopWslDistro = desktopWslConfig?.distro ?? defaultDesktopWslDistro;
+  const defaultDesktopWslDistro =
+    desktopWslDistros.find((distro) => distro.isDefault)?.name ?? null;
+  const effectiveDesktopWslDistro = desktopWslConfig?.enabled
+    ? (desktopWslConfig.distro ?? null)
+    : stagedDesktopWslDistro;
+  const selectedDesktopWslDistro = effectiveDesktopWslDistro ?? defaultDesktopWslDistro;
+  const displayedDesktopWslDistroValue =
+    effectiveDesktopWslDistro === defaultDesktopWslDistro ? "" : (effectiveDesktopWslDistro ?? "");
+  const selectableDesktopWslDistros = desktopWslDistros.filter(
+    (distro) => distro.name !== defaultDesktopWslDistro,
+  );
+
+  const normalizeDesktopWslConfig = useCallback(
+    (config: DesktopWslConfig): DesktopWslConfig => ({
+      enabled: config.enabled,
+      distro: config.distro === defaultDesktopWslDistro ? null : config.distro,
+    }),
+    [defaultDesktopWslDistro],
+  );
+
+  const leaveCurrentPrimaryThreadRoute = useCallback(async () => {
+    const primaryEnvironmentId = readPrimaryEnvironmentDescriptor()?.environmentId ?? null;
+    if (!primaryEnvironmentId) {
+      return;
+    }
+
+    const routeEnvironmentId = pathname.split("/").filter(Boolean)[0] ?? null;
+    if (routeEnvironmentId === primaryEnvironmentId) {
+      await navigate({ to: "/", replace: true });
+    }
+  }, [navigate, pathname]);
 
   const handleDesktopServerExposureChange = useCallback(
     async (checked: boolean) => {
@@ -863,19 +911,30 @@ export function ConnectionsSettings() {
     async (nextConfig: DesktopWslConfig) => {
       if (!desktopBridge) return;
       setIsUpdatingDesktopWsl(true);
+      setDesktopWslChangeStage("restarting-backend");
       setDesktopWslError(null);
       try {
-        const updated = await desktopBridge.wslSetConfig(nextConfig);
-        if (!updated) {
-          throw new Error("The WSL backend configuration was rejected.");
-        }
-        setDesktopWslConfig(nextConfig);
+        const normalizedConfig = normalizeDesktopWslConfig(nextConfig);
+        await leaveCurrentPrimaryThreadRoute();
+        await suppressWsConnectionLifecycle(async () => {
+          const updated = await desktopBridge.wslSetConfig(normalizedConfig);
+          if (!updated) {
+            throw new Error("The WSL backend configuration was rejected.");
+          }
+          setDesktopWslChangeStage("reauthenticating");
+          await refreshPrimaryEnvironmentDescriptor();
+          // Each backend signs sessions with its own key, so the OLD cookie is rejected
+          // by the new backend (401). Re-bootstrap before any WS reconnect attempts.
+          await reauthenticatePrimaryEnvironment();
+        });
+        setDesktopWslConfig(normalizedConfig);
+        setPendingDesktopWslConfig(null);
         toastManager.add({
           type: "success",
           title: "Backend restarted",
-          description: nextConfig.enabled
-            ? "The local backend is now launching inside WSL."
-            : "The local backend is now launching on Windows.",
+          description: normalizedConfig.enabled
+            ? "The local backend is running inside WSL."
+            : "The local backend is running on Windows.",
         });
       } catch (error) {
         const message =
@@ -890,11 +949,17 @@ export function ConnectionsSettings() {
         );
       } finally {
         setIsUpdatingDesktopWsl(false);
+        setDesktopWslChangeStage(null);
       }
     },
-    [desktopBridge],
+    [desktopBridge, leaveCurrentPrimaryThreadRoute, normalizeDesktopWslConfig],
   );
 
+  const handleConfirmDesktopWslChange = useCallback(() => {
+    if (pendingDesktopWslConfig === null) return;
+    void handleDesktopWslChange(pendingDesktopWslConfig);
+  }, [handleDesktopWslChange, pendingDesktopWslConfig]);
+
   const handleRevokeDesktopPairingLink = useCallback(async (id: string) => {
     setRevokingDesktopPairingLinkId(id);
     setDesktopAccessManagementError(null);
@@ -1197,6 +1262,18 @@ export function ConnectionsSettings() {
       cancelled = true;
     };
   }, [desktopBridge]);
+
+  // Mirror the saved distro into the staged value on first load and whenever WSL is
+  // enabled — that way the dropdown shows the live choice while WSL is on, and falls
+  // back to the most-recent saved choice when the user toggles off. Once the user
+  // overrides the staged value while WSL is off, we leave it alone.
+  useEffect(() => {
+    if (!desktopWslConfig) return;
+    if (!stagedDesktopWslDistroInitializedRef.current || desktopWslConfig.enabled) {
+      setStagedDesktopWslDistro(desktopWslConfig.distro);
+      stagedDesktopWslDistroInitializedRef.current = true;
+    }
+  }, [desktopWslConfig]);
   const visibleDesktopPairingLinks = useMemo(
     () => desktopPairingLinks.filter((pairingLink) => pairingLink.role === "client"),
     [desktopPairingLinks],
@@ -1335,43 +1412,128 @@ export function ConnectionsSettings() {
                   ) : null
                 }
                 control={
-                  <div className="flex items-center gap-2">
-                    <select
-                      className="h-8 rounded-md border border-input bg-background px-2 text-sm"
-                      value={desktopWslConfig?.distro ?? ""}
-                      disabled={
-                        !desktopWslConfig || desktopWslDistros.length === 0 || isUpdatingDesktopWsl
-                      }
-                      onChange={(event) => {
-                        void handleDesktopWslChange({
-                          enabled: desktopWslConfig?.enabled ?? false,
-                          distro: event.currentTarget.value || null,
-                        });
-                      }}
-                      aria-label="Select WSL distribution"
-                    >
-                      <option value="">Default distro</option>
-                      {desktopWslDistros.map((distro) => (
-                        <option key={distro.name} value={distro.name}>
-                          {distro.name}
-                          {distro.isDefault ? " (default)" : ""}
-                        </option>
-                      ))}
-                    </select>
-                    <Switch
-                      checked={desktopWslConfig?.enabled ?? false}
-                      disabled={
-                        !desktopWslConfig || desktopWslDistros.length === 0 || isUpdatingDesktopWsl
-                      }
-                      onCheckedChange={(checked) => {
-                        void handleDesktopWslChange({
-                          enabled: checked,
-                          distro: desktopWslConfig?.distro ?? null,
-                        });
-                      }}
-                      aria-label="Enable WSL backend"
-                    />
-                  </div>
+                  <AlertDialog
+                    open={pendingDesktopWslConfig !== null}
+                    onOpenChange={(open) => {
+                      if (isUpdatingDesktopWsl) return;
+                      if (!open) setPendingDesktopWslConfig(null);
+                    }}
+                  >
+                    <div className="flex items-center gap-2">
+                      <Select
+                        value={displayedDesktopWslDistroValue}
+                        onValueChange={(value) => {
+                          const nextDistro = value || null;
+                          const normalizedDistro =
+                            nextDistro === defaultDesktopWslDistro ? null : nextDistro;
+                          if (!desktopWslConfig?.enabled) {
+                            setStagedDesktopWslDistro(normalizedDistro);
+                            return;
+                          }
+                          if (normalizedDistro === desktopWslConfig.distro) return;
+                          setPendingDesktopWslConfig({
+                            enabled: true,
+                            distro: normalizedDistro,
+                          });
+                        }}
+                      >
+                        <SelectTrigger
+                          size="sm"
+                          className="w-44"
+                          aria-label="Select WSL distribution"
+                          disabled={
+                            !desktopWslConfig ||
+                            desktopWslDistros.length === 0 ||
+                            isUpdatingDesktopWsl
+                          }
+                        >
+                          <SelectValue>
+                            {effectiveDesktopWslDistro &&
+                            effectiveDesktopWslDistro !== defaultDesktopWslDistro
+                              ? effectiveDesktopWslDistro
+                              : defaultDesktopWslDistro
+                                ? `${defaultDesktopWslDistro} (default)`
+                                : "WSL default"}
+                          </SelectValue>
+                        </SelectTrigger>
+                        <SelectPopup align="end" alignItemWithTrigger={false}>
+                          <SelectItem hideIndicator value="">
+                            {defaultDesktopWslDistro
+                              ? `${defaultDesktopWslDistro} (default)`
+                              : "WSL default"}
+                          </SelectItem>
+                          {selectableDesktopWslDistros.map((distro) => (
+                            <SelectItem key={distro.name} hideIndicator value={distro.name}>
+                              {distro.name}
+                            </SelectItem>
+                          ))}
+                        </SelectPopup>
+                      </Select>
+                      <Switch
+                        checked={desktopWslConfig?.enabled ?? false}
+                        disabled={
+                          !desktopWslConfig ||
+                          desktopWslDistros.length === 0 ||
+                          isUpdatingDesktopWsl
+                        }
+                        onCheckedChange={(checked) => {
+                          if (!desktopWslConfig) return;
+                          const distro = checked
+                            ? stagedDesktopWslDistro
+                            : (desktopWslConfig.distro ?? null);
+                          setPendingDesktopWslConfig(
+                            normalizeDesktopWslConfig({ enabled: checked, distro }),
+                          );
+                        }}
+                        aria-label="Enable WSL backend"
+                      />
+                    </div>
+                    <AlertDialogPopup>
+                      <AlertDialogHeader>
+                        <AlertDialogTitle>
+                          {pendingDesktopWslConfig?.enabled
+                            ? desktopWslConfig?.enabled
+                              ? "Switch WSL distro?"
+                              : "Enable WSL backend?"
+                            : "Disable WSL backend?"}
+                        </AlertDialogTitle>
+                        <AlertDialogDescription>
+                          {pendingDesktopWslConfig?.enabled
+                            ? `T3 Code will restart the local backend inside ${
+                                pendingDesktopWslConfig.distro ??
+                                defaultDesktopWslDistro ??
+                                "the WSL default distro"
+                              }. This can take up to 30 seconds the first time. Each backend keeps its own threads — your Windows threads stay where they are and will return when you switch back.`
+                            : "T3 Code will restart the local backend on Windows. This can take up to 30 seconds. Each backend keeps its own threads — your WSL threads stay where they are and will return when you switch back."}
+                        </AlertDialogDescription>
+                      </AlertDialogHeader>
+                      <AlertDialogFooter>
+                        <AlertDialogClose
+                          disabled={isUpdatingDesktopWsl}
+                          render={<Button variant="outline" disabled={isUpdatingDesktopWsl} />}
+                        >
+                          Cancel
+                        </AlertDialogClose>
+                        <Button
+                          onClick={handleConfirmDesktopWslChange}
+                          disabled={pendingDesktopWslConfig === null || isUpdatingDesktopWsl}
+                        >
+                          {isUpdatingDesktopWsl ? (
+                            <>
+                              <Spinner className="size-3.5" />
+                              {desktopWslChangeStage === "reauthenticating"
+                                ? "Re-establishing session…"
+                                : "Restarting backend…"}
+                            </>
+                          ) : pendingDesktopWslConfig?.enabled ? (
+                            "Restart in WSL"
+                          ) : (
+                            "Restart on Windows"
+                          )}
+                        </Button>
+                      </AlertDialogFooter>
+                    </AlertDialogPopup>
+                  </AlertDialog>
                 }
               />
             ) : null}
