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.
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.
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.
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.
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.
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.
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.
{
"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.
#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();
}