@opengeni/react 0.48.0 → 0.52.1

package/src/components/sandbox-workspace.tsx

@@ -4,7 +4,8 @@
 //   Changes  — review-first git: turn-end capture (cold) or live diff (warm)
 //   Files    — tree + inline editor (capture-backed cold, live warm)
 //   Terminal — interactive xterm wired to the box PTY (Channel-A projection)
-//   Desktop  — noVNC (Channel-B), watch by default + a server-gated take-control
+//   Browser  — workspace-wide BrowserSessions, tabs, live frames, and input
+//   Computer — workspace ComputerSessions: native targets, frames, and input
 // plus a machine-state chip in the dock header (the one truthful live/waking/
 // offline indicator) and any host-injected extra tabs (Run/Debug in apps/web).
 //
@@ -13,13 +14,23 @@
 // (no `sonner` import), and every surface renders with package primitives + og
 // tokens only. `apps/web` consumes this through the exact public surface an
 // external embedder uses — that is criterion F1.
-import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  lazy,
+  type ReactNode,
+  Suspense,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import type { SessionEvent } from "@opengeni/sdk";
 import {
   CircleCheckIcon,
   CpuIcon,
   FileCode2Icon,
   GitCompareArrowsIcon,
+  Globe2Icon,
   LoaderCircleIcon,
   MonitorIcon,
   RefreshCwIcon,
@@ -30,6 +41,9 @@ import {
 import { type ClientOverride, useOpenGeni } from "../provider";
 import { cn } from "../lib/cn";
 import { xtermThemeFromTokens } from "../lib/xterm-theme";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
+import type { BrowserFrameWebSocketFactory } from "../hooks/use-browser-frame-stream";
+import type { ComputerFrameWebSocketFactory } from "../hooks/use-computer-frame-stream";
 import { useSessionCapabilities } from "../hooks/use-session-capabilities";
 import { useSandboxFiles } from "../hooks/use-sandbox-files";
 import {
@@ -45,9 +59,18 @@ import type { MachineView } from "../types/machines";
 import { SandboxFiles } from "./sandbox-files";
 import { WorkbenchChanges } from "./workbench-changes";
 import { SandboxTerminal, type XtermTheme } from "./sandbox-terminal";
-import { DesktopViewer } from "./desktop-viewer";
 import { WorkspaceDock, type WorkspaceDockProps, type WorkspaceTab } from "./workspace-dock";
 
+const LazyBrowserViewer = lazy(async () => {
+  const viewers = await import("./interactive-workbench-viewers");
+  return { default: viewers.BrowserViewer };
+});
+
+const LazyComputerViewer = lazy(async () => {
+  const viewers = await import("./interactive-workbench-viewers");
+  return { default: viewers.ComputerViewer };
+});
+
 /** A host-routed notification (replaces the app-only `sonner` toast coupling). */
 export type WorkspaceNotification = { kind: "error" | "info"; message: string };
 
@@ -55,6 +78,7 @@ export type WorkspaceNotification = { kind: "error" | "info"; message: string };
 export const WORKBENCH_TAB_CHANGES = "changes";
 export const WORKBENCH_TAB_FILES = "files";
 export const WORKBENCH_TAB_TERMINAL = "terminal";
+export const WORKBENCH_TAB_BROWSER = "browser";
 export const WORKBENCH_TAB_DESKTOP = "desktop";
 
 /**
@@ -66,6 +90,7 @@ export const WORKBENCH_SURFACES = [
   WORKBENCH_TAB_CHANGES,
   WORKBENCH_TAB_FILES,
   WORKBENCH_TAB_TERMINAL,
+  WORKBENCH_TAB_BROWSER,
   WORKBENCH_TAB_DESKTOP,
 ] as const;
 
@@ -110,6 +135,18 @@ function WorkbenchTabLabel({ icon, children }: { icon: ReactNode; children: Reac
   );
 }
 
+function WorkbenchSurfaceLoading({ name }: { name: "Browser" | "Computer" }) {
+  return (
+    <CenteredState
+      icon={
+        <LoaderCircleIcon className="size-5 animate-spin motion-reduce:animate-none" aria-hidden />
+      }
+    >
+      <p className="text-og-sm font-medium text-og-fg">Opening {name}</p>
+    </CenteredState>
+  );
+}
+
 /**
  * Decide a workspace tab from an already-local event log: the newest
  * `workspace.revision.captured` announce carries the change surface stats, so
@@ -134,7 +171,19 @@ export function initialWorkspaceTab(
     bestSeq = event.sequence;
     bestFileCount = typeof stats?.fileCount === "number" ? stats.fileCount : 0;
   }
-  return bestFileCount > 0 ? WORKBENCH_TAB_CHANGES : WORKBENCH_TAB_FILES;
+  if (bestFileCount > 0) return WORKBENCH_TAB_CHANGES;
+
+  let latestGitSeq = -1;
+  let committedOnly = false;
+  for (const event of events ?? []) {
+    if (event.type !== "git.changed" || event.sequence > bestSeq) continue;
+    if (event.sequence <= latestGitSeq) continue;
+    const payload = event.payload as { ahead?: number; reason?: string } | null;
+    latestGitSeq = event.sequence;
+    committedOnly =
+      (typeof payload?.ahead === "number" && payload.ahead > 0) || payload?.reason === "commit";
+  }
+  return committedOnly ? WORKBENCH_TAB_CHANGES : WORKBENCH_TAB_FILES;
 }
 
 /**
@@ -186,7 +235,7 @@ export type UseSandboxWorkspaceTabsOptions = ClientOverride & {
   /** Live event log (usually `useSessionEvents().events`). */
   events: SessionEvent[];
   /**
-   * Built-in surfaces this host wants to expose. Omit for all four. A disabled
+   * Built-in surfaces this host wants to expose. Omit for all five. A disabled
    * surface is behaviorally dormant: its data hooks, warm intents, stream
    * attachment, and navigation callbacks are not activated.
    */
@@ -199,6 +248,10 @@ export type UseSandboxWorkspaceTabsOptions = ClientOverride & {
   /** Host-routed notifications (mutation errors, desktop-consent failures). The
    *  package never imports a toast library — the host decides how to surface. */
   onNotify?: ((notification: WorkspaceNotification) => void) | undefined;
+  /** Alternate frame transport for non-browser runtimes and deterministic tests. */
+  browserWebSocketFactory?: BrowserFrameWebSocketFactory | undefined;
+  /** Alternate Computer frame transport for non-browser runtimes and deterministic tests. */
+  computerWebSocketFactory?: ComputerFrameWebSocketFactory | undefined;
   /** File requested by a Changes guard. The Files surface defers the read until
    *  the sandbox is live, then reveals this path. */
   requestedFilePath?: string | null | undefined;
@@ -207,10 +260,14 @@ export type UseSandboxWorkspaceTabsOptions = ClientOverride & {
   requestedFileRequestId?: string | number | null | undefined;
   /** Route a guarded diff into the host's Files tab. */
   onOpenFile?: ((path: string) => void) | undefined;
+  /** Navigate the host dock to one exact linked ComputerSession. */
+  onOpenComputerSession?: ((computerSessionId: string) => void) | undefined;
+  requestedComputerSessionId?: string | null | undefined;
+  requestedComputerRequestId?: string | number | null | undefined;
 };
 
 export type UseSandboxWorkspaceTabsResult = {
-  /** Changes | Files | Terminal | Desktop (capability-gated where noted). */
+  /** Changes | Files | Terminal | Browser | Desktop (capability-gated where noted). */
   tabs: WorkspaceTab[];
   /** The source-driven default tab: Changes when the first authoritative capture
    *  or live Git result has changes, else Files (a host `initialTab` overrides).
@@ -223,7 +280,6 @@ export type UseSandboxWorkspaceTabsResult = {
 
 type SessionWarmIntents = {
   sessionId: string;
-  watchDesktop: boolean;
   warmTerminal: boolean;
   warmFiles: boolean;
 };
@@ -231,7 +287,6 @@ type SessionWarmIntents = {
 function emptyWarmIntents(sessionId: string): SessionWarmIntents {
   return {
     sessionId,
-    watchDesktop: false,
     warmTerminal: false,
     warmFiles: false,
   };
@@ -240,14 +295,26 @@ function emptyWarmIntents(sessionId: string): SessionWarmIntents {
 /**
  * Build the workbench tabs + the machine-chip model for one session. This is the
  * dock "brain": capability negotiation, capture-backed cold reads, prewarm
- * flags, desktop consent, and the xterm theme observer — all package-local.
+ * flags, automatic desktop acknowledgment, and the xterm theme observer — all
+ * package-local.
  */
 export function useSandboxWorkspaceTabs(
   options: UseSandboxWorkspaceTabsOptions,
 ): UseSandboxWorkspaceTabsResult {
   const { client, workspaceId } = useOpenGeni(options);
-  const { sessionId, events, onNotify, requestedFilePath, requestedFileRequestId, onOpenFile } =
-    options;
+  const {
+    sessionId,
+    events,
+    onNotify,
+    browserWebSocketFactory,
+    computerWebSocketFactory,
+    requestedFilePath,
+    requestedFileRequestId,
+    onOpenFile,
+    onOpenComputerSession,
+    requestedComputerSessionId,
+    requestedComputerRequestId,
+  } = options;
   const initialTab = options.initialTab ?? null;
   const activeTab = options.activeTab ?? initialTab;
   const requestedSurfaces = options.surfaces ?? WORKBENCH_SURFACES;
@@ -255,9 +322,24 @@ export function useSandboxWorkspaceTabs(
   const changesEnabled = surfaceSet.has(WORKBENCH_TAB_CHANGES);
   const filesEnabled = surfaceSet.has(WORKBENCH_TAB_FILES);
   const terminalEnabled = surfaceSet.has(WORKBENCH_TAB_TERMINAL);
+  const browserEnabled = surfaceSet.has(WORKBENCH_TAB_BROWSER);
   const desktopEnabled = surfaceSet.has(WORKBENCH_TAB_DESKTOP);
+  const createLinkedComputer = useCallback(
+    async (name: string) => {
+      const response = await client.createComputerSession(workspaceId, {
+        operationId: crypto.randomUUID(),
+        sessionId,
+        name,
+      });
+      return {
+        id: response.session.id,
+        placement: response.session.placement,
+      };
+    },
+    [client, sessionId, workspaceId],
+  );
   const workspaceDataEnabled = changesEnabled || filesEnabled;
-  const anySurfaceEnabled = workspaceDataEnabled || terminalEnabled || desktopEnabled;
+  const machineSurfaceEnabled = workspaceDataEnabled || terminalEnabled || desktopEnabled;
   // Do not speculatively activate both remote workspace surfaces while the dock
   // is still resolving its selected tab. Modal calls cannot be cancelled after
   // dispatch, so that transient state otherwise creates an aborted duplicate
@@ -267,17 +349,17 @@ export function useSandboxWorkspaceTabs(
   const filesActive = resolvedActiveTab === WORKBENCH_TAB_FILES;
   const surfaceIdentity = WORKBENCH_SURFACES.filter((surface) => surfaceSet.has(surface)).join(",");
 
-  // The three box-warming INTENTS, each off by default and each
+  // The two box-warming INTENTS, each off by default and each
   // flipped true by a genuine user action (never on mount, never on a passive
-  // capture glance): desktop watch consent, terminal engagement (`onActivate`), and
-  // a deliberate live-file open/edit in Files. Browsing capture-served
+  // capture glance): terminal engagement (`onActivate`) and a deliberate
+  // live-file open/edit in Files. Browsing capture-served
   // Changes/Files warms nothing — that is the whole point of Refinement 1.
   const [storedWarmIntents, setStoredWarmIntents] = useState<SessionWarmIntents>(() =>
     emptyWarmIntents(sessionId),
   );
   const warmIntents =
     storedWarmIntents.sessionId === sessionId ? storedWarmIntents : emptyWarmIntents(sessionId);
-  const { watchDesktop, warmTerminal, warmFiles } = warmIntents;
+  const { warmTerminal, warmFiles } = warmIntents;
   const requestWarmIntent = useCallback(
     (intent: Exclude<keyof SessionWarmIntents, "sessionId">) => {
       setStoredWarmIntents((previous) => {
@@ -294,7 +376,7 @@ export function useSandboxWorkspaceTabs(
     workspaceId,
     sessionId,
     pollIntervalMs: 8000,
-    enabled: anySurfaceEnabled,
+    enabled: machineSurfaceEnabled,
   });
   const activeMachine: MachineView | null =
     machines.machines.find((m) => m.sandboxId === machines.activeSandboxId) ??
@@ -303,8 +385,8 @@ export function useSandboxWorkspaceTabs(
 
   const caps = useSessionCapabilities(sessionId, {
     events,
-    enabled: anySurfaceEnabled,
-    attachDesktop: desktopEnabled && watchDesktop,
+    enabled: machineSurfaceEnabled,
+    attachDesktop: false,
     attachTerminal: terminalEnabled && warmTerminal,
     // Explicit live-file intent only — NOT "the Files tab is open". A cold edit
     // or guarded-file open wakes the box; a glance at the tree/diff does not.
@@ -312,6 +394,11 @@ export function useSandboxWorkspaceTabs(
   });
   const capabilities = caps.capabilities;
   const liveness = capabilities?.liveness;
+  // A missing capability document is not evidence that the sandbox is live.
+  // Pass explicit null to live-I/O hooks so fast capture/event hydration cannot
+  // exploit their legacy "liveness omitted" compatibility path while negotiation
+  // is still pending.
+  const liveIoLiveness = liveness ?? null;
   const fileSystemOn = capabilities?.FileSystem.available ?? false;
   // The FS is writable only when it's live AND not read-only. A self-hosted box
   // that's offline (or any read-only advertisement) or a capture-served cold tree
@@ -323,26 +410,23 @@ export function useSandboxWorkspaceTabs(
   // Mutations are live-only. A capture is a review artifact, never a writable
   // surrogate for a sleeping machine; the user must deliberately open the live
   // workspace before create/rename/delete/edit controls appear.
-  const filesEditable =
-    fileSystemOn && !fsReadOnly && (liveness === "warm" || liveness === "draining");
+  const filesEditable = fileSystemOn && !fsReadOnly && sandboxAcceptsLiveIo(liveness);
   const gitOn = capabilities?.Git.available ?? false;
   const terminalOn = terminalEnabled && (capabilities?.Terminal.transport ?? null) !== null;
-  // The REAL interactive terminal is the ttyd pty-ws stream. When it's live the
-  // legacy HTTP PTY must NOT run; `useSandboxTerminal` opens its HTTP PTY only as
-  // the firehose-mode fallback (a backend without ttyd).
-  const ptyWsLive =
-    capabilities?.Terminal.transport === "pty-ws" && Boolean(capabilities?.Terminal.url);
-  const ptyCapable = (capabilities?.Terminal.ptyCapable ?? false) && !ptyWsLive;
+  // A descriptor-only pty-ws cell intentionally has no short-lived URL until
+  // terminal intent acquires one. Do not mistake that grant boundary for a
+  // legacy HTTP PTY and eagerly open a second terminal. The fallback exists only
+  // for a genuinely firehose-transport backend with no typed degradation.
+  const ptyCapable =
+    warmTerminal &&
+    (capabilities?.Terminal.ptyCapable ?? false) &&
+    capabilities?.Terminal.transport === "sse-events" &&
+    capabilities?.Terminal.reason === null;
   const terminal = useSandboxTerminal(sessionId, {
     events: terminalEnabled ? events : [],
     interactive: terminalEnabled && ptyCapable,
     liveness,
   });
-  const desktopAdvertised =
-    desktopEnabled &&
-    ((capabilities?.DesktopStream.transport ?? null) !== null ||
-      capabilities?.DesktopStream.reason === "lease_cold");
-
   // Lazy provisioning (#315) creates the box mid-turn on the first sandbox tool
   // call, emitting sandbox.provision started→completed/failed on the live stream.
   // The on-demand resting hook rests without polling, so when the box warms the
@@ -369,7 +453,7 @@ export function useSandboxWorkspaceTabs(
     enabled: workspaceDataEnabled,
   });
   const captureAvailable = captureState.available;
-  const liveWorkspaceExpected = liveness === "warm" || liveness === "draining";
+  const liveWorkspaceExpected = sandboxAcceptsLiveIo(liveness);
   // Capability negotiation and capture resolution are independent requests. A
   // cold capability document can win that race by a few milliseconds; enabling
   // the leaf hooks in that window would make them interpret `capture: null` as a
@@ -407,7 +491,7 @@ export function useSandboxWorkspaceTabs(
     enabled: filesEnabled && (captureAvailable || (fileSystemOn && liveWorkspaceExpected)),
     active: filesActive,
     repoPaths,
-    liveness,
+    liveness: liveIoLiveness,
     capture: captureState.capture,
     // A reverted optimistic mutation (e.g. a 409 rename collision) surfaces as a
     // host notification — the tree silently rolls back, the user sees why.
@@ -451,7 +535,7 @@ export function useSandboxWorkspaceTabs(
     // dormant, avoiding the old duplicate full-tree read.
     active: changesActive || resolvedActiveTab === null,
     repoPaths,
-    liveness,
+    liveness: liveIoLiveness,
     comparison: changesComparison,
     capture: changesComparison === "staged" ? null : captureState.capture,
   });
@@ -484,30 +568,6 @@ export function useSandboxWorkspaceTabs(
     return () => observer.disconnect();
   }, [terminalEnabled]);
 
-  async function acknowledgeAndWatch() {
-    try {
-      const shared = capabilities?.DesktopStream.shared ?? false;
-      await client.acknowledgeStream(workspaceId, sessionId, {
-        acknowledgeUnredacted: true,
-        acknowledgeShared: shared,
-      });
-      requestWarmIntent("watchDesktop");
-      caps.renegotiate();
-    } catch (error) {
-      onNotify?.({
-        kind: "error",
-        message: `Could not start the desktop stream: ${error instanceof Error ? error.message : String(error)}`,
-      });
-    }
-  }
-
-  // Re-warm WITHOUT re-acknowledging: the consent was already recorded, only the
-  // box drained back to cold. Idempotent — the viewer auto-warm de-dupes.
-  function rewarmDesktop() {
-    if (!watchDesktop) requestWarmIntent("watchDesktop");
-    caps.renegotiate();
-  }
-
   const dirtyCount = git.diff.length;
 
   // The one truthful machine indicator, derived from the live capability/liveness
@@ -517,10 +577,7 @@ export function useSandboxWorkspaceTabs(
     capabilitiesState: caps.state,
     activeMachineState: activeMachine?.state ?? null,
     activeIsSelfhosted: activeMachine?.kind === "selfhosted",
-    wantsWarm:
-      (terminalEnabled && warmTerminal) ||
-      (desktopEnabled && watchDesktop) ||
-      (workspaceDataEnabled && warmFiles),
+    wantsWarm: (terminalEnabled && warmTerminal) || (workspaceDataEnabled && warmFiles),
     capturedAt: captureState.capturedAt,
   });
   const workspaceWaking = chip.state === "waking";
@@ -543,7 +600,11 @@ export function useSandboxWorkspaceTabs(
   }
   const captureIsAuthoritative =
     !liveWorkspaceExpected && (liveness !== undefined || caps.error !== null);
-  const captureUnavailable = captureState.fileCount === 0 || captureState.error !== null;
+  const captureHasChanges =
+    (captureState.fileCount ?? 0) > 0 ||
+    (captureState.capture?.repos.some((repo) => (repo.branchDiff?.length ?? 0) > 0) ?? false);
+  const captureUnavailable =
+    (captureState.fileCount === 0 && !captureHasChanges) || captureState.error !== null;
   const implicitBranchFallbackPending =
     changesComparison === "branch" &&
     git.error !== null &&
@@ -563,7 +624,7 @@ export function useSandboxWorkspaceTabs(
       captureState.available
     ) {
       defaultTabRef.current.value = sourceDrivenDefaultTab(
-        captureState.fileCount > 0,
+        captureHasChanges,
         changesEnabled,
         filesEnabled,
       );
@@ -586,7 +647,7 @@ export function useSandboxWorkspaceTabs(
       // A warm live read failed but the durable capture is intact: retain an
       // immediate, deterministic review surface instead of hanging unresolved.
       defaultTabRef.current.value = sourceDrivenDefaultTab(
-        captureState.fileCount > 0,
+        captureHasChanges,
         changesEnabled,
         filesEnabled,
       );
@@ -664,7 +725,7 @@ export function useSandboxWorkspaceTabs(
                   ...(requestedFileRequestId !== null && requestedFileRequestId !== undefined
                     ? { requestedPathRequestId: requestedFileRequestId }
                     : {}),
-                  requestedPathReady: liveness === "warm" || liveness === "draining",
+                  requestedPathReady: sandboxAcceptsLiveIo(liveness),
                 }
               : {})}
             // Ordinary capture browsing does not warm a box. The first edit — or an
@@ -683,6 +744,7 @@ export function useSandboxWorkspaceTabs(
         content: (
           <div className="h-full bg-og-bg p-1">
             <SandboxTerminal
+              key={sessionId}
               result={terminal}
               terminalCapability={capabilities?.Terminal ?? null}
               onActivate={() => requestWarmIntent("warmTerminal")}
@@ -696,25 +758,51 @@ export function useSandboxWorkspaceTabs(
       });
     }
 
-    // Desktop — capability-gated + consent-gated.
-    if (desktopAdvertised) {
+    // Browser — independent from sandbox capability negotiation. BrowserSessions
+    // are workspace resources and may live in this agent's sandbox, a peer's
+    // sandbox, a connected machine, or an external browser placement.
+    if (browserEnabled) {
+      list.push({
+        id: WORKBENCH_TAB_BROWSER,
+        label: <WorkbenchTabLabel icon={<Globe2Icon />}>Browser</WorkbenchTabLabel>,
+        content: (
+          <Suspense fallback={<WorkbenchSurfaceLoading name="Browser" />}>
+            <LazyBrowserViewer
+              key={sessionId}
+              client={client}
+              workspaceId={workspaceId}
+              sessionId={sessionId}
+              onNotify={onNotify}
+              {...(desktopEnabled ? { createLinkedComputer } : {})}
+              {...(onOpenComputerSession ? { onOpenComputer: onOpenComputerSession } : {})}
+              {...(browserWebSocketFactory ? { webSocketFactory: browserWebSocketFactory } : {})}
+              className="h-full"
+            />
+          </Suspense>
+        ),
+      });
+    }
+
+    // Computer — stable legacy tab id, new workspace resource body. Like Browser,
+    // it is independent from the selected agent's sandbox capability document.
+    if (desktopEnabled) {
       list.push({
         id: WORKBENCH_TAB_DESKTOP,
-        label: <WorkbenchTabLabel icon={<MonitorIcon />}>Desktop</WorkbenchTabLabel>,
-        badge: watchDesktop ? (
-          <span className="rounded-og-xs bg-og-status-running/20 px-1 text-og-xs text-og-status-running">
-            Live
-          </span>
-        ) : undefined,
+        label: <WorkbenchTabLabel icon={<MonitorIcon />}>Computer</WorkbenchTabLabel>,
         content: (
-          <DesktopViewer
-            capability={capabilities?.DesktopStream ?? null}
-            viewerCapReached={caps.viewerCapReached}
-            watching={watchDesktop}
-            onAcknowledge={() => void acknowledgeAndWatch()}
-            onWarm={rewarmDesktop}
-            className="h-full"
-          />
+          <Suspense fallback={<WorkbenchSurfaceLoading name="Computer" />}>
+            <LazyComputerViewer
+              key={sessionId}
+              client={client}
+              workspaceId={workspaceId}
+              sessionId={sessionId}
+              onNotify={onNotify}
+              requestedComputerSessionId={requestedComputerSessionId}
+              requestedComputerRequestId={requestedComputerRequestId}
+              {...(computerWebSocketFactory ? { webSocketFactory: computerWebSocketFactory } : {})}
+              className="h-full"
+            />
+          </Suspense>
         ),
       });
     }
@@ -726,14 +814,22 @@ export function useSandboxWorkspaceTabs(
     changesEnabled,
     filesEnabled,
     terminalOn,
-    desktopAdvertised,
+    browserEnabled,
+    desktopEnabled,
     captureAvailable,
     dirtyCount,
-    watchDesktop,
     warmTerminal,
     requestedFilePath,
     requestedFileRequestId,
     onOpenFile,
+    onOpenComputerSession,
+    requestedComputerSessionId,
+    requestedComputerRequestId,
+    onNotify,
+    browserWebSocketFactory,
+    computerWebSocketFactory,
+    client,
+    workspaceId,
     liveness,
     sessionId,
     files,
@@ -747,13 +843,14 @@ export function useSandboxWorkspaceTabs(
     caps.error,
     caps.viewerCapReached,
     requestWarmIntent,
+    createLinkedComputer,
   ]);
 
   return {
     tabs,
     defaultTab,
     machine: {
-      enabled: anySurfaceEnabled,
+      enabled: machineSurfaceEnabled,
       chip,
       activeMachine,
       loading: machines.loading,
@@ -771,7 +868,7 @@ export type SandboxWorkspaceProps = ClientOverride & {
   primary: ReactNode;
   /**
    * Built-in surfaces this host wants to expose. Omit for Changes, Files,
-   * Terminal, and Desktop. Disabled surfaces remain behaviorally dormant.
+   * Terminal, Browser, and Desktop. Disabled surfaces remain behaviorally dormant.
    */
   surfaces?: readonly SandboxWorkspaceSurface[] | undefined;
   /** Host tabs injected BEFORE the workbench tabs (e.g. a "Run" landing tab). */
@@ -783,6 +880,10 @@ export type SandboxWorkspaceProps = ClientOverride & {
   initialTab?: string | undefined;
   /** Host-routed notifications (no toast dependency in the package). */
   onNotify?: ((notification: WorkspaceNotification) => void) | undefined;
+  /** Alternate Browser frame transport for non-browser runtimes and deterministic tests. */
+  browserWebSocketFactory?: BrowserFrameWebSocketFactory | undefined;
+  /** Alternate Computer frame transport for non-browser runtimes and deterministic tests. */
+  computerWebSocketFactory?: ComputerFrameWebSocketFactory | undefined;
   /** Controlled collapsed state for hosts with their own dock toggle. */
   collapsed?: boolean | undefined;
   onCollapsedChange?: ((collapsed: boolean) => void) | undefined;
@@ -814,6 +915,8 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     trailingTabs,
     initialTab,
     onNotify,
+    browserWebSocketFactory,
+    computerWebSocketFactory,
     collapsed,
     onCollapsedChange,
     showCollapseControl,
@@ -834,7 +937,13 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     path: string;
     requestId: number;
   } | null>(null);
+  const [requestedComputer, setRequestedComputer] = useState<{
+    sessionId: string;
+    computerSessionId: string;
+    requestId: number;
+  } | null>(null);
   const nextFileRequestId = useRef(0);
+  const nextComputerRequestId = useRef(0);
   const selectedTab = storedSelection?.sessionId === sessionId ? storedSelection.tab : null;
   const activeTabHint = selectedTab ?? initialTab ?? leadingTabs?.[0]?.id ?? null;
   const openFile = useCallback(
@@ -845,6 +954,18 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     },
     [sessionId],
   );
+  const openComputer = useCallback(
+    (computerSessionId: string) => {
+      nextComputerRequestId.current += 1;
+      setRequestedComputer({
+        sessionId,
+        computerSessionId,
+        requestId: nextComputerRequestId.current,
+      });
+      setStoredSelection({ sessionId, tab: WORKBENCH_TAB_DESKTOP });
+    },
+    [sessionId],
+  );
 
   const {
     tabs: workbenchTabs,
@@ -859,9 +980,16 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     ...(initialTab ? { initialTab } : {}),
     activeTab: activeTabHint,
     ...(onNotify ? { onNotify } : {}),
+    ...(browserWebSocketFactory ? { browserWebSocketFactory } : {}),
+    ...(computerWebSocketFactory ? { computerWebSocketFactory } : {}),
     requestedFilePath: requestedFile?.sessionId === sessionId ? requestedFile.path : null,
     requestedFileRequestId: requestedFile?.sessionId === sessionId ? requestedFile.requestId : null,
     onOpenFile: openFile,
+    onOpenComputerSession: openComputer,
+    requestedComputerSessionId:
+      requestedComputer?.sessionId === sessionId ? requestedComputer.computerSessionId : null,
+    requestedComputerRequestId:
+      requestedComputer?.sessionId === sessionId ? requestedComputer.requestId : null,
   });
 
   // A user's tab click wins forever; before that we follow the source-driven