@flrande/browserctl 0.5.0-dev.22.1 → 0.6.0

package/packages/driver-managed/src/managed-local-driver.ts

@@ -1,2243 +0,0 @@
-import type {
-  BrowserDriver,
-  BrowserDriverScreenshot,
-  DriverObject
-} from "../../core/src/driver";
-import type { ProfileId, TargetId } from "../../core/src/types";
-
-export type ManagedLocalBrowserName = "chromium" | "firefox" | "webkit";
-
-export type ManagedLocalBrowserLaunchConfig = {
-  browserName: ManagedLocalBrowserName;
-  headless: boolean;
-  channel?: string;
-  executablePath?: string;
-  launchTimeoutMs?: number;
-  args: string[];
-};
-
-export type ManagedLocalDriverConfig = {
-  runtime?: ManagedLocalDriverRuntime;
-  browserName?: ManagedLocalBrowserName;
-  headless?: boolean;
-  channel?: string;
-  executablePath?: string;
-  launchTimeoutMs?: number;
-  args?: string[];
-};
-
-export type ManagedLocalDriverStatus = {
-  kind: "managed-local";
-  connected: boolean;
-  launched: boolean;
-  browserName: ManagedLocalBrowserName;
-  headless: boolean;
-  channel?: string;
-  executablePath?: string;
-  launchTimeoutMs?: number;
-};
-
-export type ManagedLocalConsoleEntryLocation = {
-  url?: string;
-  lineNumber?: number;
-  columnNumber?: number;
-};
-
-export type ManagedLocalConsoleEntry = {
-  type: string;
-  text: string;
-  timestamp: string;
-  location?: ManagedLocalConsoleEntryLocation;
-};
-
-export type ManagedLocalNetworkRequestSummary = {
-  requestId: string;
-  url: string;
-  method?: string;
-  resourceType?: string;
-  status?: number;
-  timestamp: string;
-};
-
-export type ManagedLocalNetworkResponseBody = {
-  body: string;
-  encoding: "utf8" | "base64";
-};
-
-export type ManagedLocalSnapshot = {
-  kind: "managed-local";
-  profile: ProfileId;
-  targetId: TargetId;
-  hasTarget: boolean;
-  url?: string;
-  title?: string;
-  html?: string;
-  requestSummaries?: ManagedLocalNetworkRequestSummary[];
-};
-
-export type ManagedLocalScreenshot = {
-  kind: "managed-local";
-  profile: ProfileId;
-  targetId: TargetId;
-  hasTarget: boolean;
-  mimeType?: string;
-  encoding?: "base64";
-  imageBase64?: string;
-  width?: number;
-  height?: number;
-};
-
-export type ManagedLocalTelemetryDriverExtensions = {
-  getConsoleEntries?(targetId: TargetId, profile?: ProfileId): ManagedLocalConsoleEntry[];
-  getNetworkResponseBody?(
-    requestId: string,
-    targetId: TargetId,
-    profile?: ProfileId
-  ): ManagedLocalNetworkResponseBody | undefined;
-};
-
-export type ManagedLocalLocator = {
-  click(): Promise<void>;
-  fill(value: string): Promise<void>;
-  type(value: string): Promise<void>;
-};
-
-export type ManagedLocalKeyboard = {
-  press(key: string): Promise<void>;
-};
-
-export type ManagedLocalPage = {
-  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>;
-  locator(selector: string): ManagedLocalLocator;
-  route?(url: string, handler: ManagedLocalNetworkMockHandler): Promise<void>;
-  unroute?(url: string, handler?: ManagedLocalNetworkMockHandler): Promise<void>;
-  keyboard?: ManagedLocalKeyboard;
-  on?(eventName: string, listener: (payload: unknown) => unknown): void;
-};
-
-export type ManagedLocalBrowserContext = {
-  newPage(): Promise<ManagedLocalPage>;
-  close(): Promise<void>;
-};
-
-export type ManagedLocalBrowser = {
-  newContext(): Promise<ManagedLocalBrowserContext>;
-  close(): Promise<void>;
-};
-
-export type ManagedLocalDriverRuntime = {
-  launch(config: ManagedLocalBrowserLaunchConfig): Promise<ManagedLocalBrowser>;
-};
-
-const DEFAULT_PROFILE_ID: ProfileId = "profile:managed-local:default";
-const DEFAULT_BROWSER_NAME: ManagedLocalBrowserName = "chromium";
-const DEFAULT_HEADLESS = true;
-
-type ManagedLocalTab = {
-  url: string;
-  page: ManagedLocalPage;
-};
-
-type ManagedLocalProfileState = {
-  nextTargetNumber: number;
-  tabs: Map<TargetId, ManagedLocalTab>;
-  tabOrder: TargetId[];
-  focusedTargetId?: TargetId;
-  context?: ManagedLocalBrowserContext;
-};
-
-type ManagedLocalTargetOperationState = {
-  uploadFiles: string[];
-  dialogArmedCount: number;
-  triggerCount: number;
-  nextNetworkMockNumber: number;
-  networkMocks: Map<string, ManagedLocalNetworkMockBinding>;
-  requestedDownloadPath?: string;
-  downloadInFlight?: Promise<ManagedLocalDownloadArtifact>;
-  latestDownload?: ManagedLocalDownloadArtifact;
-  latestRawDownload?: unknown;
-};
-
-type ManagedLocalDownloadArtifact = {
-  path: string;
-  suggestedFilename?: string;
-  url?: string;
-  mimeType?: string;
-};
-
-type ManagedLocalNetworkMockHandler = (...args: unknown[]) => Promise<void>;
-type ManagedLocalNetworkMockBinding = {
-  urlPattern: string;
-  handler: ManagedLocalNetworkMockHandler;
-};
-
-type ManagedLocalTargetTelemetryState = {
-  consoleEntries: ManagedLocalConsoleEntry[];
-  requestSummaries: ManagedLocalNetworkRequestSummary[];
-  networkResponseBodies: Map<string, ManagedLocalNetworkResponseBody>;
-  nextRequestNumber: number;
-};
-
-function resolveProfileId(profile?: ProfileId): ProfileId {
-  return profile ?? DEFAULT_PROFILE_ID;
-}
-
-function createTargetId(profileId: ProfileId, targetNumber: number): TargetId {
-  return `target:managed-local:${profileId}:${targetNumber}`;
-}
-
-function createProfileState(): ManagedLocalProfileState {
-  return {
-    nextTargetNumber: 1,
-    tabs: new Map<TargetId, ManagedLocalTab>(),
-    tabOrder: []
-  };
-}
-
-function createTargetOperationState(): ManagedLocalTargetOperationState {
-  return {
-    uploadFiles: [],
-    dialogArmedCount: 0,
-    triggerCount: 0,
-    nextNetworkMockNumber: 1,
-    networkMocks: new Map<string, ManagedLocalNetworkMockBinding>()
-  };
-}
-
-function createTargetTelemetryState(): ManagedLocalTargetTelemetryState {
-  return {
-    consoleEntries: [],
-    requestSummaries: [],
-    networkResponseBodies: new Map<string, ManagedLocalNetworkResponseBody>(),
-    nextRequestNumber: 1
-  };
-}
-
-function createDownloadPath(profileId: ProfileId, targetId: TargetId, triggerCount: number): string {
-  return `managed-local-${encodeURIComponent(profileId)}-${encodeURIComponent(targetId)}-${triggerCount}.bin`;
-}
-
-function createRequestId(profileId: ProfileId, targetId: TargetId, requestNumber: number): string {
-  return `request:managed-local:${encodeURIComponent(profileId)}:${encodeURIComponent(targetId)}:${requestNumber}`;
-}
-
-function toErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : "Unexpected managed-local 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;
-}
-
-function readConsoleEntry(value: unknown): ManagedLocalConsoleEntry {
-  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
-): ManagedLocalNetworkRequestSummary {
-  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 ManagedLocalScreenshotImage = {
-  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): ManagedLocalScreenshotImage | 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: ManagedLocalPage): Promise<ManagedLocalScreenshotImage> {
-  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 ManagedLocalCookie = {
-  name: string;
-  value: string;
-  domain?: string;
-  path?: string;
-  expires?: number;
-  httpOnly?: boolean;
-  secure?: boolean;
-  sameSite?: string;
-  url?: string;
-};
-
-function normalizeCookies(value: unknown): ManagedLocalCookie[] {
-  if (!Array.isArray(value)) {
-    return [];
-  }
-
-  const cookies: ManagedLocalCookie[] = [];
-  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: ManagedLocalCookie): 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: ManagedLocalPage,
-  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<ManagedLocalNetworkResponseBody | 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: ManagedLocalPage,
-  profileId: ProfileId,
-  targetId: TargetId,
-  telemetryState: ManagedLocalTargetTelemetryState,
-  operationState: ManagedLocalTargetOperationState
-): void {
-  if (typeof page.on !== "function") {
-    return;
-  }
-
-  page.on("console", (message) => {
-    telemetryState.consoleEntries.push(readConsoleEntry(message));
-  });
-
-  page.on("response", async (response) => {
-    const requestId = createRequestId(profileId, targetId, telemetryState.nextRequestNumber);
-    telemetryState.nextRequestNumber += 1;
-    telemetryState.requestSummaries.push(readNetworkSummary(response, requestId));
-
-    const body = await readNetworkResponseBody(response);
-    if (body !== undefined) {
-      telemetryState.networkResponseBodies.set(requestId, body);
-    }
-  });
-
-  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<ManagedLocalDownloadArtifact> {
-  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 createPlaywrightRuntime(): ManagedLocalDriverRuntime {
-  return {
-    launch: async (config) => {
-      const playwright = await import("playwright-core");
-      const browserType =
-        config.browserName === "firefox"
-          ? playwright.firefox
-          : config.browserName === "webkit"
-            ? playwright.webkit
-            : playwright.chromium;
-
-      return browserType.launch({
-        headless: config.headless,
-        channel: config.channel,
-        executablePath: config.executablePath,
-        timeout: config.launchTimeoutMs,
-        args: config.args.length === 0 ? undefined : config.args
-      });
-    }
-  };
-}
-
-export function createManagedLocalDriver(
-  config: ManagedLocalDriverConfig = {}
-): BrowserDriver<ManagedLocalDriverStatus, ManagedLocalSnapshot> &
-  ManagedLocalTelemetryDriverExtensions &
-  BrowserDriverScreenshot<ManagedLocalScreenshot> {
-  const launchConfig: ManagedLocalBrowserLaunchConfig = {
-    browserName: config.browserName ?? DEFAULT_BROWSER_NAME,
-    headless: config.headless ?? DEFAULT_HEADLESS,
-    channel: config.channel,
-    executablePath: config.executablePath,
-    launchTimeoutMs: config.launchTimeoutMs,
-    args: config.args === undefined ? [] : [...config.args]
-  };
-  const runtime = config.runtime ?? createPlaywrightRuntime();
-  const profileStates = new Map<ProfileId, ManagedLocalProfileState>();
-  const profileInitInFlight = new Map<ProfileId, Promise<ManagedLocalProfileState>>();
-  const targetOperationStates = new Map<ProfileId, Map<TargetId, ManagedLocalTargetOperationState>>();
-  const targetTelemetryStates = new Map<ProfileId, Map<TargetId, ManagedLocalTargetTelemetryState>>();
-  let browser: ManagedLocalBrowser | undefined;
-  let launchInFlight: Promise<ManagedLocalBrowser> | undefined;
-
-  async function ensureBrowser(): Promise<ManagedLocalBrowser> {
-    if (browser !== undefined) {
-      return browser;
-    }
-
-    if (launchInFlight === undefined) {
-      launchInFlight = runtime
-        .launch({ ...launchConfig, args: [...launchConfig.args] })
-        .then((createdBrowser) => {
-          browser = createdBrowser;
-          return createdBrowser;
-        })
-        .finally(() => {
-          launchInFlight = undefined;
-        });
-    }
-
-    return launchInFlight;
-  }
-
-  async function ensureProfileState(profileId: ProfileId): Promise<ManagedLocalProfileState> {
-    const existingState = profileStates.get(profileId);
-    if (existingState !== undefined) {
-      if (existingState.context === undefined) {
-        const inFlight = profileInitInFlight.get(profileId);
-        if (inFlight !== undefined) {
-          return inFlight;
-        }
-
-        const initPromise = (async () => {
-          existingState.context = await (await ensureBrowser()).newContext();
-          return existingState;
-        })().finally(() => {
-          profileInitInFlight.delete(profileId);
-        });
-
-        profileInitInFlight.set(profileId, initPromise);
-        return initPromise;
-      }
-
-      return existingState;
-    }
-
-    const createdState = createProfileState();
-    profileStates.set(profileId, createdState);
-    const initPromise = (async () => {
-      createdState.context = await (await ensureBrowser()).newContext();
-      return createdState;
-    })()
-      .catch((error: unknown) => {
-        // Roll back profile state if launch/context setup failed before any tab existed.
-        if (createdState.tabOrder.length === 0) {
-          profileStates.delete(profileId);
-        }
-
-        throw error;
-      })
-      .finally(() => {
-        profileInitInFlight.delete(profileId);
-      });
-
-    profileInitInFlight.set(profileId, initPromise);
-    return initPromise;
-  }
-
-  async function closeProfileResources(
-    profileId: ProfileId,
-    profileState: ManagedLocalProfileState
-  ): Promise<void> {
-    if (profileState.context !== undefined) {
-      await profileState.context.close();
-      profileState.context = undefined;
-    }
-
-    profileStates.delete(profileId);
-    targetOperationStates.delete(profileId);
-    targetTelemetryStates.delete(profileId);
-
-    if (profileStates.size === 0 && browser !== undefined) {
-      await browser.close();
-      browser = undefined;
-    }
-  }
-
-  function requireTargetInProfile(
-    profileId: ProfileId,
-    targetId: TargetId
-  ): { profileState: ManagedLocalProfileState; tab: ManagedLocalTab } {
-    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
-  ): ManagedLocalTargetOperationState {
-    if (validateTarget) {
-      requireTargetInProfile(profileId, targetId);
-    }
-
-    let profileOperationStates = targetOperationStates.get(profileId);
-    if (profileOperationStates === undefined) {
-      profileOperationStates = new Map<TargetId, ManagedLocalTargetOperationState>();
-      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, ManagedLocalTargetTelemetryState> {
-    const existingStates = targetTelemetryStates.get(profileId);
-    if (existingStates !== undefined) {
-      return existingStates;
-    }
-
-    const createdStates = new Map<TargetId, ManagedLocalTargetTelemetryState>();
-    targetTelemetryStates.set(profileId, createdStates);
-    return createdStates;
-  }
-
-  function findTelemetryState(
-    targetId: TargetId,
-    profile?: ProfileId
-  ): ManagedLocalTargetTelemetryState | 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: ManagedLocalTab,
-    operationState: ManagedLocalTargetOperationState,
-    requestedPath?: string
-  ): Promise<ManagedLocalDownloadArtifact> {
-    if (requestedPath !== undefined) {
-      operationState.requestedDownloadPath = requestedPath;
-    }
-
-    if (operationState.downloadInFlight !== undefined) {
-      return operationState.downloadInFlight;
-    }
-
-    const fallbackPath =
-      operationState.requestedDownloadPath ??
-      createDownloadPath(profileId, targetId, Math.max(operationState.triggerCount, 1));
-    const waitForEventMethod = getObjectMethod(tab.page, "waitForEvent");
-    if (typeof waitForEventMethod !== "function") {
-      const artifact: ManagedLocalDownloadArtifact = { path: fallbackPath };
-      operationState.requestedDownloadPath = undefined;
-      operationState.latestDownload = artifact;
-      operationState.latestRawDownload = undefined;
-      const resolved = Promise.resolve(artifact);
-      operationState.downloadInFlight = resolved;
-      return resolved;
-    }
-
-    const inFlight = (async () => {
-      const rawDownload = await waitForEventMethod.call(tab.page, "download");
-      operationState.latestRawDownload = rawDownload;
-      const persistedPath =
-        operationState.requestedDownloadPath ??
-        createDownloadPath(profileId, targetId, Math.max(operationState.triggerCount, 1));
-      const artifact = await readDownloadArtifact(rawDownload, persistedPath);
-      operationState.latestDownload = artifact;
-      operationState.requestedDownloadPath = undefined;
-      return artifact;
-    })().finally(() => {
-      if (operationState.downloadInFlight === inFlight) {
-        operationState.downloadInFlight = undefined;
-      }
-    });
-
-    operationState.downloadInFlight = inFlight;
-    return inFlight;
-  }
-
-  async function resolveDownloadArtifactPath(
-    operationState: ManagedLocalTargetOperationState,
-    artifact: ManagedLocalDownloadArtifact,
-    requestedPath?: string
-  ): Promise<ManagedLocalDownloadArtifact> {
-    if (requestedPath === undefined || requestedPath.trim().length === 0 || artifact.path === requestedPath) {
-      return artifact;
-    }
-
-    const failurePrefix = `Failed to persist download to requested path: ${requestedPath}`;
-    const saveAsMethod = getObjectMethod(operationState.latestRawDownload, "saveAs");
-    if (typeof saveAsMethod !== "function") {
-      throw new Error(failurePrefix);
-    }
-
-    try {
-      await saveAsMethod.call(operationState.latestRawDownload, requestedPath);
-      return { ...artifact, path: requestedPath };
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new Error(message.length > 0 ? `${failurePrefix} (${message})` : failurePrefix);
-    }
-  }
-
-  return {
-    status: async () => ({
-      kind: "managed-local",
-      connected: browser !== undefined,
-      launched: browser !== undefined,
-      browserName: launchConfig.browserName,
-      headless: launchConfig.headless,
-      channel: launchConfig.channel,
-      executablePath: launchConfig.executablePath,
-      launchTimeoutMs: launchConfig.launchTimeoutMs
-    }),
-    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 = await ensureProfileState(profileId);
-      const targetId = createTargetId(profileId, profileState.nextTargetNumber);
-      const context = profileState.context;
-      if (context === undefined) {
-        throw new Error(`No browser context available for profile: ${profileId}`);
-      }
-
-      const page = await context.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);
-      }
-
-      if (profileState.tabOrder.length === 0) {
-        await closeProfileResources(profileId, profileState);
-      }
-    },
-    snapshot: async (targetId, profile) => {
-      const profileId = resolveProfileId(profile);
-      const tab = profileStates.get(profileId)?.tabs.get(targetId);
-      if (tab === undefined) {
-        return {
-          kind: "managed-local",
-          profile: profileId,
-          targetId,
-          hasTarget: false
-        };
-      }
-
-      const requestSummaries =
-        targetTelemetryStates
-          .get(profileId)
-          ?.get(targetId)
-          ?.requestSummaries.map((summary) => ({ ...summary })) ?? [];
-
-      return {
-        kind: "managed-local",
-        profile: profileId,
-        targetId,
-        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: "managed-local",
-          profile: profileId,
-          targetId,
-          hasTarget: false
-        };
-      }
-
-      const screenshot = await capturePageScreenshot(tab.page);
-      return {
-        kind: "managed-local",
-        profile: profileId,
-        targetId,
-        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,
-          targetKnown: false,
-          ok: false,
-          error: `Unknown targetId: ${targetId} (profile: ${profileId})`
-        };
-      }
-
-      const payload = action.payload;
-      const profileState = profileStates.get(profileId);
-      const operationState = getOrCreateTargetOperationState(profileId, targetId);
-      const baseResult = {
-        actionType: action.type,
-        profile: profileId,
-        targetId,
-        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 "networkMockAdd": {
-            const urlPattern = readActionPayloadString(payload, "urlPattern");
-            if (urlPattern === undefined) {
-              return {
-                ok: false,
-                executed: false,
-                error: "action.payload.urlPattern is required for networkMockAdd action."
-              };
-            }
-
-            const routeMethod = getObjectMethod(tab.page, "route");
-            if (typeof routeMethod !== "function") {
-              return {
-                ok: true,
-                executed: false
-              };
-            }
-
-            const methodFilter = readActionPayloadString(payload, "method")?.toUpperCase();
-            const status = readActionPayloadNumber(payload, "status") ?? 200;
-            if (!Number.isInteger(status) || status < 100 || status > 599) {
-              return {
-                ok: false,
-                executed: false,
-                error: "action.payload.status must be an integer between 100 and 599 for networkMockAdd action."
-              };
-            }
-            const body = readActionPayloadString(payload, "body") ?? "";
-            const contentType = readActionPayloadString(payload, "contentType") ?? "text/plain";
-            const mockId = `mock:${operationState.nextNetworkMockNumber}`;
-            operationState.nextNetworkMockNumber += 1;
-            const handler: ManagedLocalNetworkMockHandler = async (...args) => {
-              const route = args[0];
-              const explicitRequest = args[1];
-              const request = explicitRequest ?? readObjectMethod<unknown>(route, "request");
-              if (methodFilter !== undefined) {
-                const requestMethod = readObjectMethod<string>(request, "method");
-                if (requestMethod?.toUpperCase() !== methodFilter) {
-                  const continueMethod = getObjectMethod(route, "continue");
-                  if (typeof continueMethod === "function") {
-                    await continueMethod.call(route);
-                    return;
-                  }
-
-                  const fallbackMethod = getObjectMethod(route, "fallback");
-                  if (typeof fallbackMethod === "function") {
-                    await fallbackMethod.call(route);
-                    return;
-                  }
-
-                  return;
-                }
-              }
-
-              const fulfillMethod = getObjectMethod(route, "fulfill");
-              if (typeof fulfillMethod !== "function") {
-                return;
-              }
-
-              await fulfillMethod.call(route, {
-                status,
-                body,
-                headers: {
-                  "content-type": contentType
-                }
-              });
-            };
-
-            await routeMethod.call(tab.page, urlPattern, handler);
-            operationState.networkMocks.set(mockId, {
-              urlPattern,
-              handler
-            });
-            return {
-              ok: true,
-              executed: true,
-              data: {
-                mockId,
-                urlPattern,
-                ...(methodFilter !== undefined ? { method: methodFilter } : {}),
-                status
-              }
-            };
-          }
-          case "networkMockClear": {
-            const unrouteMethod = getObjectMethod(tab.page, "unroute");
-            if (typeof unrouteMethod !== "function") {
-              return {
-                ok: true,
-                executed: false
-              };
-            }
-
-            const mockId = readActionPayloadString(payload, "mockId");
-            if (mockId !== undefined) {
-              const binding = operationState.networkMocks.get(mockId);
-              if (binding === undefined) {
-                return {
-                  ok: false,
-                  executed: false,
-                  error: `Unknown network mock id: ${mockId}`
-                };
-              }
-
-              await unrouteMethod.call(tab.page, binding.urlPattern, binding.handler);
-              operationState.networkMocks.delete(mockId);
-              return {
-                ok: true,
-                executed: true,
-                data: {
-                  cleared: 1,
-                  mockId
-                }
-              };
-            }
-
-            let cleared = 0;
-            for (const [registeredId, binding] of operationState.networkMocks.entries()) {
-              try {
-                await unrouteMethod.call(tab.page, binding.urlPattern, binding.handler);
-              } catch {
-                // Ignore per-route cleanup failures.
-              }
-              operationState.networkMocks.delete(registeredId);
-              cleared += 1;
-            }
-
-            return {
-              ok: true,
-              executed: true,
-              data: {
-                cleared
-              }
-            };
-          }
-          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 context = profileState?.context;
-            const cookiesMethod = context === undefined ? undefined : 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 context = profileState?.context;
-            const addCookiesMethod = context === undefined ? undefined : 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 context = profileState?.context;
-            const clearCookiesMethod = context === undefined ? undefined : 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, path) => {
-      const profileId = resolveProfileId(profile);
-      const { tab } = requireTargetInProfile(profileId, targetId);
-      const operationState = getOrCreateTargetOperationState(profileId, targetId);
-      const requestedPath = path !== undefined && path.trim().length > 0 ? path : undefined;
-      if (operationState.downloadInFlight === undefined && operationState.latestDownload !== undefined) {
-        const download = await resolveDownloadArtifactPath(
-          operationState,
-          { ...operationState.latestDownload },
-          requestedPath
-        );
-
-        operationState.latestDownload = undefined;
-        operationState.latestRawDownload = undefined;
-        operationState.requestedDownloadPath = undefined;
-        return {
-          path: download.path,
-          profile: profileId,
-          targetId,
-          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 } : {})
-        };
-      }
-
-      const inFlightDownload = await ensureDownloadInFlight(
-        profileId,
-        targetId,
-        tab,
-        operationState,
-        requestedPath
-      );
-      const download = await resolveDownloadArtifactPath(operationState, inFlightDownload, requestedPath);
-      operationState.latestDownload = undefined;
-      operationState.latestRawDownload = undefined;
-      operationState.requestedDownloadPath = undefined;
-
-      return {
-        path: download.path,
-        profile: profileId,
-        targetId,
-        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;
-      operationState.latestDownload = undefined;
-      operationState.latestRawDownload = undefined;
-      operationState.requestedDownloadPath = undefined;
-      void ensureDownloadInFlight(profileId, targetId, tab, operationState);
-    },
-    getConsoleEntries: (targetId, profile) => {
-      const telemetryState = findTelemetryState(targetId, profile);
-      return telemetryState === undefined ? [] : telemetryState.consoleEntries.map((entry) => ({ ...entry }));
-    },
-    getNetworkResponseBody: (requestId, targetId, profile) => {
-      const body = findTelemetryState(targetId, profile)?.networkResponseBodies.get(requestId);
-      return body === undefined ? undefined : { ...body };
-    }
-  };
-}