feat(preview): viewers show the host setup command, ready to copy

When the server's browser needs host setup, web shows the exact command in
a copyable command block with Try again, and mobile shows it with a copy
action. The onboarding wizard's command block moves to a shared component
for this.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: juliusmarminge

apps/mobile/src/features/browser/PreviewStreamWebView.tsx

@@ -1,12 +1,13 @@
 import previewStreamScript from "@t3tools/mobile-preview-stream";
 import {
   previewStreamControlLabel,
+  previewStreamHostSetupMessage,
   type PreviewStreamControl,
   type PreviewStreamDownload,
   type PreviewStreamFileChooser,
   type PreviewStreamInput,
 } from "@t3tools/client-runtime/preview/server-browser-stream";
-import type { EnvironmentId } from "@t3tools/contracts";
+import type { EnvironmentId, PreviewStreamHostSetup } from "@t3tools/contracts";
 import {
   useEffect,
   useEffectEvent,
@@ -252,6 +253,7 @@ function PreviewStreamDocumentView({
   const [status, setStatus] = useState<"connecting" | "streaming" | "error">("connecting");
   const [error, setError] = useState<string | null>(null);
   const [gone, setGone] = useState(false);
+  const [hostSetup, setHostSetup] = useState<PreviewStreamHostSetup | null>(null);
   const [started, setStarted] = useState(false);
   const [control, setControl] = useState<PreviewStreamControl | null>(null);
   const [promptText, setPromptText] = useState("");
@@ -384,6 +386,10 @@ function PreviewStreamDocumentView({
               fail("This tab was closed.");
               onGone?.();
               return;
+            case "hostSetup":
+              setHostSetup({ need: message.need, command: message.command });
+              fail(previewStreamHostSetupMessage(message));
+              return;
             case "viewport":
               onViewport?.(message);
               return;
@@ -495,13 +501,30 @@ function PreviewStreamDocumentView({
               {status === "error" ? error : "Connecting to browser..."}
             </AppText>
           )}
+          {status === "error" && hostSetup && !compact ? (
+            <Pressable
+              accessibilityRole="button"
+              accessibilityLabel={`Copy ${hostSetup.command}`}
+              className="w-full flex-row items-center gap-2 rounded-xl border border-secondary-border bg-secondary px-4 py-3"
+              onPress={() => {
+                void Clipboard.setStringAsync(hostSetup.command).catch(() => undefined);
+              }}
+            >
+              <AppText selectable className="flex-1 font-mono text-sm text-secondary-foreground">
+                {hostSetup.command}
+              </AppText>
+              <AppText className="text-xs text-foreground-muted">Copy</AppText>
+            </Pressable>
+          ) : null}
           {status === "error" && !gone && !compact ? (
             <Pressable
               accessibilityRole="button"
               className="rounded-full border border-secondary-border bg-secondary px-6 py-3"
               onPress={onRetry}
             >
-              <AppText className="text-secondary-foreground">Reconnect</AppText>
+              <AppText className="text-secondary-foreground">
+                {hostSetup ? "Try again" : "Reconnect"}
+              </AppText>
             </Pressable>
           ) : null}
         </View>

apps/mobile/src/features/browser/preview-stream-document.ts

@@ -1,4 +1,5 @@
 import type { DeviceHubAccess } from "@t3tools/client-runtime/device/hub-access";
+import type { PreviewStreamHostSetup } from "@t3tools/contracts";
 import type {
   PreviewStreamControl,
   PreviewStreamDownload,
@@ -24,6 +25,7 @@ export type PreviewStreamMessage =
     }
   | { readonly type: "unauthorized" }
   | { readonly type: "gone" }
+  | ({ readonly type: "hostSetup" } & PreviewStreamHostSetup)
   | { readonly type: "viewport"; readonly width: number; readonly height: number }
   | { readonly type: "clipboard"; readonly text: string }
   | ({ readonly type: "download" } & PreviewStreamDownload)

apps/mobile/src/features/browser/preview-stream.browser.ts

@@ -1,7 +1,6 @@
 import {
   createPreviewFramePainter,
   createPreviewStreamClient,
-  previewStreamHostSetupMessage,
   previewStreamModifiers,
   type PreviewStreamClient,
   type PreviewStreamControl,
@@ -234,8 +233,7 @@ export function start(configuration: PreviewStreamConfiguration) {
         },
         onUnauthorized: () => post({ type: "unauthorized" }),
         onGone: () => post({ type: "gone" }),
-        onHostSetup: (setup) =>
-          post({ type: "status", status: "error", detail: previewStreamHostSetupMessage(setup) }),
+        onHostSetup: (setup) => post({ type: "hostSetup", ...setup }),
       },
     );
     client = next;

apps/web/src/browser/ServerBrowserSurface.tsx

@@ -35,6 +35,7 @@ import {
 } from "react";
 
 import { AgentCursorMark } from "~/components/preview/AgentBrowserCursor";
+import { CommandBlock } from "~/components/CommandBlock";
 import { Button } from "~/components/ui/button";
 import { Input } from "~/components/ui/input";
 import { toastManager } from "~/components/ui/toast";
@@ -868,10 +869,11 @@ export function ServerBrowserSurface(props: {
         ) : null}
       </div>
       {visible && hostSetup ? (
-        <div className="visible absolute inset-0 z-20 flex flex-col items-center justify-center gap-2 bg-background p-3 text-center">
-          <p role="alert" className="max-w-sm text-xs text-muted-foreground">
+        <div className="visible absolute inset-0 z-20 flex flex-col items-center justify-center gap-3 bg-background p-4 text-center">
+          <p role="alert" className="max-w-sm text-sm text-muted-foreground">
             {previewStreamHostSetupMessage(hostSetup)}
           </p>
+          <CommandBlock command={hostSetup.command} className="w-full max-w-md text-left" />
           <Button variant="outline" size="sm" onClick={() => setHostSetup(null)}>
             Try again
           </Button>

apps/web/src/components/CommandBlock.tsx

@@ -0,0 +1,45 @@
+import { Check, Copy } from "lucide";
+
+import { MorphIcon } from "~/components/MorphIcon";
+import { useCopyToClipboard } from "~/hooks/useCopyToClipboard";
+import { cn } from "~/lib/utils";
+
+import { Button } from "./ui/button";
+
+/** A shell command to copy and run elsewhere, such as on the environment's host. */
+export function CommandBlock({
+  command,
+  className,
+  prominent = false,
+}: {
+  readonly command: string;
+  readonly className?: string;
+  readonly prominent?: boolean;
+}) {
+  const { copyToClipboard, isCopied } = useCopyToClipboard({
+    timeout: 1500,
+    target: "command",
+  });
+  return (
+    <div
+      className={cn(
+        "flex items-center justify-between gap-3 rounded-lg border border-border bg-muted/50 font-mono",
+        prominent ? "px-4 py-3.5 text-base" : "px-3 py-2.5 text-sm",
+        className,
+      )}
+    >
+      <span className="min-w-0 truncate">
+        <span className="mr-2 text-muted-foreground">$</span>
+        {command}
+      </span>
+      <Button
+        size="icon-xs"
+        variant="ghost"
+        aria-label="Copy command"
+        onClick={() => copyToClipboard(command, undefined)}
+      >
+        <MorphIcon className="size-3.5" icon={isCopied ? Check : Copy} />
+      </Button>
+    </div>
+  );
+}

apps/web/src/components/onboarding/WelcomeWizard.tsx

@@ -30,7 +30,6 @@ import {
   MonitorIcon,
   TerminalIcon,
 } from "lucide-react";
-import { Check, Copy } from "lucide";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
 import { TYPOGRAPHY_ADVANCED_STORAGE_KEY } from "../../appearanceFonts";
@@ -52,7 +51,6 @@ import {
   resolveOnboardingProviderLoginCommand,
   selectOnboardingProvidersByDriver,
 } from "../../onboarding/providerReadiness.logic";
-import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { newProjectId, randomUUID } from "../../lib/utils";
 import { agentSessionImport } from "../../state/agentSessions";
 import { readProjects, useProjects } from "../../state/entities";
@@ -76,8 +74,8 @@ import { ProviderInstanceIcon } from "../chat/ProviderInstanceIcon";
 import { T3Wordmark } from "../T3Wordmark";
 import { Alert, AlertDescription } from "../ui/alert";
 import { Button } from "../ui/button";
+import { CommandBlock } from "../CommandBlock";
 import { Checkbox } from "../ui/checkbox";
-import { MorphIcon } from "~/components/MorphIcon";
 import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "../ui/collapsible";
 import { Input } from "../ui/input";
 import { Tooltip, TooltipTrigger, TooltipPopup } from "../ui/tooltip";
@@ -1713,40 +1711,3 @@ function StepShell({
     </>
   );
 }
-
-function CommandBlock({
-  command,
-  className,
-  prominent = false,
-}: {
-  readonly command: string;
-  readonly className?: string;
-  readonly prominent?: boolean;
-}) {
-  const { copyToClipboard, isCopied } = useCopyToClipboard({
-    timeout: 1500,
-    target: "command",
-  });
-  return (
-    <div
-      className={cn(
-        "flex items-center justify-between gap-3 rounded-lg border border-border bg-muted/50 font-mono",
-        prominent ? "px-4 py-3.5 text-base" : "px-3 py-2.5 text-sm",
-        className,
-      )}
-    >
-      <span className="min-w-0 truncate">
-        <span className="mr-2 text-muted-foreground">$</span>
-        {command}
-      </span>
-      <Button
-        size="icon-xs"
-        variant="ghost"
-        aria-label="Copy command"
-        onClick={() => copyToClipboard(command, undefined)}
-      >
-        <MorphIcon className="size-3.5" icon={isCopied ? Check : Copy} />
-      </Button>
-    </div>
-  );
-}

packages/client-runtime/src/preview/serverBrowserStream.ts

@@ -368,7 +368,7 @@ export function createPreviewStreamClient(
       }
       if (event.code === PREVIEW_STREAM_HOST_SETUP_CLOSE_CODE) {
         stopped = true;
-        events.onHostSetup?.(event.reason === "libraries" ? "libraries" : "sandbox");
+        events.onHostSetup?.(decodeHostSetup(event.reason));
         return;
       }
       // Rejected upgrades surface as 1006 before open for both cookies and tickets.
@@ -455,8 +455,22 @@ export function createPreviewFramePainter(
   };
 }
 
-/** What a viewer tells the person when the server's browser needs host setup. */
+/** A malformed reason still stops the viewer and offers the usual command. */
+const decodeHostSetup = (reason: string): PreviewStreamHostSetup => {
+  try {
+    const value = JSON.parse(reason) as Partial<PreviewStreamHostSetup>;
+    if (
+      (value.need === "sandbox" || value.need === "libraries") &&
+      typeof value.command === "string"
+    ) {
+      return { need: value.need, command: value.command };
+    }
+  } catch {}
+  return { need: "sandbox", command: "sudo npx t3 browser setup" };
+};
+
+/** What a viewer tells the person; `command` is shown beside it, ready to copy. */
 export const previewStreamHostSetupMessage = (setup: PreviewStreamHostSetup) =>
-  setup === "sandbox"
-    ? "This server's browser needs Chrome's sandbox, which the host blocks. Its operator can allow it with the AppArmor profile in T3 Code's remote access guide, or set T3CODE_SERVER_BROWSER_SANDBOX=0."
-    : "This server's browser is missing system libraries. Its operator can install Chrome's libraries as described in T3 Code's remote access guide.";
+  setup.need === "sandbox"
+    ? "This server's host blocks the sandbox its browser runs in. Run this once on the host, then try again:"
+    : "This server's host is missing libraries its browser needs. Run this once on the host, then try again:";