Examples

Each example uses the current packages. The recording examples need the built CEF executable in SUITECUT_NATIVE_EXECUTABLE; the browser agent examples also work with an installed Chrome or Firefox.

Record and render

A narrated tour in the embedded browser with page audio, rendered to a video. This is examples/native.ts; run it with pnpm example:native.

TypeScript
import { record, renderSuiteCut, type SuiteCutRecordOptions } from 'suitecut'

// Build the pinned CEF browser and set SUITECUT_NATIVE_EXECUTABLE first.
const options = {
  native: { width: 1920, height: 1080, framesPerSecond: 60 },
  capture: { audio: true },
  output: { manifestPath: '.suitecut/native-tour.json' },
} satisfies SuiteCutRecordOptions

const result = await record(
  'Embedded browser tour',
  async ({ page, suitecut }) => {
    await page.goto('https://example.com')
    await suitecut.highlight(page.locator('h1'))
    await suitecut.narrate('Welcome to SuiteCut 2.0 and the embedded browser.')
    await suitecut.checkpoint('Opening screen')
  },
  options,
)

await renderSuiteCut({
  manifestPath: result.manifestPath,
  outputPath: '.suitecut/native-tour.mp4',
})

A real app at 1080p60

The Song Maker example drives Chrome Music Lab's Song Maker with real pointer input: it composes a melody, changes the tempo, switches instruments and plays it back. It records the app and its Web Audio, then renders and verifies a 1920 × 1080, 60 fps MP4.

It installs @suitecut/browser-control and suitecut from freshly packed tarballs into a separate project, the way a real consumer would.

Terminal
export SUITECUT_NATIVE_EXECUTABLE="/absolute/path/to/suitecut-browser"
pnpm example:song-maker

Publish a source

Stream a page to RTMP or RTMPS. Your app owns the browser and the stop signal; keep stream keys in environment variables.

TypeScript
import { launchBrowser, createBroadcast } from 'suitecut'

// Your app decides when to stop, here on Ctrl+C.
const applicationStopSignal = new Promise<void>((resolve) => process.once('SIGINT', () => resolve()))

const source = await launchBrowser({ framesPerSecond: 120 })
let broadcast
try {
  await source.navigate('https://example.com')
  broadcast = await createBroadcast({
    source,
    stream: { url: process.env.RTMP_URL!, framesPerSecond: 60, audio: true },
  })
  await broadcast.ready()
  await Promise.race([source.failure, broadcast.failure, applicationStopSignal])
} finally {
  await broadcast?.stop()
  await source.close()
}

Drive an installed browser

@suitecut/browser-control without the embedded engine, against the Chrome you already have.

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

const browser = await launchBrowser({
  backend: 'cdp',
  executablePath: '/path/to/google-chrome',
  headless: true,
})
try {
  const page = await browser.newPage()
  await page.goto('https://example.com')
  await page.getByRole('link', { name: 'More information' }).click()
  console.log(await page.title())
} finally {
  await browser.close()
}

Agent with human handover

An agent works in the CEF engine while a person watches through the live viewer and can take over at any point.

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('Watch or take over at', viewer.url)

try {
  await viewer.runAgent(() => page.getByRole('link', { name: 'More information' }).click())
} finally {
  await viewer.close()
  await browser.close()
}

Command-line agent session

A persistent session that any script or agent can drive one command at a time.

Terminal
suitecut-native-control --session shop --browser /usr/bin/chromium open https://example.com
suitecut-native-control --session shop snapshot
suitecut-native-control --session shop --response none fill e12 'Ada'
suitecut-native-control --session shop click e15
suitecut-native-control --session shop close

MCP client

Add suitecut to any MCP client as a stdio server. See Agents and MCP for tool groups and backends.

MCP config
{
  "mcpServers": {
    "suitecut": {
      "command": "/absolute/install/prefix/bin/suitecut-native-control",
      "args": ["--browser", "/usr/bin/chromium", "--mcp", "--tools", "core,network"]
    }
  }
}

C++ agent with Firefox

The native SDK's simple agent, driving an installed Firefox over WebDriver BiDi.

C++
#include <suitecut/browser.hpp>
#include <suitecut/simple_agent.hpp>

int main() {
  suitecut::LaunchOptions options;
  options.executable = "/usr/bin/firefox";
  auto browser = suitecut::Browser::launch_firefox(options);
  browser.main_page().navigate("https://example.com");

  suitecut::AgentDriver driver(browser);
  suitecut::SimpleAgent agent(driver);
  auto seen = agent.call("observe", {});
  auto ready = agent.call("wait", {{"text", "Example Domain"}, {"timeoutMs", 2000}});
  browser.close();
}