# Browser Session > A computer/browser-use session made legible: tidy browser frame, the page, the agent's cursor with click ripple and target box, and a step log with take-over. - **Slug:** `browser-session` · **Category:** workspace · **Status:** experimental - **Import:** `import { BrowserHighlight, BrowserPoint, BrowserSession, BrowserStep, BrowserStepKind } from "@kura-ui/react/browser-session";` - **Docs:** https://kuro.abstergo.fyi/components/browser-session - **Registry item:** https://kuro.abstergo.fyi/r/browser-session.json - **Tags:** agent, browser, computer-use, browser-use, operator, cursor, screenshot, takeover ## Install ```bash # shadcn registry (copies source into your project) npx shadcn@latest add https://kuro.abstergo.fyi/r/browser-session.json # Kura CLI (same, plus dependency resolution and --json output) npx @kura-ui/cli add browser-session # npm package npm install @kura-ui/react ``` ## When to use - Show what a browser-use or computer-use agent is doing on a web page (Operator, Claude computer use, Browserbase, Playwright-driven agents). - Stream screenshots of a remote browser (`src`) with the agent's next action drawn on top (`cursor`, `highlight`). - Replay a recorded browser run step by step with the log of navigate / click / type / scroll / extract actions. - Hand control to the human when the agent hits a login, 2FA or CAPTCHA (`status="paused"` + `onResume`), or let them take over (`onTakeOver`). ## When not to use - Terminal or shell output from the agent — use terminal. - Code edits made by the agent — use diff-view or file-changes. - A plan or todo list of the whole run — use task-list. - A static rendered artifact (HTML preview, document) — use artifact-card. ## Props | Prop | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `url` | `string` | — | yes | Page URL in the address bar. The host is emphasised, the path muted; https shows a lock. | | `title` | `string` | — | no | Page title next to the address bar (hidden in narrow containers). | | `children` | `React.ReactNode` | — | no | Viewport content: a live page, or a mock rendered as markup. | | `src` | `string` | — | no | A screenshot URL to show instead of children (e.g. the latest frame from a remote browser). | | `alt` | `string` | — | no | Alt text for `src`. Default “Screenshot of {url}”. | | `viewport` | `{ width: number; height: number }` | — | no | Design size of the page in CSS px (e.g. the agent's 1280×800 screen). Children render at this size and scale to fit the frame, so % coordinates stay exact at any width. Omit to let children flow at the frame's width. | | `aspectRatio` | `number` | `16 / 10` | no | Viewport aspect ratio when `viewport` is not given. | | `scrollTop` | `number` | `0` | no | Vertical page scroll in viewport px; eases on change (use for scroll steps). | | `cursor` | `BrowserPoint \| null` | — | no | The agent's cursor { x, y } in % of the viewport. Glides to new positions. | | `cursorLabel` | `string` | — | no | Name tag on the cursor, e.g. the agent's name. | | `clickKey` | `string \| number` | — | no | Change it to play a click ripple at the cursor. Default: the active step's id when that step is a click. | | `highlight` | `BrowserHighlight \| null` | — | no | Box around the target element: { x, y, width, height } in % plus an optional `label` tag (e.g. `button "Create pull request"`). | | `steps` | `readonly BrowserStep[]` | — | no | The action log. BrowserStep = { id, kind: "navigate" \| "click" \| "type" \| "scroll" \| "extract", label, status: AgentStatus, detail? (mono: URL, selector, typed text) }. Omit to hide the log. | | `activeStep` | `string` | — | no | Id of the step being executed. Default: the first running step. | | `status` | `"browsing" \| "paused" \| "done" \| "failed"` | `"browsing"` | no | browsing = “Agent is browsing” (blue, shimmer); paused = “Paused for you” (amber, the viewport gets an amber edge); done; failed. | | `statusText` | `React.ReactNode` | — | no | Secondary text after the status, e.g. “Enter the 2FA code, then hand back”. | | `startedAt` | `Date \| number` | — | no | Session start (wall clock) for the elapsed clock; ticks while browsing. | | `loading` | `boolean` | — | no | Show the loading bar under the address bar. Default: true while the active step is a running navigate. | | `actions` | `React.ReactNode` | — | no | Extra controls in the status line (e.g. open in new tab, replay). | | `onTakeOver` | `() => void` | — | no | Shows a “Take over” button while browsing. | | `onResume` | `() => void` | — | no | Shows a “Resume agent” button while paused. | | `layout` | `"auto" \| "side" \| "stacked"` | `"auto"` | no | Step log beside the browser (side), below it (stacked), or beside only when the container is ≥ 48rem (auto). | Native attributes of the root element, `className` and `ref` are passed through. ## Anatomy - **BrowserSession** (`data-slot="browser-session"`) — Root panel; `data-status`, `data-layout`; container-query context; polite status region. - **Header** (`data-slot="browser-session-header"`) — Status line: glyph, “Agent is browsing” / “Paused for you”, statusText, done/total, elapsed, actions, Take over / Resume. - **Elapsed** (`data-slot="browser-session-elapsed"`) — Mono clock from startedAt. - **Browser** (`data-slot="browser-session-browser"`) — Column with the chrome and the viewport. - **Chrome** (`data-slot="browser-session-chrome"`) — Title (favicon letter + text) and the address bar. - **Address** (`data-slot="browser-session-address"`) — role="group" “Address”: lock, host, muted path, in mono. - **Loading** (`data-slot="browser-session-loading"`) — 2px accent sweep under the chrome while a page loads. - **Viewport** (`data-slot="browser-session-viewport"`) — Fixed-aspect frame (no layout shift); amber inner edge while paused. - **Page** (`data-slot="browser-session-page"`) — Holds children/src; scaled to fit when `viewport` is set; translated by scrollTop. - **Overlay** (`data-slot="browser-session-overlay"`) — aria-hidden layer for the highlight, ripple and cursor. - **Highlight** (`data-slot="browser-session-highlight"`) — Accent box + mono tag around the target; eases between targets. - **Cursor** (`data-slot="browser-session-cursor"`) — Pointer arrow with an optional accent name tag; glides between points. - **Ripple** (`data-slot="browser-session-ripple"`) — Accent ring that expands and fades after the cursor arrives. - **Log** (`data-slot="browser-session-log"`) — Scrollable step log; keeps the active step in view. - **Step** (`data-slot="browser-session-step"`) —
  • with `data-kind`, `data-status`, `data-active`; aria-current="step" on the active one. ## Accessibility - The overlay (cursor, ripple, highlight) is decorative and aria-hidden; what the agent is doing is carried by the step log and the status line. - The step log is an
      labelled “Browser actions”; each step speaks its status after the label, and the active one has aria-current="step". - A polite status region announces the active step's label (when it is a string), “Paused for you” / your statusText, “Session ended” or “Session failed” — never the ticking clock. - The address bar is a labelled group; the lock icon is labelled “Secure connection”. With `src`, the image gets alt text (default “Screenshot of {url}”). - Take over / Resume agent are real buttons with visible focus. Paused state is signalled by text and glyph, not only the amber edge. - Reduced motion: The cursor and highlight jump instead of gliding (the highlight still fades), the click ripple is skipped, page scroll is instant, the loading sweep becomes a static bar and the shimmer stops. | Keys | Action | | --- | --- | | Tab | Moves to the status-line actions (Take over / Resume agent) and any controls inside the page. | ## Notes for agents - Coordinates are percentages of the viewport. If your agent reports pixels on a W×H screen, pass `viewport={{ width: W, height: H }}` and use x = px / W * 100. - For remote browsers pass the latest screenshot as `src` and keep `viewport` equal to the screenshot size; draw the *next* action with `cursor` + `highlight`. - Change `clickKey` (e.g. an action counter) to replay the ripple; repeated clicks on the same step otherwise only ripple once. - Set `status="paused"` whenever the agent needs the human (login, 2FA, CAPTCHA, payment) and say why in `statusText`. - Map the agent's actions to the five kinds; put the URL, selector or typed text in `detail` (mono). ## Examples ### A page with the agent's cursor (minimal) A mock PR page at a fixed 800×500 design size, the cursor and a target box. ```tsx import { Check, GitPullRequest } from "lucide-react"; import { BrowserSession } from "@kura-ui/react/browser-session"; const W = 800; const H = 500; const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 }); const box = (x: number, y: number, w: number, h: number, label?: string) => ({ x: (x / W) * 100, y: (y / H) * 100, width: (w / W) * 100, height: (h / H) * 100, label, }); function PullRequestPage() { return (

      {PR_TITLE} #482

      Open kura wants to merge 4 commits into{" "} main from{" "} kura/auth-client
      Conversation Commits 4 Checks 3 Files changed 6
      {PR_BODY}
      All checks have passed
      {[ ["test", "142 passed · 41s"], ["typecheck", "0 errors · 18s"], ["lint", "clean · 6s"], ].map(([name, meta]) => (
      {name} {meta}
      ))}
      ); } const PR_TITLE = "Migrate session API to @acme/auth client"; const PR_BODY = "Replaces fetchUser() and the legacy /api/session REST calls with createAuthClient(). Refreshes expired sessions with the rotated token."; function SiteBar() { return (
      acme / web Code Pull requests Actions
      ); } export function BrowserSessionMinimal() { return ( ); } ``` ### Opening the pull request (full) Kura opens the compare view, types the title and description, clicks “Create pull request” and reads the PR number. The cursor glides, clicks ripple, the log advances and the session settles. ```tsx "use client"; import { Check, GitBranch, GitPullRequest, RotateCcw } from "lucide-react"; import * as React from "react"; import { IconButton } from "@kura-ui/react/icon-button"; import { BrowserSession, type BrowserStep } from "@kura-ui/react/browser-session"; const W = 800; const H = 500; const PR_TITLE = "Migrate session API to @acme/auth client"; const PR_BODY = "Replaces fetchUser() and the legacy /api/session REST calls with createAuthClient(). Refreshes expired sessions with the rotated token."; function ComparePage({ title, body, focus, }: { title: string; body: string; focus: "title" | "body" | null; }) { return (

      Open a pull request

      Create a new pull request by comparing changes across two branches.

      base: main ← compare: kura/auth-client Able to merge
      Title Description
      Markdown is supported Create pull request

      4 commits · 6 files changed · +142 −38

      ); } function PullRequestPage() { return (

      {PR_TITLE} #482

      Open kura wants to merge 4 commits into{" "} main from{" "} kura/auth-client
      Conversation Commits 4 Checks 3 Files changed 6
      {PR_BODY}
      All checks have passed
      {[ ["test", "142 passed · 41s"], ["typecheck", "0 errors · 18s"], ["lint", "clean · 6s"], ].map(([name, meta]) => (
      {name} {meta}
      ))}
      ); } const COMPARE_URL = "https://github.com/acme/web/compare/main...kura/auth-client"; const PR_URL = "https://github.com/acme/web/pull/482"; const STEPS: Omit[] = [ { id: "open", kind: "navigate", label: "Open the compare view", detail: COMPARE_URL.slice(8) }, { id: "focus", kind: "click", label: "Focus the title field", detail: "input#pr-title" }, { id: "title", kind: "type", label: "Type the PR title", detail: `“${PR_TITLE}”` }, { id: "body", kind: "type", label: "Write the description", detail: `“${PR_BODY.slice(0, 48)}…”`, }, { id: "submit", kind: "click", label: "Click “Create pull request”", detail: "button[type=submit]", }, { id: "read", kind: "extract", label: "Read the PR number", detail: "#482 · Open" }, ]; const TARGETS = { open: { cursor: at(400, 300), highlight: null }, focus: { cursor: at(140, 256), highlight: box(48, 236, 704, 36, "input#pr-title") }, title: { cursor: at(140, 256), highlight: box(48, 236, 704, 36, "input#pr-title") }, body: { cursor: at(160, 330), highlight: box(48, 308, 704, 96, "textarea#pr-body") }, submit: { cursor: at(690, 434), highlight: box(592, 416, 160, 32, 'button "Create pull request"'), }, read: { cursor: at(468, 94), highlight: box(24, 66, 478, 40, "h1 · #482") }, } as const; const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 }); const box = (x: number, y: number, w: number, h: number, label?: string) => ({ x: (x / W) * 100, y: (y / H) * 100, width: (w / W) * 100, height: (h / H) * 100, label, }); function SiteBar() { return (
      acme / web Code Pull requests Actions
      ); } function Field({ value, focused, tall }: { value: string; focused: boolean; tall?: boolean }) { return (
      {value} {focused && ( )} {!value && !focused && ( {tall ? "Add a description" : "Title"} )}
      ); } export function BrowserSessionFull() { const [step, setStep] = React.useState(0); const [typed, setTyped] = React.useState({ title: 0, body: 0 }); const [clicks, setClicks] = React.useState(0); const [run, setRun] = React.useState(0); const [startedAt, setStartedAt] = React.useState(); // biome-ignore lint/correctness/useExhaustiveDependencies: `run` replays the session React.useEffect(() => { setStep(0); setTyped({ title: 0, body: 0 }); setStartedAt(Date.now() - 6 * 60_000 - 12_000); const timers: ReturnType[] = []; const later = (ms: number, fn: () => void) => timers.push(setTimeout(fn, ms)); const type = (from: number, ms: number, key: "title" | "body", total: number) => { const n = 24; for (let i = 1; i <= n; i++) later(from + (ms / n) * i, () => setTyped((t) => ({ ...t, [key]: Math.round((total * i) / n) })), ); }; later(1300, () => setStep(1)); later(2300, () => setStep(2)); type(2400, 1500, "title", PR_TITLE.length); later(4100, () => { setStep(3); setClicks((c) => c + 1); }); type(4600, 1600, "body", PR_BODY.length); later(6500, () => setStep(4)); later(7700, () => setStep(5)); later(9200, () => setStep(6)); return () => timers.forEach(clearTimeout); }, [run]); const created = step >= 5; const current = STEPS[step]; const target = current ? TARGETS[current.id as keyof typeof TARGETS] : TARGETS.read; const steps: BrowserStep[] = STEPS.map((s, i) => ({ ...s, status: i < step ? "done" : i === step ? "running" : "queued", })); return ( = STEPS.length ? "done" : "browsing"} startedAt={startedAt} steps={steps} cursor={target.cursor} cursorLabel="Kura" clickKey={`${run}-${clicks}-${current?.kind === "click" ? current.id : ""}`} highlight={step >= STEPS.length ? null : target.highlight} onTakeOver={() => {}} statusText={step >= STEPS.length ? "acme/web#482 opened" : undefined} actions={ step >= STEPS.length && ( } variant="ghost" size="xs" className="animate-kura-fade-in" onClick={() => setRun((r) => r + 1)} /> ) } >
      {created ? ( ) : ( )}
      ); } ``` ### Paused for you (state) A 2FA prompt only the human can answer: amber edge, “Resume agent”. ```tsx "use client"; import { Check } from "lucide-react"; import * as React from "react"; import { BrowserSession } from "@kura-ui/react/browser-session"; const W = 800; const H = 500; const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 }); const box = (x: number, y: number, w: number, h: number, label?: string) => ({ x: (x / W) * 100, y: (y / H) * 100, width: (w / W) * 100, height: (h / H) * 100, label, }); function TwoFactorPage() { return (

      Two-factor authentication

      Enter the 6-digit code from your authenticator app to continue to Acme Cloud.

      {[0, 1, 2, 3, 4, 5].map((i) => ( ))}
      Verify Use a recovery code instead
      ); } export function BrowserSessionPaused() { const [paused, setPaused] = React.useState(true); const [startedAt] = React.useState(() => Date.now() - 9 * 60_000 - 41_000); return ( setPaused(false)} onTakeOver={() => setPaused(true)} steps={[ { id: "1", kind: "navigate", label: "Open the preview", status: "done", detail: "cloud.acme.dev/web/deployments", }, { id: "2", kind: "click", label: "Continue with GitHub", status: "done", detail: 'button[data-provider="github"]', }, { id: "3", kind: "type", label: "Enter the 2FA code", status: paused ? "waiting" : "running", detail: "Needs a code only you have", }, { id: "4", kind: "extract", label: "Check the login page", status: "queued", detail: "/login", }, ]} > ); } ``` ### Under the plan (composition) A narrow stacked session under a TaskList, as in a run sidebar. ```tsx import { Check, GitPullRequest } from "lucide-react"; import { TaskList } from "@kura-ui/react/task-list"; import { BrowserSession } from "@kura-ui/react/browser-session"; const W = 800; const H = 500; const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 }); const box = (x: number, y: number, w: number, h: number, label?: string) => ({ x: (x / W) * 100, y: (y / H) * 100, width: (w / W) * 100, height: (h / H) * 100, label, }); function PullRequestPage() { return (

      {PR_TITLE} #482

      Open kura wants to merge 4 commits into{" "} main from{" "} kura/auth-client
      Conversation Commits 4 Checks 3 Files changed 6
      {PR_BODY}
      All checks have passed
      {[ ["test", "142 passed · 41s"], ["typecheck", "0 errors · 18s"], ["lint", "clean · 6s"], ].map(([name, meta]) => (
      {name} {meta}
      ))}
      ); } const PR_URL = "https://github.com/acme/web/pull/482"; const PR_TITLE = "Migrate session API to @acme/auth client"; const PR_BODY = "Replaces fetchUser() and the legacy /api/session REST calls with createAuthClient(). Refreshes expired sessions with the rotated token."; function SiteBar() { return (
      acme / web Code Pull requests Actions
      ); } export function BrowserSessionComposition() { return (
      ); } ``` ## Dependencies - npm: `lucide-react` - Kura registry items: `kura-theme`, `button`, `kura-format`, `shimmer-text`, `status-glyph`, `use-elapsed`, `utils` - Related: `terminal`, `task-list`, `run-header`, `approval-prompt`, `tool-call`