@flrande/browserctl 0.1.0-dev.7.1

package/packages/driver-chrome-relay/src/chrome-relay-driver.ts

@@ -0,0 +1,2206 @@
+import type {
+  BrowserDriver,
+  BrowserDriverScreenshot,
+  DriverObject
+} from "../../core/src/driver";
+import type { ProfileId, TargetId } from "../../core/src/types";
+
+export type ChromeRelayConsoleEntryLocation = {
+  url?: string;
+  lineNumber?: number;
+  columnNumber?: number;
+};
+
+export type ChromeRelayConsoleEntry = {
+  type: string;
+  text: string;
+  timestamp: string;
+  location?: ChromeRelayConsoleEntryLocation;
+};
+
+export type ChromeRelayNetworkRequestSummary = {
+  requestId: string;
+  url: string;
+  method?: string;
+  resourceType?: string;
+  status?: number;
+  timestamp: string;
+};
+
+export type ChromeRelayNetworkResponseBody = {
+  body: string;
+  encoding: "utf8" | "base64";
+};
+
+export type ChromeRelaySnapshot = {
+  kind: "chrome-relay";
+  profile: ProfileId;
+  targetId: TargetId;
+  relayUrl: string;
+  hasTarget: boolean;
+  url?: string;
+  title?: string;
+  html?: string;
+  requestSummaries?: ChromeRelayNetworkRequestSummary[];
+};
+
+export type ChromeRelayScreenshot = {
+  kind: "chrome-relay";
+  profile: ProfileId;
+  targetId: TargetId;
+  relayUrl: string;
+  hasTarget: boolean;
+  mimeType?: string;
+  encoding?: "base64";
+  imageBase64?: string;
+  width?: number;
+  height?: number;
+};
+
+export type ChromeRelayTelemetryDriverExtensions = {
+  getConsoleEntries?(targetId: TargetId, profile?: ProfileId): ChromeRelayConsoleEntry[];
+  getNetworkResponseBody?(
+    requestId: string,
+    targetId: TargetId,
+    profile?: ProfileId
+  ): ChromeRelayNetworkResponseBody | undefined;
+};
+
+export type ChromeRelayLocator = {
+  click(): Promise<void>;
+  fill(value: string): Promise<void>;
+  type(value: string): Promise<void>;
+};
+
+export type ChromeRelayKeyboard = {
+  press(key: string): Promise<void>;
+};
+
+export type ChromeRelayPage = {
+  goto(url: string): Promise<void>;
+  bringToFront(): Promise<void>;
+  close(): Promise<void>;
+  url(): string;
+  title(): Promise<string>;
+  content(): Promise<string>;
+  screenshot?(options?: Record<string, unknown>): Promise<unknown>;
+  domQuery?(selector: string): Promise<unknown>;
+  domQueryAll?(selector: string): Promise<unknown>;
+  elementScreenshot?(selector: string): Promise<unknown>;
+  a11ySnapshot?(selector?: string): Promise<unknown>;
+  cookieGet?(name?: string): Promise<unknown>;
+  cookieSet?(cookie: { name: string; value: string; url?: string }): Promise<unknown>;
+  cookieClear?(name?: string): Promise<unknown>;
+  storageGet?(scope: string, key: string): Promise<unknown>;
+  storageSet?(scope: string, key: string, value: string): Promise<unknown>;
+  frameList?(): Promise<unknown>;
+  frameSnapshot?(frameId: string): Promise<unknown>;
+  scroll?(deltaX?: number, deltaY?: number): Promise<unknown>;
+  locator(selector: string): ChromeRelayLocator;
+  keyboard?: ChromeRelayKeyboard;
+  on?(eventName: string, listener: (payload: unknown) => unknown): void;
+};
+
+export type ChromeRelayBrowserContext = {
+  newPage(): Promise<ChromeRelayPage>;
+  close?(): Promise<void>;
+};
+
+export type ChromeRelayBrowser = {
+  contexts(): ChromeRelayBrowserContext[];
+  newContext?(): Promise<ChromeRelayBrowserContext>;
+  close(): Promise<void>;
+};
+
+export type ChromeRelayDriverRuntime = {
+  connectOverCDP(endpointUrl: string): Promise<ChromeRelayBrowser>;
+  fetchJson?(url: string): Promise<unknown>;
+  isConnected?(): boolean | Promise<boolean>;
+};
+
+export type ChromeRelayDriverConfig = {
+  relayUrl?: string;
+  runtime?: ChromeRelayDriverRuntime;
+};
+
+export type ChromeRelayDriverStatus = {
+  kind: "chrome-relay";
+  connected: boolean;
+  relayUrl: string;
+};
+
+const DEFAULT_PROFILE_ID: ProfileId = "profile:chrome-relay:default";
+const DEFAULT_RELAY_URL = "http://127.0.0.1:9223";
+const TELEMETRY_EVENT_LIMIT = 200;
+
+type ChromeRelayTab = {
+  url: string;
+  page: ChromeRelayPage;
+};
+
+type ChromeRelayProfileState = {
+  nextTargetNumber: number;
+  tabs: Map<TargetId, ChromeRelayTab>;
+  tabOrder: TargetId[];
+  focusedTargetId?: TargetId;
+};
+
+type ChromeRelayTargetOperationState = {
+  uploadFiles: string[];
+  dialogArmedCount: number;
+  triggerCount: number;
+  downloadInFlight?: Promise<ChromeRelayDownloadArtifact>;
+  latestDownload?: ChromeRelayDownloadArtifact;
+};
+
+type ChromeRelayDownloadArtifact = {
+  path: string;
+  suggestedFilename?: string;
+  url?: string;
+  mimeType?: string;
+};
+
+type ChromeRelayTargetTelemetryState = {
+  consoleEntries: ChromeRelayConsoleEntry[];
+  requestSummaries: ChromeRelayNetworkRequestSummary[];
+  networkResponseBodies: Map<string, ChromeRelayNetworkResponseBody>;
+  nextRequestNumber: number;
+};
+
+function resolveProfileId(profile?: ProfileId): ProfileId {
+  return profile ?? DEFAULT_PROFILE_ID;
+}
+
+function createTargetId(profileId: ProfileId, targetNumber: number): TargetId {
+  return `target:chrome-relay:${profileId}:${targetNumber}`;
+}
+
+function createProfileState(): ChromeRelayProfileState {
+  return {
+    nextTargetNumber: 1,
+    tabs: new Map<TargetId, ChromeRelayTab>(),
+    tabOrder: []
+  };
+}
+
+function createTargetOperationState(): ChromeRelayTargetOperationState {
+  return {
+    uploadFiles: [],
+    dialogArmedCount: 0,
+    triggerCount: 0
+  };
+}
+
+function createTargetTelemetryState(): ChromeRelayTargetTelemetryState {
+  return {
+    consoleEntries: [],
+    requestSummaries: [],
+    networkResponseBodies: new Map<string, ChromeRelayNetworkResponseBody>(),
+    nextRequestNumber: 1
+  };
+}
+
+function trimConsoleEntries(telemetryState: ChromeRelayTargetTelemetryState): void {
+  if (telemetryState.consoleEntries.length <= TELEMETRY_EVENT_LIMIT) {
+    return;
+  }
+
+  telemetryState.consoleEntries.splice(
+    0,
+    telemetryState.consoleEntries.length - TELEMETRY_EVENT_LIMIT
+  );
+}
+
+function trimNetworkTelemetry(telemetryState: ChromeRelayTargetTelemetryState): void {
+  if (telemetryState.requestSummaries.length > TELEMETRY_EVENT_LIMIT) {
+    const removedSummaries = telemetryState.requestSummaries.splice(
+      0,
+      telemetryState.requestSummaries.length - TELEMETRY_EVENT_LIMIT
+    );
+    for (const removed of removedSummaries) {
+      telemetryState.networkResponseBodies.delete(removed.requestId);
+    }
+  }
+
+  const knownRequestIds = new Set(
+    telemetryState.requestSummaries.map((summary) => summary.requestId)
+  );
+  for (const requestId of telemetryState.networkResponseBodies.keys()) {
+    if (!knownRequestIds.has(requestId)) {
+      telemetryState.networkResponseBodies.delete(requestId);
+    }
+  }
+}
+
+function sanitizePathSegment(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "_");
+}
+
+function createDownloadPath(profileId: ProfileId, targetId: TargetId, triggerCount: number): string {
+  return `chrome-relay-${sanitizePathSegment(profileId)}-${sanitizePathSegment(targetId)}-${triggerCount}.bin`;
+}
+
+function createRequestId(profileId: ProfileId, targetId: TargetId, requestNumber: number): string {
+  return `request:chrome-relay:${encodeURIComponent(profileId)}:${encodeURIComponent(targetId)}:${requestNumber}`;
+}
+
+function parseRelayUrl(config?: ChromeRelayDriverConfig): string {
+  const rawRelayUrl = config?.relayUrl === undefined ? DEFAULT_RELAY_URL : config.relayUrl.trim();
+  if (rawRelayUrl.trim().length === 0) {
+    throw new Error("Invalid relayUrl: value must not be empty.");
+  }
+
+  try {
+    return new URL(rawRelayUrl).toString();
+  } catch {
+    throw new Error(`Invalid relayUrl: ${rawRelayUrl}`);
+  }
+}
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : "Unexpected chrome-relay driver failure.";
+}
+
+function readActionPayloadString(payload: DriverObject | undefined, key: string): string | undefined {
+  const value = payload?.[key];
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+function readActionPayloadNumber(payload: DriverObject | undefined, key: string): number | undefined {
+  const value = payload?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readObjectMethod<TValue>(value: unknown, methodName: string): TValue | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const method = (value as Record<string, unknown>)[methodName];
+  if (typeof method !== "function") {
+    return undefined;
+  }
+
+  try {
+    return (method as () => TValue).call(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function getObjectMethod(
+  value: unknown,
+  methodName: string
+): ((...args: unknown[]) => unknown) | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const method = (value as Record<string, unknown>)[methodName];
+  return typeof method === "function" ? (method as (...args: unknown[]) => unknown) : undefined;
+}
+
+function readObjectStringProperty(value: unknown, key: string): string | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const property = (value as Record<string, unknown>)[key];
+  return typeof property === "string" ? property : undefined;
+}
+
+function readObjectNumberProperty(value: unknown, key: string): number | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const property = (value as Record<string, unknown>)[key];
+  return typeof property === "number" ? property : undefined;
+}
+
+async function readRuntimeConnectionStatus(
+  runtime: ChromeRelayDriverRuntime
+): Promise<boolean | undefined> {
+  if (typeof runtime.isConnected !== "function") {
+    return undefined;
+  }
+
+  try {
+    const connected = await runtime.isConnected();
+    return typeof connected === "boolean" ? connected : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readConsoleEntry(value: unknown): ChromeRelayConsoleEntry {
+  const locationValue = readObjectMethod<unknown>(value, "location");
+  const locationUrl = readObjectStringProperty(locationValue, "url");
+  const locationLineNumber = readObjectNumberProperty(locationValue, "lineNumber");
+  const locationColumnNumber = readObjectNumberProperty(locationValue, "columnNumber");
+
+  const hasLocation =
+    locationUrl !== undefined || locationLineNumber !== undefined || locationColumnNumber !== undefined;
+
+  return {
+    type: readObjectMethod<string>(value, "type") ?? "log",
+    text: readObjectMethod<string>(value, "text") ?? "",
+    timestamp: new Date().toISOString(),
+    ...(hasLocation
+      ? {
+          location: {
+            ...(locationUrl !== undefined ? { url: locationUrl } : {}),
+            ...(locationLineNumber !== undefined ? { lineNumber: locationLineNumber } : {}),
+            ...(locationColumnNumber !== undefined ? { columnNumber: locationColumnNumber } : {})
+          }
+        }
+      : {})
+  };
+}
+
+function readNetworkSummary(value: unknown, requestId: string): ChromeRelayNetworkRequestSummary {
+  const requestValue = readObjectMethod<unknown>(value, "request");
+  const method = readObjectMethod<string>(requestValue, "method");
+  const resourceType = readObjectMethod<string>(requestValue, "resourceType");
+  const status = readObjectMethod<number>(value, "status");
+
+  return {
+    requestId,
+    url: readObjectMethod<string>(value, "url") ?? "",
+    ...(typeof method === "string" ? { method } : {}),
+    ...(typeof resourceType === "string" ? { resourceType } : {}),
+    ...(typeof status === "number" ? { status } : {}),
+    timestamp: new Date().toISOString()
+  };
+}
+
+function toBase64(value: ArrayBuffer | Uint8Array): string {
+  const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
+  return Buffer.from(bytes).toString("base64");
+}
+
+function parseScreenshotBase64(
+  value: string
+): { mimeType: string; imageBase64: string } | undefined {
+  const trimmedValue = value.trim();
+  if (trimmedValue.length === 0) {
+    return undefined;
+  }
+
+  const dataUrlMatch = /^data:([^;,]+);base64,(.+)$/i.exec(trimmedValue);
+  if (dataUrlMatch !== null) {
+    const mimeType = dataUrlMatch[1] ?? "image/png";
+    const imageBase64 = dataUrlMatch[2] ?? "";
+    if (imageBase64.length === 0) {
+      return undefined;
+    }
+
+    return {
+      mimeType,
+      imageBase64
+    };
+  }
+
+  return {
+    mimeType: "image/png",
+    imageBase64: trimmedValue
+  };
+}
+
+type ChromeRelayScreenshotImage = {
+  mimeType: string;
+  encoding: "base64";
+  imageBase64: string;
+  width?: number;
+  height?: number;
+};
+
+function toOptionalPositiveNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function readScreenshotImage(value: unknown): ChromeRelayScreenshotImage | undefined {
+  if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+    return {
+      mimeType: "image/png",
+      encoding: "base64",
+      imageBase64: toBase64(value)
+    };
+  }
+
+  if (typeof value === "string") {
+    const parsed = parseScreenshotBase64(value);
+    if (parsed === undefined) {
+      return undefined;
+    }
+
+    return {
+      mimeType: parsed.mimeType,
+      encoding: "base64",
+      imageBase64: parsed.imageBase64
+    };
+  }
+
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const imageBase64 = readObjectStringProperty(value, "imageBase64");
+  if (imageBase64 === undefined || imageBase64.trim().length === 0) {
+    return undefined;
+  }
+
+  const rawEncoding = readObjectStringProperty(value, "encoding");
+  if (rawEncoding !== undefined && rawEncoding !== "base64") {
+    return undefined;
+  }
+
+  const mimeType = readObjectStringProperty(value, "mimeType") ?? "image/png";
+  const width = toOptionalPositiveNumber(readObjectNumberProperty(value, "width"));
+  const height = toOptionalPositiveNumber(readObjectNumberProperty(value, "height"));
+
+  return {
+    mimeType,
+    encoding: "base64",
+    imageBase64: imageBase64.trim(),
+    ...(width !== undefined ? { width } : {}),
+    ...(height !== undefined ? { height } : {})
+  };
+}
+
+async function capturePageScreenshot(page: ChromeRelayPage): Promise<ChromeRelayScreenshotImage> {
+  const screenshotMethod = getObjectMethod(page, "screenshot");
+  if (typeof screenshotMethod !== "function") {
+    throw new Error("Screenshot is not supported by this driver runtime.");
+  }
+
+  const screenshot = await screenshotMethod.call(page, {
+    type: "png"
+  });
+  const parsedScreenshot = readScreenshotImage(screenshot);
+  if (parsedScreenshot === undefined) {
+    throw new Error("Unexpected screenshot payload from driver runtime.");
+  }
+
+  return parsedScreenshot;
+}
+
+type ChromeRelayCookie = {
+  name: string;
+  value: string;
+  domain?: string;
+  path?: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: string;
+  url?: string;
+};
+
+function normalizeCookies(value: unknown): ChromeRelayCookie[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const cookies: ChromeRelayCookie[] = [];
+  for (const item of value) {
+    if (!isObjectRecord(item)) {
+      continue;
+    }
+
+    const name = readObjectStringProperty(item, "name");
+    const cookieValue = readObjectStringProperty(item, "value");
+    if (name === undefined || cookieValue === undefined) {
+      continue;
+    }
+
+    const domain = readObjectStringProperty(item, "domain");
+    const path = readObjectStringProperty(item, "path");
+    const sameSite = readObjectStringProperty(item, "sameSite");
+    const url = readObjectStringProperty(item, "url");
+    const expiresRaw = readObjectNumberProperty(item, "expires");
+    const httpOnlyRaw = item.httpOnly;
+    const secureRaw = item.secure;
+
+    cookies.push({
+      name,
+      value: cookieValue,
+      ...(domain !== undefined ? { domain } : {}),
+      ...(path !== undefined ? { path } : {}),
+      ...(typeof expiresRaw === "number" && Number.isFinite(expiresRaw) ? { expires: expiresRaw } : {}),
+      ...(typeof httpOnlyRaw === "boolean" ? { httpOnly: httpOnlyRaw } : {}),
+      ...(typeof secureRaw === "boolean" ? { secure: secureRaw } : {}),
+      ...(sameSite !== undefined ? { sameSite } : {}),
+      ...(url !== undefined ? { url } : {})
+    });
+  }
+
+  return cookies;
+}
+
+function toCookieInput(cookie: ChromeRelayCookie): Record<string, unknown> | undefined {
+  const base: Record<string, unknown> = {
+    name: cookie.name,
+    value: cookie.value
+  };
+
+  if (cookie.url !== undefined) {
+    return {
+      ...base,
+      url: cookie.url,
+      ...(cookie.expires !== undefined ? { expires: cookie.expires } : {}),
+      ...(cookie.httpOnly !== undefined ? { httpOnly: cookie.httpOnly } : {}),
+      ...(cookie.secure !== undefined ? { secure: cookie.secure } : {}),
+      ...(cookie.sameSite !== undefined ? { sameSite: cookie.sameSite } : {})
+    };
+  }
+
+  if (cookie.domain !== undefined && cookie.path !== undefined) {
+    return {
+      ...base,
+      domain: cookie.domain,
+      path: cookie.path,
+      ...(cookie.expires !== undefined ? { expires: cookie.expires } : {}),
+      ...(cookie.httpOnly !== undefined ? { httpOnly: cookie.httpOnly } : {}),
+      ...(cookie.secure !== undefined ? { secure: cookie.secure } : {}),
+      ...(cookie.sameSite !== undefined ? { sameSite: cookie.sameSite } : {})
+    };
+  }
+
+  return undefined;
+}
+
+function parseStorageScope(scope: string | undefined): "local" | "session" | undefined {
+  if (scope === "local" || scope === "session") {
+    return scope;
+  }
+
+  return undefined;
+}
+
+function parseFrameIndex(frameId: string | undefined): number | undefined {
+  if (typeof frameId !== "string") {
+    return undefined;
+  }
+
+  const match = /^frame:(\d+)$/.exec(frameId.trim());
+  if (match === null) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(match[1] ?? "", 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+async function evaluateInPage<TResult>(
+  page: ChromeRelayPage,
+  callback: (arg: unknown) => unknown,
+  arg: unknown
+): Promise<TResult> {
+  const evaluateMethod = getObjectMethod(page, "evaluate");
+  if (typeof evaluateMethod !== "function") {
+    throw new Error("Driver runtime page does not support evaluate.");
+  }
+
+  const result = await evaluateMethod.call(page, callback, arg);
+  return result as TResult;
+}
+
+async function readNetworkResponseBody(
+  value: unknown
+): Promise<ChromeRelayNetworkResponseBody | undefined> {
+  const textMethod = getObjectMethod(value, "text");
+  if (typeof textMethod === "function") {
+    try {
+      const textResult = await textMethod.call(value);
+      if (typeof textResult === "string") {
+        return {
+          body: textResult,
+          encoding: "utf8"
+        };
+      }
+    } catch {
+      // Ignore body extraction failures from optional runtime hooks.
+    }
+  }
+
+  const bodyMethod = getObjectMethod(value, "body");
+  if (typeof bodyMethod !== "function") {
+    return undefined;
+  }
+
+  try {
+    const bodyResult = await bodyMethod.call(value);
+    if (typeof bodyResult === "string") {
+      return {
+        body: bodyResult,
+        encoding: "utf8"
+      };
+    }
+
+    if (bodyResult instanceof Uint8Array || bodyResult instanceof ArrayBuffer) {
+      return {
+        body: toBase64(bodyResult),
+        encoding: "base64"
+      };
+    }
+
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function attachTelemetryListeners(
+  page: ChromeRelayPage,
+  profileId: ProfileId,
+  targetId: TargetId,
+  telemetryState: ChromeRelayTargetTelemetryState,
+  operationState: ChromeRelayTargetOperationState
+): void {
+  if (typeof page.on !== "function") {
+    return;
+  }
+
+  page.on("console", (message) => {
+    telemetryState.consoleEntries.push(readConsoleEntry(message));
+    trimConsoleEntries(telemetryState);
+  });
+
+  page.on("response", async (response) => {
+    const requestId = createRequestId(profileId, targetId, telemetryState.nextRequestNumber);
+    telemetryState.nextRequestNumber += 1;
+    telemetryState.requestSummaries.push(readNetworkSummary(response, requestId));
+    trimNetworkTelemetry(telemetryState);
+
+    const body = await readNetworkResponseBody(response);
+    if (body !== undefined) {
+      telemetryState.networkResponseBodies.set(requestId, body);
+      trimNetworkTelemetry(telemetryState);
+    }
+  });
+
+  page.on("dialog", async (dialog) => {
+    if (operationState.dialogArmedCount <= 0) {
+      return;
+    }
+
+    operationState.dialogArmedCount -= 1;
+    const acceptMethod = getObjectMethod(dialog, "accept");
+    if (typeof acceptMethod === "function") {
+      try {
+        await acceptMethod.call(dialog);
+        return;
+      } catch {
+        // Fall through to dismiss.
+      }
+    }
+
+    const dismissMethod = getObjectMethod(dialog, "dismiss");
+    if (typeof dismissMethod === "function") {
+      try {
+        await dismissMethod.call(dialog);
+      } catch {
+        // Ignore dialog dismissal failures.
+      }
+    }
+  });
+}
+
+async function readDownloadArtifact(
+  value: unknown,
+  fallbackPath: string
+): Promise<ChromeRelayDownloadArtifact> {
+  let resolvedPath = fallbackPath;
+  const pathMethod = getObjectMethod(value, "path");
+  if (typeof pathMethod === "function") {
+    try {
+      const pathResult = await pathMethod.call(value);
+      if (typeof pathResult === "string" && pathResult.trim().length > 0) {
+        resolvedPath = pathResult;
+      }
+    } catch {
+      // Ignore path() failures and keep fallback path.
+    }
+  }
+
+  const saveAsMethod = getObjectMethod(value, "saveAs");
+  if (typeof saveAsMethod === "function") {
+    try {
+      await saveAsMethod.call(value, fallbackPath);
+      resolvedPath = fallbackPath;
+    } catch {
+      // Ignore saveAs failures and keep best-effort path.
+    }
+  }
+
+  const suggestedFilename = readObjectMethod<string>(value, "suggestedFilename");
+  const url = readObjectMethod<string>(value, "url");
+  const mimeType = readObjectMethod<string>(value, "mimeType");
+
+  return {
+    path: resolvedPath,
+    ...(typeof suggestedFilename === "string" ? { suggestedFilename } : {}),
+    ...(typeof url === "string" ? { url } : {}),
+    ...(typeof mimeType === "string" ? { mimeType } : {})
+  };
+}
+
+function readWebSocketDebuggerUrl(value: unknown): string | undefined {
+  const rawUrl = readObjectStringProperty(value, "webSocketDebuggerUrl");
+  if (rawUrl === undefined) {
+    return undefined;
+  }
+
+  try {
+    const parsed = new URL(rawUrl);
+    if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+      return undefined;
+    }
+
+    return parsed.toString();
+  } catch {
+    return undefined;
+  }
+}
+
+async function resolveRelayEndpoint(relayUrl: string, runtime: ChromeRelayDriverRuntime): Promise<string> {
+  const parsedRelayUrl = new URL(relayUrl);
+  if (parsedRelayUrl.protocol === "ws:" || parsedRelayUrl.protocol === "wss:") {
+    return parsedRelayUrl.toString();
+  }
+
+  if (parsedRelayUrl.protocol === "http:" || parsedRelayUrl.protocol === "https:") {
+    if (typeof runtime.fetchJson === "function") {
+      const jsonVersionUrl = new URL("/json/version", parsedRelayUrl).toString();
+      try {
+        const payload = await runtime.fetchJson(jsonVersionUrl);
+        const debuggerUrl = readWebSocketDebuggerUrl(payload);
+        if (debuggerUrl !== undefined) {
+          return debuggerUrl;
+        }
+      } catch {
+        // Fall through to connect directly to relay URL.
+      }
+    }
+  }
+
+  return parsedRelayUrl.toString();
+}
+
+function createPlaywrightRuntime(): ChromeRelayDriverRuntime {
+  return {
+    connectOverCDP: async (endpointUrl) => {
+      const playwright = await import("playwright-core");
+      return (await playwright.chromium.connectOverCDP(endpointUrl)) as unknown as ChromeRelayBrowser;
+    },
+    fetchJson: async (url) => {
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`Relay metadata request failed (${response.status}) for ${url}`);
+      }
+
+      return response.json();
+    }
+  };
+}
+
+function cloneConsoleEntry(entry: ChromeRelayConsoleEntry): ChromeRelayConsoleEntry {
+  return {
+    ...entry,
+    ...(entry.location !== undefined ? { location: { ...entry.location } } : {})
+  };
+}
+
+function cloneRequestSummary(summary: ChromeRelayNetworkRequestSummary): ChromeRelayNetworkRequestSummary {
+  return { ...summary };
+}
+
+export function createChromeRelayDriver(
+  config: ChromeRelayDriverConfig = {}
+): BrowserDriver<ChromeRelayDriverStatus, ChromeRelaySnapshot> &
+  ChromeRelayTelemetryDriverExtensions &
+  BrowserDriverScreenshot<ChromeRelayScreenshot> {
+  const relayUrl = parseRelayUrl(config);
+  const runtime = config.runtime ?? createPlaywrightRuntime();
+  const profileStates = new Map<ProfileId, ChromeRelayProfileState>();
+  const targetOperationStates = new Map<ProfileId, Map<TargetId, ChromeRelayTargetOperationState>>();
+  const targetTelemetryStates = new Map<ProfileId, Map<TargetId, ChromeRelayTargetTelemetryState>>();
+  let browser: ChromeRelayBrowser | undefined;
+  let browserConnectInFlight: Promise<ChromeRelayBrowser> | undefined;
+  let browserContext: ChromeRelayBrowserContext | undefined;
+  let browserContextInFlight: Promise<ChromeRelayBrowserContext> | undefined;
+  let resolvedEndpointUrl: string | undefined;
+  let endpointResolveInFlight: Promise<string> | undefined;
+
+  async function ensureEndpointUrl(): Promise<string> {
+    if (resolvedEndpointUrl !== undefined) {
+      return resolvedEndpointUrl;
+    }
+
+    if (endpointResolveInFlight === undefined) {
+      endpointResolveInFlight = resolveRelayEndpoint(relayUrl, runtime)
+        .then((resolved) => {
+          resolvedEndpointUrl = resolved;
+          return resolved;
+        })
+        .finally(() => {
+          endpointResolveInFlight = undefined;
+        });
+    }
+
+    return endpointResolveInFlight;
+  }
+
+  async function ensureBrowser(): Promise<ChromeRelayBrowser> {
+    if (browser !== undefined) {
+      return browser;
+    }
+
+    if (browserConnectInFlight === undefined) {
+      browserConnectInFlight = (async () => {
+        const endpointUrl = await ensureEndpointUrl();
+        const createdBrowser = await runtime.connectOverCDP(endpointUrl);
+        browser = createdBrowser;
+        return createdBrowser;
+      })().finally(() => {
+        browserConnectInFlight = undefined;
+      });
+    }
+
+    return browserConnectInFlight;
+  }
+
+  async function ensureBrowserContext(): Promise<ChromeRelayBrowserContext> {
+    if (browserContext !== undefined) {
+      return browserContext;
+    }
+
+    if (browserContextInFlight === undefined) {
+      browserContextInFlight = (async () => {
+        const connectedBrowser = await ensureBrowser();
+        const existingContext = connectedBrowser.contexts()[0];
+        if (existingContext !== undefined) {
+          browserContext = existingContext;
+          return existingContext;
+        }
+
+        if (typeof connectedBrowser.newContext !== "function") {
+          throw new Error("No browser context available from relay CDP connection.");
+        }
+
+        const createdContext = await connectedBrowser.newContext();
+        browserContext = createdContext;
+        return createdContext;
+      })().finally(() => {
+        browserContextInFlight = undefined;
+      });
+    }
+
+    return browserContextInFlight;
+  }
+
+  function getOrCreateProfileState(profileId: ProfileId): ChromeRelayProfileState {
+    const existingState = profileStates.get(profileId);
+    if (existingState !== undefined) {
+      return existingState;
+    }
+
+    const createdState = createProfileState();
+    profileStates.set(profileId, createdState);
+    return createdState;
+  }
+
+  function requireTargetInProfile(
+    profileId: ProfileId,
+    targetId: TargetId
+  ): { profileState: ChromeRelayProfileState; tab: ChromeRelayTab } {
+    const profileState = profileStates.get(profileId);
+    const tab = profileState?.tabs.get(targetId);
+    if (profileState === undefined || tab === undefined) {
+      throw new Error(`Unknown targetId: ${targetId} (profile: ${profileId})`);
+    }
+
+    return { profileState, tab };
+  }
+
+  function getOrCreateTargetOperationState(
+    profileId: ProfileId,
+    targetId: TargetId,
+    validateTarget = true
+  ): ChromeRelayTargetOperationState {
+    if (validateTarget) {
+      requireTargetInProfile(profileId, targetId);
+    }
+
+    let profileOperationStates = targetOperationStates.get(profileId);
+    if (profileOperationStates === undefined) {
+      profileOperationStates = new Map<TargetId, ChromeRelayTargetOperationState>();
+      targetOperationStates.set(profileId, profileOperationStates);
+    }
+
+    const existingState = profileOperationStates.get(targetId);
+    if (existingState !== undefined) {
+      return existingState;
+    }
+
+    const createdState = createTargetOperationState();
+    profileOperationStates.set(targetId, createdState);
+    return createdState;
+  }
+
+  function getOrCreateProfileTelemetryStates(
+    profileId: ProfileId
+  ): Map<TargetId, ChromeRelayTargetTelemetryState> {
+    const existingStates = targetTelemetryStates.get(profileId);
+    if (existingStates !== undefined) {
+      return existingStates;
+    }
+
+    const createdStates = new Map<TargetId, ChromeRelayTargetTelemetryState>();
+    targetTelemetryStates.set(profileId, createdStates);
+    return createdStates;
+  }
+
+  function findTelemetryState(
+    targetId: TargetId,
+    profile?: ProfileId
+  ): ChromeRelayTargetTelemetryState | undefined {
+    if (profile !== undefined) {
+      return targetTelemetryStates.get(resolveProfileId(profile))?.get(targetId);
+    }
+
+    for (const profileTelemetryStates of targetTelemetryStates.values()) {
+      const telemetryState = profileTelemetryStates.get(targetId);
+      if (telemetryState !== undefined) {
+        return telemetryState;
+      }
+    }
+
+    return undefined;
+  }
+
+  function ensureDownloadInFlight(
+    profileId: ProfileId,
+    targetId: TargetId,
+    tab: ChromeRelayTab,
+    operationState: ChromeRelayTargetOperationState
+  ): Promise<ChromeRelayDownloadArtifact> {
+    if (operationState.downloadInFlight !== undefined) {
+      return operationState.downloadInFlight;
+    }
+
+    const fallbackPath = createDownloadPath(
+      profileId,
+      targetId,
+      Math.max(operationState.triggerCount, 1)
+    );
+    const waitForEventMethod = getObjectMethod(tab.page, "waitForEvent");
+    if (typeof waitForEventMethod !== "function") {
+      const artifact: ChromeRelayDownloadArtifact = { path: fallbackPath };
+      operationState.latestDownload = artifact;
+      const resolved = Promise.resolve(artifact);
+      operationState.downloadInFlight = resolved;
+      return resolved;
+    }
+
+    const inFlight = (async () => {
+      const rawDownload = await waitForEventMethod.call(tab.page, "download");
+      const artifact = await readDownloadArtifact(rawDownload, fallbackPath);
+      operationState.latestDownload = artifact;
+      return artifact;
+    })().finally(() => {
+      if (operationState.downloadInFlight === inFlight) {
+        operationState.downloadInFlight = undefined;
+      }
+    });
+
+    operationState.downloadInFlight = inFlight;
+    return inFlight;
+  }
+
+  return {
+    status: async () => {
+      const runtimeConnected = await readRuntimeConnectionStatus(runtime);
+      return {
+        kind: "chrome-relay",
+        connected: runtimeConnected ?? browser !== undefined,
+        relayUrl
+      };
+    },
+    listProfiles: async () => {
+      const knownProfiles = new Set<ProfileId>([DEFAULT_PROFILE_ID]);
+      for (const profileId of profileStates.keys()) {
+        knownProfiles.add(profileId);
+      }
+
+      return Array.from(knownProfiles).sort();
+    },
+    listTabs: async (profile) => {
+      const profileId = resolveProfileId(profile);
+      const profileState = profileStates.get(profileId);
+      return profileState === undefined ? [] : [...profileState.tabOrder];
+    },
+    openTab: async (url, profile) => {
+      const profileId = resolveProfileId(profile);
+      const profileState = getOrCreateProfileState(profileId);
+      const targetId = createTargetId(profileId, profileState.nextTargetNumber);
+      const page = await (await ensureBrowserContext()).newPage();
+      const telemetryState = createTargetTelemetryState();
+      const operationState = getOrCreateTargetOperationState(profileId, targetId, false);
+      attachTelemetryListeners(page, profileId, targetId, telemetryState, operationState);
+      await page.goto(url);
+
+      profileState.nextTargetNumber += 1;
+      profileState.tabs.set(targetId, { url, page });
+      profileState.tabOrder.push(targetId);
+      getOrCreateProfileTelemetryStates(profileId).set(targetId, telemetryState);
+      if (profileState.focusedTargetId === undefined) {
+        profileState.focusedTargetId = targetId;
+      }
+
+      return targetId;
+    },
+    focusTab: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const { profileState, tab } = requireTargetInProfile(profileId, targetId);
+      await tab.page.bringToFront();
+      profileState.focusedTargetId = targetId;
+    },
+    closeTab: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const { profileState, tab } = requireTargetInProfile(profileId, targetId);
+      await tab.page.close();
+
+      profileState.tabs.delete(targetId);
+      profileState.tabOrder = profileState.tabOrder.filter((existingTargetId) => existingTargetId !== targetId);
+      if (profileState.focusedTargetId === targetId) {
+        profileState.focusedTargetId = profileState.tabOrder[0];
+      }
+
+      const profileOperationStates = targetOperationStates.get(profileId);
+      profileOperationStates?.delete(targetId);
+      if (profileOperationStates !== undefined && profileOperationStates.size === 0) {
+        targetOperationStates.delete(profileId);
+      }
+
+      const profileTelemetryStates = targetTelemetryStates.get(profileId);
+      profileTelemetryStates?.delete(targetId);
+      if (profileTelemetryStates !== undefined && profileTelemetryStates.size === 0) {
+        targetTelemetryStates.delete(profileId);
+      }
+    },
+    snapshot: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const tab = profileStates.get(profileId)?.tabs.get(targetId);
+      if (tab === undefined) {
+        return {
+          kind: "chrome-relay",
+          profile: profileId,
+          targetId,
+          relayUrl,
+          hasTarget: false
+        };
+      }
+
+      const requestSummaries =
+        targetTelemetryStates
+          .get(profileId)
+          ?.get(targetId)
+          ?.requestSummaries.map(cloneRequestSummary) ?? [];
+
+      return {
+        kind: "chrome-relay",
+        profile: profileId,
+        targetId,
+        relayUrl,
+        hasTarget: true,
+        url: tab.page.url(),
+        title: await tab.page.title(),
+        html: await tab.page.content(),
+        requestSummaries
+      };
+    },
+    screenshot: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const tab = profileStates.get(profileId)?.tabs.get(targetId);
+      if (tab === undefined) {
+        return {
+          kind: "chrome-relay",
+          profile: profileId,
+          targetId,
+          relayUrl,
+          hasTarget: false
+        };
+      }
+
+      const screenshot = await capturePageScreenshot(tab.page);
+      return {
+        kind: "chrome-relay",
+        profile: profileId,
+        targetId,
+        relayUrl,
+        hasTarget: true,
+        ...screenshot
+      };
+    },
+    act: async (action, targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const tab = profileStates.get(profileId)?.tabs.get(targetId);
+      if (tab === undefined) {
+        return {
+          actionType: action.type,
+          profile: profileId,
+          targetId,
+          relayUrl,
+          targetKnown: false,
+          ok: false,
+          executed: false,
+          error: `Unknown targetId: ${targetId} (profile: ${profileId})`
+        };
+      }
+
+      const payload = action.payload;
+      const operationState = getOrCreateTargetOperationState(profileId, targetId);
+      const baseResult = {
+        actionType: action.type,
+        profile: profileId,
+        targetId,
+        relayUrl,
+        targetKnown: true
+      };
+
+      const performAction = async (): Promise<{
+        ok: boolean;
+        executed: boolean;
+        error?: string;
+        data?: Record<string, unknown>;
+      }> => {
+        switch (action.type) {
+          case "navigate":
+          case "goto": {
+            const nextUrl = readActionPayloadString(payload, "url");
+            if (nextUrl === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.url is required for navigate action."
+              };
+            }
+
+            await tab.page.goto(nextUrl);
+            tab.url = nextUrl;
+            return { ok: true, executed: true };
+          }
+          case "click": {
+            const selector = readActionPayloadString(payload, "selector");
+            if (selector === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector is required for click action."
+              };
+            }
+
+            const locator = tab.page.locator(selector);
+            if (operationState.uploadFiles.length > 0) {
+              const setInputFilesMethod = getObjectMethod(locator, "setInputFiles");
+              if (typeof setInputFilesMethod === "function") {
+                await setInputFilesMethod.call(locator, [...operationState.uploadFiles]);
+                operationState.uploadFiles = [];
+                return { ok: true, executed: true };
+              }
+            }
+
+            await locator.click();
+            return { ok: true, executed: true };
+          }
+          case "fill": {
+            const selector = readActionPayloadString(payload, "selector");
+            const value = readActionPayloadString(payload, "value");
+            if (selector === undefined || value === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector and action.payload.value are required for fill action."
+              };
+            }
+
+            await tab.page.locator(selector).fill(value);
+            return { ok: true, executed: true };
+          }
+          case "type": {
+            const selector = readActionPayloadString(payload, "selector");
+            const text = readActionPayloadString(payload, "text");
+            if (selector === undefined || text === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector and action.payload.text are required for type action."
+              };
+            }
+
+            await tab.page.locator(selector).type(text);
+            return { ok: true, executed: true };
+          }
+          case "press": {
+            const key = readActionPayloadString(payload, "key");
+            if (key === undefined || tab.page.keyboard === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.key is required for press action."
+              };
+            }
+
+            await tab.page.keyboard.press(key);
+            return { ok: true, executed: true };
+          }
+          case "scroll": {
+            const deltaX = readActionPayloadNumber(payload, "deltaX") ?? 0;
+            const deltaY = readActionPayloadNumber(payload, "deltaY") ?? 900;
+
+            const customScrollMethod = getObjectMethod(tab.page, "scroll");
+            if (typeof customScrollMethod === "function") {
+              const customResult = await customScrollMethod.call(tab.page, deltaX, deltaY);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      deltaX,
+                      deltaY
+                    }
+              };
+            }
+
+            const evaluateMethod = getObjectMethod(tab.page, "evaluate");
+            if (typeof evaluateMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const scrollResult = await evaluateMethod.call(
+              tab.page,
+              (rawArg: unknown) => {
+                const value =
+                  rawArg !== null && typeof rawArg === "object"
+                    ? (rawArg as { deltaX?: unknown; deltaY?: unknown })
+                    : {};
+                const resolvedDeltaX =
+                  typeof value.deltaX === "number" && Number.isFinite(value.deltaX) ? value.deltaX : 0;
+                const resolvedDeltaY =
+                  typeof value.deltaY === "number" && Number.isFinite(value.deltaY) ? value.deltaY : 900;
+                window.scrollBy({
+                  left: resolvedDeltaX,
+                  top: resolvedDeltaY
+                });
+
+                return {
+                  deltaX: resolvedDeltaX,
+                  deltaY: resolvedDeltaY,
+                  scrollX: window.scrollX,
+                  scrollY: window.scrollY
+                };
+              },
+              {
+                deltaX,
+                deltaY
+              }
+            );
+
+            return {
+              ok: true,
+              executed: true,
+              data: isObjectRecord(scrollResult)
+                ? scrollResult
+                : {
+                    deltaX,
+                    deltaY
+                  }
+            };
+          }
+          case "domQuery": {
+            const selector = readActionPayloadString(payload, "selector");
+            if (selector === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector is required for domQuery action."
+              };
+            }
+
+            const customDomQueryMethod = getObjectMethod(tab.page, "domQuery");
+            if (typeof customDomQueryMethod === "function") {
+              const customResult = await customDomQueryMethod.call(tab.page, selector);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      selector,
+                      found: false
+                    }
+              };
+            }
+
+            const queryResult = await evaluateInPage<Record<string, unknown>>(
+              tab.page,
+              (rawArg) => {
+                const selectorValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { selector?: unknown }).selector === "string"
+                    ? (rawArg as { selector: string }).selector
+                    : "";
+                const element = selectorValue.length > 0 ? document.querySelector(selectorValue) : null;
+                if (element === null) {
+                  return {
+                    selector: selectorValue,
+                    found: false
+                  };
+                }
+
+                const attributes: Record<string, string> = {};
+                for (const attribute of Array.from(element.attributes)) {
+                  attributes[attribute.name] = attribute.value;
+                }
+
+                return {
+                  selector: selectorValue,
+                  found: true,
+                  node: {
+                    tagName: element.tagName.toLowerCase(),
+                    id: element.id || undefined,
+                    className: element.className || undefined,
+                    text: (element.textContent || "").trim().slice(0, 300),
+                    attributes
+                  }
+                };
+              },
+              { selector }
+            );
+
+            return {
+              ok: true,
+              executed: true,
+              data: isObjectRecord(queryResult)
+                ? queryResult
+                : {
+                    selector,
+                    found: false
+                  }
+            };
+          }
+          case "domQueryAll": {
+            const selector = readActionPayloadString(payload, "selector");
+            if (selector === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector is required for domQueryAll action."
+              };
+            }
+
+            const customDomQueryAllMethod = getObjectMethod(tab.page, "domQueryAll");
+            if (typeof customDomQueryAllMethod === "function") {
+              const customResult = await customDomQueryAllMethod.call(tab.page, selector);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      selector,
+                      count: 0,
+                      nodes: []
+                    }
+              };
+            }
+
+            const queryResult = await evaluateInPage<Record<string, unknown>>(
+              tab.page,
+              (rawArg) => {
+                const selectorValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { selector?: unknown }).selector === "string"
+                    ? (rawArg as { selector: string }).selector
+                    : "";
+                const elements = selectorValue.length > 0 ? document.querySelectorAll(selectorValue) : [];
+                const nodes = Array.from(elements).map((element, index) => {
+                  const attributes: Record<string, string> = {};
+                  for (const attribute of Array.from(element.attributes)) {
+                    attributes[attribute.name] = attribute.value;
+                  }
+
+                  return {
+                    index,
+                    tagName: element.tagName.toLowerCase(),
+                    id: element.id || undefined,
+                    className: element.className || undefined,
+                    text: (element.textContent || "").trim().slice(0, 300),
+                    attributes
+                  };
+                });
+
+                return {
+                  selector: selectorValue,
+                  count: nodes.length,
+                  nodes
+                };
+              },
+              { selector }
+            );
+
+            return {
+              ok: true,
+              executed: true,
+              data: isObjectRecord(queryResult)
+                ? queryResult
+                : {
+                    selector,
+                    count: 0,
+                    nodes: []
+                  }
+            };
+          }
+          case "elementScreenshot": {
+            const selector = readActionPayloadString(payload, "selector");
+            if (selector === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector is required for elementScreenshot action."
+              };
+            }
+
+            const customElementScreenshotMethod = getObjectMethod(tab.page, "elementScreenshot");
+            if (typeof customElementScreenshotMethod === "function") {
+              const customResult = await customElementScreenshotMethod.call(tab.page, selector);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      selector,
+                      found: false
+                    }
+              };
+            }
+
+            const found = await evaluateInPage<boolean>(
+              tab.page,
+              (rawArg) => {
+                const selectorValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { selector?: unknown }).selector === "string"
+                    ? (rawArg as { selector: string }).selector
+                    : "";
+                return selectorValue.length > 0 && document.querySelector(selectorValue) !== null;
+              },
+              { selector }
+            );
+            if (!found) {
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  selector,
+                  found: false
+                }
+              };
+            }
+
+            const locator = tab.page.locator(selector);
+            const locatorScreenshotMethod = getObjectMethod(locator, "screenshot");
+            if (typeof locatorScreenshotMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const rawScreenshot = await locatorScreenshotMethod.call(locator, { type: "png" });
+            const parsedScreenshot = readScreenshotImage(rawScreenshot);
+            if (parsedScreenshot === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "Unable to parse element screenshot payload."
+              };
+            }
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                selector,
+                found: true,
+                ...parsedScreenshot
+              }
+            };
+          }
+          case "a11ySnapshot": {
+            const selector = readActionPayloadString(payload, "selector");
+            const customA11ySnapshotMethod = getObjectMethod(tab.page, "a11ySnapshot");
+            if (typeof customA11ySnapshotMethod === "function") {
+              const customResult = await customA11ySnapshotMethod.call(tab.page, selector);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      found: false
+                    }
+              };
+            }
+
+            const accessibilityValue =
+              typeof tab.page === "object" && tab.page !== null
+                ? (tab.page as Record<string, unknown>).accessibility
+                : undefined;
+            const accessibilitySnapshotMethod = getObjectMethod(accessibilityValue, "snapshot");
+            if (typeof accessibilitySnapshotMethod === "function") {
+              const snapshot = await accessibilitySnapshotMethod.call(accessibilityValue, {});
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  selector,
+                  found: true,
+                  snapshot
+                }
+              };
+            }
+
+            const fallbackSnapshot = await evaluateInPage<Record<string, unknown>>(
+              tab.page,
+              (rawArg) => {
+                const selectorValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { selector?: unknown }).selector === "string"
+                    ? (rawArg as { selector: string }).selector
+                    : "";
+                const root =
+                  selectorValue.length > 0
+                    ? document.querySelector(selectorValue)
+                    : document.body ?? document.documentElement;
+                if (root === null) {
+                  return {
+                    selector: selectorValue,
+                    found: false
+                  };
+                }
+
+                const build = (element: Element, depth: number): Record<string, unknown> => {
+                  const role =
+                    element.getAttribute("role") ??
+                    (element.tagName.toLowerCase() === "a"
+                      ? "link"
+                      : element.tagName.toLowerCase() === "button"
+                        ? "button"
+                        : element.tagName.toLowerCase() === "input"
+                          ? "textbox"
+                          : "generic");
+                  const name =
+                    element.getAttribute("aria-label") ??
+                    element.getAttribute("alt") ??
+                    (element.textContent || "").trim().slice(0, 120);
+                  if (depth >= 5) {
+                    return {
+                      role,
+                      ...(name.length > 0 ? { name } : {})
+                    };
+                  }
+
+                  const children = Array.from(element.children)
+                    .slice(0, 30)
+                    .map((child) => build(child, depth + 1));
+                  return {
+                    role,
+                    ...(name.length > 0 ? { name } : {}),
+                    ...(children.length > 0 ? { children } : {})
+                  };
+                };
+
+                return {
+                  selector: selectorValue,
+                  found: true,
+                  snapshot: build(root, 0)
+                };
+              },
+              { selector: selector ?? "" }
+            );
+
+            return {
+              ok: true,
+              executed: true,
+              data: isObjectRecord(fallbackSnapshot)
+                ? fallbackSnapshot
+                : {
+                    selector,
+                    found: false
+                  }
+            };
+          }
+          case "cookieGet": {
+            const cookieName = readActionPayloadString(payload, "name");
+            const customCookieGetMethod = getObjectMethod(tab.page, "cookieGet");
+            if (typeof customCookieGetMethod === "function") {
+              const customResult = await customCookieGetMethod.call(tab.page, cookieName);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      cookies: []
+                    }
+              };
+            }
+
+            const contextMethod = getObjectMethod(tab.page, "context");
+            if (typeof contextMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const context = await contextMethod.call(tab.page);
+            const cookiesMethod = getObjectMethod(context, "cookies");
+            if (typeof cookiesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            let rawCookies: unknown;
+            try {
+              rawCookies = await cookiesMethod.call(context, [tab.page.url()]);
+            } catch {
+              rawCookies = await cookiesMethod.call(context);
+            }
+            const cookies = normalizeCookies(rawCookies).filter(
+              (cookie) => cookieName === undefined || cookie.name === cookieName
+            );
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                cookies,
+                ...(cookieName !== undefined ? { name: cookieName } : {})
+              }
+            };
+          }
+          case "cookieSet": {
+            const cookieName = readActionPayloadString(payload, "name");
+            const cookieValue = readActionPayloadString(payload, "value");
+            const cookieUrl = readActionPayloadString(payload, "url") ?? tab.page.url();
+            if (cookieName === undefined || cookieValue === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.name and action.payload.value are required for cookieSet action."
+              };
+            }
+
+            const customCookieSetMethod = getObjectMethod(tab.page, "cookieSet");
+            if (typeof customCookieSetMethod === "function") {
+              const customResult = await customCookieSetMethod.call(tab.page, {
+                name: cookieName,
+                value: cookieValue,
+                url: cookieUrl
+              });
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      set: true,
+                      cookie: {
+                        name: cookieName,
+                        value: cookieValue,
+                        url: cookieUrl
+                      }
+                    }
+              };
+            }
+
+            const contextMethod = getObjectMethod(tab.page, "context");
+            if (typeof contextMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const context = await contextMethod.call(tab.page);
+            const addCookiesMethod = getObjectMethod(context, "addCookies");
+            if (typeof addCookiesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            await addCookiesMethod.call(context, [
+              {
+                name: cookieName,
+                value: cookieValue,
+                url: cookieUrl
+              }
+            ]);
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                set: true,
+                cookie: {
+                  name: cookieName,
+                  value: cookieValue,
+                  url: cookieUrl
+                }
+              }
+            };
+          }
+          case "cookieClear": {
+            const cookieName = readActionPayloadString(payload, "name");
+            const customCookieClearMethod = getObjectMethod(tab.page, "cookieClear");
+            if (typeof customCookieClearMethod === "function") {
+              const customResult = await customCookieClearMethod.call(tab.page, cookieName);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      cleared: true
+                    }
+              };
+            }
+
+            const contextMethod = getObjectMethod(tab.page, "context");
+            if (typeof contextMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const context = await contextMethod.call(tab.page);
+            const clearCookiesMethod = getObjectMethod(context, "clearCookies");
+            if (typeof clearCookiesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            if (cookieName === undefined) {
+              await clearCookiesMethod.call(context);
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  cleared: true,
+                  count: -1
+                }
+              };
+            }
+
+            const cookiesMethod = getObjectMethod(context, "cookies");
+            const addCookiesMethod = getObjectMethod(context, "addCookies");
+            if (typeof cookiesMethod !== "function" || typeof addCookiesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            let rawCookies: unknown;
+            try {
+              rawCookies = await cookiesMethod.call(context, [tab.page.url()]);
+            } catch {
+              rawCookies = await cookiesMethod.call(context);
+            }
+            const currentCookies = normalizeCookies(rawCookies);
+            const keptCookieInputs = currentCookies
+              .filter((cookie) => cookie.name !== cookieName)
+              .map((cookie) => toCookieInput(cookie))
+              .filter((cookie): cookie is Record<string, unknown> => cookie !== undefined);
+            const removedCount = currentCookies.length - keptCookieInputs.length;
+
+            await clearCookiesMethod.call(context);
+            if (keptCookieInputs.length > 0) {
+              await addCookiesMethod.call(context, keptCookieInputs);
+            }
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                cleared: true,
+                name: cookieName,
+                count: removedCount
+              }
+            };
+          }
+          case "storageGet": {
+            const scope = parseStorageScope(readActionPayloadString(payload, "scope"));
+            const key = readActionPayloadString(payload, "key");
+            if (scope === undefined || key === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.scope and action.payload.key are required for storageGet action."
+              };
+            }
+
+            const customStorageGetMethod = getObjectMethod(tab.page, "storageGet");
+            if (typeof customStorageGetMethod === "function") {
+              const customResult = await customStorageGetMethod.call(tab.page, scope, key);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      scope,
+                      key,
+                      exists: false
+                    }
+              };
+            }
+
+            const result = await evaluateInPage<Record<string, unknown>>(
+              tab.page,
+              (rawArg) => {
+                const scopeValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { scope?: unknown }).scope === "string"
+                    ? (rawArg as { scope: string }).scope
+                    : "local";
+                const keyValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { key?: unknown }).key === "string"
+                    ? (rawArg as { key: string }).key
+                    : "";
+                const storage = scopeValue === "session" ? window.sessionStorage : window.localStorage;
+                const value = storage.getItem(keyValue);
+                return {
+                  scope: scopeValue,
+                  key: keyValue,
+                  exists: value !== null,
+                  ...(value !== null ? { value } : {})
+                };
+              },
+              { scope, key }
+            );
+
+            return {
+              ok: true,
+              executed: true,
+              data: isObjectRecord(result)
+                ? result
+                : {
+                    scope,
+                    key,
+                    exists: false
+                  }
+            };
+          }
+          case "storageSet": {
+            const scope = parseStorageScope(readActionPayloadString(payload, "scope"));
+            const key = readActionPayloadString(payload, "key");
+            const value = readActionPayloadString(payload, "value");
+            if (scope === undefined || key === undefined || value === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.scope, action.payload.key and action.payload.value are required for storageSet action."
+              };
+            }
+
+            const customStorageSetMethod = getObjectMethod(tab.page, "storageSet");
+            if (typeof customStorageSetMethod === "function") {
+              const customResult = await customStorageSetMethod.call(tab.page, scope, key, value);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      scope,
+                      key,
+                      value,
+                      set: true
+                    }
+              };
+            }
+
+            await evaluateInPage(
+              tab.page,
+              (rawArg) => {
+                const scopeValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { scope?: unknown }).scope === "string"
+                    ? (rawArg as { scope: string }).scope
+                    : "local";
+                const keyValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { key?: unknown }).key === "string"
+                    ? (rawArg as { key: string }).key
+                    : "";
+                const valueText =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { value?: unknown }).value === "string"
+                    ? (rawArg as { value: string }).value
+                    : "";
+                const storage = scopeValue === "session" ? window.sessionStorage : window.localStorage;
+                storage.setItem(keyValue, valueText);
+              },
+              { scope, key, value }
+            );
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                scope,
+                key,
+                value,
+                set: true
+              }
+            };
+          }
+          case "frameList": {
+            const customFrameListMethod = getObjectMethod(tab.page, "frameList");
+            if (typeof customFrameListMethod === "function") {
+              const customResult = await customFrameListMethod.call(tab.page);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      frames: []
+                    }
+              };
+            }
+
+            const framesMethod = getObjectMethod(tab.page, "frames");
+            if (typeof framesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const rawFrames = await framesMethod.call(tab.page);
+            if (!Array.isArray(rawFrames)) {
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  frames: []
+                }
+              };
+            }
+
+            const mainFrameMethod = getObjectMethod(tab.page, "mainFrame");
+            const mainFrame = typeof mainFrameMethod === "function" ? await mainFrameMethod.call(tab.page) : undefined;
+            const frames = rawFrames.map((frame, index) => {
+              const name = readObjectMethod<string>(frame, "name");
+              const url = readObjectMethod<string>(frame, "url") ?? "";
+              return {
+                frameId: `frame:${index}`,
+                index,
+                ...(typeof name === "string" && name.length > 0 ? { name } : {}),
+                url,
+                isMainFrame: frame === mainFrame
+              };
+            });
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                frames
+              }
+            };
+          }
+          case "frameSnapshot": {
+            const frameId = readActionPayloadString(payload, "frameId");
+            if (frameId === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.frameId is required for frameSnapshot action."
+              };
+            }
+
+            const customFrameSnapshotMethod = getObjectMethod(tab.page, "frameSnapshot");
+            if (typeof customFrameSnapshotMethod === "function") {
+              const customResult = await customFrameSnapshotMethod.call(tab.page, frameId);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      frameId,
+                      found: false
+                    }
+              };
+            }
+
+            const frameIndex = parseFrameIndex(frameId);
+            if (frameIndex === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: `Invalid frameId: ${frameId}`
+              };
+            }
+
+            const framesMethod = getObjectMethod(tab.page, "frames");
+            if (typeof framesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const rawFrames = await framesMethod.call(tab.page);
+            if (!Array.isArray(rawFrames) || frameIndex >= rawFrames.length) {
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  frameId,
+                  found: false
+                }
+              };
+            }
+
+            const frame = rawFrames[frameIndex];
+            const contentMethod = getObjectMethod(frame, "content");
+            if (typeof contentMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const mainFrameMethod = getObjectMethod(tab.page, "mainFrame");
+            const mainFrame = typeof mainFrameMethod === "function" ? await mainFrameMethod.call(tab.page) : undefined;
+            const frameName = readObjectMethod<string>(frame, "name");
+            const frameUrl = readObjectMethod<string>(frame, "url") ?? "";
+            const frameHtml = await contentMethod.call(frame);
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                frameId,
+                index: frameIndex,
+                found: true,
+                ...(typeof frameName === "string" && frameName.length > 0 ? { name: frameName } : {}),
+                url: frameUrl,
+                isMainFrame: frame === mainFrame,
+                html: typeof frameHtml === "string" ? frameHtml : ""
+              }
+            };
+          }
+          default:
+            return {
+              ok: true,
+              executed: false
+            };
+        }
+      };
+
+      try {
+        return {
+          ...baseResult,
+          ...(await performAction())
+        };
+      } catch (error) {
+        return {
+          ...baseResult,
+          ok: false,
+          executed: false,
+          error: toErrorMessage(error)
+        };
+      }
+    },
+    armUpload: async (targetId, files, profile) => {
+      const profileId = resolveProfileId(profile);
+      const operationState = getOrCreateTargetOperationState(profileId, targetId);
+      operationState.uploadFiles = [...files];
+    },
+    armDialog: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const operationState = getOrCreateTargetOperationState(profileId, targetId);
+      operationState.dialogArmedCount += 1;
+    },
+    waitDownload: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const { tab } = requireTargetInProfile(profileId, targetId);
+      const operationState = getOrCreateTargetOperationState(profileId, targetId);
+      const download = await ensureDownloadInFlight(profileId, targetId, tab, operationState);
+
+      return {
+        path: download.path,
+        profile: profileId,
+        targetId,
+        relayUrl,
+        uploadFiles: [...operationState.uploadFiles],
+        dialogArmedCount: operationState.dialogArmedCount,
+        triggerCount: operationState.triggerCount,
+        ...(download.suggestedFilename !== undefined
+          ? { suggestedFilename: download.suggestedFilename }
+          : {}),
+        ...(download.url !== undefined ? { url: download.url } : {}),
+        ...(download.mimeType !== undefined ? { mimeType: download.mimeType } : {})
+      };
+    },
+    triggerDownload: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const { tab } = requireTargetInProfile(profileId, targetId);
+      const operationState = getOrCreateTargetOperationState(profileId, targetId);
+      operationState.triggerCount += 1;
+      void ensureDownloadInFlight(profileId, targetId, tab, operationState);
+    },
+    getConsoleEntries: (targetId, profile) => {
+      const telemetryState = findTelemetryState(targetId, profile);
+      return telemetryState === undefined ? [] : telemetryState.consoleEntries.map(cloneConsoleEntry);
+    },
+    getNetworkResponseBody: (requestId, targetId, profile) => {
+      const body = findTelemetryState(targetId, profile)?.networkResponseBodies.get(requestId);
+      return body === undefined ? undefined : { ...body };
+    }
+  };
+}