Skip to content

Automate browser based workflows with AI

feat(SKY-11758): studio Browser pane absorbs run visuals + single pane header (SKY-11762) (#7044)

Celal Zamanoğluc1c2f6558019
diff --git a/skyvern-frontend/src/routes/workflows/hooks/useWorkflowRunsQuery.ts b/skyvern-frontend/src/routes/workflows/hooks/useWorkflowRunsQuery.ts
index 7aa68bdcb..248dbccfb 100644
--- a/skyvern-frontend/src/routes/workflows/hooks/useWorkflowRunsQuery.ts
+++ b/skyvern-frontend/src/routes/workflows/hooks/useWorkflowRunsQuery.ts
@@ -21,6 +21,8 @@ type Props = {
page: number;
pageSize?: number;
search?: string;
+ // ANDed with the internal gating (workflow id + globalWorkflows loaded).
+ enabled?: boolean;
} & UseQueryOptions;
function useWorkflowRunsQuery({
@@ -29,6 +31,7 @@ function useWorkflowRunsQuery({
page,
pageSize,
search,
+ enabled,
...queryOptions
}: Props) {
const { data: globalWorkflows } = useGlobalWorkflowsQuery();
@@ -77,7 +80,7 @@ function useWorkflowRunsQuery({
})
.then((response) => response.data);
},
- enabled: !!workflowPermanentId && !!globalWorkflows,
+ enabled: !!workflowPermanentId && !!globalWorkflows && (enabled ?? true),
...queryOptions,
});
}
diff --git a/skyvern-frontend/src/routes/workflows/studio/BrowserPaneHeader.tsx b/skyvern-frontend/src/routes/workflows/studio/BrowserPaneHeader.tsx
new file mode 100644
index 000000000..2f7af0ff9
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/studio/BrowserPaneHeader.tsx
@@ -0,0 +1,273 @@
+import {
+ ImageIcon,
+ OpenInNewWindowIcon,
+ PlayIcon,
+ ReloadIcon,
+} from "@radix-ui/react-icons";
+import { AxiosError } from "axios";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+import { useParams } from "react-router-dom";
+
+import { getClient } from "@/api/AxiosClient";
+import { DebugSessionApiResponse } from "@/api/types";
+import { PowerIcon } from "@/components/icons/PowerIcon";
+import { Button } from "@/components/ui/button";
+import {
+ Dialog,
+ DialogClose,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+ DialogTrigger,
+} from "@/components/ui/dialog";
+import { toast } from "@/components/ui/use-toast";
+import { useBrowserStreamingMode } from "@/hooks/useRuntimeConfig";
+import { useCredentialGetter } from "@/hooks/useCredentialGetter";
+import { StreamModeBadge } from "@/routes/streaming/StreamDiagnostics";
+import { useRecordingLauncherStore } from "@/store/useRecordingLauncherStore";
+import { useRecordingStore } from "@/store/useRecordingStore";
+import { useStudioBrowserStore } from "@/store/useStudioBrowserStore";
+import { cn } from "@/util/utils";
+
+import { useBrowserPaneView } from "./useBrowserPaneView";
+import { useStudioPaneCompact } from "./StudioShellContext";
+import { ViewToggle } from "./ViewToggle";
+
+const ICON_BUTTON =
+ "shrink-0 rounded p-1 text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-40";
+
+const RECORDING_ARCHIVED_LABEL =
+ "Recording archived — contact [email protected] to request restoration";
+
+export function BrowserPaneViewPills() {
+ const compact = useStudioPaneCompact();
+ const { browserStreamingMode } = useBrowserStreamingMode();
+ const { view, setView, visuals } = useBrowserPaneView();
+ const hasRecording = visuals.recordingUrls.length > 0;
+
+ return (
+ <>
+ {compact ? null : (
+ <StreamModeBadge mode={browserStreamingMode} className="shrink-0" />
+ )}
+ <div
+ role="group"
+ aria-label="Browser view"
+ className="flex shrink-0 items-center gap-0.5 rounded-md border border-slate-700 bg-slate-elevation2 p-0.5"
+ >
+ <ViewToggle
+ active={view === "live"}
+ onClick={() => setView("live")}
+ compact={compact}
+ label="Live"
+ icon={
+ <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-success" />
+ }
+ />
+ {hasRecording ? (
+ <ViewToggle
+ active={view === "recording"}
+ onClick={() => setView("recording")}
+ compact={compact}
+ label="Recording"
+ icon={<PlayIcon className="h-3 w-3" />}
+ />
+ ) : visuals.recordingArchived ? (
+ <button
+ type="button"
+ disabled
+ title={RECORDING_ARCHIVED_LABEL}
+ aria-label={RECORDING_ARCHIVED_LABEL}
+ className="inline-flex cursor-not-allowed items-center gap-1.5 rounded px-2 py-1 text-[11px] font-medium text-muted-foreground opacity-60"
+ >
+ <PlayIcon className="h-3 w-3" />
+ {compact ? null : "Recording archived"}
+ </button>
+ ) : null}
+ {visuals.hasScreenshots ? (
+ <ViewToggle
+ active={view === "screenshots"}
+ onClick={() => setView("screenshots")}
+ compact={compact}
+ label="Screenshots"
+ icon={<ImageIcon className="h-3 w-3" />}
+ />
+ ) : null}
+ </div>
+ </>
+ );
+}
+
+export function BrowserPaneActions() {
+ const { workflowPermanentId } = useParams();
+ const compact = useStudioPaneCompact();
+ const credentialGetter = useCredentialGetter();
+ const queryClient = useQueryClient();
+ const { debugBrowserSessionId: browserSessionId, liveSurface } =
+ useBrowserPaneView();
+ const isRecording = useRecordingStore((s) => s.isRecording);
+ const manualCapturePaused = useRecordingStore((s) => s.manualCapturePaused);
+ const startRecordingAtEnd = useRecordingLauncherStore(
+ (s) => s.startRecordingAtEnd,
+ );
+ // These act on the debug browser; while the pane streams the run's own
+ // browser instead, they'd hit an invisible session — disable with a reason.
+ const debugHidden = liveSurface === "run";
+ const blockedTitle =
+ "Showing the run's browser — debug browser controls come back after the run";
+ const reload = useStudioBrowserStore((s) => s.reload);
+ const [confirmOff, setConfirmOff] = useState(false);
+
+ const cycleBrowser = useMutation({
+ mutationFn: async (workflowId: string) => {
+ const client = await getClient(credentialGetter, "sans-api-v1");
+ return client.post<DebugSessionApiResponse>(
+ `/debug-session/${workflowId}/new`,
+ );
+ },
+ onSuccess: (response) => {
+ queryClient.setQueryData(
+ ["debugSession", workflowPermanentId],
+ response.data,
+ );
+ void queryClient.invalidateQueries({
+ queryKey: ["debugSession", workflowPermanentId],
+ });
+ setConfirmOff(false);
+ toast({
+ variant: "success",
+ title: "Browser restarted",
+ description: "A fresh browser is starting.",
+ });
+ },
+ onError: (error: AxiosError) => {
+ toast({
+ variant: "destructive",
+ title: "Failed to turn off browser",
+ description: error.message,
+ });
+ },
+ });
+
+ const openInNewTab = () => {
+ if (!browserSessionId) {
+ return;
+ }
+ window.open(
+ `${window.location.origin}/browser-session/${browserSessionId}`,
+ "_blank",
+ "noopener",
+ );
+ };
+
+ return (
+ <>
+ {isRecording ? (
+ <span
+ className={cn(
+ "flex shrink-0 items-center gap-1.5 rounded-full px-2 py-0.5 text-xs font-medium",
+ manualCapturePaused
+ ? "bg-amber-500/10 text-amber-500"
+ : "bg-red-500/10 text-red-500",
+ )}
+ >
+ <span
+ className={cn(
+ "h-2 w-2 rounded-full",
+ manualCapturePaused ? "bg-amber-500" : "animate-pulse bg-red-500",
+ )}
+ />
+ {compact ? null : manualCapturePaused ? "Paused" : "Recording"}
+ </span>
+ ) : (
+ <Button
+ variant="secondary"
+ size="sm"
+ className="h-7 shrink-0 gap-1.5 px-2 text-xs"
+ title="Record browser actions into blocks"
+ disabled={!browserSessionId || !startRecordingAtEnd}
+ onClick={() => startRecordingAtEnd?.()}
+ >
+ <span className="h-2 w-2 rounded-full bg-red-500" />
+ {compact ? null : "Record"}
+ </Button>
+ )}
+ <button
+ type="button"
+ title={debugHidden ? blockedTitle : "Reconnect"}
+ aria-label="Reconnect browser stream"
+ onClick={reload}
+ disabled={!browserSessionId || debugHidden}
+ className={ICON_BUTTON}
+ >
+ <ReloadIcon className="h-3.5 w-3.5" />
+ </button>
+ <button
+ type="button"
+ title={debugHidden ? blockedTitle : "Open in new tab"}
+ aria-label="Open browser in new tab"
+ onClick={openInNewTab}
+ disabled={!browserSessionId || debugHidden}
+ className={ICON_BUTTON}
+ >
+ <OpenInNewWindowIcon className="h-3.5 w-3.5" />
+ </button>
+ <Dialog
+ open={confirmOff}
+ onOpenChange={(open) => {
+ if (!open && cycleBrowser.isPending) {
+ return;
+ }
+ setConfirmOff(open);
+ }}
+ >
+ <DialogTrigger asChild>
+ <button
+ type="button"
+ title={debugHidden ? blockedTitle : "Turn off browser"}
+ aria-label="Turn off browser"
+ disabled={!workflowPermanentId || !browserSessionId || debugHidden}
+ className={ICON_BUTTON}
+ >
+ <PowerIcon className="h-3.5 w-3.5" />
+ </button>
+ </DialogTrigger>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>Turn off this browser?</DialogTitle>
+ <DialogDescription>
+ This ends the current browser and starts a fresh one. Anything in
+ progress here will stop.
+ </DialogDescription>
+ </DialogHeader>
+ <DialogFooter>
+ <DialogClose asChild>
+ <Button variant="secondary" disabled={cycleBrowser.isPending}>
+ Cancel
+ </Button>
+ </DialogClose>
+ <Button
+ variant="destructive"
+ disabled={!workflowPermanentId || cycleBrowser.isPending}
+ onClick={() =>
+ workflowPermanentId && cycleBrowser.mutate(workflowPermanentId)
+ }
+ >
+ {cycleBrowser.isPending ? (
+ <>
+ <ReloadIcon className="mr-2 size-4 animate-spin" />
+ Turning off…
+ </>
+ ) : (
+ "Turn off"
+ )}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ </>
+ );
+}
diff --git a/skyvern-frontend/src/routes/workflows/studio/BrowserTab.test.tsx b/skyvern-frontend/src/routes/workflows/studio/BrowserTab.test.tsx
new file mode 100644
index 000000000..753e75288
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/studio/BrowserTab.test.tsx
@@ -0,0 +1,473 @@
+// @vitest-environment jsdom
+
+import {
+ act,
+ cleanup,
+ fireEvent,
+ render,
+ screen,
+} from "@testing-library/react";
+import { MemoryRouter, Route, Routes } from "react-router-dom";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import { ActionTypes, Status, type ActionsApiResponse } from "@/api/types";
+import { useRecordingStore } from "@/store/useRecordingStore";
+import { useRunViewStore } from "@/store/RunViewStore";
+import { useStudioBrowserStore } from "@/store/useStudioBrowserStore";
+
+import type {
+ WorkflowRunBlock,
+ WorkflowRunTimelineItem,
+} from "../types/workflowRunTypes";
+import { BrowserPaneActions, BrowserPaneViewPills } from "./BrowserPaneHeader";
+import { BrowserTab } from "./BrowserTab";
+import { StudioShellContext } from "./StudioShellContext";
+
+const mocks = vi.hoisted(() => ({
+ workflowRun: undefined as unknown,
+ timeline: undefined as unknown,
+ debugSession: undefined as unknown,
+ runs: [] as Array<{ workflow_run_id: string }>,
+}));
+
+vi.mock("../hooks/useWorkflowRunWithWorkflowQuery", () => ({
+ useWorkflowRunWithWorkflowQuery: (options?: { workflowRunId?: string }) => ({
+ data: options?.workflowRunId ? mocks.workflowRun : undefined,
+ }),
+}));
+vi.mock("../hooks/useWorkflowRunTimelineQuery", () => ({
+ useWorkflowRunTimelineQuery: (options?: { workflowRunId?: string }) => ({
+ data: options?.workflowRunId ? mocks.timeline : undefined,
+ }),
+}));
+vi.mock("../hooks/useDebugSessionQuery", () => ({
+ useDebugSessionQuery: () => ({ data: mocks.debugSession }),
+}));
+vi.mock("../hooks/useWorkflowRunsQuery", () => ({
+ useWorkflowRunsQuery: () => ({ data: mocks.runs, isPending: false }),
+}));
+vi.mock("@/hooks/useRuntimeConfig", () => ({
+ useBrowserStreamingMode: () => ({ browserStreamingMode: "vnc" }),
+}));
+vi.mock("posthog-js/react", () => ({
+ usePostHog: () => ({ capture: vi.fn() }),
+}));
+vi.mock("@/hooks/useCredentialGetter", () => ({
+ useCredentialGetter: () => null,
+}));
+vi.mock("@/routes/streaming/StreamDiagnostics", () => ({
+ StreamModeBadge: ({ mode }: { mode: string }) => (
+ <span data-testid="stream-mode-badge">{mode}</span>
+ ),
+ StreamStatusPanel: ({ diagnostic }: { diagnostic: { title: string } }) => (
+ <div data-testid="stream-status">{diagnostic.title}</div>
+ ),
+}));
+vi.mock("./runview/HeroRecording", () => ({
+ HeroRecording: ({ recordingUrls }: { recordingUrls: string[] }) => (
+ <div data-testid="hero-recording" data-count={recordingUrls.length} />
+ ),
+}));
+vi.mock("./runview/HeroScreenshot", () => ({
+ HeroScreenshot: ({ selection }: { selection: unknown }) => (
+ <div
+ data-testid="hero-screenshot"
+ data-selection={JSON.stringify(selection)}
+ />
+ ),
+}));
+vi.mock("./runview/RunLiveStream", () => ({
+ RunLiveStream: (props: {
+ workflowRunId: string;
+ browserSessionId: string | null;
+ interactive: boolean;
+ }) => (
+ <div
+ data-testid="run-live-stream"
+ data-run={props.workflowRunId}
+ data-session={props.browserSessionId ?? ""}
+ data-interactive={props.interactive ? "yes" : "no"}
+ />
+ ),
+}));
+
+const initialBrowserState = useStudioBrowserStore.getState();
+const initialRunViewState = useRunViewStore.getState();
+const initialRecordingState = useRecordingStore.getState();
+
+function buildBlock(
+ overrides: Partial<WorkflowRunBlock> = {},
+): WorkflowRunBlock {
+ return {
+ workflow_run_block_id: "wrb_1",
+ workflow_run_id: "wr_1",
+ parent_workflow_run_block_id: null,
+ block_type: "task",
+ label: "Go to portal",
+ description: null,
+ title: null,
+ status: Status.Completed,
+ failure_reason: null,
+ output: null,
+ continue_on_failure: false,
+ task_id: null,
+ url: null,
+ navigation_goal: null,
+ navigation_payload: null,
+ data_extraction_goal: null,
+ data_schema: null,
+ terminate_criterion: null,
+ complete_criterion: null,
+ include_action_history_in_verification: null,
+ engine: null,
+ actions: null,
+ created_at: "2026-01-01T00:00:00Z",
+ modified_at: "2026-01-01T00:00:00Z",
+ duration: null,
+ loop_values: null,
+ current_value: null,
+ current_index: null,
+ ...overrides,
+ };
+}
+
+function buildAction(
+ overrides: Partial<ActionsApiResponse> = {},
+): ActionsApiResponse {
+ return {
+ action_id: "act_1",
+ action_type: ActionTypes.Click,
+ status: Status.Completed,
+ intention: "Click the login button",
+ description: null,
+ reasoning: null,
+ step_id: "step_1",
+ action_order: 0,
+ screenshot_artifact_id: "art_1",
+ ...overrides,
+ } as ActionsApiResponse;
+}
+
+function buildBlockItem(
+ block: WorkflowRunBlock,
+ children: Array<WorkflowRunTimelineItem> = [],
+): WorkflowRunTimelineItem {
+ return {
+ type: "block",
+ block,
+ children,
+ thought: null,
+ created_at: block.created_at,
+ modified_at: block.modified_at,
+ };
+}
+
+function seedRun({
+ status,
+ browserSessionId = null,
+ recordingUrl = null,
+}: {
+ status: Status;
+ browserSessionId?: string | null;
+ recordingUrl?: string | null;
+}) {
+ mocks.runs = [{ workflow_run_id: "wr_1" }];
+ mocks.workflowRun = {
+ workflow_run_id: "wr_1",
+ status,
+ browser_session_id: browserSessionId,
+ recording_url: recordingUrl,
+ recording_urls: recordingUrl ? [recordingUrl] : null,
+ workflow: {
+ workflow_definition: { blocks: [], finally_block_label: null },
+ },
+ };
+ mocks.timeline = [buildBlockItem(buildBlock({ actions: [buildAction()] }))];
+}
+
+function renderBrowserPane(initialPath: string) {
+ const setBrowserStreamSlot = vi.fn();
+ const queryClient = new QueryClient();
+ const view = render(
+ <QueryClientProvider client={queryClient}>
+ <StudioShellContext.Provider
+ value={{
+ copilotPortalEl: null,
+ setEditorStreamSlot: () => {},
+ setBrowserStreamSlot,
+ setRunStreamSlot: () => {},
+ }}
+ >
+ <MemoryRouter initialEntries={[initialPath]}>
+ <Routes>
+ <Route
+ path="/workflows/:workflowPermanentId/studio"
+ element={
+ <>
+ <div data-testid="pane-header">
+ <BrowserPaneViewPills />
+ <BrowserPaneActions />
+ </div>
+ <BrowserTab />
+ </>
+ }
+ />
+ </Routes>
+ </MemoryRouter>
+ </StudioShellContext.Provider>
+ </QueryClientProvider>,
+ );
+ return { ...view, setBrowserStreamSlot };
+}
+
+const STUDIO_PATH = "/workflows/wpid_test/studio?panes=copilot,browser";
+
+beforeEach(() => {
+ useStudioBrowserStore.setState(initialBrowserState, true);
+ useRunViewStore.setState(initialRunViewState, true);
+ useRecordingStore.setState(initialRecordingState, true);
+ mocks.workflowRun = undefined;
+ mocks.timeline = undefined;
+ mocks.debugSession = undefined;
+ mocks.runs = [];
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+describe("BrowserTab view machine", () => {
+ it("shows the live debug stream slot with no run history", () => {
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(STUDIO_PATH);
+
+ expect(screen.getByTestId("browser-pane-stream-slot")).toBeTruthy();
+ expect(
+ screen.getByRole("button", { name: "Live" }).getAttribute("aria-pressed"),
+ ).toBe("true");
+ expect(screen.queryByRole("button", { name: "Recording" })).toBeNull();
+ expect(screen.queryByRole("button", { name: "Screenshots" })).toBeNull();
+ });
+
+ it("registers the shell stream slot while live", () => {
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ const { setBrowserStreamSlot } = renderBrowserPane(STUDIO_PATH);
+
+ expect(setBrowserStreamSlot).toHaveBeenCalledWith(expect.any(HTMLElement));
+ });
+
+ it("shows the warming panel with no session and no history", () => {
+ renderBrowserPane(STUDIO_PATH);
+
+ expect(screen.getByTestId("stream-status").textContent).toContain(
+ "Warming up your browser",
+ );
+ });
+
+ it("defaults an idle workflow with history and no session to the replay", () => {
+ seedRun({ status: Status.Completed, recordingUrl: "https://r.test/1.mp4" });
+ renderBrowserPane(STUDIO_PATH);
+
+ expect(screen.getByTestId("hero-recording")).toBeTruthy();
+ });
+
+ it("prefers the live debug browser over an old run's replay when idle", () => {
+ seedRun({ status: Status.Completed, recordingUrl: "https://r.test/1.mp4" });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(STUDIO_PATH);
+
+ expect(screen.getByTestId("browser-pane-stream-slot")).toBeTruthy();
+ });
+
+ it("replays a finished run named in the URL even while the session is live", () => {
+ seedRun({ status: Status.Completed, recordingUrl: "https://r.test/1.mp4" });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1`);
+
+ expect(screen.getByTestId("hero-recording")).toBeTruthy();
+ });
+
+ it("shows the inspected step's screenshot when ?active= is set", () => {
+ seedRun({ status: Status.Completed });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1&active=act_1`);
+
+ const shot = screen.getByTestId("hero-screenshot");
+ expect(JSON.parse(shot.getAttribute("data-selection") ?? "{}")).toEqual({
+ kind: "action",
+ artifactId: "art_1",
+ stepId: "step_1",
+ actionOrder: 0,
+ });
+ expect(screen.getByText(/Inspecting ·/)).toBeTruthy();
+ });
+
+ it("stays live for an executing block run in the debug session", () => {
+ seedRun({ status: Status.Running, browserSessionId: "pbs_test" });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1&bl=Block%201`);
+
+ expect(screen.getByTestId("browser-pane-stream-slot")).toBeTruthy();
+ expect(screen.queryByTestId("run-live-stream")).toBeNull();
+ });
+
+ it("keeps the live debug browser after a block run finalizes", () => {
+ seedRun({
+ status: Status.Completed,
+ browserSessionId: "pbs_test",
+ recordingUrl: "https://r.test/1.mp4",
+ });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1&bl=Block%201`);
+
+ expect(screen.getByTestId("browser-pane-stream-slot")).toBeTruthy();
+ });
+
+ it("streams a running full run through its own run stream", () => {
+ seedRun({ status: Status.Running, browserSessionId: "pbs_run" });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1`);
+
+ const stream = screen.getByTestId("run-live-stream");
+ expect(stream.getAttribute("data-run")).toBe("wr_1");
+ expect(stream.getAttribute("data-session")).toBe("pbs_run");
+ expect(stream.getAttribute("data-interactive")).toBe("no");
+ expect(screen.queryByTestId("browser-pane-stream-slot")).toBeNull();
+ });
+
+ it("makes a paused run's stream interactive (human input)", () => {
+ seedRun({ status: Status.Paused, browserSessionId: "pbs_run" });
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1`);
+
+ expect(
+ screen.getByTestId("run-live-stream").getAttribute("data-interactive"),
+ ).toBe("yes");
+ });
+
+ it("waits for a queued full run instead of mounting its stream", () => {
+ seedRun({ status: Status.Queued });
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1`);
+
+ expect(screen.getByTestId("stream-status").textContent).toContain(
+ "Starting the browser",
+ );
+ expect(screen.queryByTestId("run-live-stream")).toBeNull();
+ });
+
+ it("drops a stale replay pill when a recording starts", () => {
+ seedRun({ status: Status.Completed, recordingUrl: "https://r.test/1.mp4" });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ // The user pinned the replay before hitting Record.
+ useStudioBrowserStore.setState({ view: "recording" });
+ useRecordingStore.setState({ isRecording: true });
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1`);
+
+ expect(screen.getByTestId("browser-pane-stream-slot")).toBeTruthy();
+ expect(screen.queryByTestId("hero-recording")).toBeNull();
+ });
+
+ it("pins the live debug stream while a browser recording runs", () => {
+ // Even with a pinned step (?active=), recording surfaces the live browser.
+ seedRun({ status: Status.Completed });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ useRecordingStore.setState({ isRecording: true });
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1&active=act_1`);
+
+ expect(screen.getByTestId("browser-pane-stream-slot")).toBeTruthy();
+ expect(screen.getByText("Recording", { exact: true })).toBeTruthy();
+ });
+
+ it("flags a queued block run on the live debug stream", () => {
+ seedRun({ status: Status.Queued, browserSessionId: "pbs_test" });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1&bl=Block%201`);
+
+ expect(screen.getByTestId("browser-pane-stream-slot")).toBeTruthy();
+ expect(screen.getByText(/Run queued/)).toBeTruthy();
+ });
+});
+
+describe("BrowserTab pills and selection sync", () => {
+ it("switches views from the header pills", () => {
+ seedRun({ status: Status.Completed, recordingUrl: "https://r.test/1.mp4" });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1`);
+
+ expect(screen.getByTestId("hero-recording")).toBeTruthy();
+
+ fireEvent.click(screen.getByRole("button", { name: "Live" }));
+ expect(screen.getByTestId("browser-pane-stream-slot")).toBeTruthy();
+
+ fireEvent.click(screen.getByRole("button", { name: "Screenshots" }));
+ expect(screen.getByTestId("hero-screenshot")).toBeTruthy();
+
+ fireEvent.click(screen.getByRole("button", { name: "Recording" }));
+ expect(screen.getByTestId("hero-recording")).toBeTruthy();
+ });
+
+ it("returns to the selected step when the timeline re-pins it", () => {
+ seedRun({ status: Status.Completed });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1&active=act_1`);
+
+ expect(screen.getByTestId("hero-screenshot")).toBeTruthy();
+
+ fireEvent.click(screen.getByRole("button", { name: "Live" }));
+ expect(screen.getByTestId("browser-pane-stream-slot")).toBeTruthy();
+
+ // A timeline click pins the frame (even the already-selected one); the
+ // pane hands the view back to the machine, which lands on Screenshots.
+ act(() => {
+ useRunViewStore.getState().pinFrame("act_1");
+ });
+ expect(screen.getByTestId("hero-screenshot")).toBeTruthy();
+ });
+
+ it("disables debug-browser actions while the run's own stream is shown", () => {
+ seedRun({ status: Status.Running, browserSessionId: "pbs_run" });
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1`);
+
+ expect(screen.getByTestId("run-live-stream")).toBeTruthy();
+ for (const name of [
+ "Reconnect browser stream",
+ "Open browser in new tab",
+ "Turn off browser",
+ ]) {
+ expect((screen.getByLabelText(name) as HTMLButtonElement).disabled).toBe(
+ true,
+ );
+ }
+ });
+
+ it("keeps debug-browser actions enabled on the live debug stream", () => {
+ mocks.debugSession = { browser_session_id: "pbs_test" };
+ renderBrowserPane(STUDIO_PATH);
+
+ for (const name of [
+ "Reconnect browser stream",
+ "Open browser in new tab",
+ "Turn off browser",
+ ]) {
+ expect((screen.getByLabelText(name) as HTMLButtonElement).disabled).toBe(
+ false,
+ );
+ }
+ });
+
+ it("marks the resolved view's pill as pressed", () => {
+ seedRun({ status: Status.Completed, recordingUrl: "https://r.test/1.mp4" });
+ renderBrowserPane(`${STUDIO_PATH}&wr=wr_1`);
+
+ expect(
+ screen
+ .getByRole("button", { name: "Recording" })
+ .getAttribute("aria-pressed"),
+ ).toBe("true");
+ expect(
+ screen.getByRole("button", { name: "Live" }).getAttribute("aria-pressed"),
+ ).toBe("false");
+ });
+});
diff --git a/skyvern-frontend/src/routes/workflows/studio/BrowserTab.tsx b/skyvern-frontend/src/routes/workflows/studio/BrowserTab.tsx
index 603408d8c..3e6ed286b 100644
--- a/skyvern-frontend/src/routes/workflows/studio/BrowserTab.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/BrowserTab.tsx
@@ -1,231 +1,135 @@
-import {
- GlobeIcon,
- OpenInNewWindowIcon,
- ReloadIcon,
-} from "@radix-ui/react-icons";
-import { AxiosError } from "axios";
-import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { useState } from "react";
-import { useParams } from "react-router-dom";
+import { useCallback } from "react";
+import { ClockIcon, CounterClockwiseClockIcon } from "@radix-ui/react-icons";
+import { usePostHog } from "posthog-js/react";
-import { getClient } from "@/api/AxiosClient";
-import { DebugSessionApiResponse } from "@/api/types";
-import { PowerIcon } from "@/components/icons/PowerIcon";
-import { Button } from "@/components/ui/button";
-import {
- Dialog,
- DialogClose,
- DialogContent,
- DialogDescription,
- DialogFooter,
- DialogHeader,
- DialogTitle,
- DialogTrigger,
-} from "@/components/ui/dialog";
-import { toast } from "@/components/ui/use-toast";
-import { useBrowserStreamingMode } from "@/hooks/useRuntimeConfig";
-import { useCredentialGetter } from "@/hooks/useCredentialGetter";
-import {
- StreamModeBadge,
- StreamStatusPanel,
-} from "@/routes/streaming/StreamDiagnostics";
-import { useStudioBrowserStore } from "@/store/useStudioBrowserStore";
-import { useRecordingStore } from "@/store/useRecordingStore";
-import { useRecordingLauncherStore } from "@/store/useRecordingLauncherStore";
+import { StreamStatusPanel } from "@/routes/streaming/StreamDiagnostics";
-import { useDebugSessionQuery } from "../hooks/useDebugSessionQuery";
+import { HeroRecording } from "./runview/HeroRecording";
+import { HeroScreenshot } from "./runview/HeroScreenshot";
+import { RunLiveStream } from "./runview/RunLiveStream";
+import { useBrowserPaneView } from "./useBrowserPaneView";
import { useStudioShellContext } from "./StudioShellContext";
-const ICON_BUTTON =
- "shrink-0 rounded p-1.5 text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-40";
-
/**
- * Browser tab of the studio shell — the persistent debug browser. The stream node
- * lives in the shell and is re-parented into this tab's slot.
+ * Browser pane body of the studio shell — the run-aware visual surface. Live
+ * shows the persistent debug browser (the shell re-parents the singleton stream
+ * into this pane's slot) or the inspected run's own live stream; Recording and
+ * Screenshots replay the inspected run. The view machine lives in
+ * useBrowserPaneView; the pane chrome header hosts the pills and stream controls.
*/
export function BrowserTab() {
- const { workflowPermanentId } = useParams();
const { setBrowserStreamSlot } = useStudioShellContext();
- const { browserStreamingMode } = useBrowserStreamingMode();
- const credentialGetter = useCredentialGetter();
- const queryClient = useQueryClient();
- const { data: debugSession } = useDebugSessionQuery({
- workflowPermanentId,
- enabled: false,
- });
- const browserSessionId = debugSession?.browser_session_id ?? null;
+ const {
+ view,
+ visuals,
+ runId,
+ debugBrowserSessionId,
+ runInDebugSession,
+ liveSurface,
+ } = useBrowserPaneView();
+ const postHog = usePostHog();
- const streamUrl = useStudioBrowserStore((s) => s.streamUrl);
- const reload = useStudioBrowserStore((s) => s.reload);
- const isRecording = useRecordingStore((s) => s.isRecording);
- const manualCapturePaused = useRecordingStore((s) => s.manualCapturePaused);
- const startRecordingAtEnd = useRecordingLauncherStore(
- (s) => s.startRecordingAtEnd,
- );
- const [confirmOff, setConfirmOff] = useState(false);
+ const {
+ workflowRun,
+ running,
+ provisioning,
+ isPaused,
+ recordingUrls,
+ heroSelection,
+ heroLabel,
+ scrubbing,
+ } = visuals;
- const cycleBrowser = useMutation({
- mutationFn: async (workflowId: string) => {
- const client = await getClient(credentialGetter, "sans-api-v1");
- return client.post<DebugSessionApiResponse>(
- `/debug-session/${workflowId}/new`,
- );
- },
- onSuccess: (response) => {
- queryClient.setQueryData(
- ["debugSession", workflowPermanentId],
- response.data,
- );
- void queryClient.invalidateQueries({
- queryKey: ["debugSession", workflowPermanentId],
- });
- setConfirmOff(false);
- toast({
- variant: "success",
- title: "Browser restarted",
- description: "A fresh browser is starting.",
+ const onRecordingPlay = useCallback(
+ (index: number) => {
+ if (!workflowRun) {
+ return;
+ }
+ postHog.capture("run.recording.viewed", {
+ org_id: workflowRun.workflow?.organization_id,
+ run_id: workflowRun.workflow_run_id,
+ recording_index: index,
+ recording_count: recordingUrls.length,
});
},
- onError: (error: AxiosError) => {
- toast({
- variant: "destructive",
- title: "Failed to turn off browser",
- description: error.message,
- });
- },
- });
+ [postHog, workflowRun, recordingUrls.length],
+ );
- const openInNewTab = () => {
- if (!browserSessionId) {
- return;
- }
- window.open(
- `${window.location.origin}/browser-session/${browserSessionId}`,
- "_blank",
- "noopener",
- );
- };
+ // A running run outside the debug session streams through its own per-run
+ // socket; everything else lives on the shared debug-session singleton.
+ // (The runId check re-narrows for TS; "run" already implies it.)
+ const showRunStream = liveSurface === "run" && runId != null;
return (
- <div className="flex h-full min-h-0 w-full flex-col gap-3 p-3">
- <div className="flex shrink-0 items-center gap-1.5 rounded-lg border border-border bg-slate-elevation1 px-3 py-2">
- <GlobeIcon className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
- <span className="min-w-0 flex-1 truncate text-sm font-medium text-foreground">
- {streamUrl || "Live browser"}
- </span>
- {isRecording ? (
- manualCapturePaused ? (
- <span className="flex shrink-0 items-center gap-1.5 rounded-full bg-amber-500/10 px-2.5 py-1 text-xs font-medium text-amber-500">
- <span className="h-2 w-2 rounded-full bg-amber-500" />
- Paused
- </span>
+ <div className="flex h-full min-h-0 w-full flex-col p-3">
+ <div className="relative flex min-h-0 flex-1 items-center justify-center overflow-hidden rounded-lg border border-border bg-slate-950">
+ {view === "live" ? (
+ showRunStream ? (
+ provisioning ? (
+ // Mounting the stream while the run is still queued opens a
+ // socket the backend never feeds; wait until it actually runs.
+ <StreamStatusPanel
+ diagnostic={{
+ title: "Starting the browser",
+ detail: "Getting your run's browser ready…",
+ pending: true,
+ }}
+ />
+ ) : (
+ <RunLiveStream
+ workflowRunId={runId}
+ browserSessionId={workflowRun?.browser_session_id ?? null}
+ interactive={isPaused}
+ />
+ )
+ ) : debugBrowserSessionId ? (
+ <>
+ <div
+ ref={setBrowserStreamSlot}
+ data-testid="browser-pane-stream-slot"
+ className="absolute inset-0"
+ />
+ {provisioning && runInDebugSession ? (
+ // A block run can queue behind a running full run
+ // (run_sequentially); the debug browser is already live, so
+ // say why nothing moves yet.
+ <div className="absolute left-3 top-3 flex items-center gap-2 rounded-md bg-black/70 px-3 py-1.5 text-xs text-white backdrop-blur">
+ <ClockIcon className="h-3.5 w-3.5 shrink-0" />
+ <span>Run queued — waiting to start</span>
+ </div>
+ ) : null}
+ </>
) : (
- <span className="flex shrink-0 items-center gap-1.5 rounded-full bg-red-500/10 px-2.5 py-1 text-xs font-medium text-red-500">
- <span className="h-2 w-2 animate-pulse rounded-full bg-red-500" />
- Recording
- </span>
+ <StreamStatusPanel
+ diagnostic={{
+ title: "Warming up your browser",
+ detail:
+ "Spinning up the debug browser — this only takes a moment.",
+ pending: true,
+ }}
+ />
)
- ) : (
- <Button
- variant="secondary"
- size="sm"
- className="shrink-0 gap-1.5"
- disabled={!browserSessionId || !startRecordingAtEnd}
- onClick={() => startRecordingAtEnd?.()}
- >
- <span className="h-2 w-2 rounded-full bg-red-500" />
- Record
- </Button>
- )}
- <button
- type="button"
- title="Reconnect"
- aria-label="Reconnect browser stream"
- onClick={reload}
- disabled={!browserSessionId}
- className={ICON_BUTTON}
- >
- <ReloadIcon className="h-4 w-4" />
- </button>
- <button
- type="button"
- title="Open in new tab"
- aria-label="Open browser in new tab"
- onClick={openInNewTab}
- disabled={!browserSessionId}
- className={ICON_BUTTON}
- >
- <OpenInNewWindowIcon className="h-4 w-4" />
- </button>
- <StreamModeBadge mode={browserStreamingMode} className="shrink-0" />
- <Dialog
- open={confirmOff}
- onOpenChange={(open) => {
- if (!open && cycleBrowser.isPending) {
- return;
- }
- setConfirmOff(open);
- }}
- >
- <DialogTrigger asChild>
- <button
- type="button"
- title="Turn off browser"
- aria-label="Turn off browser"
- disabled={!workflowPermanentId || !browserSessionId}
- className={ICON_BUTTON}
- >
- <PowerIcon className="h-4 w-4" />
- </button>
- </DialogTrigger>
- <DialogContent>
- <DialogHeader>
- <DialogTitle>Turn off this browser?</DialogTitle>
- <DialogDescription>
- This ends the current browser and starts a fresh one. Anything
- in progress here will stop.
- </DialogDescription>
- </DialogHeader>
- <DialogFooter>
- <DialogClose asChild>
- <Button variant="secondary" disabled={cycleBrowser.isPending}>
- Cancel
- </Button>
- </DialogClose>
- <Button
- variant="destructive"
- disabled={!workflowPermanentId || cycleBrowser.isPending}
- onClick={() =>
- workflowPermanentId &&
- cycleBrowser.mutate(workflowPermanentId)
- }
- >
- {cycleBrowser.isPending ? (
- <>
- <ReloadIcon className="mr-2 size-4 animate-spin" />
- Turning off…
- </>
- ) : (
- "Turn off"
- )}
- </Button>
- </DialogFooter>
- </DialogContent>
- </Dialog>
- </div>
-
- <div className="relative flex min-h-0 flex-1 items-center justify-center overflow-hidden rounded-lg border border-border bg-slate-950">
- {browserSessionId ? (
- <div ref={setBrowserStreamSlot} className="absolute inset-0" />
- ) : (
- <StreamStatusPanel
- diagnostic={{
- title: "Warming up your browser",
- detail:
- "Spinning up the debug browser — this only takes a moment.",
- pending: true,
- }}
+ ) : view === "recording" ? (
+ <HeroRecording
+ recordingUrls={recordingUrls}
+ onPlay={onRecordingPlay}
/>
+ ) : heroSelection ? (
+ <>
+ <HeroScreenshot selection={heroSelection} running={running} />
+ {scrubbing ? (
+ <div className="absolute left-3 top-3 flex max-w-[26rem] items-center gap-2 rounded-md bg-black/70 px-3 py-1.5 text-xs text-white backdrop-blur">
+ <CounterClockwiseClockIcon className="h-3.5 w-3.5 shrink-0" />
+ <span className="truncate">
+ Inspecting · <b>{heroLabel}</b>
+ </span>
+ </div>
+ ) : null}
+ </>
+ ) : (
+ <div className="absolute inset-0 grid place-items-center text-sm text-muted-foreground">
+ Waiting for the first action…
+ </div>
)}
</div>
</div>
diff --git a/skyvern-frontend/src/routes/workflows/studio/StudioBrowserStream.test.tsx b/skyvern-frontend/src/routes/workflows/studio/StudioBrowserStream.test.tsx
index 00e84f9ce..ae6f4f9ea 100644
--- a/skyvern-frontend/src/routes/workflows/studio/StudioBrowserStream.test.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/StudioBrowserStream.test.tsx
@@ -28,6 +28,14 @@ vi.mock("../hooks/useWorkflowRunWithWorkflowQuery", () => ({
workflowRunQueryMock(options),
}));
+vi.mock("../hooks/useWorkflowRunTimelineQuery", () => ({
+ useWorkflowRunTimelineQuery: () => ({ data: undefined }),
+}));
+
+vi.mock("../hooks/useWorkflowRunsQuery", () => ({
+ useWorkflowRunsQuery: () => ({ data: [], isPending: false }),
+}));
+
vi.mock("@/hooks/useRuntimeConfig", () => ({
useBrowserStreamingMode: () => ({
browserStreamingMode: runtimeConfigMock.browserStreamingMode,
@@ -227,29 +235,29 @@ describe("StudioBrowserStream browser activity notifications", () => {
});
});
-describe("StudioBrowserStream block-run take-control gating", () => {
- it("locks take-control while a block run executes in the debug session", () => {
+describe("StudioBrowserStream block-run co-drive", () => {
+ it("keeps take-control available while a block run executes (co-drive)", () => {
mockWorkflowRun(Status.Running, "pbs_test");
renderStudioBrowserStream(BLOCK_RUN_OPEN_PATH);
- expect(controlButtonsAttr("emit vnc frame")).toBe("no");
+ expect(controlButtonsAttr("emit vnc frame")).toBe("yes");
expect(screen.getByRole("status").textContent).toContain(
- "Skyvern is running this block",
+ "Agent is running — you're sharing the browser",
);
});
- it("locks the CDP stream the same way (input socket keys off the same prop)", () => {
+ it("keeps the CDP stream controllable the same way", () => {
runtimeConfigMock.browserStreamingMode = "cdp";
mockWorkflowRun(Status.Running, "pbs_test");
renderStudioBrowserStream(BLOCK_RUN_OPEN_PATH);
- expect(controlButtonsAttr("emit cdp activity")).toBe("no");
+ expect(controlButtonsAttr("emit cdp activity")).toBe("yes");
expect(screen.getByRole("status").textContent).toContain(
- "Skyvern is running this block",
+ "Agent is running — you're sharing the browser",
);
});
- it("re-enables take-control once the block run finalizes", () => {
+ it("drops the sharing pill once the block run finalizes", () => {
mockWorkflowRun(Status.Completed, "pbs_test");
renderStudioBrowserStream(BLOCK_RUN_OPEN_PATH);
@@ -257,7 +265,7 @@ describe("StudioBrowserStream block-run take-control gating", () => {
expect(screen.queryByRole("status")).toBeNull();
});
- it("releases the lock while the block run is paused (may need human input)", () => {
+ it("shows no sharing pill while the block run is paused (needs human input)", () => {
mockWorkflowRun(Status.Paused, "pbs_test");
renderStudioBrowserStream(BLOCK_RUN_OPEN_PATH);
@@ -265,11 +273,24 @@ describe("StudioBrowserStream block-run take-control gating", () => {
expect(screen.queryByRole("status")).toBeNull();
});
- it("ignores a block run executing in a different browser session", () => {
+ it("parks controls when the block run streams from a different session", () => {
+ // The pane's live surface is the run's own stream; the debug singleton is
+ // parked, so it must withdraw take-control (and show no pill).
mockWorkflowRun(Status.Running, "pbs_other");
renderStudioBrowserStream(BLOCK_RUN_OPEN_PATH);
- expect(controlButtonsAttr("emit vnc frame")).toBe("yes");
+ expect(controlButtonsAttr("emit vnc frame")).toBe("no");
+ expect(screen.queryByRole("status")).toBeNull();
+ });
+
+ it("cedes control while the pane shows a replay view", () => {
+ // ?active= pins a step -> Screenshots view; the singleton is parked, so
+ // the control offer (and any held grab) is withdrawn.
+ mockWorkflowRun(Status.Running, "pbs_test");
+ renderStudioBrowserStream(`${BLOCK_RUN_OPEN_PATH}&active=act_1`);
+
+ expect(controlButtonsAttr("emit vnc frame")).toBe("no");
+ expect(screen.queryByRole("status")).toBeNull();
});
it("ignores a full (non-block) run even when its session matches", () => {
@@ -277,9 +298,10 @@ describe("StudioBrowserStream block-run take-control gating", () => {
renderStudioBrowserStream(`${BROWSER_OPEN_PATH}&wr=run_1`);
expect(controlButtonsAttr("emit vnc frame")).toBe("yes");
+ expect(screen.queryByRole("status")).toBeNull();
});
- it("shows no lock pill while the Browser pane is closed", () => {
+ it("keeps other surfaces view-only while the Browser pane is closed", () => {
mockWorkflowRun(Status.Running, "pbs_test");
renderStudioBrowserStream(BLOCK_RUN_CLOSED_PATH);
@@ -287,7 +309,7 @@ describe("StudioBrowserStream block-run take-control gating", () => {
expect(screen.queryByRole("status")).toBeNull();
});
- it("defers to an active recording instead of yanking its control", () => {
+ it("shows no sharing pill during a recording (the recorder is driving)", () => {
useRecordingStore.setState({ isRecording: true });
mockWorkflowRun(Status.Running, "pbs_test");
renderStudioBrowserStream(BLOCK_RUN_OPEN_PATH);
diff --git a/skyvern-frontend/src/routes/workflows/studio/StudioBrowserStream.tsx b/skyvern-frontend/src/routes/workflows/studio/StudioBrowserStream.tsx
index f08222dde..cfdb8f463 100644
--- a/skyvern-frontend/src/routes/workflows/studio/StudioBrowserStream.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/StudioBrowserStream.tsx
@@ -1,11 +1,10 @@
import { useCallback, useEffect } from "react";
-import { useParams } from "react-router-dom";
import { useRecordingStore } from "@/store/useRecordingStore";
import { useStudioBrowserStore } from "@/store/useStudioBrowserStore";
-import { useDebugSessionQuery } from "../hooks/useDebugSessionQuery";
import { StreamPresenter } from "./StreamPresenter";
+import { useBrowserPaneView } from "./useBrowserPaneView";
import { useExecutingBlockRun } from "./useExecutingBlockRun";
import { useStudioPanes } from "./useStudioPanes";
@@ -14,7 +13,6 @@ import { useStudioPanes } from "./useStudioPanes";
* between the open panes so the socket persists instead of re-booting.
*/
export function StudioBrowserStream() {
- const { workflowPermanentId } = useParams();
const { panes } = useStudioPanes();
const browserPaneOpen = panes.includes("browser");
const isRecording = useRecordingStore((s) => s.isRecording);
@@ -23,14 +21,17 @@ export function StudioBrowserStream() {
const markActivity = useStudioBrowserStore((s) => s.markActivity);
const clearActivity = useStudioBrowserStore((s) => s.clearActivity);
const reset = useStudioBrowserStore((s) => s.reset);
- const { data: debugSession } = useDebugSessionQuery({
- workflowPermanentId,
- enabled: false,
- });
- const browserSessionId = debugSession?.browser_session_id ?? null;
+ const { view, liveSurface, debugBrowserSessionId } = useBrowserPaneView();
+ const browserSessionId = debugBrowserSessionId;
const executingBlockRun = useExecutingBlockRun();
- // Recording keeps control by design — the recorder is driving the browser.
- const controlLocked = executingBlockRun && !isRecording;
+ // Co-drive: take-control stays available while a block run executes; the pill
+ // just flags the shared browser. Recording is exempt — the recorder is driving.
+ const coDriving = executingBlockRun && !isRecording;
+ // Only offer control while this stream is the pane's visible surface. A replay
+ // view or a per-run stream parks this node; withdrawing the offer makes
+ // BrowserStream release any held grab (it can't be exercised unseen).
+ const debugStreamShown =
+ browserPaneOpen && view === "live" && liveSurface === "debug";
useEffect(() => {
reset();
@@ -68,7 +69,7 @@ export function StudioBrowserStream() {
key={`${browserSessionId}:${reloadNonce}`}
browserSessionId={browserSessionId}
interactive={false}
- showControlButtons={browserPaneOpen && !controlLocked}
+ showControlButtons={debugStreamShown}
isRecording={isRecording}
// While recording, the Copilot pane hosts the live-drafts panel, whose
// header already shows the timer + step count — the REC pill would
@@ -77,18 +78,17 @@ export function StudioBrowserStream() {
onUrlChange={handleUrlChange}
onActivity={handleActivity}
/>
- {/* Explains the missing take-control; only the Browser pane offers it. */}
- {controlLocked && browserPaneOpen ? (
+ {coDriving && debugStreamShown ? (
<div
role="status"
className="pointer-events-none absolute left-1/2 top-3 z-10 flex max-w-[90%] -translate-x-1/2 items-center gap-2 rounded-md bg-black/70 px-3 py-1.5 text-xs text-white backdrop-blur duration-200 motion-safe:animate-in motion-safe:fade-in"
>
<span
aria-hidden
- className="size-1.5 shrink-0 rounded-full bg-studio-accent motion-safe:animate-pulse"
+ className="size-1.5 shrink-0 rounded-full bg-success motion-safe:animate-pulse"
/>
<span className="truncate">
- Skyvern is running this block — view only until it finishes
+ Agent is running — you're sharing the browser
</span>
</div>
) : null}
diff --git a/skyvern-frontend/src/routes/workflows/studio/StudioShell.tsx b/skyvern-frontend/src/routes/workflows/studio/StudioShell.tsx
index 830b07a53..169716878 100644
--- a/skyvern-frontend/src/routes/workflows/studio/StudioShell.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/StudioShell.tsx
@@ -18,6 +18,7 @@ import { cn } from "@/util/utils";
import { useDebugSessionQuery } from "../hooks/useDebugSessionQuery";
+import { BrowserPaneActions, BrowserPaneViewPills } from "./BrowserPaneHeader";
import { BrowserTab } from "./BrowserTab";
import { EditorTab, type StudioWorkspaceProps } from "./EditorTab";
import { RunTab } from "./RunTab";
@@ -28,7 +29,10 @@ import { STUDIO_PANE_META } from "./paneMeta";
import { STUDIO_PANE_MIN_WIDTH, type StudioPaneId } from "./panes";
import { StudioPaneDefaultsProvider } from "./StudioPaneDefaults";
import { useStudioPaneDefaults } from "./StudioPaneDefaultsContext";
-import { StudioShellContext } from "./StudioShellContext";
+import {
+ StudioPaneCompactContext,
+ StudioShellContext,
+} from "./StudioShellContext";
import { StudioSpine } from "./StudioSpine";
import { StudioStageLauncher } from "./StudioStageLauncher";
import { StudioTopBar } from "./StudioTopBar";
@@ -39,20 +43,54 @@ import { useStudioPanes } from "./useStudioPanes";
// whole stage; the shared floors live in panes.ts next to the fit math.
const COPILOT_MAX_WIDTH = 440;
+// Below this header width, pane header chrome (view pills, badges) collapses
+// to icons — same idea as the run hero, measured per pane, not per viewport.
+const PANE_HEADER_COMPACT_BELOW_PX = 480;
+
function StudioPane({
id,
open,
order,
onClose,
+ headerExtras,
+ headerActions,
children,
}: {
id: StudioPaneId;
open: boolean;
order: number | undefined;
onClose: () => void;
+ // Rendered after the pane label (badges, view pills).
+ headerExtras?: ReactNode;
+ // Rendered right-aligned, before the close button.
+ headerActions?: ReactNode;
children: ReactNode;
}) {
const { label, icon: Icon } = STUDIO_PANE_META[id];
+ const headerRef = useRef<HTMLDivElement>(null);
+ const hasChrome = headerExtras != null || headerActions != null;
+ const [compact, setCompact] = useState(false);
+ // Layout effect + an immediate measure so a narrow pane never paints one
+ // frame of full-width labels before the observer's first callback.
+ useLayoutEffect(() => {
+ const el = headerRef.current;
+ if (!hasChrome || !el || typeof ResizeObserver === "undefined") {
+ setCompact(false);
+ return;
+ }
+ const apply = (width: number) => {
+ // A closed pane measures 0 (display:none); keep its last real state.
+ if (width > 0) {
+ setCompact(width < PANE_HEADER_COMPACT_BELOW_PX);
+ }
+ };
+ apply(el.getBoundingClientRect().width);
+ const observer = new ResizeObserver((entries) => {
+ apply(entries[0]?.contentRect.width ?? 0);
+ });
+ observer.observe(el);
+ return () => observer.disconnect();
+ }, [hasChrome]);
return (
<section
id={studioPanelId(id)}
@@ -70,17 +108,25 @@ function StudioPane({
: "hidden",
)}
>
- <div className="flex h-9 shrink-0 items-center gap-2 border-b border-border px-3">
+ <div
+ ref={headerRef}
+ className="flex h-9 shrink-0 items-center gap-2 border-b border-border px-3"
+ >
<Icon className="size-3.5 shrink-0 text-studio-accent" aria-hidden />
- <span className="min-w-0 flex-1 truncate text-xs font-medium text-foreground">
+ <span className="min-w-0 truncate text-xs font-medium text-foreground">
{label}
</span>
+ <StudioPaneCompactContext.Provider value={compact}>
+ {headerExtras}
+ <span className="min-w-0 flex-1" />
+ {headerActions}
+ </StudioPaneCompactContext.Provider>
<button
type="button"
onClick={onClose}
title={`Close ${label}`}
aria-label={`Close ${label} pane`}
- className="rounded p-1 text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+ className="shrink-0 rounded p-1 text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
>
<Cross2Icon className="size-3.5" />
</button>
@@ -262,7 +308,11 @@ function StudioStage(props: StudioWorkspaceProps) {
</StudioPane>
{/* Kept mounted (CSS-hidden) so its stream slot stays registered;
the persistent stream node is re-parented in, not remounted. */}
- <StudioPane {...paneProps("browser")}>
+ <StudioPane
+ {...paneProps("browser")}
+ headerExtras={<BrowserPaneViewPills />}
+ headerActions={<BrowserPaneActions />}
+ >
<BrowserTab />
</StudioPane>
<StudioPane {...paneProps("run")}>
diff --git a/skyvern-frontend/src/routes/workflows/studio/StudioShellContext.ts b/skyvern-frontend/src/routes/workflows/studio/StudioShellContext.ts
index d77fbd4f4..769ee1c21 100644
--- a/skyvern-frontend/src/routes/workflows/studio/StudioShellContext.ts
+++ b/skyvern-frontend/src/routes/workflows/studio/StudioShellContext.ts
@@ -23,3 +23,11 @@ export const StudioShellContext = createContext<StudioShellContextValue>({
export function useStudioShellContext(): StudioShellContextValue {
return useContext(StudioShellContext);
}
+
+// True when the hosting pane header is too narrow for labels; header chrome
+// (view pills, badges) collapses to icons. Provided by StudioPane.
+export const StudioPaneCompactContext = createContext(false);
+
+export function useStudioPaneCompact(): boolean {
+ return useContext(StudioPaneCompactContext);
+}
diff --git a/skyvern-frontend/src/routes/workflows/studio/ViewToggle.tsx b/skyvern-frontend/src/routes/workflows/studio/ViewToggle.tsx
new file mode 100644
index 000000000..49cd52e43
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/studio/ViewToggle.tsx
@@ -0,0 +1,41 @@
+import { cn } from "@/util/utils";
+
+/**
+ * Segmented-control button shared by the studio's view toggles (run hero,
+ * browser pane header). Collapses to its icon when the host header is compact.
+ */
+export function ViewToggle({
+ active,
+ onClick,
+ icon,
+ label,
+ compact,
+ title,
+}: {
+ active: boolean;
+ onClick: () => void;
+ icon: React.ReactNode;
+ label: string;
+ compact: boolean;
+ title?: string;
+}) {
+ return (
+ <button
+ type="button"
+ onClick={onClick}
+ title={title ?? (compact ? label : undefined)}
+ aria-label={label}
+ aria-pressed={active}
+ className={cn(
+ "inline-flex items-center gap-1.5 rounded px-2 py-1 text-[11px] font-medium",
+ "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+ active
+ ? "bg-studio-accent/15 text-foreground"
+ : "text-muted-foreground hover:bg-accent hover:text-accent-foreground",
+ )}
+ >
+ {icon}
+ {compact ? null : label}
+ </button>
+ );
+}
diff --git a/skyvern-frontend/src/routes/workflows/studio/browserPaneView.test.ts b/skyvern-frontend/src/routes/workflows/studio/browserPaneView.test.ts
new file mode 100644
index 000000000..d4aa37d0d
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/studio/browserPaneView.test.ts
@@ -0,0 +1,174 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveBrowserPaneView } from "./browserPaneView";
+
+const base = {
+ intent: "auto" as const,
+ recording: false,
+ scrubbing: false,
+ inspectingRun: false,
+ blockRunInDebugSession: false,
+ running: false,
+ debugSessionUp: false,
+ hasRecording: false,
+ hasScreenshots: false,
+ failed: false,
+};
+
+describe("resolveBrowserPaneView", () => {
+ it("pins Live regardless of run state", () => {
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ intent: "live",
+ inspectingRun: true,
+ hasRecording: true,
+ hasScreenshots: true,
+ }),
+ ).toBe("live");
+ });
+
+ it("pins Recording only when a recording exists", () => {
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ intent: "recording",
+ hasRecording: true,
+ }),
+ ).toBe("recording");
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ intent: "recording",
+ debugSessionUp: true,
+ }),
+ ).toBe("live");
+ });
+
+ it("pins Screenshots only when screenshots exist", () => {
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ intent: "screenshots",
+ hasScreenshots: true,
+ }),
+ ).toBe("screenshots");
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ intent: "screenshots",
+ debugSessionUp: true,
+ }),
+ ).toBe("live");
+ });
+
+ it("overrides a stored replay intent when a recording starts", () => {
+ for (const intent of ["recording", "screenshots"] as const) {
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ intent,
+ recording: true,
+ hasRecording: true,
+ hasScreenshots: true,
+ debugSessionUp: true,
+ }),
+ ).toBe("live");
+ }
+ });
+
+ it("pins live while a browser recording is in progress", () => {
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ recording: true,
+ scrubbing: true,
+ inspectingRun: true,
+ hasRecording: true,
+ hasScreenshots: true,
+ }),
+ ).toBe("live");
+ });
+
+ it("shows the selected step while scrubbing", () => {
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ scrubbing: true,
+ running: true,
+ debugSessionUp: true,
+ }),
+ ).toBe("screenshots");
+ });
+
+ it("stays live for a block run in the debug session, even finalized", () => {
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ blockRunInDebugSession: true,
+ inspectingRun: true,
+ debugSessionUp: true,
+ hasRecording: true,
+ hasScreenshots: true,
+ }),
+ ).toBe("live");
+ });
+
+ it("goes live while the inspected run is running", () => {
+ expect(
+ resolveBrowserPaneView({ ...base, inspectingRun: true, running: true }),
+ ).toBe("live");
+ });
+
+ it("replays a finished inspected run (recording first)", () => {
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ inspectingRun: true,
+ debugSessionUp: true,
+ hasRecording: true,
+ hasScreenshots: true,
+ }),
+ ).toBe("recording");
+ });
+
+ it("shows screenshots for a failed inspected run", () => {
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ inspectingRun: true,
+ failed: true,
+ hasRecording: true,
+ hasScreenshots: true,
+ }),
+ ).toBe("screenshots");
+ });
+
+ it("defaults to the live debug browser when no run is inspected", () => {
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ debugSessionUp: true,
+ hasRecording: true,
+ hasScreenshots: true,
+ }),
+ ).toBe("live");
+ });
+
+ it("defaults to the last run's replay when idle with history and no session", () => {
+ expect(
+ resolveBrowserPaneView({
+ ...base,
+ hasRecording: true,
+ hasScreenshots: true,
+ }),
+ ).toBe("recording");
+ expect(resolveBrowserPaneView({ ...base, hasScreenshots: true })).toBe(
+ "screenshots",
+ );
+ });
+
+ it("falls back to live (warming up) with nothing to show", () => {
+ expect(resolveBrowserPaneView(base)).toBe("live");
+ });
+});
diff --git a/skyvern-frontend/src/routes/workflows/studio/browserPaneView.ts b/skyvern-frontend/src/routes/workflows/studio/browserPaneView.ts
new file mode 100644
index 000000000..eebf49621
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/studio/browserPaneView.ts
@@ -0,0 +1,77 @@
+import type { BrowserPaneViewIntent } from "@/store/useStudioBrowserStore";
+
+export type BrowserPaneView = "live" | "recording" | "screenshots";
+
+type ResolveBrowserPaneViewArgs = {
+ intent: BrowserPaneViewIntent;
+ // A browser recording is in progress — the user is driving the live debug
+ // browser, so the pane must surface it over any replay.
+ recording: boolean;
+ // ?active= pins a specific timeline step.
+ scrubbing: boolean;
+ // The URL names a run (?wr= / a run path param) — the pane is inspecting it.
+ inspectingRun: boolean;
+ // A block-scoped run (?bl=) shares the live debug session; the live browser
+ // stays the surface even after it finalizes (the block-iterate loop).
+ blockRunInDebugSession: boolean;
+ running: boolean;
+ debugSessionUp: boolean;
+ hasRecording: boolean;
+ hasScreenshots: boolean;
+ failed: boolean;
+};
+
+/**
+ * The Browser pane's view machine, ported from RunHero's resolveRunHeroCenterView:
+ * live while running, replay (recording/screenshots) on step-select or once the
+ * inspected run finishes, and an idle workflow with history but no live session
+ * defaults to the last run's replay instead of an empty stream.
+ */
+export function resolveBrowserPaneView({
+ intent,
+ recording,
+ scrubbing,
+ inspectingRun,
+ blockRunInDebugSession,
+ running,
+ debugSessionUp,
+ hasRecording,
+ hasScreenshots,
+ failed,
+}: ResolveBrowserPaneViewArgs): BrowserPaneView {
+ // An active recording outranks everything, stored replay intents included:
+ // the recorder is driving the live browser and must see it immediately.
+ if (recording) {
+ return "live";
+ }
+ if (intent === "live") {
+ return "live";
+ }
+ // A pinned replay intent can outlive its data (reload, run swap); fall back
+ // to the machine until there is something to render.
+ if (intent === "recording" && hasRecording) {
+ return "recording";
+ }
+ if (intent === "screenshots" && hasScreenshots) {
+ return "screenshots";
+ }
+ if (scrubbing) {
+ return "screenshots";
+ }
+ if (blockRunInDebugSession) {
+ return "live";
+ }
+ if (running) {
+ return "live";
+ }
+ if (inspectingRun) {
+ return hasRecording && !failed ? "recording" : "screenshots";
+ }
+ if (debugSessionUp) {
+ return "live";
+ }
+ if (hasRecording && !failed) {
+ return "recording";
+ }
+ return hasScreenshots ? "screenshots" : "live";
+}
diff --git a/skyvern-frontend/src/routes/workflows/studio/runview/RunHero.tsx b/skyvern-frontend/src/routes/workflows/studio/runview/RunHero.tsx
index dcb0e41c9..b375238b7 100644
--- a/skyvern-frontend/src/routes/workflows/studio/runview/RunHero.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/runview/RunHero.tsx
@@ -16,10 +16,10 @@ import {
import { Button } from "@/components/ui/button";
import { StreamStatusPanel } from "@/routes/streaming/StreamDiagnostics";
import { useRunViewStore } from "@/store/RunViewStore";
-import { cn } from "@/util/utils";
import { WorkflowRunCode } from "../../workflowRun/WorkflowRunCode";
import { useStudioShellContext } from "../StudioShellContext";
+import { ViewToggle } from "../ViewToggle";
import { matchFailureTips } from "./failureTips";
import { HeroRecording } from "./HeroRecording";
import { HeroScreenshot, type HeroSelection } from "./HeroScreenshot";
@@ -66,42 +66,6 @@ const HEADER_COMPACT_BELOW_PX = 640;
const RECORDING_ARCHIVED_LABEL =
"Recording archived — contact [email protected] to request restoration";
-function ViewToggle({
- active,
- onClick,
- icon,
- label,
- compact,
- title,
-}: {
- active: boolean;
- onClick: () => void;
- icon: React.ReactNode;
- label: string;
- compact: boolean;
- title?: string;
-}) {
- return (
- <button
- type="button"
- onClick={onClick}
- title={title ?? (compact ? label : undefined)}
- aria-label={label}
- aria-pressed={active}
- className={cn(
- "inline-flex items-center gap-1.5 rounded px-2 py-1 text-[11px] font-medium",
- "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
- active
- ? "bg-studio-accent/15 text-foreground"
- : "text-muted-foreground hover:bg-accent hover:text-accent-foreground",
- )}
- >
- {icon}
- {compact ? null : label}
- </button>
- );
-}
-
export function RunHero({
workflowRunId,
heroSelection,
diff --git a/skyvern-frontend/src/routes/workflows/studio/runview/RunView.test.tsx b/skyvern-frontend/src/routes/workflows/studio/runview/RunView.test.tsx
index 7258c1240..cf4074fff 100644
--- a/skyvern-frontend/src/routes/workflows/studio/runview/RunView.test.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/runview/RunView.test.tsx
@@ -13,6 +13,7 @@ import { type ReactNode } from "react";
import { ActionTypes, Status, type ActionsApiResponse } from "@/api/types";
import { useRunViewStore } from "@/store/RunViewStore";
+import { useStudioBrowserStore } from "@/store/useStudioBrowserStore";
import type {
WorkflowRunBlock,
WorkflowRunTimelineItem,
@@ -203,7 +204,15 @@ afterEach(() => {
mocks.debugSession = undefined;
mocks.runHeroProps = [];
});
-beforeEach(() => useRunViewStore.getState().reset());
+const initialStudioBrowserState = useStudioBrowserStore.getState();
+
+// jsdom doesn't implement scrollIntoView; focusBrowserPane calls it via rAF.
+Element.prototype.scrollIntoView = vi.fn();
+
+beforeEach(() => {
+ useRunViewStore.getState().reset();
+ useStudioBrowserStore.setState(initialStudioBrowserState, true);
+});
describe("getSelectedRunFrameId", () => {
test("defaults to live stream while a run is running", () => {
@@ -326,6 +335,25 @@ describe("RunView block run and the Browser pane", () => {
});
});
+ test("focusBrowserPane pins the Browser pane's Live view", () => {
+ seedLiveBlockRun();
+ useStudioBrowserStore.setState({ view: "screenshots" });
+ render(
+ <MemoryRouter
+ initialEntries={["/?wr=wr_1&bl=Block%201&panes=run,browser"]}
+ >
+ <RunView workflowRunId="wr_1" />
+ </MemoryRouter>,
+ );
+
+ const props = mocks.runHeroProps[mocks.runHeroProps.length - 1];
+ act(() => {
+ (props?.onFocusBrowserPane as () => void)();
+ });
+ // The CTA promises live; a pinned replay pill must not swallow it.
+ expect(useStudioBrowserStore.getState().view).toBe("live");
+ });
+
test("Browser pane closed, Run pane open: the hero stays self-sufficient", () => {
seedLiveBlockRun();
render(
diff --git a/skyvern-frontend/src/routes/workflows/studio/runview/RunView.tsx b/skyvern-frontend/src/routes/workflows/studio/runview/RunView.tsx
index 302095bbe..b63dd81ae 100644
--- a/skyvern-frontend/src/routes/workflows/studio/runview/RunView.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/runview/RunView.tsx
@@ -14,6 +14,7 @@ import {
isWorkflowRunBlock,
} from "@/routes/workflows/types/workflowRunTypes";
import { useRunViewStore } from "@/store/RunViewStore";
+import { useStudioBrowserStore } from "@/store/useStudioBrowserStore";
import { type ApiCommandOptions } from "@/util/apiCommands";
import { runsApiBaseUrl } from "@/util/env";
import { cn, isRecord } from "@/util/utils";
@@ -249,6 +250,8 @@ export function RunView({
// node (StudioShell priority); the hero then points at it instead.
const debugStreamInBrowserPane = showDebugStream && browserPaneOpen;
const focusBrowserPane = useCallback(() => {
+ // The pane may sit on a pinned replay view; this CTA promises live.
+ useStudioBrowserStore.getState().setView("live");
openPane("browser");
// Defer past the pane-open commit so the scroll sees the visible panel.
requestAnimationFrame(() => {
diff --git a/skyvern-frontend/src/routes/workflows/studio/useBrowserPaneView.ts b/skyvern-frontend/src/routes/workflows/studio/useBrowserPaneView.ts
new file mode 100644
index 000000000..0c2d4e44d
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/studio/useBrowserPaneView.ts
@@ -0,0 +1,108 @@
+import { useEffect, useRef } from "react";
+import { useParams, useSearchParams } from "react-router-dom";
+
+import { useRecordingStore } from "@/store/useRecordingStore";
+import { useRunViewStore } from "@/store/RunViewStore";
+import {
+ useStudioBrowserStore,
+ type BrowserPaneViewIntent,
+} from "@/store/useStudioBrowserStore";
+
+import { useDebugSessionQuery } from "../hooks/useDebugSessionQuery";
+import {
+ resolveBrowserPaneView,
+ type BrowserPaneView,
+} from "./browserPaneView";
+import { useRunVisuals, type RunVisuals } from "./useRunVisuals";
+import { useStudioInspectedRun } from "./useStudioInspectedRun";
+
+type BrowserPaneViewState = {
+ view: BrowserPaneView;
+ setView: (view: BrowserPaneViewIntent) => void;
+ visuals: RunVisuals;
+ runId: string | undefined;
+ debugBrowserSessionId: string | null;
+ // The inspected run executes in the live debug session, so its live view is
+ // the shared singleton stream — never a second socket to the same browser.
+ runInDebugSession: boolean;
+ // What the Live view shows: the shared debug-session singleton, or the
+ // inspected run's own per-run stream (running outside the debug session).
+ liveSurface: "debug" | "run";
+};
+
+/**
+ * Run-aware Browser pane state: which of Live / Recording / Screenshots the
+ * pane shows, resolved from the pill intent and the inspected run. Shared by
+ * the pane body and its header chrome (queries dedupe via react-query).
+ */
+export function useBrowserPaneView(): BrowserPaneViewState {
+ const { workflowPermanentId } = useParams();
+ const [searchParams] = useSearchParams();
+ const { runId, explicit } = useStudioInspectedRun();
+ const visuals = useRunVisuals(runId);
+ const { data: debugSession } = useDebugSessionQuery({
+ workflowPermanentId,
+ enabled: false,
+ });
+ const debugBrowserSessionId = debugSession?.browser_session_id ?? null;
+ const intent = useStudioBrowserStore((s) => s.view);
+ const setView = useStudioBrowserStore((s) => s.setView);
+ const pinNonce = useRunViewStore((s) => s.pinNonce);
+ const isRecording = useRecordingStore((s) => s.isRecording);
+
+ // Timeline selection outranks a pinned pill: a step click (?active= change or
+ // a re-pin of the same step) or a run swap hands the pane back to the machine,
+ // which lands on Screenshots for a pinned step and Live for a fresh run.
+ const activeParam = searchParams.get("active");
+ const syncRef = useRef({ activeParam, pinNonce, runId, isRecording });
+ useEffect(() => {
+ const prev = syncRef.current;
+ const recordingStarted = isRecording && !prev.isRecording;
+ if (
+ prev.activeParam !== activeParam ||
+ prev.pinNonce !== pinNonce ||
+ prev.runId !== runId ||
+ recordingStarted
+ ) {
+ syncRef.current = { activeParam, pinNonce, runId, isRecording };
+ setView("auto");
+ } else if (prev.isRecording !== isRecording) {
+ syncRef.current = { activeParam, pinNonce, runId, isRecording };
+ }
+ }, [activeParam, pinNonce, runId, isRecording, setView]);
+
+ const runInDebugSession =
+ visuals.workflowRun?.browser_session_id != null &&
+ visuals.workflowRun.browser_session_id === debugBrowserSessionId;
+ const blockRunInDebugSession = searchParams.has("bl") && runInDebugSession;
+
+ const view = resolveBrowserPaneView({
+ intent,
+ recording: isRecording,
+ scrubbing: visuals.scrubbing,
+ inspectingRun: explicit,
+ blockRunInDebugSession,
+ running: visuals.running,
+ debugSessionUp: debugBrowserSessionId != null,
+ hasRecording: visuals.recordingUrls.length > 0,
+ hasScreenshots: visuals.hasScreenshots,
+ failed: visuals.failed,
+ });
+
+ // Recording pins the live surface to the debug browser (the recorder drives
+ // it), even if an inspected run happens to be streaming elsewhere.
+ const liveSurface: "debug" | "run" =
+ !isRecording && visuals.running && !runInDebugSession && runId != null
+ ? "run"
+ : "debug";
+
+ return {
+ view,
+ setView,
+ visuals,
+ runId,
+ debugBrowserSessionId,
+ runInDebugSession,
+ liveSurface,
+ };
+}
diff --git a/skyvern-frontend/src/routes/workflows/studio/useExecutingBlockRun.ts b/skyvern-frontend/src/routes/workflows/studio/useExecutingBlockRun.ts
index 4bbe7d2bd..ce12ee343 100644
--- a/skyvern-frontend/src/routes/workflows/studio/useExecutingBlockRun.ts
+++ b/skyvern-frontend/src/routes/workflows/studio/useExecutingBlockRun.ts
@@ -8,9 +8,9 @@ import { useWorkflowRunWithWorkflowQuery } from "../hooks/useWorkflowRunWithWork
/**
* True while a block-scoped run (?wr= + ?bl=) is executing inside the current
- * debug session: the agent owns the shared debug browser, so user take-control
- * stays off until the run finalizes. Paused runs release the gate — a pause
- * can be waiting on human input (2FA, verification).
+ * debug session: the agent is driving the shared debug browser, so the stream
+ * flags that the user is co-driving. Paused runs don't count — a pause can be
+ * waiting on human input (2FA, verification).
*/
export function useExecutingBlockRun(): boolean {
const { workflowPermanentId } = useParams();
diff --git a/skyvern-frontend/src/routes/workflows/studio/useRunVisuals.ts b/skyvern-frontend/src/routes/workflows/studio/useRunVisuals.ts
new file mode 100644
index 000000000..24ba28e95
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/studio/useRunVisuals.ts
@@ -0,0 +1,170 @@
+import { useMemo } from "react";
+import { useSearchParams } from "react-router-dom";
+
+import { Status, WorkflowRunStatusApiResponseWithWorkflow } from "@/api/types";
+import { statusIsFinalized } from "@/routes/tasks/types";
+import {
+ isAction,
+ isObserverThought,
+ isWorkflowRunBlock,
+ WorkflowRunTimelineItem,
+} from "@/routes/workflows/types/workflowRunTypes";
+
+import { useWorkflowRunTimelineQuery } from "../hooks/useWorkflowRunTimelineQuery";
+import { useWorkflowRunWithWorkflowQuery } from "../hooks/useWorkflowRunWithWorkflowQuery";
+import { getRecordingUrls } from "../workflowRun/recordingUrls";
+import {
+ findActiveItem,
+ findTimelineBlock,
+ resolveScreenshotBlockId,
+} from "../workflowRun/workflowTimelineUtils";
+import { type HeroSelection } from "./runview/HeroScreenshot";
+import {
+ actionLabel,
+ buildFilmstrip,
+ runOutcomeFromStatus,
+} from "./runProjections";
+
+export type RunVisuals = {
+ workflowRun: WorkflowRunStatusApiResponseWithWorkflow | undefined;
+ timeline: WorkflowRunTimelineItem[] | undefined;
+ running: boolean;
+ failed: boolean;
+ finalized: boolean;
+ provisioning: boolean;
+ isPaused: boolean;
+ recordingUrls: string[];
+ recordingArchived: boolean;
+ hasScreenshots: boolean;
+ // ?active= pins a specific step (anything but the live-edge "stream" pin).
+ scrubbing: boolean;
+ heroSelection: HeroSelection | null;
+ heroLabel: string;
+};
+
+function hasScreenshotCandidate(selection: HeroSelection | null): boolean {
+ if (!selection) {
+ return false;
+ }
+ if (selection.kind === "action") {
+ return Boolean(
+ selection.artifactId ||
+ (selection.stepId && selection.actionOrder != null),
+ );
+ }
+ return true;
+}
+
+/**
+ * The inspected run's visual state for the Browser pane, derived the same way
+ * RunView drives its hero: ?active= (or the live edge) picks the timeline item,
+ * and screenshots resolve per element kind (action → own artifact, container
+ * block → leaf block, thought → LLM screenshot).
+ */
+export function useRunVisuals(workflowRunId: string | undefined): RunVisuals {
+ const queryOptions = workflowRunId ? { workflowRunId } : undefined;
+ const { data: workflowRun } = useWorkflowRunWithWorkflowQuery(queryOptions);
+ const { data: timeline } = useWorkflowRunTimelineQuery(queryOptions);
+ const [searchParams] = useSearchParams();
+ const activeParam = searchParams.get("active");
+
+ const outcome = runOutcomeFromStatus(workflowRun?.status);
+ const running = outcome === "running";
+ // A user-canceled run isn't a failure — its replay defaults like a success.
+ const canceled = workflowRun?.status === Status.Canceled;
+ const failed = outcome === "failed" && !canceled;
+ const finalized = workflowRun ? statusIsFinalized(workflowRun) : false;
+ const provisioning =
+ workflowRun?.status === Status.Created ||
+ workflowRun?.status === Status.Queued;
+ const isPaused = workflowRun?.status === Status.Paused;
+
+ const recordingUrls = useMemo(
+ () => getRecordingUrls(workflowRun),
+ [workflowRun],
+ );
+
+ const frames = useMemo(() => buildFilmstrip(timeline), [timeline]);
+ const lastFrame = frames.length > 0 ? frames[frames.length - 1] : null;
+ const scrubbing = activeParam != null && activeParam !== "stream";
+ const selectedFrameId = scrubbing ? activeParam : (lastFrame?.id ?? null);
+ const finallyBlockLabel =
+ workflowRun?.workflow?.workflow_definition?.finally_block_label ?? null;
+ const activeItem = useMemo(
+ () =>
+ findActiveItem(
+ timeline ?? [],
+ selectedFrameId,
+ finalized,
+ finallyBlockLabel,
+ ),
+ [timeline, selectedFrameId, finalized, finallyBlockLabel],
+ );
+
+ const heroSelection = useMemo<HeroSelection | null>(() => {
+ if (isAction(activeItem)) {
+ return {
+ kind: "action",
+ artifactId: activeItem.screenshot_artifact_id ?? null,
+ stepId: activeItem.step_id ?? null,
+ actionOrder: activeItem.action_order ?? null,
+ };
+ }
+ if (isWorkflowRunBlock(activeItem)) {
+ const screenshotBlockId = resolveScreenshotBlockId(
+ timeline ?? [],
+ activeItem,
+ null,
+ );
+ const blockType =
+ findTimelineBlock(timeline ?? [], screenshotBlockId)?.block_type ??
+ activeItem.block_type ??
+ null;
+ return {
+ kind: "block",
+ workflowRunBlockId: screenshotBlockId,
+ blockType,
+ };
+ }
+ if (isObserverThought(activeItem)) {
+ return { kind: "thought", thoughtId: activeItem.thought_id };
+ }
+ return null;
+ }, [activeItem, timeline]);
+
+ const hasScreenshotFrame = useMemo(
+ () =>
+ frames.some(
+ (frame) =>
+ frame.screenshotArtifactId != null ||
+ (frame.stepId != null && frame.actionOrder != null),
+ ),
+ [frames],
+ );
+ const hasScreenshots =
+ hasScreenshotFrame || hasScreenshotCandidate(heroSelection);
+
+ const heroLabel = isAction(activeItem)
+ ? actionLabel(activeItem)
+ : isWorkflowRunBlock(activeItem)
+ ? (activeItem.label ?? "Screenshot")
+ : isObserverThought(activeItem)
+ ? (activeItem.thought ?? "Thought")
+ : "Screenshot";
+
+ return {
+ workflowRun,
+ timeline,
+ running,
+ failed,
+ finalized,
+ provisioning,
+ isPaused,
+ recordingUrls,
+ recordingArchived: workflowRun?.recording_archived ?? false,
+ hasScreenshots,
+ scrubbing,
+ heroSelection,
+ heroLabel,
+ };
+}
diff --git a/skyvern-frontend/src/routes/workflows/studio/useStudioInspectedRun.ts b/skyvern-frontend/src/routes/workflows/studio/useStudioInspectedRun.ts
new file mode 100644
index 000000000..a57f13359
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/studio/useStudioInspectedRun.ts
@@ -0,0 +1,30 @@
+import { useParams } from "react-router-dom";
+
+import { useWorkflowRunsQuery } from "../hooks/useWorkflowRunsQuery";
+import { useStudioRunId } from "./useStudioRunId";
+
+/**
+ * The run the studio's visual surfaces inspect: the run named in the URL when
+ * present, otherwise the workflow's most recent run (same fallback as RunTab).
+ */
+export function useStudioInspectedRun(): {
+ runId: string | undefined;
+ // True when the URL names the run; false for the latest-run fallback.
+ explicit: boolean;
+ pending: boolean;
+} {
+ const urlRunId = useStudioRunId();
+ const { workflowPermanentId } = useParams();
+ const { data: runs, isPending } = useWorkflowRunsQuery({
+ workflowPermanentId,
+ page: 1,
+ pageSize: 1,
+ // The latest-run fallback is only needed when the URL names no run.
+ enabled: !urlRunId,
+ });
+ return {
+ runId: urlRunId ?? runs?.[0]?.workflow_run_id,
+ explicit: Boolean(urlRunId),
+ pending: !urlRunId && isPending,
+ };
+}
diff --git a/skyvern-frontend/src/store/RunViewStore.ts b/skyvern-frontend/src/store/RunViewStore.ts
index 15f108b00..f6fbc135c 100644
--- a/skyvern-frontend/src/store/RunViewStore.ts
+++ b/skyvern-frontend/src/store/RunViewStore.ts
@@ -15,6 +15,9 @@ type RunViewState = {
// The frame the user is inspecting. null means "follow the live edge" while
// running, or the recording once finalized.
pinnedFrameId: string | null;
+ // Bumped on every pinFrame so the Browser pane can react to a re-pin of the
+ // already-selected frame (the id alone wouldn't change).
+ pinNonce: number;
centerView: RunCenterView;
// True when the run-tab header is too narrow for labels (set by RunHero); the
// toggles and externally-rendered dropdown triggers then collapse to icons.
@@ -28,10 +31,16 @@ type RunViewState = {
export const useRunViewStore = create<RunViewState>((set) => ({
pinnedFrameId: null,
+ pinNonce: 0,
centerView: "default",
headerCompact: false,
// Inspecting a frame or jumping to live/recording always drops any override.
- pinFrame: (id) => set({ pinnedFrameId: id, centerView: "default" }),
+ pinFrame: (id) =>
+ set((state) => ({
+ pinnedFrameId: id,
+ centerView: "default",
+ pinNonce: state.pinNonce + 1,
+ })),
jumpToLive: () => set({ pinnedFrameId: null, centerView: "default" }),
setCenterView: (view) =>
set((state) => ({
diff --git a/skyvern-frontend/src/store/useStudioBrowserStore.ts b/skyvern-frontend/src/store/useStudioBrowserStore.ts
index 375d8020c..426718f37 100644
--- a/skyvern-frontend/src/store/useStudioBrowserStore.ts
+++ b/skyvern-frontend/src/store/useStudioBrowserStore.ts
@@ -1,17 +1,28 @@
import { create } from "zustand";
+// "auto" follows the run-aware machine in studio/browserPaneView.ts; the header
+// pills pin an explicit view until the next timeline selection or run change.
+export type BrowserPaneViewIntent =
+ | "auto"
+ | "live"
+ | "recording"
+ | "screenshots";
+
/**
- * Bridges the studio's single live-browser stream and the Browser tab's chrome:
- * the stream publishes its URL here; the toolbar drives a reconnect back into it.
+ * Bridges the studio's single live-browser stream and the Browser pane's chrome:
+ * the stream publishes its URL here; the header drives a reconnect back into it
+ * and holds the pane's Live/Recording/Screenshots view intent.
*/
type StudioBrowserState = {
streamUrl: string | null;
hasUnseenActivity: boolean;
reloadNonce: number;
+ view: BrowserPaneViewIntent;
setStreamUrl: (url: string | null) => void;
markActivity: () => void;
clearActivity: () => void;
reload: () => void;
+ setView: (view: BrowserPaneViewIntent) => void;
reset: () => void;
};
@@ -19,6 +30,7 @@ export const useStudioBrowserStore = create<StudioBrowserState>()((set) => ({
streamUrl: null,
hasUnseenActivity: false,
reloadNonce: 0,
+ view: "auto",
setStreamUrl: (streamUrl) => set({ streamUrl }),
markActivity: () =>
set((state) =>
@@ -29,5 +41,8 @@ export const useStudioBrowserStore = create<StudioBrowserState>()((set) => ({
state.hasUnseenActivity ? { hasUnseenActivity: false } : state,
),
reload: () => set((state) => ({ reloadNonce: state.reloadNonce + 1 })),
- reset: () => set({ streamUrl: null, hasUnseenActivity: false }),
+ setView: (view) => set({ view }),
+ // Also clears the view intent: workflow navigation resets this store without
+ // a selection/run change, so a stale replay pill could otherwise survive.
+ reset: () => set({ streamUrl: null, hasUnseenActivity: false, view: "auto" }),
}));