Browser

A composable React viewport for agent-browser. Stream a real session, visualize agent actions and hand control to a person without changing transports.

pnpm add @browser-ui/react

Demo

Built by danielsims

Find Mac mini, configure the desktop and a Studio Display, then hand the live session back at Apple’s final review.

Usage

Pass the stream URL from your agent-browser session and the small amount of state your application already owns.

agent-session.tsx

import { Browser } from "@browser-ui/react";

type AgentBrowserProps = {
  streamUrl: string;
  operating: boolean;
  action?: string;
  onTakeControl: () => void;
};

export function AgentBrowser({
  streamUrl,
  operating,
  action,
  onTakeControl,
}: AgentBrowserProps) {
  return (
    <Browser
      streamUrl={streamUrl}
      viewportSize={{ width: 1440, height: 900 }}
      operating={operating}
      operatingLabel={action}
      showPictureInPicture
      showFullscreen
      onTakeControl={onTakeControl}
    />
  );
}

Props

The composed API stays controlled where product behavior matters and provides sensible defaults for presentation.

Stream

streamUrlstring · required

WebSocket endpoint returned by agent-browser. Frames and user input travel over this connection.

viewportSize{ width, height }

Remote browser resolution, independent from the rendered component. Keep it fixed to preserve desktop breakpoints in PiP.

displayAspectRatioCSS aspect-ratio

Shape of the rendered component only. It never changes the remote viewport.

colorScheme"light" | "dark" | "system"

Controls Browser UI chrome independently from the streamed page. System follows the host device preference.

onUrlChange(url) => void

Reports navigation messages emitted by the remote browser.

onViewportResize(width, height) => void

Reports the requested remote viewport dimensions to the session owner.

onStatusChange(status) => void

Reports connecting, connected, disconnected and error states.

Agent activity

operatingboolean · false

Shows the activity shader and pauses direct viewport input while the agent owns the session.

operatingLabelstring

Current action displayed in the compact status control.

agentCursorBrowserAgentCursorState

Normalized cursor position and pressed or typing state for visualizing live or recorded agent actions.

agentCursor.sizenumber · 24

Controls the rendered cursor width in CSS pixels.

agentCursor.backgroundColorCSS color · #2f6bff

Controls the soft radial glow beneath the cursor.

onTakeControl() => void

Called when the person stops the workflow and takes ownership of browser input.

loadingLabelstring

Copy shown while the WebSocket is connecting or reconnecting.

Display

variant"framed" | "bare"

Use the standalone glass frame or an unstyled edge-to-edge surface.

showControlsboolean · false

Adds the optional address and reload controls.

showPictureInPictureboolean · false

Adds the floating picture-in-picture control.

showFullscreenboolean · false

Adds application fullscreen without changing the remote viewport size.

fullscreenTargetHTMLElement | null

Constrains fullscreen to a host element and tracks its bounds and border radius.

mode"inline" | "picture-in-picture" | "fullscreen"

Controls the display mode from your application.

defaultModedisplay mode · "inline"

Initial display mode when Browser manages its own state.

onModeChange(mode) => void

Reports transitions between inline, PiP and fullscreen.

Navigation

urlstring

Current URL shown by the optional controls.

onNavigate(url) => void

Receives address submissions so the session owner can navigate agent-browser.

onReload() => void

Receives reload requests from the optional browser controls.

ariaLabelstring

Accessible name for the interactive remote viewport.

viewportClassNamestring

Class name applied directly to AgentBrowserViewport.