Crate plumb_cdp 

plumb-cdp

Chromium DevTools Protocol driver for Plumb.

This crate owns every interaction with the browser. It is the only Plumb crate where unsafe is permitted — and only for FFI-adjacent hot spots, each with an explicit // SAFETY: comment. The walking skeleton doesn’t yet use unsafe; the override exists to preempt future friction when snapshot conversion lands.

Supported Chromium versions

Plumb accepts Chromium major versions in the inclusive range MIN_SUPPORTED_CHROMIUM_MAJOR..=MAX_SUPPORTED_CHROMIUM_MAJOR. The lower bound is the oldest major Plumb has validated against; the upper bound is the newest major tested up to. Both are public so callers can introspect the accepted range. Constraining the browser to a known range is part of Plumb’s determinism guarantee (docs/local/prd.md §9, §16) — DOMSnapshot output stability is re-verified whenever the upper bound moves.

Behavior

ChromiumDriver::snapshot_all launches Chromium exactly once, validates Browser::version, and then loops over the requested targets — for each it opens a fresh page, applies the per-target viewport via CDP Emulation.setDeviceMetricsOverride, navigates to the URL, and calls DOMSnapshot.captureSnapshot with the COMPUTED_STYLE_WHITELIST from PRD §10.3. Each CDP response is flattened into a PlumbSnapshot with deterministic ordering (nodes sorted by dom_order, computed styles inserted in whitelist order). ChromiumDriver::snapshot is a thin wrapper over snapshot_all for callers that only want a single target. The plumb-fake:// URL scheme in plumb-cli is handled by FakeDriver from this crate’s test-fake wiring.

PersistentBrowser is the long-lived counterpart for callers that lint many URLs in one process (the MCP server). It launches Chromium once, validates the version, and gives each PersistentBrowser::snapshot call a fresh incognito BrowserContext so cookies and localStorage from call N do not leak into call N+1.

Modules

chrome_path

Plumb-side Chromium path discovery.

fetcher

Opt-in Chromium auto-fetch.

Structs

ChromiumDriver

Real Chromium-backed driver.

ChromiumOptions

Configuration for ChromiumDriver.

Cookie

A cookie to install before navigation.

FakeDriver

Deterministic fake driver. Recognizes plumb-fake://hello and returns PlumbSnapshot::canned. Used by the walking-skeleton CLI and by downstream tests.

PersistentBrowser

A persistent Chromium browser kept warm across multiple snapshots.

StorageState

Playwright storage-state.json representation.

StorageStateCookie

One cookie entry in a Playwright storage-state.json.

StorageStateLocalStorageEntry

One localStorage[] entry in a Playwright storage-state.json.

StorageStateOrigin

One origins[] entry in a Playwright storage-state.json.

Target

A snapshot target: URL + viewport + per-target capture knobs.

Enums

CdpError

Errors returned by drivers.

Constants

COMPUTED_STYLE_WHITELIST

CSS property whitelist passed to DOMSnapshot.captureSnapshot as the computedStyles argument.

MAX_SUPPORTED_CHROMIUM_MAJOR

Highest Chromium major version Plumb has tested up to. Booting a Chromium binary with a larger major refuses to run; bump this constant after running the e2e suite against the new major.

MIN_SUPPORTED_CHROMIUM_MAJOR

Lowest Chromium major version Plumb has validated against. Booting a Chromium binary with a smaller major refuses to run.

Traits

BrowserDriver

Async trait for browser drivers. Implementations are expected to be cheap to construct and expensive per-call.

Functions

is_fake_url

Whether a URL belongs to the fake-driver scheme.

parse_header_kv

Parse and validate an HTTP header name: value token.

validate_safe_path

Public CLI-facing wrapper around canonicalize_safe_path.