Browser control

@suitecut/browser-control is the standalone Node.js SDK for browsers. It doesn't depend on suitecut's narration, rendering or test runner, and its protocol adapters have no external automation dependencies. It needs Node.js 22 or newer.

Backends

  • cef, the default: suitecut's embedded engine, with native capture and the live viewer.
  • cdp: an installed Chrome, Chromium, Edge or Brave over CDP.
  • bidi: an installed Firefox over WebDriver BiDi.

The package doesn't bundle or download browsers. Safari and WebKit aren't supported.

Installed browsers

Set backend and point executablePath at the browser. Owned launches use a temporary profile and a loopback debugging endpoint; both are cleaned up on close. Sandboxing stays on unless you pass an argument that turns it off.

TypeScript
import { launchBrowser } from '@suitecut/browser-control'

const browser = await launchBrowser({
  backend: 'cdp',
  executablePath: '/path/to/google-chrome',
  headless: true,
  viewport: { width: 1440, height: 900 },
})

try {
  const context = await browser.newContext()
  const page = await context.newPage()
  await page.goto('https://example.com')
  console.log(await page.getByRole('heading').innerText())
  await page.setViewportSize({ width: 1280, height: 720 })
  await page.screenshot({ path: 'page.png' })
} finally {
  await browser.close()
}

For protocol-only apps, @suitecut/browser-control/remote exports launchProtocolBrowser and connectBrowser without loading the CEF module graph.

TypeScript
import { launchProtocolBrowser } from '@suitecut/browser-control/remote'

const firefox = await launchProtocolBrowser({
  backend: 'bidi',
  executablePath: '/path/to/firefox',
  headless: true,
  viewport: { width: 1280, height: 720 },
})
try {
  const page = await firefox.newPage()
  await page.goto('https://example.com')
  console.log(await page.title())
} finally {
  await firefox.close()
}

Attach to a running browser

connectBrowser attaches to a browser whose debugging endpoint is already enabled. CDP accepts an HTTP origin or a browser WebSocket URL; Firefox needs its WebSocket session endpoint. close() disconnects without shutting the browser down unless you set closeBrowserOnClose: true.

TypeScript
import { connectBrowser } from '@suitecut/browser-control/remote'

const chrome = await connectBrowser({
  backend: 'cdp',
  endpointURL: 'http://127.0.0.1:9222',
  timeoutMs: 15_000,
})
console.log((await chrome.pages()).length)
await chrome.close()

const firefox = await connectBrowser({
  backend: 'bidi',
  endpointURL: 'ws://127.0.0.1:9223/session',
})
await firefox.close()

Protocol features

Both protocol backends support tabs, isolated contexts where available, cookies, navigation, evaluation, screenshots, viewport changes, CSS, role, text, label and test-id locators, form controls, and browser-dispatched keyboard and pointer input. Check browser.capabilities() for what a backend supports, and use browser.sendCommand() for raw protocol commands.

CDP also supports iframes, file uploads, downloads, JavaScript dialogs, popups, hover, dragging and scrolling. Subscribe to downloads before triggering them; dialogs without a listener are dismissed.

TypeScript
await page.frameLocator('iframe[title="Billing"]').getByLabel('Account number').fill('12345')
await page.getByLabel('Supporting document').setInputFiles('/absolute/path/document.pdf')

const pending = page.waitForEvent('download')
await page.getByRole('button', { name: 'Export' }).click()
const download = await pending
await download.saveAs('/absolute/path/export.csv')

page.once('dialog', async (dialog) => {
  await dialog.accept()
})

Live viewer

With the CEF backend, the viewer streams the same browser session to a local web page. It binds to 127.0.0.1 behind a private link; treat that link as a credential and forward the port over SSH for remote machines.

Terminal
npx browser-control view https://example.com \
  --executable /absolute/path/to/suitecut-browser \
  --resolution auto

--resolution auto fits the page to the viewer while a person has control. Fixed sizes such as 1920x1080 are also available, up to 3840 × 2160 physical pixels. Resizing changes the page's real CSS viewport, not just the displayed image.

Human handover

Take control waits for admitted agent work to finish, then hands input to a person. Resume AI releases held keys and buttons and returns control. Both use the same page, cookies and storage.

TypeScript
import { launchBrowser, createBrowserViewer } from '@suitecut/browser-control'

const browser = await launchBrowser({
  executablePath: '/absolute/path/to/suitecut-browser',
  headless: true,
  pixelFormat: 'bgra',
})
const page = await browser.newPage()
await page.goto('https://example.com')
const viewer = await createBrowserViewer({ browser, page, resolutionMode: 'auto' })
console.log(viewer.url)

try {
  // One fully awaited agent step at a time. Each step waits during human control.
  await viewer.runAgent(() => page.getByRole('link', { name: 'More information' }).click())
} finally {
  await viewer.close()
  await browser.close()
}

During human control, direct SDK calls fail explicitly. viewer.runAgent() waits for control instead, so submit bounded steps through it. Up to eight clients can watch, with one owning input.

Build and install

The package is built and packed from the repository; it hasn't been published to npm. Install the tarball in your app and distribute the CEF runtime separately.

Terminal
pnpm --filter @suitecut/browser-control build
pnpm --filter @suitecut/browser-control pack --pack-destination /absolute/output/directory
npm install /absolute/path/to/suitecut-browser-control-2.0.0.tgz