brawsr examples

Executable examples for the public brawsr API and released TypeScript and Python SDKs. The examples focus on application safe points, stale browser handles, branch ownership, and explicit cleanup rather than hiding those decisions in a framework wrapper.

Setup

npm ci
UV_CACHE_DIR=/tmp/brawsr-examples-uv uv sync --locked --python 3.11
export BRAWSR_API_KEY=brawsr_...

Both SDKs connect to https://api.brawsr.io by default. BRAWSR_EXAMPLE_URL optionally replaces the page used by browser examples. For another brawsr deployment, set the example-only BRAWSR_EXAMPLE_BASE_URL; normal users do not need it.

Start here

The rewind examples are deliberately self-contained and are the best place to start. They prepare browser state, checkpoint it, make a later change, rewind, reconnect, and verify the restored value:

npm exec -- tsx typescript/playwright-rewind.ts
UV_CACHE_DIR=/tmp/brawsr-examples-uv uv run python python/playwright_rewind.py

Successful output contains "rewound":true and "value":"checkpointed". The checkpoint and session identifiers are safe to use for debugging, but the examples never print API keys, authorization headers, or CDP URLs.

More examples

Example	What it demonstrates
typescript/playwright-fork.ts	One or ten ordered Playwright branches inheriting checkpointed state
python/playwright_fork.py	The equivalent two-branch flow with the Python SDK
typescript/puppeteer-fork.ts	Authenticated Puppeteer CDP handoff and fork
typescript/speculative-branching.ts	Compare primary/fallback routes from one prepared browser state
typescript/concurrent-jobs.ts	Two parallel jobs inheriting state, with every result retained
typescript/recursive-fork.ts	Prepared state inherited and verified across two generations
stagehand/stagehand-smoke.ts	Optional Stagehand discovery of a brawsr-backed page
typescript/raw-cdp-smoke.ts	Authenticated raw WebSocket CDP with response correlation

Run them from the repository root:

# Playwright fork-1 or fork-10
BRAWSR_FORK_N=1 npm exec -- tsx typescript/playwright-fork.ts
BRAWSR_FORK_N=10 npm exec -- tsx typescript/playwright-fork.ts

npm exec -- tsx typescript/puppeteer-fork.ts
npm exec -- tsx typescript/raw-cdp-smoke.ts
npm exec -- tsx typescript/speculative-branching.ts
npm exec -- tsx typescript/concurrent-jobs.ts
npm exec -- tsx typescript/recursive-fork.ts
UV_CACHE_DIR=/tmp/brawsr-examples-uv uv run python python/playwright_fork.py

Stagehand is an optional, separately installed integration so its larger dependency tree does not affect the default examples setup:

cd stagehand
npm ci
npm run start

See stagehand/README.md for the authenticated CDP compatibility note and verification details.

The default organization limit supports three concurrent sessions. Use BRAWSR_FORK_N=1 or BRAWSR_FORK_N=2 with that limit; fork-10 requires an organization concurrency limit of at least 11 for the source and ten children. The speculative, concurrent-job, and recursive examples stay within the default limit.

The canonical rewind and framework-fork examples follow a real application sequence: create a labeled session, attach a browser client, prepare browser state, create a checkpoint, continue browser work, then rewind or fork from the earlier checkpoint. createCheckpoint/create_checkpoint already waits until its returned checkpoint can be used, so examples do not add a redundant waiter. Checkpoint, rewind, and fork remain one mutation call each; explicit typed waiters are for sequencing a later lifecycle mutation or resuming a caller-side timeout, never for decoding raw operation JSON.

A rewind result is CDP-usable immediately. Reconnect and continue browser work from that result; wait for waitRewind/wait_rewind only before issuing another lifecycle mutation on the same session, including close. A timeout does not cancel server work; resume with waitRewind, waitCheckpoint, or waitFork and the operation ID carried by the typed timeout error.

playwright-fork.ts also verifies the source's one-hop lineage after its children become ready.

Fork children are independent peer sessions in stable branch-index order. speculative-branching.ts verifies that primary and fallback routes inherited the prepared source state, checks each route for an expected heading, then applies application-owned result selection. Set BRAWSR_FALLBACK_URL to compare a real alternate route. concurrent-jobs.ts verifies the same inheritance while retaining every result with no winner/loser concept. recursive-fork.ts prepares root state, verifies it in a child, changes and checkpoints the child, then verifies that state and both parent links in a grandchild. Every created session is closed explicitly in a finally block.

Important limits

• Rewind restores browser/VM state; it cannot undo effects already accepted by a website or external service.
• Existing CDP, Playwright, and Puppeteer handles are stale after rewind. Attach again using the returned connection details.
• There is no browser-state merge, automatic branch selection, or automatic sibling cleanup.
• Long-lived WebSocket, SSE, WebRTC, or TLS streams may not survive a restore.
• Selenium/WebDriver reconnect is not supported.

Verification

npm run verify
UV_CACHE_DIR=/tmp/brawsr-examples-uv uv run ruff format --check python test_python
UV_CACHE_DIR=/tmp/brawsr-examples-uv uv run ruff check python test_python
UV_CACHE_DIR=/tmp/brawsr-examples-uv uv run mypy python
UV_CACHE_DIR=/tmp/brawsr-examples-uv uv run pytest -q
npm audit --audit-level=high

# Optional Stagehand integration
npm --prefix stagehand ci
npm --prefix stagehand run verify
npm --prefix stagehand audit --audit-level=high