Adr 0005 Cloudflare Browser Run Cdp And Demo Capture

Remote CDP Browser Testing & On-Demand Screencast Capture

Distillation Note: Retained as an uningested point-in-time write-up per founder guidance; deferred from immediate distillation into canonical living specifications.

1. Problem Context

Running headless browser verification across multiple edge applications in GitHub Actions originally required downloading Chromium (playwright install --with-deps chromium) and booting local astro preview servers on every CI shard, adding 45–70 seconds of setup overhead per runner and testing against local emulation rather than the deployed Cloudflare Workers edge isolate. Additionally, capturing full-fidelity dual-viewport walkthrough videos on every PR push consumed excessive GitHub Actions runner minutes.

2. Core Architecture

2.1 Remote CDP Execution with Automatic Local Fallback

What is CDP?: The Chrome DevTools Protocol (CDP) is the low-level WebSocket debugging protocol used by Playwright and Puppeteer to drive a headless Chromium instance, navigate pages, simulate inputs, and inspect the DOM.
Remote Edge Browser Run: When targeting deployed edge URLs with Cloudflare Browser Run credentials configured, Playwright connects over remote CDP WebSockets (chromium.connectOverCDP) to a headless browser running inside Cloudflare’s edge network, eliminating Chromium binary downloads and local preview server boot overhead in cloud pipelines.
Hermetic Local Fallback: When Cloudflare credentials are absent or PLAYWRIGHT_FORCE_LOCAL=true is set, browser tests automatically fall back to local Chromium and local astro preview so offline local development remains 100% self-contained.

2.2 Streaming CDP Screencast Pipeline (`Page.startScreencast` $\to$ `ffmpeg`)

Why Custom Frame Streaming is Required: Playwright’s built-in recordVideo option only writes video files when Playwright spawns a local browser process on the runner’s filesystem—it does not stream pixel video back over remote CDP WebSocket connections. Furthermore, Cloudflare Browser Run’s built-in ?recording=true flag records rrweb DOM mutation events (serialized JSON snapshots of HTML/CSS changes for DOM replay players) rather than actual rendered pixel video files (.mp4 / .webp).
CDP Frame Stream to ffmpeg: To capture real rendered video from a remote edge browser, our walkthrough capture pipeline subscribes to CDP Page.startScreencast (which streams compressed JPEG frames over the WebSocket as the browser renders each frame) and pipes those frames into ffmpeg to produce progressive H.264 .mp4 and animated .webp artifacts across canonical desktop (1920x1080) and mobile (390x844) viewports.

2.3 On-Demand Demo Capture Triggering

Full dual-viewport video walkthrough capture runs on-demand via the demo-capture label or manual workflow dispatch (demo-capture.yml), operating alongside our opt-in PR preview lifecycle (CI_EPHEMERAL_PREVIEWS.md) and monorepo canary scoping (CI_CHANGE_DETECTION.md).

Decisions Intentionally Deferred

Prospect outreach link sharing topology, R2 artifact retention lifecycles, and interactive rrweb playback in the Command Center are deferred.