obscura/docs/Connect-Puppeteer-or-Playwright.md

Obscura speaks the Chrome DevTools Protocol over WebSocket. Puppeteer and Playwright can connect to its CDP endpoint for the supported workflows below.

Start the server

obscura serve --port 9222

obscura listening on ws://127.0.0.1:9222

Puppeteer

npm install puppeteer-core

const puppeteer = require('puppeteer-core');

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9222',
});

const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title()); // "Example Domain"

await browser.disconnect();

Use puppeteer-core, not puppeteer. The puppeteer package bundles a Chrome download.

Playwright

npm install playwright

const { chromium } = require('playwright');

const browser = await chromium.connectOverCDP('ws://127.0.0.1:9222');
const context = browser.contexts()[0] || await browser.newContext();
const page = await context.newPage();

await page.goto('https://example.com');
console.log(await page.title());

await browser.close();

Use connectOverCDP, not connect. Playwright's connect speaks Playwright's own protocol, which obscura does not implement.

waitUntil

Default is domcontentloaded. For full subresource load:

await page.goto('https://example.com', { waitUntil: 'load' });

Value	Returns when
domcontentloaded	HTML parsed, scripts ran (default)
load	All subresources finished
networkidle2	≤2 network connections active for 500ms
networkidle0	0 network connections active for 500ms

Supported

• page.goto, page.reload, page.goBack, page.goForward
• page.evaluate, page.evaluateHandle
• page.click, page.type, page.fill, page.focus
• page.waitForSelector, page.waitForFunction, page.waitForNavigation
• page.cookies, page.setCookie, context.cookies
• page.setRequestInterception, block / modify
• page.exposeFunction
• page.content, page.title, page.url
• page.screenshot for viewport, clipped, and full-page capture
• page.pdf for raster-backed print output
• raw CDP Page.startScreencast with frame acknowledgements (page.createCDPSession() in Puppeteer; context.newCDPSession(page) in Playwright)

DOM-agent frameworks such as browser-use also connect: obscura implements DOMSnapshot.captureSnapshot and Target.targetInfoChanged for perception, and DOM.focus so a focused field receives Input.dispatchKeyEvent keystrokes.

Capture example

await page.setViewport({ width: 1440, height: 1000 });
await page.screenshot({ path: 'viewport.png' });
await page.screenshot({ path: 'full-page.png', fullPage: true });
await page.pdf({ path: 'page.pdf', format: 'A4', printBackground: true });

Rendering is included in official binaries and requires --features render for source builds. The client-specific guides cover scrolling, raw CDP screencasting, and current output limits.

Current limits

• Pages share one V8 isolate. CPU-bound JavaScript on one page can delay others.
• PDF output is raster-backed; text is not selectable and tagged PDF, headers/footers, outlines, and full CSS paged media are not implemented.
• Service workers, native media playback, some Web APIs, and long-tail CSS or compositor effects are still incomplete relative to Chromium.