universal_browser_cdp library
Pure-Dart Chrome DevTools Protocol (CDP) client.
Attach to a Chromium-based browser's debug endpoint and drive it: probe
readiness (/json/version, the oka borrowed-lease identity check),
enumerate targets (/json/list), then observe and act — accessibility
snapshots, intent-level actions, screenshots, screencast-ready frame
events.
The client takes an endpoint; it never launches a browser. Production
lifecycle (spawning, leases, profiles) belongs to oka's session targets;
this package consumes the session-<name>-handle they publish.
Classes
- BehavioralCdpDriver
- The CDP lowering of the behavior contract (ADR 0044).
- CdpBehaviorReceiptWriter
-
Writes the behavior receipt pair for a dispatch, mirroring the
screencast recording contract:
<base>.behavior.stream.jsonl— a meta line plus one canonical step document per line — and<base>.behavior.receipts.jsonl— an envelope, one line per dispatched event, and a terminal line. A receipt records what was planned and dispatched; it never claims what the page did. - CdpBehaviorScheduler
- Client-side scheduler materializing a plan onto one CDP page.
- CdpBrowser
- A browser-level session over one WebSocket: target enumeration, page creation, and flat-session multiplexing — the multi-tab verbs.
- CdpBrowserSession
- A browser-level session: discovery, one page attachment, and its driver. Production lifecycle (spawning, leases) belongs to oka; this class only consumes an already-published debug endpoint.
- CdpConnection
- A WebSocket JSON-RPC connection to a CDP endpoint (browser or page).
- CdpDiscovery
- HTTP-side discovery against a CDP endpoint's debug server.
- CdpDriver
-
AutomationDriverover a CDP page: the observe/act/verify loop for Chromium-based browsers and webviews. - CdpEvent
- One protocol event pushed by the endpoint (no request id).
- CdpFlatSession
-
One flat session over a browser-level CdpConnection
(
Target.attachToTargetwithflatten: true). - CdpNetworkLog
- Observation-side network log for one page: request lifecycle entries, in-flight counting, and response-body retrieval.
- CdpPage
- A page-level CDP facade: navigation, evaluation, accessibility snapshots, screenshots, and trusted-input synthesis.
- CdpSemanticTargeting
- Fresh, exact semantic targeting. Flutter proxy nodes are accepted only when the center hits the rendering surface in the same Flutter glass pane. The generic DOM actionability path continues to reject unrelated occluders.
- CdpTargetInfo
-
One entry of
GET /json/list. - CdpTransport
- The request/event surface shared by a raw page socket (CdpConnection) and a browser-level flat session (CdpFlatSession).
- CdpVersionInfo
-
GET /json/versionresponse. - NetworkEntry
- One observed network request and its lifecycle.
Enums
- NameMatch
- How CdpPage.resolveNamedRect matches the accessible name.
- What a navigation waits for before CdpPage.navigate returns.
Functions
-
cdpModifierMask(
Iterable< String> modifiers) → int -
CDP
Inputmodifier bitmask for the family's modifier names (Alt 1, Control 2, Meta 4, Shift 8); unknown names contribute 0.
Exceptions / Errors
- AutomationException
- Base class of all family exceptions: a stable message, a machine-readable kind, and structured details agents can classify without parsing prose.
- CdpProtocolException
- A CDP error response.
- DriverUnsupportedException
- A driver was asked to perform something its capability set excludes.
- EndpointUnreachableException
- The endpoint did not answer or answered with an unexpected identity.
- ProtocolException
- A protocol-level error response came back from the endpoint.