docs: document browser cdp runtime

steipete · steipete · commit c32748bc28d6 · 2026-06-04T07:34:30.000-04:00
diff --git a/extensions/browser/src/browser/bridge-server.ts b/extensions/browser/src/browser/bridge-server.ts
@@ -1,3 +1,9 @@
+/**
+ * Loopback browser bridge server.
+ *
+ * Hosts the browser control routes on an authenticated local port for sandbox,
+ * host, and node browser integrations that need HTTP access to browser control.
+ */
 import type { Server } from "node:http";
 import type { AddressInfo } from "node:net";
 import express from "express";
@@ -13,6 +19,7 @@ import {
   installBrowserCommonMiddleware,
 } from "./server-middleware.js";
 
+/** Running bridge server details returned to callers that manage its lifecycle. */
 export type BrowserBridge = {
   server: Server;
   port: number;
@@ -54,6 +61,7 @@ function buildNoVncBootstrapHtml(params: ResolvedNoVncObserver): string {
 </html>`;
 }
 
+/** Start an authenticated loopback browser bridge and register browser routes. */
 export async function startBrowserBridgeServer(params: {
   resolved: ResolvedBrowserConfig;
   host?: string;
@@ -144,6 +152,7 @@ export async function startBrowserBridgeServer(params: {
   return { server, port: resolvedPort, baseUrl, state };
 }
 
+/** Stop a browser bridge server and clear its ephemeral port auth. */
 export async function stopBrowserBridgeServer(server: Server): Promise<void> {
   try {
     const address = server.address() as AddressInfo | null;
diff --git a/extensions/browser/src/browser/cdp.ts b/extensions/browser/src/browser/cdp.ts
@@ -1,3 +1,9 @@
+/**
+ * Chrome DevTools Protocol browser operations.
+ *
+ * Provides screenshots, target creation, JavaScript evaluation, ARIA/role
+ * snapshots, DOM text, and selector lookup on top of the CDP socket helpers.
+ */
 import { resolveIntegerOption } from "openclaw/plugin-sdk/number-runtime";
 import type { SsrFPolicy } from "../infra/net/ssrf.js";
 import {
@@ -22,6 +28,7 @@ export {
   isWebSocketUrl,
 } from "./cdp.helpers.js";
 
+/** Normalize a reported CDP WebSocket URL against the configured CDP base URL. */
 export function normalizeCdpWsUrl(wsUrl: string, cdpUrl: string): string {
   const ws = new URL(wsUrl);
   const cdp = new URL(cdpUrl);
@@ -58,6 +65,7 @@ export function normalizeCdpWsUrl(wsUrl: string, cdpUrl: string): string {
   return ws.toString();
 }
 
+/** Capture a PNG screenshot through CDP. */
 export async function captureScreenshotPng(opts: {
   wsUrl: string;
   fullPage?: boolean;
@@ -71,6 +79,7 @@ export async function captureScreenshotPng(opts: {
   });
 }
 
+/** Capture a PNG or JPEG screenshot through CDP, optionally full-page. */
 export async function captureScreenshot(opts: {
   wsUrl: string;
   fullPage?: boolean;
@@ -183,11 +192,13 @@ export async function captureScreenshot(opts: {
   );
 }
 
+/** HTTP and WebSocket timeout options for CDP actions that need discovery. */
 export type CdpActionTimeouts = {
   httpTimeoutMs?: number;
   handshakeTimeoutMs?: number;
 };
 
+/** Create a new browser target after applying navigation and CDP SSRF policy. */
 export async function createTargetViaCdp(opts: {
   cdpUrl: string;
   url: string;
@@ -302,6 +313,7 @@ async function prepareCdpPageSession(send: CdpSendFn, sessionId?: string): Promi
   await send("Runtime.runIfWaitingForDebugger", undefined, sessionId).catch(() => {});
 }
 
+/** Runtime.evaluate remote-object subset used by CDP helpers. */
 export type CdpRemoteObject = {
   type: string;
   subtype?: string;
@@ -311,6 +323,7 @@ export type CdpRemoteObject = {
   preview?: unknown;
 };
 
+/** Exception details surfaced from CDP Runtime.evaluate. */
 export type CdpExceptionDetails = {
   text?: string;
   lineNumber?: number;
@@ -319,6 +332,7 @@ export type CdpExceptionDetails = {
   stackTrace?: unknown;
 };
 
+/** Evaluate JavaScript in a CDP target and return by value when possible. */
 export async function evaluateJavaScript(opts: {
   wsUrl: string;
   expression: string;
@@ -349,6 +363,7 @@ export async function evaluateJavaScript(opts: {
   });
 }
 
+/** Normalized accessibility tree node returned by ARIA snapshots. */
 export type AriaSnapshotNode = {
   ref: string;
   role: string;
@@ -359,9 +374,11 @@ export type AriaSnapshotNode = {
   depth: number;
 };
 
+/** Prefix assigned to generated accessibility-node refs. */
 export const AX_REF_PREFIX = "ax";
 export const AX_REF_PATTERN = new RegExp(`^${AX_REF_PREFIX}\\d+$`);
 
+/** Raw accessibility node subset read from CDP Accessibility.getFullAXTree. */
 export type RawAXNode = {
   nodeId?: string;
   role?: { value?: string };
@@ -386,6 +403,7 @@ function axValue(v: unknown): string {
   return "";
 }
 
+/** Format raw AX nodes into bounded ARIA snapshot nodes. */
 export function formatAriaSnapshot(nodes: RawAXNode[], limit: number): AriaSnapshotNode[] {
   const byId = new Map<string, RawAXNode>();
   for (const n of nodes) {
@@ -454,6 +472,7 @@ export function formatAriaSnapshot(nodes: RawAXNode[], limit: number): AriaSnaps
   return out;
 }
 
+/** Capture an accessibility-tree snapshot through CDP. */
 export async function snapshotAria(opts: {
   wsUrl: string;
   limit?: number;
@@ -474,6 +493,7 @@ export async function snapshotAria(opts: {
   );
 }
 
+/** Role snapshot ref metadata used by agent-facing snapshots. */
 export type CdpRoleRef = {
   role: string;
   name?: string;
@@ -482,6 +502,7 @@ export type CdpRoleRef = {
   frameId?: string;
 };
 
+/** Options for CDP role snapshot extraction and compaction. */
 export type CdpRoleSnapshotOptions = {
   interactive?: boolean;
   compact?: boolean;
@@ -919,6 +940,7 @@ async function buildCdpRoleSnapshot(params: {
   };
 }
 
+/** Build a role/name text snapshot with stable refs from CDP DOM and AX data. */
 export async function snapshotRoleViaCdp(opts: {
   wsUrl: string;
   options?: CdpRoleSnapshotOptions;
@@ -958,6 +980,7 @@ export async function snapshotRoleViaCdp(opts: {
   );
 }
 
+/** Capture a raw DOM snapshot through CDP. */
 export async function snapshotDom(opts: {
   wsUrl: string;
   limit?: number;
@@ -1028,6 +1051,7 @@ export async function snapshotDom(opts: {
   return { nodes: Array.isArray(nodes) ? (nodes as DomSnapshotNode[]) : [] };
 }
 
+/** Simplified DOM node returned by DOM snapshot helpers. */
 export type DomSnapshotNode = {
   ref: string;
   parentRef: string | null;
@@ -1043,6 +1067,7 @@ export type DomSnapshotNode = {
   value?: string;
 };
 
+/** Extract visible DOM text from a CDP target. */
 export async function getDomText(opts: {
   wsUrl: string;
   format: "html" | "text";
@@ -1084,6 +1109,7 @@ export async function getDomText(opts: {
   return { text };
 }
 
+/** Query a selector in a CDP target and return matching node metadata. */
 export async function querySelector(opts: {
   wsUrl: string;
   selector: string;
@@ -1139,6 +1165,7 @@ export async function querySelector(opts: {
   return { matches: Array.isArray(matches) ? (matches as QueryMatch[]) : [] };
 }
 
+/** Selector match metadata returned by querySelector. */
 export type QueryMatch = {
   index: number;
   tag: string;
diff --git a/extensions/browser/src/browser/chrome-mcp.runtime.ts b/extensions/browser/src/browser/chrome-mcp.runtime.ts
@@ -1,5 +1,12 @@
+/**
+ * Lazy Chrome MCP module loader.
+ *
+ * Keeps the heavy chrome-devtools-mcp adapter behind a runtime import boundary
+ * for routes that only need it when existing-session profiles are selected.
+ */
 type ChromeMcpModule = typeof import("./chrome-mcp.js");
 
+/** Import the Chrome MCP adapter module on demand. */
 export async function getChromeMcpModule(): Promise<ChromeMcpModule> {
   return await import("./chrome-mcp.js");
 }
diff --git a/extensions/browser/src/browser/chrome-mcp.snapshot.ts b/extensions/browser/src/browser/chrome-mcp.snapshot.ts
@@ -1,3 +1,9 @@
+/**
+ * Chrome MCP snapshot conversion helpers.
+ *
+ * Converts chrome-devtools-mcp structured snapshots into OpenClaw ARIA nodes
+ * and compact AI snapshots with stable refs and duplicate tracking.
+ */
 import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { normalizeString } from "../record-shared.js";
 import type { SnapshotAriaNode } from "./client.types.js";
@@ -8,6 +14,7 @@ import {
 } from "./pw-role-snapshot.js";
 import { CONTENT_ROLES, INTERACTIVE_ROLES, STRUCTURAL_ROLES } from "./snapshot-roles.js";
 
+/** Structured snapshot node shape returned by chrome-devtools-mcp. */
 export type ChromeMcpSnapshotNode = {
   id?: string;
   role?: string;
@@ -75,6 +82,7 @@ function registerRef(
   return undefined;
 }
 
+/** Flatten a Chrome MCP snapshot tree into OpenClaw ARIA-style nodes. */
 export function flattenChromeMcpSnapshotToAriaNodes(
   root: ChromeMcpSnapshotNode,
   limit = 500,
@@ -109,6 +117,7 @@ export function flattenChromeMcpSnapshotToAriaNodes(
   return out;
 }
 
+/** Build a compact text snapshot and ref map from a Chrome MCP snapshot tree. */
 export function buildAiSnapshotFromChromeMcpSnapshot(params: {
   root: ChromeMcpSnapshotNode;
   options?: RoleSnapshotOptions;
diff --git a/extensions/browser/src/browser/chrome-mcp.ts b/extensions/browser/src/browser/chrome-mcp.ts
