feat(web): the desktop app renders its own server's browser tabs natively

Server tabs of the environment the desktop app launched mount as a
<webview> created with their server tab key, so the desktop offers the
page to the server instead of streaming it back as JPEG frames. Every
other client and environment keeps streaming. The server reports these
tabs' navigation itself, so the desktop stops reporting it.

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

Author: juliusmarminge

apps/web/src/browser/ElectronBrowserHost.tsx

@@ -2,28 +2,37 @@
 
 import { parseScopedThreadKey } from "@t3tools/client-runtime/environment";
 import { FILL_PREVIEW_VIEWPORT } from "@t3tools/contracts";
+import { useAtomValue } from "@effect/atom-react";
 import { useEffect, useMemo } from "react";
 
+import { primaryEnvironmentIdAtom } from "~/state/primaryEnvironment";
+
 import { isElectron } from "~/env";
 import { useTheme } from "~/hooks/useTheme";
 import { useActivePreviewSessions } from "~/previewStateStore";
 
 import { readPreviewAnnotationTheme } from "./annotationTheme";
 import { useBrowserPointerStore } from "./browserPointerStore";
 import { HostedBrowserWebview } from "./HostedBrowserWebview";
+import { rendersServerTabNatively } from "./previewRuntime";
 import { previewRuntimeTabId } from "./previewRuntimeTabId";
 
 export function ElectronBrowserHost() {
   const { resolvedTheme } = useTheme();
   const previewByThreadKey = useActivePreviewSessions();
+  const primaryEnvironmentId = useAtomValue(primaryEnvironmentIdAtom);
   const sessions = useMemo(
     () =>
       Object.entries(previewByThreadKey).flatMap(([threadKey, previewState]) => {
         const threadRef = parseScopedThreadKey(threadKey);
-        // Server tabs stream from the environment and never get a local webview.
+        // Server tabs of other environments stream; this desktop's own server tabs render here.
         return threadRef
           ? Object.values(previewState.sessions)
-              .filter((snapshot) => snapshot.runtime !== "server")
+              .filter(
+                (snapshot) =>
+                  snapshot.runtime !== "server" ||
+                  rendersServerTabNatively(threadRef.environmentId, primaryEnvironmentId, snapshot),
+              )
               .map((snapshot) => ({
                 threadRef,
                 snapshot,
@@ -38,7 +47,7 @@ export function ElectronBrowserHost() {
               }))
           : [];
       }),
-    [previewByThreadKey],
+    [previewByThreadKey, primaryEnvironmentId],
   );
 
   useEffect(() => {
@@ -98,6 +107,7 @@ export function ElectronBrowserHost() {
             pictureInPicture={pictureInPicture}
             profileId={snapshot.profileId}
             zoomFactor={zoomFactor}
+            serverDriven={snapshot.runtime === "server"}
           />
         );
       })}

apps/web/src/browser/HostedBrowserWebview.test.tsx

@@ -174,7 +174,7 @@ describe("HostedBrowserWebview settings hydration", () => {
       await retry;
     });
 
-    expect(acquire).toHaveBeenCalledExactlyOnceWith(runtimeTabId);
+    expect(acquire).toHaveBeenCalledExactlyOnceWith(runtimeTabId, undefined);
     expect(mocks.getPreviewConfig).toHaveBeenCalledExactlyOnceWith(threadRef.environmentId, "work");
     expect(createGuest).toHaveBeenCalledOnce();
     expect(createGuest).toHaveBeenCalledWith(

apps/web/src/browser/HostedBrowserWebview.tsx

@@ -56,6 +56,8 @@ export function HostedBrowserWebview(props: {
    */
   readonly profileId: string | undefined;
   readonly zoomFactor: number;
+  /** A tab of the desktop's own server; the server drives this webview's page. */
+  readonly serverDriven?: boolean;
 }) {
   const {
     threadRef,
@@ -66,6 +68,7 @@ export function HostedBrowserWebview(props: {
     pictureInPicture,
     zoomFactor,
     profileId,
+    serverDriven = false,
   } = props;
   const clientSettingsHydrated = useClientSettingsHydrated();
   const config = usePreviewWebviewConfig(threadRef.environmentId, profileId);
@@ -93,18 +96,21 @@ export function HostedBrowserWebview(props: {
     (state) => (state.activityByTabId[runtimeTabId] ?? 0) > 0,
   );
   const recordingActive = useActiveBrowserRecordingTabIds().has(runtimeTabId);
-  usePreviewBridge({ threadRef, tabId, runtimeTabId });
+  usePreviewBridge({ threadRef, tabId, runtimeTabId, serverDriven });
 
   useEffect(() => {
     if (!clientSettingsHydrated) return;
     crashRecoveryRef.current = INITIAL_WEBVIEW_CRASH_RECOVERY_STATE;
-    const lease = acquireDesktopTab(runtimeTabId);
+    const lease = acquireDesktopTab(
+      runtimeTabId,
+      serverDriven ? { threadId: threadRef.threadId, tabId } : undefined,
+    );
     tabLeaseRef.current = lease;
     return () => {
       if (tabLeaseRef.current === lease) tabLeaseRef.current = null;
       lease.release();
     };
-  }, [clientSettingsHydrated, runtimeTabId]);
+  }, [clientSettingsHydrated, runtimeTabId, serverDriven, tabId, threadRef.threadId]);
 
   const [webviewGeneration, setWebviewGeneration] = useState(0);
   const [recoverySrc, setRecoverySrc] = useState(initialSrc);

apps/web/src/browser/desktopTabLifetime.ts

@@ -36,7 +36,11 @@ export interface AcquiredDesktopTab {
   readonly release: () => void;
 }
 
-export function acquireDesktopTab(tabId: string): AcquiredDesktopTab {
+/** `serverTab` names the server tab this desktop tab renders, so the server can drive it. */
+export function acquireDesktopTab(
+  tabId: string,
+  serverTab?: { readonly threadId: string; readonly tabId: string },
+): AcquiredDesktopTab {
   const current =
     leases.get(tabId) ??
     ({
@@ -45,7 +49,10 @@ export function acquireDesktopTab(tabId: string): AcquiredDesktopTab {
       // Zoom/appearance defaults travel with creation so the guest never
       // paints a frame at 100%/system before the preference is applied.
       ready: enqueueDesktopTabOperation(tabId, async () =>
-        previewBridge?.createTab(tabId, browserDefaultTabState(await resolveBrowserDefaults())),
+        previewBridge?.createTab(tabId, {
+          ...browserDefaultTabState(await resolveBrowserDefaults()),
+          ...(serverTab === undefined ? {} : { serverTab }),
+        }),
       ),
     } satisfies DesktopTabLease);
   if (current.closeTimer !== null) window.clearTimeout(current.closeTimer);

apps/web/src/browser/previewRuntime.ts

@@ -1,6 +1,10 @@
-import type { EnvironmentId, PreviewRuntime } from "@t3tools/contracts";
+import { useAtomValue } from "@effect/atom-react";
+import type { EnvironmentId, PreviewRuntime, PreviewSessionSnapshot } from "@t3tools/contracts";
 
+import { isElectron } from "~/env";
 import { isPreviewSupportedInRuntime } from "~/previewStateStore";
+import { appAtomRegistry } from "~/rpc/atomRegistry";
+import { primaryEnvironmentIdAtom } from "~/state/primaryEnvironment";
 import {
   readEnvironmentSupportsServerBrowser,
   useEnvironmentSupportsServerBrowser,
@@ -19,3 +23,39 @@ export function usePreviewAvailable(environmentId: EnvironmentId | null): boolea
   const serverBrowser = useEnvironmentSupportsServerBrowser(environmentId);
   return isPreviewSupportedInRuntime() || serverBrowser;
 }
+
+/**
+ * Whether this client draws a server tab with its own `<webview>`. The desktop
+ * app renders tabs of the server it launched, which drives them over the
+ * desktop browser channel; every other client and environment streams them.
+ */
+export function rendersServerTabNatively(
+  environmentId: EnvironmentId,
+  primaryEnvironmentId: EnvironmentId | null,
+  snapshot: Pick<PreviewSessionSnapshot, "runtime"> | null | undefined,
+): boolean {
+  return (
+    isElectron &&
+    snapshot?.runtime === "server" &&
+    primaryEnvironmentId !== null &&
+    environmentId === primaryEnvironmentId
+  );
+}
+
+export function readRendersServerTabNatively(
+  environmentId: EnvironmentId,
+  snapshot: Pick<PreviewSessionSnapshot, "runtime"> | null | undefined,
+): boolean {
+  return rendersServerTabNatively(
+    environmentId,
+    appAtomRegistry.get(primaryEnvironmentIdAtom),
+    snapshot,
+  );
+}
+
+export function useRendersServerTabNatively(
+  environmentId: EnvironmentId,
+  snapshot: Pick<PreviewSessionSnapshot, "runtime"> | null | undefined,
+): boolean {
+  return rendersServerTabNatively(environmentId, useAtomValue(primaryEnvironmentIdAtom), snapshot);
+}

apps/web/src/components/preview/PreviewView.tsx

@@ -59,6 +59,7 @@ import { revealInFileExplorerLabel } from "./fileExplorerLabel";
 import { shouldShowPreviewEmptyState } from "./previewEmptyStateLogic";
 import { Badge } from "~/components/ui/badge";
 import { BrowserSurfaceSlot } from "~/browser/BrowserSurfaceSlot";
+import { useRendersServerTabNatively } from "~/browser/previewRuntime";
 import { ServerBrowserSurface, type ServerBrowserHandle } from "~/browser/ServerBrowserSurface";
 import { cn } from "~/lib/utils";
 import { useBrowserSurfaceStore } from "~/browser/browserSurfaceStore";
@@ -152,8 +153,10 @@ export function PreviewView({
         : findActiveBrowserRecordingRuntimeTabId(threadRef, tabId)
       : null;
   const snapshot = tabId ? (previewState.sessions[tabId] ?? null) : null;
-  // Server tabs run in the environment's own browser and stream to any client.
-  const isServerTab = snapshot?.runtime === "server";
+  // Server tabs run in the environment's browser and stream to any client, except the
+  // desktop app's own server's tabs, which render here natively while the server drives them.
+  const nativeServerTab = useRendersServerTabNatively(threadRef.environmentId, snapshot);
+  const isServerTab = snapshot?.runtime === "server" && !nativeServerTab;
   const serverSurfaceRef = useRef<ServerBrowserHandle | null>(null);
   const [serverControlledTabId, setServerControlledTabId] = useState<string | null>(null);
   const serverInputDisabled = isServerTab && serverControlledTabId !== runtimeTabId;

apps/web/src/components/preview/ThreadPreviewMiniPlayer.tsx

@@ -21,6 +21,7 @@ import {
 import { useBrowserSurfaceStore } from "~/browser/browserSurfaceStore";
 import type { BrowserViewportResizeDirection } from "~/browser/browserViewportLayout";
 import { previewRuntimeTabId } from "~/browser/previewRuntimeTabId";
+import { useRendersServerTabNatively } from "~/browser/previewRuntime";
 import { type ServerBrowserHandle, ServerBrowserSurface } from "~/browser/ServerBrowserSurface";
 import {
   closeServerPictureInPicture,
@@ -127,7 +128,8 @@ function BrowserMiniPlayer({ threadRef, tabId, miniPlayer }: Props & { readonly
   const fittedSourceContent = useBrowserSurfaceStore(
     (state) => state.byTabId[runtimeTabId]?.fittedSourceContent ?? null,
   );
-  const serverTab = snapshot?.runtime === "server";
+  const nativeServerTab = useRendersServerTabNatively(threadRef.environmentId, snapshot);
+  const serverTab = snapshot?.runtime === "server" && !nativeServerTab;
   const [streamViewport, setStreamViewport] = useState<PreviewStreamViewport | null>(null);
   const serverSurfaceRef = useRef<ServerBrowserHandle | null>(null);
   const serverPictureInPicture =

apps/web/src/components/preview/usePreviewBridge.ts

@@ -39,8 +39,10 @@ export function usePreviewBridge(input: {
   threadRef: ScopedThreadRef;
   tabId: string;
   runtimeTabId: string;
+  /** The server drives this tab and reports its navigation itself. */
+  serverDriven?: boolean;
 }): void {
-  const { threadRef, tabId, runtimeTabId } = input;
+  const { threadRef, tabId, runtimeTabId, serverDriven = false } = input;
   const clearBrowserPointer = useBrowserPointerStore((state) => state.clear);
   const reportStatus = useAtomCommand(previewEnvironment.reportStatus, "preview status report");
   const bridge = previewBridge;
@@ -79,7 +81,7 @@ export function usePreviewBridge(input: {
         lastReportedUrl: lastReportedUrl.current,
         lastReportedKind: lastReportedKind.current,
       });
-      if (!reported) return;
+      if (!reported || serverDriven) return;
       lastReportedUrl.current = reported.lastReportedUrl;
       lastReportedKind.current = reported.lastReportedKind;
       void reportStatus({