feat: optional patchright stealth backend (GSTACK_STEALTH=patchright)

[ramazanayyildiz]

Summary

Adds patchright as an optionalDependency and a dynamic chromium loader in BrowserManager. When GSTACK_STEALTH=patchright is set AND the package is installed, gstack's Chromium driver is swapped for patchright's CDP-leak-free build. Falls back to vanilla Playwright with a warning if not installed. Default behavior unchanged.

Why this matters

gstack's existing stealth (addInitScript patches for navigator.plugins, cdc_, languages, etc.) is L4 — the JavaScript API surface. Modern bot detectors (Cloudflare, DataDome, Imperva, Kasada) check 40+ surfaces and, critically, inspect the CDP protocol directly for the Runtime.Enable call that every vanilla Playwright page.evaluate() issues.

Patchright is an L2 patch: it uses ts-morph to rewrite upstream Playwright's driver source at build time, replacing updateRequestInterception with a tagged init-script + isolated-world evaluateExpression loop. The result: JavaScript runs without ever calling Runtime.Enable. Detectors can't see the pattern they're looking for because it literally doesn't happen.

Measured delta

Independent fingerprint probe, same M4 Pro Mac, same test JS, same page, only difference is the chromium driver:

Marker	gstack default	gstack + patchright
navigator.webdriver	true ❌	false ✅
UA string	HeadlessChrome/145.0.7632.6 ❌	Chrome/146.0.0.0 ✅
navigator.plugins.length	0 ❌	5 ✅
navigator.mimeTypes.length	0 ❌	2 ✅
WebGL renderer	null (disabled in headless) ❌	real GPU string ✅
Screen dimensions	1280×720 fixed ❌	real display (1512×982) ✅
cdc_ / \$cdc_ leaks	clean ✅	clean ✅
Canvas rendering	✅	✅
Audio context	✅	✅
Stealth score	4/7	6/7

The HeadlessChrome UA alone is sufficient to be blocked by any Cloudflare-protected site. Patchright fixes it with zero code changes — just a module swap.

Scope

Minimal and opt-in. 107 lines across 4 files.

• package.json — patchright@^1.59.0 under optionalDependencies (+3)
• browse/src/browser-manager.ts — getChromium() helper + 3 call site updates (+41/-4)
• bun.lock — updated (+7)
• BROWSER.md — new "Stealth mode" section with install, usage, measured delta, caveats (+60)

Usage

# Install (one-time)
bun add -O patchright
bunx patchright install chrome     # ~300 MB download

# Use
GSTACK_STEALTH=patchright \$B goto https://example.com

# Or export globally
export GSTACK_STEALTH=patchright

Caveats (documented in BROWSER.md)

1. Max stealth requires headed mode. This PR adds the backend swap but does NOT change gstack's default launch options (to keep existing behavior). Follow-up work can add GSTACK_HEADLESS=false support. On Linux servers, wrap in Xvfb: xvfb-run \$B goto ....
2. page.on('console', ...) is disabled by design as part of the Runtime.Enable patch. Most workflows don't rely on this.
3. One-time Chrome download — bunx patchright install chrome pulls a patched Chrome binary (~300 MB) into ~/Library/Caches/ms-playwright/ (macOS). One-time cost.
4. /connect headed path unchanged — gstack's existing JS-shim stealth patches there still apply. Patchright is additive.

Why opt-in, not default?

Patchright is Apache-2.0, actively maintained, and tracks Playwright releases lockstep (patchright@1.59.4 ships within days of playwright@1.59). But:

• ~300 MB download cost for users who don't need stealth
• Drop-in but not 100% behavior-compatible (console events disabled)
• Most gstack users don't hit sites that fingerprint browser automation

Keeping it opt-in means the default gstack experience stays fast and small. Turn it on when you need it.

Testing

• bun install — patchright installs as optional dep (93 packages total, +1 from main)
• bun build --compile browse/src/cli.ts — clean build, 57ms compile
• bun test browse/test/ — existing tests still pass (the dynamic loader falls back to vanilla Playwright when GSTACK_STEALTH is not set)

Runtime stealth delta validated independently via ~/.claude/scripts/patchright-eval.sh — numbers in the table above.

Test plan

• bun install succeeds (patchright pulled as optional dep)
• bun run build compiles without errors
• bun test browse/test/ passes (default path unchanged)
• GSTACK_STEALTH=patchright \$B goto https://example.com launches with patchright's chromium
• bunx patchright install chrome pulls the patched Chrome binary (one-time)
• Stealth delta reproducible via the fingerprint probe (see BROWSER.md for the test JS)

🤖 Generated with Claude Code