docs: document browser root modules

extensions/browser/src/control-service.ts

@@ -1,3 +1,6 @@
+/**
+ * Browser control service lifecycle for plugin-managed, in-process operation.
+ */
 import {
   createBrowserControlContext,
   ensureBrowserControlRuntime,
@@ -15,6 +18,7 @@ import { isDefaultBrowserPluginEnabled } from "./plugin-enabled.js";
 const log = createSubsystemLogger("browser");
 const logService = log.child("service");
 
+/** Starts Browser control without binding the HTTP server when config enables it. */
 export async function startBrowserControlServiceFromConfig(): Promise<BrowserServerState | null> {
   const current = getBrowserControlState();
   if (current) {
@@ -53,6 +57,7 @@ export async function startBrowserControlServiceFromConfig(): Promise<BrowserSer
   return state;
 }
 
+/** Stops the in-process Browser control service runtime. */
 export async function stopBrowserControlService(): Promise<void> {
   await stopBrowserControlRuntime({
     requestedBy: "service",
@@ -60,4 +65,5 @@ export async function stopBrowserControlService(): Promise<void> {
   });
 }
 
+/** Re-export Browser control context accessors for gateway-local dispatch. */
 export { createBrowserControlContext, getBrowserControlState };

extensions/browser/src/core-api.ts

@@ -1,3 +1,7 @@
+/**
+ * Browser plugin internal barrel that gathers runtime, SDK, CLI, and gateway
+ * APIs for modules that need a stable local import surface.
+ */
 export {
   DEFAULT_AI_SNAPSHOT_MAX_CHARS,
   DEFAULT_UPLOAD_DIR,

extensions/browser/src/doctor-browser.ts

@@ -1,3 +1,7 @@
+/**
+ * Browser doctor checks for Chrome MCP readiness and legacy managed-profile
+ * residue cleanup.
+ */
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
@@ -31,6 +35,7 @@ type ManagedProfile = {
   name: string;
 };
 
+/** Legacy managed clawd profile paths that can be archived by doctor --fix. */
 export type LegacyClawdBrowserProfileResidue = {
   legacyProfileDir: string;
   legacyUserDataDir: string;
@@ -147,6 +152,7 @@ function isLegacyClawdProfileConfigured(cfg: OpenClawConfig, legacyProfileDir: s
   return false;
 }
 
+/** Detects unmanaged legacy clawd browser profile residue on disk. */
 export function detectLegacyClawdBrowserProfileResidue(
   cfg: OpenClawConfig,
   deps?: BrowserDoctorFilesystemDeps,
@@ -198,6 +204,7 @@ function formatLegacyClawdBrowserProfileResidueNote(
   ].join("\n");
 }
 
+/** Emits Browser doctor notes for Chrome MCP, managed Chrome, and legacy residue readiness. */
 export async function noteChromeMcpBrowserReadiness(
   cfg: OpenClawConfig,
   deps?: {
@@ -348,6 +355,7 @@ export async function noteChromeMcpBrowserReadiness(
   noteFn(lines.join("\n"), "Browser");
 }
 
+/** Archives legacy clawd browser profile residue when doctor --fix is requested. */
 export async function maybeArchiveLegacyClawdBrowserProfileResidue(
   cfg: OpenClawConfig,
   deps?: BrowserDoctorFilesystemDeps,

extensions/browser/src/plugin-enabled.ts

@@ -1,6 +1,10 @@
+/**
+ * Browser plugin enablement resolver for bundled-plugin defaults.
+ */
 import type { OpenClawConfig } from "./sdk-config.js";
 import { normalizePluginsConfig, resolveEffectiveEnableState } from "./sdk-config.js";
 
+/** Returns whether the bundled Browser plugin is effectively enabled by config. */
 export function isDefaultBrowserPluginEnabled(cfg: OpenClawConfig): boolean {
   return resolveEffectiveEnableState({
     id: "browser",

extensions/browser/src/plugin-service.ts

@@ -1,3 +1,6 @@
+/**
+ * Browser plugin service factory that lazily starts the control server.
+ */
 import {
   startLazyPluginServiceModule,
   type LazyPluginServiceHandle,
@@ -20,6 +23,7 @@ function validateBrowserControlOverrideSpecifier(specifier: string): string {
   return trimmed;
 }
 
+/** Creates the Browser plugin service registered by the plugin entrypoint. */
 export function createBrowserPluginService(): OpenClawPluginService {
   let handle: BrowserControlHandle = null;
 

extensions/browser/src/record-shared.ts

@@ -1,13 +1,19 @@
+/**
+ * Small record/string coercion helpers shared by Browser setup and audits.
+ */
 import {
   asNullableRecord,
   hasNonEmptyString as sharedHasNonEmptyString,
   isRecord,
 } from "openclaw/plugin-sdk/string-coerce-runtime";
 
+/** Re-export record guards under Browser-local names. */
 export { asNullableRecord as asRecord, isRecord };
 
+/** Re-export shared non-empty string predicate. */
 export const hasNonEmptyString = sharedHasNonEmptyString;
 
+/** Normalizes primitive string/number/boolean values to non-empty strings. */
 export function normalizeString(value: unknown): string | undefined {
   if (typeof value === "string") {
     const trimmed = value.trim();

extensions/browser/src/sdk-config.ts

@@ -1,3 +1,6 @@
+/**
+ * Browser-local SDK config bridge plus Browser-specific default port helpers.
+ */
 import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/string-coerce-runtime";
 
 export {
@@ -29,6 +32,7 @@ const DEFAULT_BROWSER_CDP_PORT_RANGE_END = 18899;
 const DEFAULT_BROWSER_CDP_PORT_RANGE_SPAN =
   DEFAULT_BROWSER_CDP_PORT_RANGE_END - DEFAULT_BROWSER_CDP_PORT_RANGE_START;
 
+/** Default loopback port for the Browser control server. */
 export const DEFAULT_BROWSER_CONTROL_PORT = 18791;
 
 function isValidPort(port: number): boolean {
@@ -43,10 +47,12 @@ function derivePort(base: number, offset: number, fallback: number): number {
   return clampPort(base + offset, fallback);
 }
 
+/** Derives the Browser control port from the gateway port. */
 export function deriveDefaultBrowserControlPort(gatewayPort: number): number {
   return derivePort(gatewayPort, 2, DEFAULT_BROWSER_CONTROL_PORT);
 }
 
+/** Derives the managed Chrome CDP port range from the Browser control port. */
 export function deriveDefaultBrowserCdpPortRange(browserControlPort: number): PortRange {
   const start = derivePort(browserControlPort, 9, DEFAULT_BROWSER_CDP_PORT_RANGE_START);
   const end = start + DEFAULT_BROWSER_CDP_PORT_RANGE_SPAN;
@@ -71,6 +77,7 @@ function matchesBooleanToken(value: string, tokens: readonly string[]): boolean
   return tokens.includes(value);
 }
 
+/** Parses common string booleans with optional custom truthy/falsy tokens. */
 export function parseBooleanValue(
   value: unknown,
   options: BooleanParseOptions = {},

extensions/browser/src/sdk-node-runtime.ts

@@ -1,3 +1,7 @@
+/**
+ * Browser-local SDK bridge for gateway, plugin runtime, CLI runtime, and timeout
+ * helpers.
+ */
 export {
   addGatewayClientOptions,
   callGatewayFromCli,
@@ -65,6 +69,7 @@ function waitForAbort(
   };
 }
 
+/** Runs async work with an optional aborting timeout signal. */
 export async function withTimeout<T>(
   work: (signal: AbortSignal | undefined) => Promise<T>,
   timeoutMs?: number,

extensions/browser/src/sdk-security-runtime.ts

@@ -1,3 +1,6 @@
+/**
+ * Browser-local SDK security bridge plus directory creation helper.
+ */
 import fs from "node:fs/promises";
 import path from "node:path";
 import {
@@ -35,6 +38,7 @@ export {
 } from "openclaw/plugin-sdk/security-runtime";
 export type { LookupFn, SsrFPolicy } from "openclaw/plugin-sdk/security-runtime";
 
+/** Ensures an absolute directory exists without escaping its nearest existing ancestor. */
 export async function ensureAbsoluteDirectory(
   dirPath: string,
   options?: { scopeLabel?: string; mode?: number },

extensions/browser/src/sdk-setup-tools.ts

@@ -1,3 +1,6 @@
+/**
+ * Browser-local SDK setup/tooling bridge for CLI, media, and action helpers.
+ */
 export {
   callGatewayTool,
   listNodes,

extensions/browser/src/security-audit.ts

@@ -1,3 +1,6 @@
+/**
+ * Browser plugin security audit checks for auth and remote CDP exposure.
+ */
 import type { OpenClawPluginSecurityAuditContext } from "openclaw/plugin-sdk/plugin-entry";
 import { hasConfiguredSecretInput } from "openclaw/plugin-sdk/secret-input";
 import { formatCliCommand } from "openclaw/plugin-sdk/setup-tools";
@@ -18,6 +21,7 @@ function isTrustedPrivateHostname(hostname: string): boolean {
   return normalized.length > 0 && BLOCKED_HOSTNAMES.has(normalized);
 }
 
+/** Collects Browser plugin security audit findings for the current config/env. */
 export function collectBrowserSecurityAuditFindings(ctx: OpenClawPluginSecurityAuditContext) {
   const findings: Array<{
     checkId: string;

extensions/browser/src/server.ts

@@ -1,3 +1,6 @@
+/**
+ * Browser control HTTP server startup and shutdown entrypoints.
+ */
 import type { Server } from "node:http";
 import express from "express";
 import {
@@ -28,6 +31,7 @@ import { isDefaultBrowserPluginEnabled } from "./plugin-enabled.js";
 const log = createSubsystemLogger("browser");
 const logServer = log.child("server");
 
+/** Starts the Browser control HTTP server from runtime config. */
 export async function startBrowserControlServerFromConfig(): Promise<BrowserServerState | null> {
   const current = getBrowserControlState();
   if (current?.server) {
@@ -107,6 +111,7 @@ export async function startBrowserControlServerFromConfig(): Promise<BrowserServ
   return state;
 }
 
+/** Stops the Browser control HTTP server and unregisters bridge auth. */
 export async function stopBrowserControlServer(): Promise<void> {
   const current = getBrowserControlState();
   if (current?.port) {

extensions/browser/src/utils.ts

@@ -1 +1,4 @@
+/**
+ * Browser utility re-exports for config paths, escaping, and user path resolution.
+ */
 export { CONFIG_DIR, escapeRegExp, resolveUserPath } from "./sdk-config.js";

extensions/browser/test-fetch.ts

@@ -1,3 +1,6 @@
+/**
+ * Test fetch helper that adds no-op preconnect support expected by Browser tests.
+ */
 type FetchPreconnectOptions = {
   dns?: boolean;
   tcp?: boolean;
@@ -10,6 +13,7 @@ type FetchWithPreconnect = {
   __openclawAcceptsDispatcher: true;
 };
 
+/** Adds Browser test preconnect metadata to a fetch-like function. */
 export function withBrowserFetchPreconnect<T extends typeof fetch>(fn: T): T & FetchWithPreconnect;
 export function withBrowserFetchPreconnect<T extends object>(
   fn: T,

extensions/browser/test-support.ts

@@ -1,3 +1,6 @@
+/**
+ * Browser test-support re-exports from shared plugin-sdk test fixtures.
+ */
 export {
   createCliRuntimeCapture,
   expectGeneratedTokenPersistedToGatewayAuth,